# ABSTRACT: Authoring an C<Alien::> module using Alien::Base::ModuleBuild
# PODNAME: Alien::Base::ModuleBuild::Authoring
# VERSION

__END__

=pod

=encoding UTF-8

=head1 NAME

Alien::Base::ModuleBuild::Authoring - Authoring an C<Alien::> module using Alien::Base::ModuleBuild

=head1 VERSION

version 1.17

=head1 DESCRIPTION

B<NOTE>: Please consider for new development of L<Alien>s that you use
L<Alien::Build> and L<alienfile> instead.  Like L<Alien::Base::ModuleBuild> they work
with L<Alien::Base>.  Unlike L<Alien::Base::ModuleBuild> they are more easily customized
and handle a number of corner cases better.  For a good place to start,
please see L<Alien::Build::Manual::AlienAuthor>.  Although the
Alien-Base / Alien-Build team will continue to maintain this module,
(we will continue to fix bugs where appropriate), we aren't adding any
new features to this module.

Congratulations! You have made the decision to help the Perl community by providing a C library via CPAN. The L<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. L<Alien::Base> tries to ease that pain by providing most of the needed functionality; usually authors should only need a little boilerplate and configuration!

=head1 STATUS

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

=head1 ECOSYSTEM

The L<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 C<Alien::MyLibrary> which provides F<libmylibrary.so>. Further it will assume that you or someone else is going to use this module/library to write C<Some::Module::MyLibrary>. Finally an end user might use that module to write F<myscript.pl>.

=head2 Alien::Base::ModuleBuild

L<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 L<Module::Build>, which is what supports the building and installing of the surrounding C<Alien::> module. C<Alien::MyLibrary>'s F<Build.PL> file will use L<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 L<Module::Build>, except that there will be a few additional configuration parameters (see L<Alien::Base::ModuleBuild::API>).

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

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

=head2 Alien::Base

L<Alien::Base> is the base class of C<Alien::MyLibrary>. In this context, L<Alien::Base> has two distinct uses. First it is used by C<Alien::MyLibrary> to provide the build information/flags for building C<Some::Module::MyLibrary>. Secondly it is used (again through C<Alien::MyLibrary>) to provide run-time access to F<libmylibrary.so> to C<Some::Module::MyLibrary>.

=head3 Alien::Base for Building

C<Alien::MyLibrary> is called by C<Some::Library::MyLibrary>'s build script, either F<Build.PL> or F<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 C<config> method.

=head3 Alien::Base for Run-Time Provision

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

 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
 package Alien::MyLibrary;
 
 use parent 'Alien::Base';
 
 1;

Finally, C<Alien::MyLibrary> must also be called by C<Some::Library::MyLibrary> before C<DynaLoader::bootstrap> or C<XSLoader::load>. The C<use> directive is recommended, however if you must use C<require> then be sure to call the C<import> method too. Without this C<import> call, the loader doesn't know where to find F<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

=head1 EXAMPLES

The example code that was housed in this distribution during alpha phase has been moved to two different CPAN distributions. Those are:

=over

=item *

L<Acme::Alien::DontPanic> -- An example C<Alien::> module which provides F<libdontpanic.so>. It provides the C function C<answer> which is simply:

 int answer () { return 42 }

=item *

L<Acme::Ford::Prefect> -- An XS module which provides the Perl-level access to C<answer>. It relies on F<libdontpanic.so> and uses L<Acme::Alien::DontPanic> to locate/load it.

=back

Additionally, there exist in-production C<Alien::> distributions that serve as de-facto tests of L<Alien::Base>'s networking components:

=over

=item *

L<Alien::LibYAML> -- Builds and installs F<libyaml>, acquiring the library archive from its hosted location via C<Alien::Base::Repository::HTTP>.

=item *

L<Alien::GSL> -- Builds and installs F<libgsl>, acquiring the library source archive via C<Alien::Base::Repository::FTP>.

=item *

L<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 L<Alien::Base> for providing tools rather than libraries.

=back

=head1 SEE ALSO

=over

=item *

L<Module::Build>

=item *

L<Alien>

=item *

L<Alien::Base>

=item *

L<Alien::Base::FAQ>

=back

=head1 AUTHOR

Original author: Joel A Berger E<lt>joel.a.berger@gmail.comE<gt>

Current maintainer: Graham Ollis E<lt>plicease@cpan.orgE<gt>

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)

Salvador Fandiño (salva)

Gianni Ceccarelli (dakkar)

Pavel Shaydo (zwon, trinitum)

Kang-min Liu (劉康民, gugod)

Nicholas Shipp (nshp)

Petr Písař (ppisar)

Alberto Simões (ambs)

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012-2022 by Joel A Berger.

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

=cut
