NAME

Alien::Base::ModuleBuild::API - API Reference for Alien:: Authors

DESCRIPTION

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

CONSTRUCTOR

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

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 pkg-config. This name is available in the command interpolation as %n.

alien_temp_dir

[version 0.001]

The name of the temporary folder which will house the library when it is downloaded and built. The default name is _alien.

alien_share_dir

[version 0.001]

The name of the folder which will both serve a stub share directory via Module::Build's share_dir/dist_dir parameter. This directory is added in a smart manner which attempts not to interfere with other author-defined share_dirs. The default name is _share. This folder will hold a README file which is then installed to the target installed share location. It is THAT location that the library will be installed to.

alien_selection_method

[not yet implemented]

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

alien_build_commands

[version 0.001]

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

alien_install_commands

[version 0.001]

An arrayref of commands used to install it to the share directory specified by interpolation var %s. Each command is first passed through the command interpolation engine, so those variables may be used. The default is tailored to the Gnu toolchain, i.e. AutoConf and Make; it is [ 'make install' ].

alien_version_check

[version 0.001]

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

alien_provides_cflags

alien_provides_libs

[version 0.001]

These parameters, if specified, augment the information found by 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.

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 Alien::Base::ModuleBuild::Repository objects (or more likely, subclasses thereof). Which class is created is governed by the protocol attribute and the alien_repository_class property below. Available attributes are:

protocol: One of ftp or http or local. The first two are obvious, local allows packaging a tarball with the Alien:: module.
protocol_class: Defines the protocol handler class. Defaults to 'Net::FTP' or 'HTTP::Tiny' as appropriate.
host: This is either the root server address for the FTP and HTTP classes (i.e. my.server.com)
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 host. For a local file, this specifies the folder containing the tarball relative to the base_dir.
pattern: This is a qr regex matching acceptable files found in the 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.
exact_filename: This key may be specified in place of pattern when the filename of the tarball is known, in which case such a file is downloaded from the given host and location. Note that, in general, specifying a pattern gives more flexibility, but there may be cases when you find more convenient to use exact_filename.
exact_version: This key may be specified with the exact_filename key when the version of the tarball is known.
platform: This attribute is a string telling the repository validator which platform the repository serves. This may be the string src (the default) for platform-independent source files, or a string which matches the Module::Build method os_type (e.g. "Windows", "Unix", "MacOS", "VMS").

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 alien_repository hashref, but that attribute is defined here, then this value will be used. This hashref is empty by default.

alien_repository_class

[version 0.001]

As the repositories in 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 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.

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.

$Alien::Base::ModuleBuild::Verbose
$ENV{ALIEN_VERBOSE}: Setting the either to a true value will output a little more info from within the module itself. At this point Alien::Base is going to be fairly verbose without this enabled.
$Alien::Base::ModuleBuild::Force
$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.

CONFIG DATA

The 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 Module::Build::ConfigData. During the build-phase this information is mutable and is available through the Module::Build::config_data method. As the build-phase ends the data is serialized and stored as Alien::MyModule::ConfigData (assuming you are authoring Alien::MyModule). Then during the use-phase, the Alien::MyModule::ConfigData::config method (via the 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:

working_directory: Holder for the full path to the extracted source of the library. This is used to munge the pkg-config data later on.
pkgconfig: A hashref of Alien::Base::PkgConfig objects created from .pc files found in working_directory. One extra object (whose key is _manual is created from the alien_provides_* information.
install_type: Remembers if the library was found system-wide (value: system) or was installed during build (value: share).
version: The version number installed or available.
name: Holder for alien_name as needed by pkg-config.

COMMAND INTERPOLATION

Before 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 alien_share_dir before this path is known. The availble sequences are:

%s

The full path to the final installed location of the share directory (builder method alien_library_destination). This is where the library should install itself; for autoconf style installs this will look like

--prefix=%s

%p

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

%pconfigure

%n

Shortcut for the name stored in alien_name

pkg-config --modversion %n

%x

The current Perl interpreter (aka $^X)

%%

A literal %.

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

CONSTRUCTOR

PACKAGE AND ENVIRONMENT VARIABLES

CONFIG DATA

COMMAND INTERPOLATION

AUTHOR

SEE ALSO

COPYRIGHT AND LICENSE

Module Install Instructions