1Alien::Build::Manual::PUlsuegrinCAountthroirb(u3t)ed PerAlliDeonc:u:mBeunitladt:i:oMnanual::PluginAuthor(3)
2
3
4

NAME

6       Alien::Build::Manual::PluginAuthor - Alien::Build plugin author
7       documentation
8

VERSION

10       version 2.40
11

SYNOPSIS

13       your plugin:
14
15        package Alien::Build::Plugin::Build::MyPlugin;
16
17        use strict;
18        use warnings;
19        use Alien::Build::Plugin;
20
21        has arg1 => 'default_for arg1';
22        has arg2 => sub { [ 'default', 'for', 'arg2' ] };
23
24        sub init
25        {
26          my($self, $meta) = @_;
27          ...
28        }
29
30        1;
31
32       and then from alienfile:
33
34        use alienfile;
35        plugin 'Build::MyPlugin' => (
36          arg1 => 'override for arg1',
37          arg2 => [ 'something', 'else' ],
38        );
39

DESCRIPTION

41       This document explains how to write Alien::Build plugins using the
42       Alien::Build::Plugin base class.  Plugins use Alien::Build::Plugin,
43       which sets the appropriate base class, and provides you with the "has"
44       property builder.  "has" takes two arguments, the name of the property
45       and the default value.  (As with Moose and Moo, you should use a code
46       reference to specify default values for non-string defaults).
47
48       The only method that you need to implement is "init".  From this method
49       you can add hooks to change the behavior of the alienfile recipe.
50
51        sub init
52        {
53          my($self, $meta) = @_;
54          $meta->register_hook(
55            probe => sub {
56              my($build) = @_;
57              if( ... )
58              {
59                return 'system';
60              }
61              else
62              {
63                return 'share';
64              }
65            },
66          );
67        }
68
69       Hooks get the Alien::Build instance as their first argument, and
70       depending on the hook may get additional arguments.
71
72       You can also modify hooks using "before_hook", "around_hook" and
73       "after_hook":
74
75        sub init
76        {
77          my($self, $meta) = @_;
78
79          $meta->before_hook(
80            build => sub {
81              my($build) = @_;
82              $build->log('this runs before the build');
83            },
84          );
85
86          $meta->after_hook(
87            build => sub {
88              my($build) = @_;
89              $build->log('this runs after the build');
90            },
91          );
92
93          $meta->around_hook(
94            build => sub {
95              my $orig = shift;
96
97              # around hooks are useful for setting environment variables
98              local $ENV{CPPFLAGS} = '-I/foo/include';
99
100              $orig->(@_);
101            },
102          );
103        }
104
105       You can and should write tests for your plugin.  The best way to do
106       this is using Test::Alien::Build, which allows you to write an inline
107       alienfile in your test.
108
109        use Test::V0;
110        use Test::Alien::Build;
111
112        my $build = alienfile_ok q{
113          use alienfile;
114          plugin 'Build::MyPlugin' => (
115            arg1 => 'override for arg1',
116            arg2 => [ 'something', 'else' ],
117          );
118          ...
119        };
120
121        # you can interrogate $build, it is an instance of L<Alien::Build>.
122
123        my $alien = alien_build_ok;
124
125        # you can interrogate $alien, it is an instance of L<Alien::Base>.
126

HOOKS

128   probe hook
129        $meta->register_hook( probe => sub {
130          my($build) = @_;
131          return 'system' if ...; # system install
132          return 'share';         # otherwise
133        });
134
135        $meta->register_hook( probe => [ $command ] );
136
137       This hook should return the string "system" if the operating system
138       provides the library or tool.  It should return "share" otherwise.
139
140       You can also use a command that returns true when the tool or library
141       is available.  For example for use with "pkg-config":
142
143        $meta->register_hook( probe =>
144          [ '%{pkgconf} --exists libfoo' ] );
145
146       Or if you needed a minimum version:
147
148        $meta->register_hook( probe =>
149          [ '%{pkgconf} --atleast-version=1.00 libfoo' ] );
150
151       Note that this hook SHOULD NOT gather system properties, such as
152       cflags, libs, versions, etc, because the probe hook will be skipped in
153       the event the environment variable "ALIEN_INSTALL_TYPE" is set.  The
154       detection of these properties should instead be done by the
155       "gather_system" hook, below.
156
157   gather_system hook
158        $meta->register_hook( gather_system => sub {
159          my($build) = @_;
160          $build->runtime_prop->{cflags}  = ...;
161          $build->runtime_prop->{libs}    = ...;
162          $build->runtime_prop->{version} = ...;
163        });
164
165       This hook is called for a system install to determine the properties
166       necessary for using the library or tool.  These properties should be
167       stored in the "runtime_prop" hash as shown above.  Typical properties
168       that are needed for libraries are cflags and libs.  If at all possible
169       you should also try to determine the version of the library or tool.
170
171   download hook
172        $meta->register_hook( download => sub {
173          my($build) = @_;
174          ...
175        });
176
177       This hook is used to download from the internet the source.  Either as
178       an archive (like tar, zip, etc), or as a directory of files (git clone,
179       etc).  When the hook is called, the current working directory will be a
180       new empty directory, so you can save the download to the current
181       directory.  If you store a single file in the directory, Alien::Build
182       will assume that it is an archive, which will be processed by the
183       extract hook below.  If you store multiple files, Alien::Build will
184       assume the current directory is the source root.  If no files are
185       stored at all, an exception with an appropriate diagnostic will be
186       thrown.
187
188       Note: If you register this hook, then the fetch, decode and prefer
189       hooks will NOT be called.
190
191   fetch hook
192        package Alien::Build::Plugin::MyPlugin;
193
194        use strict;
195        use warnings;
196        use Alien::Build::Plugin;
197        use Carp ();
198
199        has '+url' => sub { Carp::croak "url is required property" };
200
201        sub init
202        {
203          my($self, $meta) = @_;
204
205          $meta->register_hook( fetch => sub {
206            my($build, $url, %options) = @_;
207            ...
208          }
209        }
210
211        1;
212
213       Used to fetch a resource.  The first time it will be called without an
214       argument (or with $url set to "undef", so the configuration used to
215       find the resource should be specified by the plugin's properties.  On
216       subsequent calls the first argument will be a URL.
217
218       The %options hash may contain these options:
219
220       http_headers
221           HTTP request headers, if an appropriate protocol is being used.
222           The headers are provided as an array reference of key/value pairs,
223           which allows for duplicate header keys with multiple values.
224
225           If a non-HTTP protocol is used, or if the plugin cannot otherwise
226           send HTTP request headers, the plugin SHOULD issue a warning using
227           the "$build->log" method, but because this option wasn't part of
228           the original spec, the plugin MAY no issue that warning while
229           ignoring it.
230
231       Note that versions of Alien::Build prior to 2.39 did not pass the
232       options hash into the fetch plugin.
233
234       Normally the first fetch will be to either a file or a directory
235       listing.  If it is a file then the content should be returned as a hash
236       reference with the following keys:
237
238        # content of file stored in Perl
239        return {
240          type     => 'file',
241          filename => $filename,
242          content  => $content,
243          version  => $version,  # optional, if known
244        };
245
246        # content of file stored in the filesystem
247        return {
248          type     => 'file',
249          filename => $filename,
250          path     => $path,     # full file system path to file
251          version  => $version,  # optional, if known
252          tmp      => $tmp,      # optional
253        };
254
255       $tmp if set will indicate if the file is temporary or not, and can be
256       used by Alien::Build to save a copy in some cases.  The default is
257       true, so Alien::Build assumes the file or directory is temporary if you
258       don't tell it otherwise.
259
260       If the URL points to a directory listing you should return it as either
261       a hash reference containing a list of files:
262
263        return {
264          type => 'list',
265          list => [
266            # filename: each filename should be just the
267            #   filename portion, no path or url.
268            # url: each url should be the complete url
269            #   needed to fetch the file.
270            # version: OPTIONAL, may be provided by some fetch or prefer
271            { filename => $filename1, url => $url1, version => $version1 },
272            { filename => $filename2, url => $url2, version => $version2 },
273          ]
274        };
275
276       or if the listing is in HTML format as a hash reference containing the
277       HTML information:
278
279        return {
280          type => 'html',
281          charset => $charset, # optional
282          base    => $base,    # the base URL: used for computing relative URLs
283          content => $content, # the HTML content
284        };
285
286       or a directory listing (usually produced by ftp servers) as a hash
287       reference:
288
289        return {
290          type    => 'dir_listing',
291          base    => $base,
292          content => $content,
293        };
294
295   decode hook
296        sub init
297        {
298          my($self, $meta) = @_;
299
300          $meta->register_hook( decode => sub {
301            my($build, $res) = @_;
302            ...
303          }
304        }
305
306       This hook takes a response hash reference from the "fetch" hook above
307       with a type of "html" or "dir_listing" and converts it into a response
308       hash reference of type "list".  In short it takes an HTML or FTP file
309       listing response from a fetch hook and converts it into a list of
310       filenames and links that can be used by the prefer hook to choose the
311       correct file to download.  See "fetch" for the specification of the
312       input and response hash references.
313
314   prefer hook
315        sub init
316        {
317          my($self, $meta) = @_;
318
319          $meta->register_hook( prefer => sub {
320            my($build, $res) = @_;
321            return {
322              type => 'list',
323              list => [sort @{ $res->{list} }],
324            };
325          }
326        }
327
328       This hook sorts candidates from a listing generated from either the
329       "fetch" or "decode" hooks.  It should return a new list hash reference
330       with the candidates sorted from best to worst.  It may also remove
331       candidates that are totally unacceptable.
332
333   extract hook
334        $meta->register_hook( extract => sub {
335          my($build, $archive) = @_;
336          ...
337        });
338
339   patch hook
340        $meta->register_hook( patch => sub {
341          my($build) = @_;
342          ...
343        });
344
345       This hook is completely optional.  If registered, it will be triggered
346       after extraction and before build.  It allows you to apply any patches
347       or make any modifications to the source if they are necessary.
348
349   patch_ffi hook
350        $meta->register_hook( patch_ffi => sub {
351          my($build) = @_;
352          ...
353        });
354
355       This hook is exactly like the "patch" hook, except it fires only on an
356       FFI build.
357
358   build hook
359        $meta->register_hook( build => sub {
360          my($build) = @_;
361          ...
362        });
363
364       This does the main build of the alienized project and installs it into
365       the staging area.  The current directory is the build root.  You need
366       to run whatever tools are necessary for the project, and install them
367       into "%{.install.prefix}".
368
369   build_ffi hook
370        $meta->register_hook( build_ffi => sub {
371          my($build) = @_;
372          ...
373        });
374
375       This is the same as "build", except it fires only on a FFI build.
376
377   gather_share hook
378        $meta->register_hook( gather_share => sub {
379          my($build) = @_;
380          ...
381        });
382
383       This is the same as "gather_system", except it fires after a "share"
384       install.
385
386   gather_ffi hook
387        $meta->register_hook( gather_ffi => sub {
388          my($build) = @_;
389          ...
390        });
391
392       This is the same as "gather_share", except it fires after a "share" FFI
393       install.
394
395   override hook
396        $meta->register_hook( override => sub {
397          my($build) = @_;
398        });
399
400       This allows you to alter the override logic.  It should return one of
401       "share", "system", "default" or ''.  The default implementation is just
402       this:
403
404        return $ENV{ALIEN_INSTALL_TYPE} || '';
405
406   clean_install
407        $meta->register_hook( clean_install => sub {
408          my($build) = @_;
409        });
410
411       This hook allows you to remove files from the final install location
412       before the files are installed by the installer layer (examples:
413       Alien::Build::MM, Alien::Build::MB or App::af).  This hook is never
414       called by default, and must be enabled via the interface to the
415       installer layer.
416
417       This hook SHOULD NOT remove the "_alien" directory or its content from
418       the install location.
419
420       The default implementation removes all the files EXCEPT the "_alien"
421       directory and its content.
422

AUTHOR

424       Author: Graham Ollis <plicease@cpan.org>
425
426       Contributors:
427
428       Diab Jerius (DJERIUS)
429
430       Roy Storey (KIWIROY)
431
432       Ilya Pavlov
433
434       David Mertens (run4flat)
435
436       Mark Nunberg (mordy, mnunberg)
437
438       Christian Walde (Mithaldu)
439
440       Brian Wightman (MidLifeXis)
441
442       Zaki Mughal (zmughal)
443
444       mohawk (mohawk2, ETJ)
445
446       Vikas N Kumar (vikasnkumar)
447
448       Flavio Poletti (polettix)
449
450       Salvador Fandiño (salva)
451
452       Gianni Ceccarelli (dakkar)
453
454       Pavel Shaydo (zwon, trinitum)
455
456       Kang-min Liu (劉康民, gugod)
457
458       Nicholas Shipp (nshp)
459
460       Juan Julián Merelo Guervós (JJ)
461
462       Joel Berger (JBERGER)
463
464       Petr Pisar (ppisar)
465
466       Lance Wicks (LANCEW)
467
468       Ahmad Fatoum (a3f, ATHREEF)
469
470       José Joaquín Atria (JJATRIA)
471
472       Duke Leto (LETO)
473
474       Shoichi Kaji (SKAJI)
475
476       Shawn Laffan (SLAFFAN)
477
478       Paul Evans (leonerd, PEVANS)
479
480       Håkon Hægland (hakonhagland, HAKONH)
481
483       This software is copyright (c) 2011-2020 by Graham Ollis.
484
485       This is free software; you can redistribute it and/or modify it under
486       the same terms as the Perl 5 programming language system itself.
487
488
489
490perl v5.32.1                      2021-05-A1l3ien::Build::Manual::PluginAuthor(3)
Impressum