Alien::Base::Authoring - Authoring an Alien:: module
Alien::
Congratulations! You have made the decision to help the Perl community by providing a C library via CPAN. The Alien namespace has been instrumental in providing C libraries for many years, but authoring those modules has been a commitment that most authors weren't willing to take on. Alien::Base tries to ease that pain by providing most of the needed functionality; usually authors should only need a little boilerplate and configuration!
Alien::Base is under active development. The API is relatively stable, although breaking changes may be introduced if the rewards are deemed greater than the pains that they produce.
The Alien::Base ecosystem is made up of several elements. Some of these elements are the base classes in the distribution itself. Of course, no ecosystem is complete without inhabitants, therefore, it is also important to consider the users of these base classes. This documentation will assume that you are writing Alien::MyLibrary which provides libmylibrary.so. Further it will assume that you or someone else is going to use this module/library to write Some::Module::MyLibrary. Finally an end user might use that module to write myscript.pl.
Alien::MyLibrary
Some::Module::MyLibrary
Alien::Base::ModuleBuild provides a base class, utility methods and configuration handling for the build/install phase of the library. It is itself a subclass of Module::Build, which is what supports the building and installing of the surrouning Alien:: module. Alien::MyLibrary's Build.PL file will use Alien::Base::ModuleBuild to create its builder object.
# 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 libary (the commands specified in builder parameter alien_build_commands). The alien_install action is responsible for installing the library into its final destination.
alien_code
alien_install
build
./Build
install
./Build install
alien_build_commands
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.
./Build test
alien_test_commands
alien_install_commands
Alien::Base is the base class of Alien::MyLibrary. In this context, Alien::Base has two distinct uses. First it is used by Alien::MyLibrary to provide the build information/flags for building Some::Module::MyLibrary. Secondly it is used (again through Alien::MyLibrary) to provide run-time access to libmylibrary.so to Some::Module::MyLibrary.
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.
Some::Library::MyLibrary
# 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.
config
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}.
import
DynaLoader::dl_load_file
dlopen
$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.
DynaLoader::bootstrap
XSLoader::load
use
require
# 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
The example code that was housed in this distribution during alpha phase has been moved to two different CPAN distributions. Those are:
Acme::Alien::DontPanic -- An example Alien:: module which provides libdontpanic.so. It provides the C function answer which is simply:
answer
int answer () { return 42 }
Acme::Ford::Prefect -- An XS module which provides the Perl-level access to answer. It relies on libdontpanic.so and uses Acme::Alien::DontPanic to locate/load it.
Additionally, there exist in-production Alien:: distributions that serve as de-facto tests of Alien::Base's networking components:
Alien::LibYAML -- Builds and installs libyaml, acquiring the library archive from its hosted location via Alien::Base::Repository::HTTP.
Alien::Base::Repository::HTTP
Alien::GSL -- Builds and installs libgsl, aquiring the library source archive via Alien::Base::Repository::FTP.
Alien::Base::Repository::FTP
Alien::gmake -- Builds and installs GNU make. Rather than being a library, this is a tool used to build other tools and libraries. It is useful for other Alien modules that require the GNU version of make. It also demonstrates the use of Alien::Base for providing tools rather than libraries.
Joel Berger <joel.a.berger@gmail.com>
Module::Build
Alien
Alien::Base
Alien::Base::FAQ
http://github.com/Perl5-Alien/Alien-Base
Original author: Joel Berger, <joel.a.berger@gmail.com>
Current maintainer: Graham Ollis <plicease@cpan.org> and the Alien::Base team
Copyright (C) 2012-2017 by Joel Berger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Alien::Base, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Alien::Base
CPAN shell
perl -MCPAN -e shell install Alien::Base
For more information on module installation, please visit the detailed CPAN module installation guide.