search

PerlAlien / Alien-Build

Build external dependencies for use in CPAN
16 stars 25 forks source link
alien cpan perl

readme

Alien::Build static linux macos windows msys2-mingw

Build external dependencies for use in CPAN

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 the Alien::Build class. If you are starting out you probably want to do so from one of these documents:

Note that you will 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) or Alien::Build::MB (for use with Module::Build). One of the goals of this project is to remain installer agnostic.

CONSTRUCTORS

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.

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.

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.

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.

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.

METHODS

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:

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:

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:

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:

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:

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.

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:

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.

ENVIRONMENT

Alien::Build responds to these environment variables:

SUPPORT

The intent of the Alien-Build team is to support the same versions of Perl that are supported by the Perl toolchain. As of this writing that means 5.16 and better.

Please feel encouraged to report issues that you encounter to the project GitHub Issue tracker:

Better if you can fix the issue yourself, please feel encouraged to open pull-request on the project GitHub:

If you are confounded and have questions, join us on the #native channel on irc.perl.org. The Alien-Build developers frequent this channel and can probably help point you in the right direction. If you don't have an IRC client handy, you can use this web interface:

SEE ALSO

Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser, Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ, Alien::Build::Manual::PluginAuthor

alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien

THANKS

Alien::Base was originally written by Joel Berger, the rest of this project would not have been possible without him getting the project started. Thanks to his support I have been able to augment the original Alien::Base system with a reliable set of tools (Alien::Build, alienfile, Test::Alien), which make up this toolset.

The original Alien::Base is still copyright (c) 2012-2020 Joel Berger. It has the same license as the rest of the Alien::Build and related tools distributed as Alien-Build. Joel Berger thanked a number of people who helped in in the development of Alien::Base, in the documentation for that module.

I would also like to acknowledge the other members of the PerlAlien github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk (ETJ). Also important in the early development of Alien::Build were the early adopters Chase Whitener (genio, CAPOEIRAB, author of Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF, author of Alien::libudev and Alien::LibUSB).

The Alien ecosystem owes a debt to Dan Book, who goes by Grinnz on IRC, for answering question about how to use Alien::Build and friends.

AUTHOR

Author: Graham Ollis plicease@cpan.org

Contributors:

Diab Jerius (DJERIUS)

Roy Storey (KIWIROY)

Ilya Pavlov

David Mertens (run4flat)

Mark Nunberg (mordy, mnunberg)

Christian Walde (Mithaldu)

Brian Wightman (MidLifeXis)

Zaki Mughal (zmughal)

mohawk (mohawk2, ETJ)

Vikas N Kumar (vikasnkumar)

Flavio Poletti (polettix)

Salvador Fandiño (salva)

Gianni Ceccarelli (dakkar)

Pavel Shaydo (zwon, trinitum)

Kang-min Liu (劉康民, gugod)

Nicholas Shipp (nshp)

Juan Julián Merelo Guervós (JJ)

Joel Berger (JBERGER)

Petr Písař (ppisar)

Lance Wicks (LANCEW)

Ahmad Fatoum (a3f, ATHREEF)

José Joaquín Atria (JJATRIA)

Duke Leto (LETO)

Shoichi Kaji (SKAJI)

Shawn Laffan (SLAFFAN)

Paul Evans (leonerd, PEVANS)

Håkon Hægland (hakonhagland, HAKONH)

nick nauwelaerts (INPHOBIA)

Florian Weimer

COPYRIGHT AND LICENSE

This software is copyright (c) 2011-2022 by Graham Ollis.

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