=head1 NAME
 
Alien::Base::ModuleBuild::API - API Reference for Alien:: Authors
 
=head1 DESCRIPTION

A list of extra properties and methods provided by 
L<Alien::Base::ModuleBuild> beyond those contained in L<Module::Build::API>.
Note that all property and method names are prefixed with C<alien_> to prevent future 
collisions L<Module::Build> builtins.

=head2 CONSTRUCTOR

L<Alien::Base::ModuleBuild> adds several parameters to the L<new|Module::Build::API/CONSTRUCTORS> constructor in L<Module::Build>. Unless otherwise specified all of the parameters listed in L<Module::Build::API> are available and behave identically to the description contained therein.

=over

=item alien_name

[version 0.001]

The name of the primary library which will be provided. This should be in the form to be passed to C<pkg-config>. This name is available in the L<command interpolation|/"COMMAND INTERPOLATION"> as C<%n>.

=item alien_temp_dir

[version 0.001]

The name of the temporary folder which will house the library when it is downloaded and built. This folder will always be removed by the C<clean> action. The default name is C<_alien>.

=item alien_share_dir

[version 0.001]

The name of the folder which will both serve as the "install" directory (i.e. <--prefix>) for C<make install> as well as a share directory via L<Module::Build>'s C<share_dir>/C<dist_dir> parameter. This directory is added in a smart manner which attempts not to interfere with other author-defined C<share_dir>s. The default name is C<_install>.

=item alien_selection_method

[not yet implemented]

This is intended to choose the mechanism for selecting one file from many. The default name is C<newest>.

=item alien_build_commands

[version 0.001]

An arrayref of commands used to build the library and install it to the directory specified in C<alien_share_dir>. Each command is first passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">, so those variables may be used. The default is tailored to the Gnu toolchain, i.e. AutoConf and Make; it is C<[ '%pconfigure --prefix=%s', 'make', 'make install' ]>.

=item alien_version_check

[version 0.001]

A command to run to check the version of the library installed on the system. The default is C<pkg-config --modversion %n>.

=item alien_provides_cflags

=item alien_provides_libs

[version 0.001]

These parameters, if specified, augment the information found by F<pkg-config>. If no package config data is found, these are used to generate the necessary information. In that case, if these are not specified, they are attempted to be created from found shared-object files and header files. They both are empty by default.

=item alien_repository

[version 0.001]

A hashref or arrayref of hashrefs defining the repositories used to find and fetch library tarballs (or zipballs etc.). These attributes are used to create C<Alien::Base::ModuleBuild::Repository> objects (or more likely, subclasses thereof). Which class is created is governed by the C<protocol> attribute and the C<alien_repository_class> property below. Available attributes are:

=over

=item protocol

One of C<ftp> or C<http> or C<local>. The first two are obvious, C<local> allows packaging a tarball with the Alien:: module.

=item protocol_class

Defines the protocol handler class. Defaults to 'Net::FTP' or 'HTTP::Tiny' as appropriate.

=item host

This is either the root server address for the FTP and HTTP classes (i.e. C<my.server.com>)

=item location

This key is protocol specific. For FTP this contains the name of the folder to search. For HTTP this is the page to be searched for links; this is specified as a path relative to the C<host>. For a local file, this specifies the folder containing the tarball relative to the C<base_dir>.

=item pattern

This is a C<qr> regex matching acceptable files found in the C<location>. If the pattern contains a capture group, the captured string is interpreted as the version number. N.B. if no versions are found, the files are sorted by filename using version semantics, this mechanism is not likely to be as accurate as specifying a capture group.

=item platform

This attribute is a string telling the repository validator which platform the repository serves. This may be the string C<src> (the default) for platform-independent source files, or a string which matches the L<Module::Build> method C<os_type> (e.g. "Windows", "Unix", "MacOS", "VMS").

=back

=item alien_repository_default

[version 0.001]

This property is a shortcut for specifying multiple repositories with similar attributes. If a repository attribute is not defined in its C<alien_repository> hashref, but that attribute is defined here, then this value will be used. This hashref is empty by default.

=item alien_repository_class

[version 0.001]

As the repositories in C<alien_repository> are converted to objects, this hash controls the type of object that is created. The keys are the relevant protocol. This allows for easy subclassing any or all protocol classes. The defaults are as follows.

 http    => 'Alien::Base::ModuleBuild::Repository::HTTP',
 ftp     => 'Alien::Base::ModuleBuild::Repository::FTP',
 local   => 'Alien::Base::ModuleBuild::Repository::Local',
 default => 'Alien::Base::ModuleBuild::Repository',

Unlike most L<Module::Build> parameters, authors may specify only those keys which are to be overridden. If any of the above keys are not specified, the above defaults will be used.

=back

=head2 PACKAGE AND ENVIRONMENT VARIABLES

A few global variables are used to set gross behavior. For each pair of variables, if both are set, the environment variable takes precedence.

=over 

=item $Alien::Base::ModuleBuild::Verbose

=item $ENV{ALIEN_VERBOSE}

Setting the either to a true value will output a little more info from within the module itself, plus is will not suppress the messages from the library-build phase (i.e. make etc.). 

=item $Alien::Base::ModuleBuild::Force

=item $ENV{ALIEN_FORCE}

Setting either to a true value will cause the builder to ignore a system-wide installation and build a local version of the library.

=back

=head2 CONFIG DATA

The L<Alien::Base> system needs to store some data to be used in other phases of the build and eventual use. This is done via the mechanism provided by L<Module::Build::ConfigData>. During the build-phase this information is mutable and is available through the C<Module::Build::config_data> method. As the build-phase ends the data is serialized and stored as C<Alien::MyModule::ConfigData> (assuming you are authoring C<Alien::MyModule>). Then during the use-phase, the C<Alien::MyModule::ConfigData::config> method (via the C<Alien::MyModule::config> wrapper) is used to query the information. This data is not strictly immutable, but it changing it involves file permissions and is best left alone.

Config keys of interest are:

=over

=item build_share_dir

Holder for the full path to the shared directory specified in C<alien_share_dir> builder object parameter. This is used to munge the pkg-config data later on.

=item pkgconfig

A hashref of Alien::Base::PkgConfig objects created from F<.pc> files found in C<build_share_dir>. One extra object (whose key is C<_manual> is created from the C<alien_provides_*> information.

=item install_type

Remembers if the library was found system-wide (value: C<system>) or was installed during build (value: C<share>).

=item version

The version number installed or available.

=item name

Holder for C<alien_name> as needed by pkg-config.

=back

=head2 COMMAND INTERPOLATION

Before L<Alien::Base::ModuleBuild> executes system commands, it replaces a few special escape sequences with useful data. This is needed especially for referencing the full path to the C<alien_share_dir> before this path is known. The availble sequences are:

=over

=item %s

The full path to the share directory (C<alien_share_dir>). This is where the library should install itself; for autoconf style installs this will look like 

 --prefix=%s

=item %p

Platform independent "local command prefix". On *nix systems this is C<./>, on Windows it is an empty string.

 %pconfigure

=item %n

Shortcut for the name stored in C<alien_name>

 pkg-config --modversion %n

=item %x

The current Perl interpreter (aka $^X)

=item %%

A literal C<%>.

=back

=head1 AUTHOR

Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>

=head1 SEE ALSO

=over

=item * 

L<Module::Build::API>

=back

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2012 by Joel Berger

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

=cut
