new

my $build = Alien::Build->new;

This creates a new empty instance of Alien::Build. Normally you will want to use "load" below to create an instance of Alien::Build from an alienfile recipe.

load

my $build = Alien::Build->load($alienfile);

This creates an Alien::Build instance with the given alienfile recipe.

resume

my $build = Alien::Build->resume($alienfile, $root);

Load a checkpointed Alien::Build instance. You will need the original alienfile and the build root (usually "_alien"), and a build that had been properly checkpointed using the "checkpoint" method below.

meta_prop

my $href = $build->meta_prop;
my $href = Alien::Build->meta_prop;

Meta properties have to do with the recipe itself, and not any particular instance that probes or builds that recipe. Meta properties can be changed from within an alienfile using the "meta_prop" directive, or from a plugin from its "init" method (though should NOT be modified from any hooks registered within that "init" method). This is not strictly enforced, but if you do not follow this rule your recipe will likely be broken.

arch

This is a hint to an installer like Alien::Build::MM or Alien::Build::MB, that the library or tool contains architecture dependent files and so should be stored in an architecture dependent location. If not specified by your alienfile then it will be set to true.

check_digest

True if cryptographic digest should be checked when files are fetched or downloaded. This is set by Digest negotiator plugin.

destdir

Some plugins (Alien::Build::Plugin::Build::Autoconf for example) support installing via "DESTDIR". They will set this property to true if they plan on doing such an install. This helps Alien::Build find the staged install files and how to locate them.

If available, "DESTDIR" is used to stage install files in a sub directory before copying the files into "blib". This is generally preferred method if available.

destdir_filter

Regular expression for the files that should be copied from the "DESTDIR" into the stage directory. If not defined, then all files will be copied.

destdir_ffi_filter

Same as "destdir_filter" except applies to "build_ffi" instead of "build".

digest

This properties contains the cryptographic digests (if any) that should be used when verifying any fetched and downloaded files. It is a hash reference where the key is the filename and the value is an array reference containing a pair of values, the first being the algorithm ('SHA256' is recommended) and the second is the actual digest. The special filename "*" may be specified to indicate that any downloaded file should match that digest. If there are both real filenames and the "*" placeholder, the real filenames will be used for filenames that match and any other files will use the placeholder. Example:

$build->meta_prop->{digest} = {
  'foo-1.00.tar.gz' => [ SHA256 => '9feac593aa49a44eb837de52513a57736457f1ea70078346c60f0bfc5f24f2c1' ],
  'foo-1.01.tar.gz' => [ SHA256 => '6bbde6a7f10ae5924cf74afc26ff5b7bc4b4f9dfd85c6b534c51bd254697b9e7' ],
  '*'               => [ SHA256 => '33a20aae3df6ecfbe812b48082926d55391be4a57d858d35753ab1334b9fddb3' ],
};

Cryptographic signatures will only be checked if the check_digest meta property is set and if the Digest negotiator plugin is loaded. (The Digest negotiator can be used directly, but is also loaded automatically if you use the digest directive is used by the alienfile).

env

Environment variables to override during the build stage.

env_interpolate

Environment variable values will be interpolated with helpers. Example:

meta->prop->{env_interpolate} = 1;
meta->prop->{env}->{PERL} = '%{perl}';

local_source

Set to true if source code package is available locally. (that is not fetched over the internet). This is computed by default based on the "start_url" property. Can be set by an alienfile or plugin.

platform

Hash reference. Contains information about the platform beyond just $^O.

out_of_source

Build in a different directory from the where the source code is stored. In autoconf this is referred to as a "VPATH" build. Everyone else calls this an "out-of-source" build. When this property is true, instead of extracting to the source build root, the downloaded source will be extracted to an source extraction directory and the source build root will be empty. You can use the "extract" install property to get the location of the extracted source.

network

True if a network fetch is available. This should NOT be set by an alienfile or plugin. This is computed based on the "ALIEN_INSTALL_NETWORK" environment variables.

start_url

The default or start URL used by fetch plugins.

install_prop

my $href = $build->install_prop;

Install properties are used during the install phase (either under "share" or "system" install). They are remembered for the entire install phase, but not kept around during the runtime phase. Thus they cannot be accessed from your Alien::Base based module.

autoconf_prefix

The prefix as understood by autoconf. This is only different on Windows Where MSYS is used and paths like "C:/foo" are represented as "/C/foo" which are understood by the MSYS tools, but not by Perl. You should only use this if you are using Alien::Build::Plugin::Build::Autoconf in your alienfile. This is set during before the build hook is run.

download

The location of the downloaded archive (tar.gz, or similar) or directory. This will be undefined until the archive is actually downloaded.

download_detail

This property contains optional details about a downloaded file. This property is populated by Alien::Build core. This property is a hash reference. The key is the path to the file that has been downloaded and the value is a hash reference with additional detail. All fields are optional.

env

Environment variables to override during the build stage. Plugins are free to set additional overrides using this hash.

extract

The location of the last source extraction. For a "out-of-source" build (see the "out_of_source" meta property above), this will only be set once. For other types of builds, the source code may be extracted multiple times, and thus this property may change.

old

[deprecated]

Hash containing information on a previously installed Alien of the same name, if available. This may be useful in cases where you want to reuse the previous install if it is still sufficient.

patch

Directory with patches, if available. This will be "undef" if there are no patches. When initially installing an alien this will usually be a sibling of the "alienfile", a directory called "patch". Once installed this will be in the share directory called "_alien/patch". The former is useful for rebuilding an alienized package using af.

prefix

The install time prefix. Under a "destdir" install this is the same as the runtime or final install location. Under a non-"destdir" install this is the "stage" directory (usually the appropriate share directory under "blib").

root

The build root directory. This will be an absolute path. It is the absolute form of "./_alien" by default.

stage

The stage directory where files will be copied. This is usually the root of the blib share directory.

system_probe_class

After the probe step this property may contain the plugin class that performed the system probe. It shouldn't be filled in directly by the plugin (instead if should use the hook property "probe_class", see below). This is optional, and not all probe plugins will provide this information.

system_probe_instance_id

After the probe step this property may contain the plugin instance id that performed the system probe. It shouldn't be filled in directly by the plugin (instead if should use the hook property "probe_instance_id", see below). This is optional, and not all probe plugins will provide this information.

plugin_instance_prop

my $href = $build->plugin_instance_prop($plugin);

This returns the private plugin instance properties for a given plugin. This method should usually only be called internally by plugins themselves to keep track of internal state. Because the content can be used arbitrarily by the owning plugin because it is private to the plugin, and thus is not part of the Alien::Build spec.

runtime_prop

my $href = $build->runtime_prop;

Runtime properties are used during the install and runtime phases (either under "share" or "system" install). This should include anything that you will need to know to use the library or tool during runtime, and shouldn't include anything that is no longer relevant once the install process is complete.

alien_build_version

The version of Alien::Build used to install the library or tool.

alt

Alternate configurations. If the alienized package has multiple libraries this could be used to store the different compiler or linker flags for each library. Typically this will be set by a plugin in the gather stage (for either share or system installs).

cflags

The compiler flags. This is typically set by a plugin in the gather stage (for either share or system installs).

cflags_static

The static compiler flags. This is typically set by a plugin in the gather stage (for either share or system installs).

command

The command name for tools where the name my differ from platform to platform. For example, the GNU version of make is usually "make" in Linux and "gmake" on FreeBSD. This is typically set by a plugin in the gather stage (for either share or system installs).

ffi_name

The name DLL or shared object "name" to use when searching for dynamic libraries at runtime. This is passed into FFI::CheckLib, so if your library is something like "libarchive.so" or "archive.dll" you would set this to "archive". This may be a string or an array of strings. This is typically set by a plugin in the gather stage (for either share or system installs).

ffi_checklib

This property contains two sub properties:

inline_auto_include

[version 2.53]

This property is an array reference of C code that will be passed into Inline::C to make sure that appropriate headers are automatically included. See "auto_include" in Inline::C for details.

install_type

The install type. This is set by AB core after the probe hook is executed. Is one of:

libs

The library flags. This is typically set by a plugin in the gather stage (for either share or system installs).

libs_static

The static library flags. This is typically set by a plugin in the gather stage (for either share or system installs).

perl_module_version

The version of the Perl module used to install the alien (if available). For example if Alien::curl is installing "libcurl" this would be the version of Alien::curl used during the install step.

prefix

The final install root. This is usually they share directory.

version

The version of the library or tool. This is typically set by a plugin in the gather stage (for either share or system installs).

hook_prop

my $href = $build->hook_prop;

Hook properties are for the currently running (if any) hook. They are used only during the execution of each hook and are discarded after. If no hook is currently running then "hook_prop" will return "undef".

name

The name of the currently running hook.

version (probe)

Probe and PkgConfig plugins may set this property indicating the version of the alienized package. Not all plugins and configurations may be able to provide this.

probe_class (probe)

Probe and PkgConfig plugins may set this property indicating the plugin class that made the probe. If the probe results in a system install this will be propagated to "system_probe_class" for later use.

probe_instance_id (probe)

Probe and PkgConfig plugins may set this property indicating the plugin instance id that made the probe. If the probe results in a system install this will be propagated to "system_probe_instance_id" for later use.

checkpoint

$build->checkpoint;

Save any install or runtime properties so that they can be reloaded on a subsequent run in a separate process. This is useful if your build needs to be done in multiple stages from a "Makefile", such as with ExtUtils::MakeMaker. Once checkpointed you can use the "resume" constructor (documented above) to resume the probe/build/install] process.

root

my $dir = $build->root;

This is just a shortcut for:

my $root = $build->install_prop->{root};

Except that it will be created if it does not already exist.

install_type

my $type = $build->install_type;

This will return the install type. (See the like named install property above for details). This method will call "probe" if it has not already been called.

download_rule

my $rule = $build->download_rule;

This returns install rule as a string. This is determined by the environment and should be one of:

"warn"

Warn only if fetching via non secure source (secure sources include "https", and bundled files, may include other encrypted protocols in the future).

"digest"

Require that any downloaded source package have a cryptographic signature in the alienfile and that signature matches what was downloaded.

"encrypt"

Require that any downloaded source package is fetched via secure source.

"digest_or_encrypt"

Require that any downloaded source package is either fetched via a secure source or has a cryptographic signature in the alienfile and that signature matches what was downloaded.

"digest_and_encrypt"

Require that any downloaded source package is both fetched via a secure source and has a cryptographic signature in the alienfile and that signature matches what was downloaded.

The current default is "warn", but in the near future this will be upgraded to "digest_or_encrypt".

set_prefix

$build->set_prefix($prefix);

Set the final (unstaged) prefix. This is normally only called by Alien::Build::MM and similar modules. It is not intended for use from plugins or from an alienfile.

set_stage

$build->set_stage($dir);

Sets the stage directory. This is normally only called by Alien::Build::MM and similar modules. It is not intended for use from plugins or from an alienfile.

requires

my $hash = $build->requires($phase);

Returns a hash reference of the modules required for the given phase. Phases include:

configure

These modules must already be available when the alienfile is read.

any

These modules are used during either a "system" or "share" install.

share

These modules are used during the build phase of a "share" install.

system

These modules are used during the build phase of a "system" install.

load_requires

$build->load_requires($phase);

This loads the appropriate modules for the given phase (see "requires" above for a description of the phases).

probe

my $install_type = $build->probe;

Attempts to determine if the operating system has the library or tool already installed. If so, then the string "system" will be returned and a system install will be performed. If not, then the string "share" will be installed and the tool or library will be downloaded and built from source.

If the environment variable "ALIEN_INSTALL_TYPE" is set, then that will force a specific type of install. If the detection logic cannot accommodate the install type requested then it will fail with an exception.

download

$build->download;

Download the source, usually as a tarball, usually from the internet.

Under a "system" install this does not do anything.

fetch

my $res = $build->fetch;
my $res = $build->fetch($url, %options);

Fetch a resource using the fetch hook. Returns the same hash structure described below in the fetch hook documentation.

[version 2.39]

As of Alien::Build 2.39, these options are supported:

http_headers

my $res = $build->fetch($url, http_headers => [ $key1 => $value1, $key2 => $value 2, ... ]);

Set the HTTP request headers on all outgoing HTTP requests. Note that not all protocols or fetch plugins support setting request headers, but the ones that do not should issue a warning if you try to set request headers and they are not supported.

check_digest

[experimental]

my $bool = $build->check_digest($path);

Checks any cryptographic signatures for the given file. The file is specified by $path which may be one of:

string

Containing the path to the file to be checked.

Path::Tiny

Containing the path to the file to be checked.

"HASH"

A Hash reference containing information about a file. See the fetch hook for details on the format.

Returns true if the cryptographic signature matches, false if cryptographic signatures are disabled. Will throw an exception if the signature does not match, or if no plugin provides the correct algorithm for checking the signature.

decode

my $decoded_res = $build->decode($res);

Decode the HTML or file listing returned by "fetch". Returns the same hash structure described below in the decode hook documentation.

prefer

my $sorted_res = $build->prefer($res);

Filter and sort candidates. The preferred candidate will be returned first in the list. The worst candidate will be returned last. Returns the same hash structure described below in the prefer hook documentation.

extract

my $dir = $build->extract;
my $dir = $build->extract($archive);

Extracts the given archive into a fresh directory. This is normally called internally to Alien::Build, and for normal usage is not needed from a plugin or alienfile.

build

$build->build;

Run the build step. It is expected that "probe" and "download" have already been performed. What it actually does depends on the type of install:

share

The source is extracted, and built as determined by the alienfile recipe. If there is a "gather_share" that will be executed last.

system

The gather_system hook will be executed.

test

$build->test;

Run the test phase

clean_install

$build->clean_install

Clean files from the final install location. The default implementation removes all files recursively except for the "_alien" directory. This is helpful when you have an old install with files that may break the new build.

For a non-share install this doesn't do anything.

system

$build->system($command);
$build->system($command, @args);

Interpolates the command and arguments and run the results using the Perl "system" command.

log

$build->log($message);

Send a message to the log. By default this prints to "STDOUT".

meta

my $meta = Alien::Build->meta;
my $meta = $build->meta;

Returns the meta object for your Alien::Build class or instance. The meta object is a way to manipulate the recipe, and so any changes to the meta object should be made before the "probe", "download" or "build" steps.

prop

my $href = $build->meta->prop;

Meta properties. This is the same as calling "meta_prop" on the class or Alien::Build instance.

add_requires

Alien::Build->meta->add_requires($phase, $module => $version, ...);

Add the requirement to the given phase. Phase should be one of:

configure

any

share

system

interpolator

my $interpolator = $build->meta->interpolator;
my $interpolator = Alien::Build->interpolator;

Returns the Alien::Build::Interpolate instance for the Alien::Build class.

has_hook

my $bool = $build->meta->has_hook($name);
my $bool = Alien::Build->has_hook($name);

Returns if there is a usable hook registered with the given name.

register_hook

$build->meta->register_hook($name, $instructions);
Alien::Build->meta->register_hook($name, $instructions);

Register a hook with the given name. $instruction should be either a code reference, or a command sequence, which is an array reference.

default_hook

$build->meta->default_hook($name, $instructions);
Alien::Build->meta->default_hook($name, $instructions);

Register a default hook, which will be used if the alienfile does not register its own hook with that name.

around_hook

$build->meta->around_hook($hook_name, $code);
Alien::Build->meta->around_hook($hook_name, $code);

Wrap the given hook with a code reference. This is similar to a Moose method modifier, except that it wraps around the given hook instead of a method. For example, this will add a probe system requirement:

$build->meta->around_hook(
  probe => sub {
    my $orig = shift;
    my $build = shift;
    my $type = $orig->($build, @_);
    return $type unless $type eq 'system';
    # also require a configuration file
    if(-f '/etc/foo.conf')
    {
      return 'system';
    }
    else
    {
      return 'share';
    }
  },
);

after_hook

$build->meta->after_hook($hook_name, sub {
  my(@args) = @_;
  ...
});

Execute the given code reference after the hook. The original arguments are passed into the code reference.

before_hook

$build->meta->before_hook($hook_name, sub {
  my(@args) = @_;
  ...
});

Execute the given code reference before the hook. The original arguments are passed into the code reference.

apply_plugin

Alien::Build->meta->apply_plugin($name);
Alien::Build->meta->apply_plugin($name, @args);

Apply the given plugin with the given arguments.