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 1.55
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) = @_;
207            ...
208          }
209        }
210
211        1;
212
213       Used to fetch a resource.  The first time it will be called without an
214       argument, so the configuration used to find the resource should be
215       specified by the plugin's properties.  On subsequent calls the first
216       argument will be a URL.
217
218       Normally the first fetch will be to either a file or a directory
219       listing.  If it is a file then the content should be returned as a hash
220       reference with the following keys:
221
222        # content of file stored in Perl
223        return {
224          type     => 'file',
225          filename => $filename,
226          content  => $content,
227          version  => $version,  # optional, if known
228        };
229
230        # content of file stored in the filesystem
231        return {
232          type     => 'file',
233          filename => $filename,
234          path     => $path,     # full file system path to file
235          version  => $version,  # optional, if known
236          tmp      => $tmp,      # optional
237        };
238
239       $tmp if set will indicate if the file is temporary or not, and can be
240       used by Alien::Build to save a copy in some cases.  The default is
241       true, so Alien::Build assumes the file or directory is temporary if you
242       don't tell it otherwise.
243
244       If the URL points to a directory listing you should return it as either
245       a hash reference containing a list of files:
246
247        return {
248          type => 'list',
249          list => [
250            # filename: each filename should be just the
251            #   filename portion, no path or url.
252            # url: each url should be the complete url
253            #   needed to fetch the file.
254            # version: OPTIONAL, may be provided by some fetch or prefer
255            { filename => $filename1, url => $url1, version => $version1 },
256            { filename => $filename2, url => $url2, version => $version2 },
257          ]
258        };
259
260       or if the listing is in HTML format as a hash reference containing the
261       HTML information:
262
263        return {
264          type => 'html',
265          charset => $charset, # optional
266          base    => $base,    # the base URL: used for computing relative URLs
267          content => $content, # the HTML content
268        };
269
270       or a directory listing (usually produced by ftp servers) as a hash
271       reference:
272
273        return {
274          type    => 'dir_listing',
275          base    => $base,
276          content => $content,
277        };
278
279   decode hook
280        sub init
281        {
282          my($self, $meta) = @_;
283
284          $meta->register_hook( decode => sub {
285            my($build, $res) = @_;
286            ...
287          }
288        }
289
290       This hook takes a response hash reference from the "fetch" hook above
291       with a type of "html" or "dir_listing" and converts it into a response
292       hash reference of type "list".  In short it takes an HTML or FTP file
293       listing response from a fetch hook and converts it into a list of
294       filenames and links that can be used by the prefer hook to choose the
295       correct file to download.  See "fetch" for the specification of the
296       input and response hash references.
297
298   prefer hook
299        sub init
300        {
301          my($self, $meta) = @_;
302
303          $meta->register_hook( prefer => sub {
304            my($build, $res) = @_;
305            return {
306              type => 'list',
307              list => [sort @{ $res->{list} }],
308            };
309          }
310        }
311
312       This hook sorts candidates from a listing generated from either the
313       "fetch" or "decode" hooks.  It should return a new list hash reference
314       with the candidates sorted from best to worst.  It may also remove
315       candidates that are totally unacceptable.
316
317   extract hook
318        $meta->register_hook( extract => sub {
319          my($build, $archive) = @_;
320          ...
321        });
322
323   patch hook
324        $meta->register_hook( patch => sub {
325          my($build) = @_;
326          ...
327        });
328
329       This hook is completely optional.  If registered, it will be triggered
330       after extraction and before build.  It allows you to apply any patches
331       or make any modifications to the source if they are necessary.
332
333   patch_ffi hook
334        $meta->register_hook( patch_ffi => sub {
335          my($build) = @_;
336          ...
337        });
338
339       This hook is exactly like the "patch" hook, except it fires only on an
340       FFI build.
341
342   build hook
343        $meta->register_hook( build => sub {
344          my($build) = @_;
345          ...
346        });
347
348       This does the main build of the alienized project and installs it into
349       the staging area.  The current directory is the build root.  You need
350       to run whatever tools are necessary for the project, and install them
351       into "%{.install.prefix}".
352
353   build_ffi hook
354        $meta->register_hook( build_ffi => sub {
355          my($build) = @_;
356          ...
357        });
358
359       This is the same as "build", except it fires only on a FFI build.
360
361   gather_share hook
362        $meta->register_hook( gather_share => sub {
363          my($build) = @_;
364          ...
365        });
366
367       This is the same as "gather_system", except it fires after a "share"
368       install.
369
370   gather_ffi hook
371        $meta->register_hook( gather_ffi => sub {
372          my($build) = @_;
373          ...
374        });
375
376       This is the same as "gather_share", except it fires after a "share" FFI
377       install.
378
379   override hook
380        $meta->register_hook( override => sub {
381          my($build) = @_;
382        });
383
384       This allows you to alter the override logic.  It should return one of
385       "share", "system", "default" or ''.  The default implementation is just
386       this:
387
388        return $ENV{ALIEN_INSTALL_TYPE} || '';
389

AUTHOR

391       Author: Graham Ollis <plicease@cpan.org>
392
393       Contributors:
394
395       Diab Jerius (DJERIUS)
396
397       Roy Storey
398
399       Ilya Pavlov
400
401       David Mertens (run4flat)
402
403       Mark Nunberg (mordy, mnunberg)
404
405       Christian Walde (Mithaldu)
406
407       Brian Wightman (MidLifeXis)
408
409       Zaki Mughal (zmughal)
410
411       mohawk (mohawk2, ETJ)
412
413       Vikas N Kumar (vikasnkumar)
414
415       Flavio Poletti (polettix)
416
417       Salvador Fandiño (salva)
418
419       Gianni Ceccarelli (dakkar)
420
421       Pavel Shaydo (zwon, trinitum)
422
423       Kang-min Liu (劉康民, gugod)
424
425       Nicholas Shipp (nshp)
426
427       Juan Julián Merelo Guervós (JJ)
428
429       Joel Berger (JBERGER)
430
431       Petr Pisar (ppisar)
432
433       Lance Wicks (LANCEW)
434
435       Ahmad Fatoum (a3f, ATHREEF)
436
437       José Joaquín Atria (JJATRIA)
438
439       Duke Leto (LETO)
440
441       Shoichi Kaji (SKAJI)
442
443       Shawn Laffan (SLAFFAN)
444
445       Paul Evans (leonerd, PEVANS)
446
448       This software is copyright (c) 2011-2018 by Graham Ollis.
449
450       This is free software; you can redistribute it and/or modify it under
451       the same terms as the Perl 5 programming language system itself.
452
453
454
455perl v5.28.1                      2019-02-A2l4ien::Build::Manual::PluginAuthor(3)
Impressum