Alien::Base::ModuleBuild

 # file: Alien-MyLibrary/Build.PL
 use Alien::Base::ModuleBuild;
 my $builder = Alien::Base::ModuleBuild->new(...);
 $builder->create_build_script;

This is just like you would do for Module::Build, except that there will be a few additional configuration parameters (see Alien::Base::ModuleBuild::API).

Alien::Base::ModuleBuild adds the additional build actions "alien_code" and "alien_install". These actions need never be run directly, the usual "build" action (usually seen as "./Build") and "install" ("./Build install") will call them for you. The "alien_code" action is responsible for finding, downloading, extracting and building the external library (the commands specified in builder parameter "alien_build_commands"). The "alien_install" action is responsible for installing the library into its final destination.

The "./Build test" command will invoke any library tests specified in "alien_test_commands", though none are defined by default. Finally "./Build install" will invoke whatever "alien_install_commands" were specified.

Alien::Base

Alien::Base for Building

"Alien::MyLibrary" is called by "Some::Library::MyLibrary"'s build script, either Build.PL or Makefile.PL. Most of the functionality can be utilized through class method calls, though creating an object can save a few keystrokes.

 # file: Some-Module-MyLibrary/Build.PL
 use Module::Build;
 use Alien::MyLibrary;

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

Additional information can be gotten from the "config" method.

Alien::Base for Run-Time Provision

"Alien::MyLibrary" must be a subclass of Alien::Base. This provides the "import" method, which does the run-time provisioning so that when the XS file is loaded, it can find libmylibrary.so. The "import" method does this by pre-loading the library via "DynaLoader::dl_load_file" which is a platform-independent wrapper for "dlopen" or your system's equivalent. It no longer appends to $ENV{LD_RUN_PATH}.

 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
 package Alien::MyLibrary;

 use parent 'Alien::Base';

 1;

Finally, "Alien::MyLibrary" must also be called by "Some::Library::MyLibrary" before "DynaLoader::bootstrap" or "XSLoader::load". The "use" directive is recommended, however if you must use "require" then be sure to call the "import" method too. Without this "import" call, the loader doesn't know where to find libmylibrary.so.

 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
 package Some::Module::MyLibrary;

 use Alien::MyLibrary;
 our $VERSION = '0.54';

 require XSLoader;
 XSLoader::load('Some::Module::MyLibrary', $VERSION);

 # your code