Alien-Build
view release on metacpan or search on metacpan
lib/Alien/Build/Manual/PluginAuthor.pod view on Meta::CPAN
# PODNAME: Alien::Build::Manual::PluginAuthor
# ABSTRACT: Alien::Build plugin author documentation
# VERSION
__END__
=pod
=encoding UTF-8
=head1 NAME
Alien::Build::Manual::PluginAuthor - Alien::Build plugin author documentation
=head1 VERSION
version 2.84
=head1 SYNOPSIS
your plugin:
package Alien::Build::Plugin::Build::MyPlugin;
use strict;
use warnings;
use Alien::Build::Plugin;
has arg1 => 'default_for arg1';
has arg2 => sub { [ 'default', 'for', 'arg2' ] };
sub init
{
my($self, $meta) = @_;
...
}
1;
and then from L<alienfile>:
use alienfile;
plugin 'Build::MyPlugin' => (
arg1 => 'override for arg1',
arg2 => [ 'something', 'else' ],
);
=for html <p>flowchart</p>
<div style="display: flex"><div style="margin: 3px; flex: 1 1 50%">
<img src="image/PluginAuthor-flowchart.png" style="max-width: 100%">
</div></div>
<p><b>Notes</b>: The colored blocks indicate <tt>alienfile</tt> blocks.
Hooks are indicated as predefined process (rectangle with double struck
vertical edges). Hooks that can easily be implemented from an
<tt>alienfile</tt> are indicated in blue (Note that <tt>[]</tt> is used
to indicate passing in an array reference, but a subroutine
reference can also be used). For simplicity, the the flowchart does
not include when required modules are loaded. Except for configure
time requirements, they are loaded when the corresponding <tt>alienfile</tt>
blocks are entered. It is not shown, but generally any plugin can cause
a <b>Fail</b> by throwing an exception with <tt>die</tt>.</p>
Perlish pseudo code for how plugins are called:
my $probe;
my $override = override();
if($override eq 'system') {
$probe = probe();
if($probe ne 'system') {
die 'system tool or library not found';
}
}
elsif($override eq 'default') {
$probe = probe();
} else { # $override eq 'share'
# note that in this instance the
# probe hook is never called
$probe = 'share';
}
if($probe eq 'system') {
gather_system();
} else { # $probe eq 'share'
download();
extract();
patch();
build();
gather_share();
# Check to see if there isa build_ffi hook
if(defined &build_ffi) {
patch_ffi();
build_ffi();
gather_ffi();
}
}
# By default this just returns the value of $ENV{ALIEN_INSTALL_TYPE}
sub override {
return $ENV{ALIEN_INSTALL_TYPE};
}
# Default download implementation; can be
# replaced by specifying a different download
# hook. See Alien::Build::Plugin::Core::Download
lib/Alien/Build/Manual/PluginAuthor.pod view on Meta::CPAN
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
true value.
=head2 clean_install
$meta->register_hook( clean_install => sub {
my($build) = @_;
});
This hook allows you to remove files from the final install location before
the files are installed by the installer layer (examples: L<Alien::Build::MM>,
L<Alien::Build::MB> or L<App::af>). This hook is not called by default,
and must be enabled via the interface to the installer layer
(example: L<Alien::Build::MM/clean_install>).
This hook SHOULD NOT remove the C<_alien> directory or its content from the
install location.
The default implementation removes all the files EXCEPT the C<_alien> directory
and its content.
=head2 download hook
$meta->register_hook( download => sub {
my($build) = @_;
...
});
This hook is used to download from the internet the source. Either as
an archive (like tar, zip, etc), or as a directory of files (C<git clone>,
etc). When the hook is called, the current working directory will be a
new empty directory, so you can save the download to the current
directory. If you store a single file in the directory, L<Alien::Build>
will assume that it is an archive, which will be processed by the
L<extract hook|/"extract hook">. If you store multiple files, L<Alien::Build> will
assume the current directory is the source root. If no files are stored
at all, an exception with an appropriate diagnostic will be thrown.
B<Note>: If you register this hook, then the fetch, decode and prefer
hooks will NOT be called, unless you call them yourself from this hook.
=head2 extract hook
$meta->register_hook( extract => sub {
my($build, $archive) = @_;
...
});
This hook is used to extract an archive that has already been downloaded.
L<Alien::Build> already has plugins for the most common archive formats,
so you will likely only need this to add support for new or novel archive
formats. When this hook is called, the current working directory will
be a new empty directory, so you can save the content of the archive to
the current directory. If a single directory is written to the current
directory, L<Alien::Build> will assume that is the root directory of the
package. If multiple files and/or directories are present, that will
indicate that the current working directory is the root of the package.
The logic typically handles correctly the default behavior for tar
(where packages are typically extracted to a subdirectory) and for
zip (where packages are typically extracted to the current directory).
=head2 fetch hook
package Alien::Build::Plugin::MyPlugin;
use strict;
use warnings;
use Alien::Build::Plugin;
use Carp ();
has '+url' => sub { Carp::croak "url is required property" };
sub init
{
my($self, $meta) = @_;
$meta->register_hook( fetch => sub {
my($build, $url, %options) = @_;
...
}
}
1;
Used to fetch a resource. The first time it will be called without an
argument (or with C<$url> set to C<undef>, so the configuration used to
find the resource should be specified by the plugin's properties. On
subsequent calls the first argument will be a URL.
The C<%options> hash may contain these options:
=over 4
=item http_headers
( run in 0.858 second using v1.01-cache-2.11-cpan-3d66aa2751a )