/ 
Alien-Base-0.009_04
River stage zero No dependents
/ Alien::Base

NAME

Alien::Base - Base classes for Alien:: modules

SYNOPSIS

package Alien::MyLibrary;

use strict;
use warnings;

use parent 'Alien::Base';

1;

(For a synopsis of the Build.PL that comes with your Alien::MyLibrary see Alien::Base::ModuleBuild)

Then a MyLibrary::XS can use Alien::MyLibrary in its Build.PL:

use Alien::MyLibrary;
use Module::Build 0.28; # need at least 0.28

my $builder = Module::Build->new(
  ...
  extra_compiler_flags => Alien::MyLibrary->cflags,
  extra_linker_flags   => Alien::MyLibrary->libs,
  ...
);

$builder->create_build_script;

Or if you prefer ExtUtils::MakeMaker, in its Makefile.PL:

use Alien::MyLibrary
use ExtUtils::MakeMaker;

WriteMakefile(
  ...
  CFLAGS => Alien::MyLibrary->cflags,
  LIBS   => ALien::MyLibrary->libs,
  ...
);

Or if you are using ExtUtils::Depends:

use ExtUtils::MakeMaker;
use ExtUtils::Depends;
my $eud = ExtUtils::Depends->new(qw( MyLibrary::XS Alien::MyLibrary ));
WriteMakefile(
  ...
  $eud->get_makefile_vars
);

In your MyLibrary::XS module, you may need to use Alien::MyLibrary if dynamic libraries are used:

package MyLibrary::XS;

use Alien::MyLibrary;

...

Or you can use it from an FFI module:

package MyLibrary::FFI;

use Alien::MyLibrary;
use FFI::Platypus;

my $ffi = FFI::Platypus->new;
$ffi->lib(Alien::MyLibrary->dynamic_libs);

$ffi->attach( 'my_library_function' => [] => 'void' );

You can even use it with Inline (C and C++ languages are supported):

package MyLibrary::Inline;

use Alien::MyLibrary;
# Inline 0.56 or better is required
use Inline 0.56 with => 'Alien::MyLibrary';
...

DESCRIPTION

Alien::Base comprises base classes to help in the construction of Alien:: modules. Modules in the Alien namespace are used to locate and install (if necessary) external libraries needed by other Perl modules.

This is the documentation for the Alien::Base module itself. To learn more about the system as a whole please see Alien::Base::Authoring.

METHODS

In the example snippets here, Alien::MyLibrary represents any subclass of Alien::Base.

dist_dir

my $dir = Alien::MyLibrary->dist_dir;

Returns the directory that contains the install root for the packaged software, if it was built from install (i.e., if install_type is share).

cflags

my $cflags = Alien::MyLibrary->cflags;

use Text::ParseWords qw( shellwords );
my @cflags = shellwords( Alien::MyLibrary->cflags );

Returns the C compiler flags necessary to compile an XS module using the alien software. If you need this in list form (for example if you are calling system with a list argument) you can pass this value into shellwords from the Perl core Text::ParseWords module.

libs

my $libs = Alien::MyLibrary->libs;

use Text::ParseWords qw( shellwords );
my @cflags = shellwords( Alien::MyLibrary->libs );

Returns the library linker flags necessary to link an XS module against the alien software. If you need this in list form (for example if you are calling system with a list argument) you can pass this value into shellwords from the Perl core Text::ParseWords module.

install_type

my $install_type = Alien::MyLibrary->install_type;

Returns the install type that was used when Alien::MyLibrary was installed. Types include:

system

The library was provided by the operating system

share

The library was not available when Alien::MyLibrary was installed, so it was built from source code, either downloaded from the Internet or bundled with Alien::MyLibrary.

config

my $value = Alien::MyLibrary->config($key);

Returns the configuration data as determined during the install of Alien::MyLibrary. For the appropriate config keys, see Alien::Base::ModuleBuild::API#CONFIG-DATA.

dynamic_libs

my @dlls = Alien::MyLibrary->dynamic_libs;
my($dll) = Alien::MyLibrary->dynamic_libs;

Returns a list of the dynamic library or shared object files for the alien software. Currently this only works for when install_type is share and alien_isolate_dynamic is used (See Alien::Base::ModuleBuild::API#CONSTRUCTOR for all build arguments).

bin_dir

my(@dir) = Alien::MyLibrary->bin_dir

Returns a list of directories with executables in them. For a system install this will be an empty list. For a share install this will be a directory under dist_dir named bin if it exists. You may wish to override the default behavior if you have executables or scripts that get installed into non-standard locations.

inline_auto_include

my(@headers) = Alien::MyLibrary->inline_auto_include;

List of header files to automatically include in inline C and C++ code when using Inline::C or Inline::CPP. This is provided as a public interface primarily so that it can be overidden at run time. This can also be specified in your Build.PL with Alien::Base::ModuleBuild using the alien_inline_auto_include property.

SUPPORT AND CONTRIBUTING

If you find a bug, please report it on the projects issue tracker on GitHub:

https://github.com/Perl5-Alien/Alien-Base/issues

Development is discussed on the projects google groups. This is also a reasonable place to post a question if you don't want to open an issue in GitHub.

https://groups.google.com/forum/#!forum/perl5-alien

If you have implemented a new feature or fixed a bug, please open a pull request.

https://github.com/Perl5-Alien/Alien-Base/pulls

SEE ALSO

AUTHOR

Original author: Joel Berger, <joel.a.berger@gmail.com>

Current maintainer: Graham Ollis <plicease@cpan.org> and the Alien::Base team

CONTRIBUTORS

David Mertens (run4flat)
Mark Nunberg (mordy, mnunberg)
Christian Walde (Mithaldu)
Brian Wightman (MidLifeXis)
Graham Ollis (plicease)
Zaki Mughal (zmughal)
mohawk2
Vikas N Kumar (vikasnkumar)

COPYRIGHT AND LICENSE

Copyright (C) 2012-2015 by Joel Berger

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.