NAME

Alien::Build - Build external dependencies for use in CPAN

VERSION

version 0.49

SYNOPSIS

my $build = Alien::Build->load('./alienfile');
$build->load_requires('configure');
$build->set_prefix('/usr/local');
$build->set_stage('/foo/mystage');  # needs to be absolute
$build->load_requires($build->install_type);
$build->download;
$build->build;
# files are now in /foo/mystage, it is your job (or
# ExtUtils::MakeMaker, Module::Build, etc) to copy
# those files into /usr/local

DESCRIPTION

This module provides tools for building external (non-CPAN) dependencies for CPAN. It is mainly designed to be used at install time of a CPAN client, and work closely with Alien::Base which is used at runtime.

This is the detailed documentation for Alien::Build class. If you are starting out as a user of an Alien::Build based Alien module, see Alien::Build::Manual::AlienUser. If you are starting out writing a new Alien::Build based Alien module, see Alien::Build::Manual::AlienAuthor. As an Alien author, you will also likely be interested in Alien::Build::Manual::FAQ. If you are interested in writing a Alien::Build plugin, see Alien::Build::Manual::PluginAuthor.

Note that you will usually not usually create a Alien::Build instance directly, but rather be using a thin installer layer, such as Alien::Build::MM (for use with ExtUtils::MakeMaker). One of the goals of this project is to remain installer agnostic.

CONSTRUCTOR

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.

PROPERTIES

There are three main properties for Alien::Build. There are a number of properties documented here with a specific usage. Note that these properties may need to be serialized into something primitive like JSON that does not support: regular expressions, code references of blessed objects.

If you are writing a plugin (Alien::Build::Plugin) you should use a prefix like "plugin_name" (where name is the name of your plugin) so that it does not interfere with other plugin or future versions of Alien::Build. For example, if you were writing Alien::Build::Plugin::Fetch::NewProtocol, please use the prefix plugin_fetch_newprotocol:

sub init
{
  my($self, $meta) = @_;
  
  $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
  
  $meta->register_hook(
    some_hook => sub {
      my($build) = @_;
      $build->install_prop->{plugin_fetch_newprotocol_bar => 'some other value' );
      $build->runtime_prop->{plugin_fetch_newprotocol_baz => 'and another value' );
    }
  );
}

If you are writing a alienfile recipe please use the prefix my_:

use alienfile;

meta_prop->{my_foo} = 'some value';

probe sub {
  my($build) = @_;
  $build->install_prop->{my_bar} = 'some other value';
  $build->install_prop->{my_baz} = 'and another value';
};

Any property may be used from a command:

probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
probe [ 'some command %{.meta.my_foo}' ];
probe [ 'some command %{.install.my_bar}' ];
probe [ 'some command %{.runtime.my_baz}' ];

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.

destdir

Use the DESTDIR environment variable to stage your install before copying the files into blib. This is the preferred method of installing libraries because it improves reliability. This technique is supported by autoconf and others.

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.

env

Environment variables to override during the build stage.

platform

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

compiler_type

Refers to the type of flags that the compiler accepts. May be expanded in the future, but for now, will be one of:

microsoft: On Windows when using Microsoft Visual C++
unix: Virtually everything else, including gcc on windows.

The main difference is that with Visual C++ -LIBPATH should be used instead of -L, and static libraries should have the .LIB suffix instead of .a.

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::Autoconf in your alienfile.

env

Environment variables to override during the build stage.

old

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.

prefix: The prefix for the previous install.
runtime: The runtime properties from the previous install.

patch

Directory with patches.

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.

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.

cflags

The compiler flags

cflags_static

The static compiler flags

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.

install_type

The install type. Is one of:

system: For when the library or tool is provided by the operating system, can be detected by Alien::Build, and is considered satisfactory by the alienfile recipe.
share: For when a system install is not possible, the library source will be downloaded from the internet or retrieved in another appropriate fashion and built.

libs

The library flags

libs_static

The static library flags

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

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.

METHODS

load

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

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

checkpoint

$build->checkpoint;

Save any install or runtime properties so that they can be reloaded on a subsequent run. This is useful if your build needs to be done in multiple stages from a Makefile, such as with ExtUtils::MakeMaker.

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

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.

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);

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

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

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 METHODS

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);

around_hook

$build->meta->around_hook($hook, $code);
Alien::Build->meta->around_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';
    }
  },
);

ENVIRONMENT

Alien::Build responds to these environment variables:

ALIEN_INSTALL_TYPE: If set to share or system, it will override the system detection logic.
ALIEN_BUILD_PRELOAD: semicolon separated list of plugins to automatically load before parsing your alienfile.
ALIEN_BUILD_PRELOAD: semicolon separated list of plugins to automatically load after parsing your alienfile.
DESTDIR: This environment variable will be manipulated during a destdir install.
PKG_CONFIG: This environment variable can be used to override the program name for pkg-config for some PkgConfig plugins: Alien::Build::Plugin::PkgConfig.
ftp_proxy, all_proxy: If these environment variables are set, it may influence the Download negotiation plugin Alien::Build::Plugin::Downaload::Negotiate. Other proxy variables may be used by some Fetch plugins, if they support it.

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Diab Jerius (DJERIUS)

Roy Storey

COPYRIGHT AND LICENSE

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

To install Alien::Build, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Alien::Build

CPAN shell

perl -MCPAN -e shell
install Alien::Build

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)