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
-
The library was not available when
Alien::MyLibrary
was installed, so it was built from source code, either downloaded from the Internet or bundled withAlien::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.
alien_helper
my $helpers = Alien::MyLibrary->alien_helper;
Returns a hash reference of helpers provided by the Alien module. The keys are helper names and the values are code references. The code references will be executed at command time and the return value will be interpolated into the command before execution. The default implementation returns an empty hash reference, and you are expected to override the method to create your own helpers.
For compatability with the Alien::Base::ModuleBuild
attribute alien_helper
, helpers may also be specified as Perl strings that will be evaluated and executed at command time. This is necessary because of limitations with Module::Build
, and you are strongly encouraged to use code references when defining helpers from an Alien module.
Helpers allow users of your Alien module to use platform or environment determined logic to compute command names or arguments in alien_build_commands
or alien_install_commands
in their Build.PL
. Helpers allow you to do this without making your Alien module a requirement when a build from source code is not necessary.
As a concrete example, consider Alien::gmake, which provides the helper gmake
:
package Alien::gmake;
...
sub alien_helper {
my($class) = @_;
return {
gmake => sub {
# return the executable name for GNU make,
# usually either make or gmake depending on
# the platform and environment
$class->exe;
}
},
}
Now consider Alien::nasm. nasm
requires GNU Make to build from source code, but if the system nasm
package is installed we don't need it. From the Build.PL
of Alien::nasm
:
# Alien::nasm Build.PL
...
Alien::Build::ModuleBuild->new(
...
alien_bin_requires => {
'Alien::gmake' => '0.05', # helper introduced in 0.05
},
alien_build_commands => [
'%c --prefix=%s',
'%{gmake}',
],
alien_install_commands => [
'%{gmake} install',
],
...
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
First check the Alien::Base::FAQ for questions that have already been answered.
IRC: #native on irc.perl.org
(click for instant chatroom login)
If you find a bug, please report it on the projects issue tracker on GitHub:
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.
If you have implemented a new feature or fixed a bug, please open a pull request.
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)
- Flavio Poletti (polettix)
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.