view release on metacpan or  search on metacpan

lib/Alien/Build/Manual/PluginAuthor.pod  view on Meta::CPAN

logic removed:

 sub init
 {
   my($self, $meta) = @_;
   $meta->register_hook(
     probe => sub {
       my($build) = @_;
       if( ... )
       {
         return 'system';
       }
       else
       {
         return 'share';
       }
     },
   );
 }

Hooks get the L<Alien::Build> instance as their first argument, and depending
on the hook may get additional arguments.

=head2 Modifying hooks

You can also modify hooks using C<before_hook>, C<around_hook> and C<after_hook>,
similar to L<Moose> modifiers:

 sub init
 {
   my($self, $meta) = @_;
 
   $meta->before_hook(
     build => sub {
       my($build) = @_;
       $build->log('this runs before the build');
     },
   );
 
   $meta->after_hook(
     build => sub {
       my($build) = @_;
       $build->log('this runs after the build');
     },
   );
 
   $meta->around_hook(
     build => sub {
       my $orig = shift;
 
       # around hooks are useful for setting environment variables
       local $ENV{CPPFLAGS} = '-I/foo/include';
 
       $orig->(@_);
     },
   );
 }

=head2 Testing plugins

You can and should write tests for your plugin.  The best way to do
this is using L<Test::Alien::Build>, which allows you to write an
inline L<alienfile> in your test.  Here is an example:

 use Test::V0;
 use Test::Alien::Build;
 
 my $build = alienfile_ok q{
   use alienfile;
   plugin 'Build::MyPlugin' => (
     arg1 => 'override for arg1',
     arg2 => [ 'something', 'else' ],
   );
   ...
 };
 
 # 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}>).

lib/Alien/Build/Manual/PluginAuthor.pod  view on Meta::CPAN

 $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} || '';
 });

This allows you to alter the override logic.  It should return one of
C<share>, C<system>, C<default> or C<''>.  The default implementation
is shown above.  L<Alien::Build::Plugin::Probe::Override> and
L<Alien::Build::Plugin::Probe::OverrideCI> are examples of how you
can use this hook.

=head2 patch hook

 $meta->register_hook( patch => sub {
   my($build) = @_;
   ...
 });

This hook is completely optional.  If registered, it will be triggered after
extraction and before build.  It allows you to apply any patches or make any
modifications to the source if they are necessary.

=head2 patch_ffi hook

 $meta->register_hook( patch_ffi => sub {
   my($build) = @_;
   ...
 });

This hook is exactly like the L<patch hook|/"patch hook">, except it fires only on an
FFI build.

=head2 prefer hook

 $meta->register_hook( prefer => sub {
   my($build, $res) = @_;
   return {
     type => 'list',
     list => [sort @{ $res->{list} }],
   };
 }

This hook sorts candidates from a listing generated from either the C<fetch>
or C<decode> hooks.  It should return a new list hash reference with the
candidates sorted from best to worst.  It may also remove candidates
that are totally unacceptable.

=head2 probe hook

 $meta->register_hook( probe => sub {
   my($build) = @_;
   return 'system' if ...; # system install
   return 'share';         # otherwise
 });
 
 $meta->register_hook( probe => [ $command ] );

This hook should return the string C<system> if the operating
system provides the library or tool.  It should return C<share>
otherwise.

You can also use a command that returns true when the tool
or library is available.  For example for use with C<pkg-config>:

 $meta->register_hook( probe =>
   [ '%{pkgconf} --exists libfoo' ] );

Or if you needed a minimum version:

 $meta->register_hook( probe =>
   [ '%{pkgconf} --atleast-version=1.00 libfoo' ] );

Note that this hook SHOULD NOT gather system properties, such as
cflags, libs, versions, etc, because the probe hook will be skipped
in the event the environment variable C<ALIEN_INSTALL_TYPE> is set.
The detection of these properties should instead be done by the
L<gather_system|/"gather_system hook"> hook.

Multiple probe hooks can be given.  These will be used in sequence,
stopping at the first that detects a system installation.

=head1 SEE ALSO

=over 4

=item L<Alien::Build::Manual>

Other L<Alien::Build> manuals.

=back

=head1 AUTHOR

Author: Graham Ollis E<lt>plicease@cpan.orgE<gt>

Contributors:

Diab Jerius (DJERIUS)

Roy Storey (KIWIROY)

Ilya Pavlov

David Mertens (run4flat)