CONSTRUCTOR

alien_arch

[version 0.019]

Install module into an architecture specific directory. This is off by default, unless $ENV{ALIEN_ARCH} is true. Most Alien distributions will be installing binary code. If you are an integrator where the @INC path is shared by multiple Perls in a non-homogeneous environment you can set $ENV{ALIEN_ARCH} to 1 and Alien modules will be installed in architecture specific directories.

alien_autoconf_with_pic

[version 0.005]

Add "--with-pic" option to autoconf style "configure" script when called. This is the default, and normally a good practice. Normally autoconf will ignore this and any other options that it does not recognize, but some non-autoconf "configure" scripts may complain.

alien_bin_requires

[version 0.006]

Hash reference of modules (keys) and versions (values) that specifies "Alien" modules that provide binary tools that are required to build. Any Alien::Base module that includes binaries should work. Also supported are Alien::MSYS, Alien::CMake, Alien::TinyCC and Alien::Autotools.

[version 0.007]

These only become required for building if Alien::Base::ModuleBuild determines that a source code build is required.

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 "[ '%c --prefix=%s', 'make' ]".

[version 0.009]

Each command may be either a string or an array reference. If the array reference form is used then the multiple argument form of "system" is used. Prior to version 0.009, only the string form was supported.

alien_env

[version 0.027]

Environment overrides. Allows you to set environment variables as a hash reference that will override environment variables. You can use the same interpolated escape sequences and helpers that commands use. Set to undef to remove the variable.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_env => {
     PERL => '%X',     # sets the environment variable PERL to the location
                       # of the Perl interpreter.
     PERCENT => '%%',  # evaluates to '%'
     REMOVE => undef,  # remove the environment variable if it is defined
   },
   ...
 );
 ...
    

Please keep in mind that frequently users have a good reason to have set environment variables, and you should not override them without a good reason. An example of a good justification would be if a project has a Makefile that interacts badly with common environment variables. This can sometimes be a problem since Makefile variables can be overridden with environment variables.

A useful pattern is to use a helper to only override an environment variable if it is not already set.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_helper => {
     foo => '$ENV{FOO}||"my preferred value if not already set"'
   },
   alien_env => {
     FOO => '%{foo}',
   },
   ...
 );
 ...
    

A common pitfall with environment variables is that setting one to the empty string ('') is not portable. On Unix it works fine as you would expect, but in Windows it actually unsets the environment variable, which may not be what you intend.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_env => {
     # is allowed, but may not do what you intend
     # on some platforms!
     FOO => '',
   },
 );
 ...
    

alien_extra_site_config

[version 0.030]

Append extra values to the "config.site" file when using autoconf.

When <autoconf> is detected, a "config.site" file is created with values appropriate for building software that can link against the Perl that you are building with. This is important on some platforms, for example 64 bit systems where the compilers generate 32 bit code by default. You can also add values to the "config.site" file using this directive.

For values that are already provided by "Alien::Base::ModuleBuild", your value will be appended after the existing value. For values that aren't provided, it will simply use your value by itself.

For example if you needed to add a define to a CFLAGS, you might do something like this:

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_extra_site_config => {
     # CFLAGS is usually specified by A::B::MB
     CFLAGS => '-DFOO=1',
     # BAR usually is not.
     BAR => 'baz',
   },
   ...
 );
 ...
    

And the actual value for CFLAGS in the "config.site" might have values like this:

 CFLAGS=-O3 -g -DFOO=1
 BAR=baz
    

alien_ffi_name

[version 0.007]

The name of the shared library for use with FFI. Provided for situations where the shared library name cannot be determined from the "pkg-config" name specified with "alien_name". For example "libxml2" has a "pkg-config" of "libxml-2.0", but a shared library name of "xml2". By default alien_name is used with any "lib" prefix removed. For example "libarchive" to be translated into "archive" which is what you want for that package.

alien_helper

[version 0.020]

Provide helpers to generate commands or arguments at build or install time. This property is a hash reference. The keys are the helper names and the values are strings containing Perl code that will be evaluated and interpolated into the command before execution. Because helpers are only needed when building a package from the source code, any dependency may be specified as an "alien_bin_requires". For example:

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_bin_requires => {
     'Alien::foo' => 0,
   },
   alien_helper => {
     'foocommand'  => 'Alien::foo->some_command',
     'fooargument' => 'Alien::foo->some_argument',
   },
   alien_build_commands => [
     '%{foocommand} %{fooargument}',
   ],
   ...
 );
    

[version 0.022]

One helper that you get for free is "%{pkg_config}" which will be the pkg-config implementation chosen by Alien::Base::ModuleBuild. This will either be the real pkg-config provided by the operating system (preferred) or PkgConfig, the pure perl implementation found on CPAN.

alien_inline_auto_include

[version 0.006]

Array reference containing the list of header files to be used automatically by "Inline::C" and "Inline::CPP".

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' ]".

[version 0.009]

Each command may be either a string or an array reference. If the array reference form is used then the multiple argument form of "system" is used. Prior to version 0.009, only the string form was supported.

alien_install_type

[version 1.08]

Set the install type. Legal values are "system" and "share". The environment variable "ALIEN_INSTALL_TYPE" and "ALIEN_FORCE" will be used in preference over this property.

alien_isolate_dynamic

[version 0.005]

If set to true, then dynamic libraries will be moved from the "lib" directory to a separate "dynamic" directory. This makes them available for FFI modules (see FFI::Platypus), while preferring static libraries when creating XS extensions.

alien_msys

[version 0.006]

On windows wrap build and install commands in an "MSYS" environment using Alien::MSYS. This option will automatically add Alien::MSYS as a build requirement when building on Windows.

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_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:

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.

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_selection_method

[not yet implemented]

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

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_dir"s. 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_stage_install

It might be tempting to use this option if you have a library or tool that hard codes paths from the install location inside the executable or library code. However, using this option relies on blib detection which is not very reliable, and can leave your install in an broken state if the package install step fails. If you really need this option, please consider instead migrating to Alien::Build, which has a much more reliable way of staging installs correctly.

[version 0.016]

Alien packages are installed directly into the blib directory by the `./Build' command rather than to the final location during the `./Build install` step.

[version 0.017]

As of 0.017 this is the default.

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_test_commands

[version 0.001]

An arrayref of commands used to test the library. Each command is first passed through the command interpolation engine, so those variables may be used. The default is to do no tests. The most common command used by the GNU toolchain is "[ 'make check' ]", but beware that is not supported by all packages.

[version 0.009]

Each command may be either a string or an array reference. If the array reference form is used, then the multiple argument form of system is used.

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

PACKAGE AND ENVIRONMENT VARIABLES

$ENV{ALIEN_ARCH}

[version 0.017]

Setting this changes the default for alien_arch above. If the module specifies its own alien_arch in its "Build.PL" file then it will override this setting. Typically installing into an architecture specific directory is what you want to do, since most Alien::Base based distributions provide architecture specific binary code, so you should consider carefully before installing modules with this environment variable set to 0. This may be useful for integrators creating a single non-architecture specific RPM, .deb or similar package. In this case the integrator should ensure that the Alien package be installed with a system install_type and use the system package.

$ENV{ALIEN_BLIB}

Setting this to true indicates that you don't intend to actually install your Alien::Base subclass, but rather use it from the built blib directory. This behavior is mostly to support automated testing from CPANtesters and should be automagically determined. If by chance you happen to trip the behavior accidentally, setting this environment variable to false (0) before building should prevent problems.

$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. This is the equivalent to setting $ENV{ALIEN_INSTALL_TYPE} to 'share'. $ENV{ALIEN_INSTALL_TYPE} takes precedence.

$ENV{ALIEN_INSTALL_TYPE}

Setting to "share" will ignore a system-wide installation and build a local version of the library. Setting to "system" will only use a system-wide installation and die if it cannot be found.

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

CONFIG DATA

Config keys of interest are:

name

Holder for "alien_name" as needed by pkg-config.

install_type

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

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.

version

The version number installed or available.

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.

COMMAND INTERPOLATION

%{helper}

[version 0.020]

Call the given helper, either provided by the "alien_helper" or "alien_bin_requires" property. See Alien::Base#alien_helper.

%c

Platform independent incantation for running autoconf "configure" script. On *nix systems this is "./configure", on Windows this is "sh configure". On windows Alien::MSYS is injected as a dependency and all commands are executed in an "MSYS" environment.

%n

Shortcut for the name stored in "alien_name"

 pkg-config --modversion %n
    

%p

deprecated

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

 %pconfigure
    

Please note that this only works to run scripts on Unix, and does not work on Windows. It is thus, not fit for purpose and should not be used. As an alternative:

%s

The full path to the installed location of the 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
    

This will be the local blib directory location if "alien_stage_install" is true (which is the default as of 0.17. This will be the final install location if "alien_stage_install" is false (which was the default prior to 0.17). Please see the documentation above on "alien_stage_install" which includes some caveats before you consider changing this option.

%v

Captured version of the original archive.

%x

The current Perl interpreter (aka $^X)

%X

[version 0.027]

The current Perl interpreter using the Unix style path separator "/" instead of the native Windows "\".

%%

A literal "%".