Alien-Build
view release on metacpan or search on metacpan
lib/Alien/Build/Manual/PluginAuthor.pod view on Meta::CPAN
);
...
};
# you can interrogate $build, it is an instance of L<Alien::Build>.
my $alien = alien_build_ok;
# you can interrogate $alien, it is an instance of L<Alien::Base>.
=head2 Negotiator plugins
A Negotiator plugin doesn't itself typically implement anything on
its own, but picks the best plugin to achieve a particular goal.
The "best" plugin can in some cases vary depending on the platform
or tools that are available. For example The
L<download negotiator|Alien::Build::Plugin::Download::Negotiate>
might choose to use the fetch plugin that relies on the command line
C<curl>, or it might choose the fetch plugin that relies on the Perl
module L<HTTP::Tiny> depending on the platform and what is already
installed. (For either to be useful they have to support SSL).
The Negotiator plugin is by convention named something like
C<Alien::Build::Plugin::*::Negotiate>, but is typically invoked
without the C<::Negotiate> suffix. For example:
plugin 'Download'; # is short for Alien::Build::Plugin::Download::Negotiator
Here is a simple example of a negotiator which picks C<curl> if already
installed and L<HTTP::Tiny> otherwise. (The actual download plugin
is a lot smarter and complicated than this, but this is a good
simplified example).
package Alien::Build::Plugin::Download::Negotiate;
use strict;
use warnings;
use Alien::Build::Plugin;
use File::Which qw( which );
sub init
{
my($self, $meta) = @_;
if(which('curl')) {
$meta->apply_plugin('Fetch::Curl');
} else {
$meta->apply_plugin('Fetch::HTTPTiny');
}
}
=head2 Hooks
The remainder of this document is a reference for the hooks that you
can register. Generally speaking you can register any hook that you
like, but some care must be taken as some hooks have default behavior
that will be overridden when you register a hook. The hooks are
presented in alphabetical order. The execution order is shown
in the flowchart above (if you are browsing the HTML version of this
document), or the Perlish pseudo code in the synopsis section.
=head1 HOOKS
=head2 build hook
$meta->register_hook( build => sub {
my($build) = @_;
...
});
This does the main build of the alienized project and installs it into
the staging area. The current directory is the build root. You need
to run whatever tools are necessary for the project, and install them
into C<$build->install_prop->{prefix}> (C<%{.install.prefix}>).
=head2 build_ffi hook
$meta->register_hook( build_ffi => sub {
my($build) = @_;
...
});
This is the same as L<build|/"build hook">, except it fires only on a FFI build.
=head2 decode hook
$meta->register_hook( decode => sub {
my($build, $res) = @_;
...
}
This hook takes a response hash reference from the C<fetch> hook above
with a type of C<html> or C<dir_listing> and converts it into a response
hash reference of type C<list>. In short it takes an HTML or FTP file
listing response from a fetch hook and converts it into a list of filenames
and links that can be used by the prefer hook to choose the correct file to
download. See the L<fetch hook|/"fetch hook"> for the specification of the
input and response hash references.
=head2 check_digest hook
# implement the well known FOO-92 digest
$meta->register_hook( check_digest => sub {
my($build, $file, $algorithm, $digest) = @_;
if($algorithm ne 'FOO92') {
return 0;
}
my $actual = foo92_hex_digest($file);
if($actual eq $digest) {
return 1;
} else {
die "Digest FOO92 does not match: got $actual, expected $digest";
}
});
This hook should check the given C<$file> (the format is the same as used by
L<the fetch hook|/"fetch hook">) matches the given C<$digest> using the
given C<$algorithm>. If the plugin does not support the given algorithm,
then it should return a false value. If the digest does not match, it
should throw an exception. If the digest matches, it should return a
lib/Alien/Build/Manual/PluginAuthor.pod view on Meta::CPAN
return {
type => 'file',
filename => $filename,
path => $path, # full file system path to file
version => $version, # optional, if known
tmp => $tmp, # optional
protocol => $protocol, # AB 2.60 optional, but recommended
};
C<$tmp> if set will indicate if the file is temporary or not, and can
be used by L<Alien::Build> to save a copy in some cases. The default
is true, so L<Alien::Build> assumes the file or directory is temporary
if you don't tell it otherwise. Probably the most common situation
when you would set C<tmp> to false, is when the file is bundled inside
the L<Alien> distribution. See L<Alien::Build::Plugin::Fetch::Local>
for example.
If the URL points to a directory listing you should return it as either
a hash reference containing a list of files:
return {
type => 'list',
list => [
# filename: each filename should be just the
# filename portion, no path or url.
# url: each url should be the complete url
# needed to fetch the file.
# version: OPTIONAL, may be provided by some fetch or prefer
{ filename => $filename1, url => $url1, version => $version1 },
{ filename => $filename2, url => $url2, version => $version2 },
],
protocol => $protocol, # AB 2.60 optional, but recommended
};
or if the listing is in HTML format as a hash reference containing the
HTML information:
return {
type => 'html',
charset => $charset, # optional
base => $base, # the base URL: used for computing relative URLs
content => $content, # the HTML content
protocol => $protocol, # optional, but recommended
};
or a directory listing (usually produced by an FTP servers) as a hash
reference:
return {
type => 'dir_listing',
base => $base,
content => $content,
protocol => $protocol, # AB 2.60 optional, but recommended
};
[version 2.60]
For all of these responses C<$protocol> is optional, since it was not part
of the original spec, however it is strongly recommended that you include
this field, because future versions of L<Alien::Build> will use this to
determine if a file was downloaded securely (that is via a secure protocol
such as SSL).
Some plugins (like L<decode plugins |Alien::Build::Plugin::Decode>) trans
late a file hash from one type to another, they should maintain the
C<$protocol> from the old to the new representation of the file.
=head2 gather_ffi hook
$meta->register_hook( gather_ffi => sub {
my($build) = @_;
$build->runtime_prop->{cflags} = ...;
$build->runtime_prop->{libs} = ...;
$build->runtime_prop->{version} = ...;
});
This hook is called for a FFI build to determine the properties
necessary for using the library or tool. These properties should be
stored in the L<runtime_prop|Alien::Build/runtime_prop> hash as shown above.
Typical properties that are needed for libraries are cflags and libs.
If at all possible you should also try to determine the version of the
library or tool.
=head2 gather_share hook
$meta->register_hook( gather_share => sub {
my($build) = @_;
$build->runtime_prop->{cflags} = ...;
$build->runtime_prop->{libs} = ...;
$build->runtime_prop->{version} = ...;
});
This hook is called for a share install to determine the properties
necessary for using the library or tool. These properties should be
stored in the L<runtime_prop|Alien::Build/runtime_prop> hash as shown above.
Typical properties that are needed for libraries are cflags and libs.
If at all possible you should also try to determine the version of the
library or tool.
=head2 gather_system hook
$meta->register_hook( gather_system => sub {
my($build) = @_;
$build->runtime_prop->{cflags} = ...;
$build->runtime_prop->{libs} = ...;
$build->runtime_prop->{version} = ...;
});
This hook is called for a system install to determine the properties
necessary for using the library or tool. These properties should be
stored in the L<runtime_prop|Alien::Build/runtime_prop> hash as shown above.
Typical properties that are needed for libraries are cflags and libs.
If at all possible you should also try to determine the version of the
library or tool.
=head2 override hook
$meta->register_hook( override => sub {
my($build) = @_;
return $ENV{ALIEN_INSTALL_TYPE} || '';
});
( run in 0.691 second using v1.01-cache-2.11-cpan-39bf76dae61 )