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