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


 package Alien::MyLibrary;

 use strict;
 use warnings;

 use parent 'Alien::Base';


(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,

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

 use Alien::MyLibrary
 use ExtUtils::MakeMaker;
   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 ));

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->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';


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.


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


 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).


 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.


 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.


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

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


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 with Alien::MyLibrary.


 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.


 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).


 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.


 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.


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.!forum/perl5-alien

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



Original author: Joel Berger, <>

Current maintainer: Graham Ollis <> and the Alien::Base team


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


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.