1Alien::Build::Manual::PUlsuegrinCAountthroirb(u3t)ed PerAlliDeonc:u:mBeunitladt:i:oMnanual::PluginAuthor(3)
2
6 Alien::Build::Manual::PluginAuthor - Alien::Build plugin author
7 documentation
8
10 version 2.80
11
13 your plugin:
14 package Alien::Build::Plugin::Build::MyPlugin;
16 use strict;
18 use warnings;
19 use Alien::Build::Plugin;
20 has arg1 => 'default_for arg1';
22 has arg2 => sub { [ 'default', 'for', 'arg2' ] };
23 sub init
25 {
26 my($self, $meta) = @_;
27 ...
28 }
29 1;
31 and then from alienfile:
33 use alienfile;
35 plugin 'Build::MyPlugin' => (
36 arg1 => 'override for arg1',
37 arg2 => [ 'something', 'else' ],
38 );
39 Perlish pseudo code for how plugins are called:
41 my $probe;
43 my $override = override();
44 if($override eq 'system') {
46 $probe = probe();
48 if($probe ne 'system') {
50 die 'system tool or library not found';
51 }
52 }
54 elsif($override eq 'default') {
56 $probe = probe();
57 } else { # $override eq 'share'
59 # note that in this instance the
60 # probe hook is never called
61 $probe = 'share';
62 }
63 if($probe eq 'system') {
65 gather_system();
66 } else { # $probe eq 'share'
68 download();
70 extract();
71 patch();
72 build();
73 gather_share();
74 # Check to see if there isa build_ffi hook
76 if(defined &build_ffi) {
77 patch_ffi();
78 build_ffi();
79 gather_ffi();
80 }
81 }
82 # By default this just returns the value of $ENV{ALIEN_INSTALL_TYPE}
84 sub override {
85 return $ENV{ALIEN_INSTALL_TYPE};
86 }
87 # Default download implementation; can be
89 # replaced by specifying a different download
90 # hook. See Alien::Build::Plugin::Core::Download
91 # for detailed implementation.
92 sub download {
93 my $response = fetch();
95 if($response->{type} eq 'html' || $response->{type} eq 'dir_listing') {
97 # decode will transform an HTML listing (html) or a FTP directory
98 # listing (dir_listing) into a regular list
99 $response = decode($response);
100 }
101 if($response->{type} eq 'list') {
103 # prefer will filter bad entries in the list
105 # and sort them so that the first one is
106 # the one that we want
107 $response = prefer($response);
108 my $first_preferred = $res->{list}->[0];
110 # prefer can sometimes infer the version from the
112 # filename.
113 if(defined $first_preferred->{version}) {
114 # not a hook
115 runtime_prop->{version} = $first_preferred->{version};
116 }
117 $response = fetch($first_preferred);
119 }
121 if($response->{type} eq 'file') {
123 # not a hook
124 write_file_to_disk $response;
125 }
126 }
128
130 This document explains how to write Alien::Build plugins using the
131 Alien::Build::Plugin base class.
132 Writing plugins
134 Plugins use Alien::Build::Plugin, which sets the appropriate base
135 class, and provides you with the "has" property builder. "has" takes
136 two arguments, the name of the property and the default value. (As
137 with Moose and Moo, you should use a code reference to specify default
138 values for non-string defaults). No not set this as your plugin's base
139 class directly:
140 use parent qw( Alien::Build::Plugin ); # wrong
142 use Alien::Build::Plugin; # right
143 The only method that you need to implement is "init". From this method
145 you can add hooks to change the behavior of the alienfile recipe. This
146 is a very simple example of a probe hook, with the actual probe logic
147 removed:
148 sub init
150 {
151 my($self, $meta) = @_;
152 $meta->register_hook(
153 probe => sub {
154 my($build) = @_;
155 if( ... )
156 {
157 return 'system';
158 }
159 else
160 {
161 return 'share';
162 }
163 },
164 );
165 }
166 Hooks get the Alien::Build instance as their first argument, and
168 depending on the hook may get additional arguments.
169 Modifying hooks
171 You can also modify hooks using "before_hook", "around_hook" and
172 "after_hook", similar to Moose modifiers:
173 sub init
175 {
176 my($self, $meta) = @_;
177 $meta->before_hook(
179 build => sub {
180 my($build) = @_;
181 $build->log('this runs before the build');
182 },
183 );
184 $meta->after_hook(
186 build => sub {
187 my($build) = @_;
188 $build->log('this runs after the build');
189 },
190 );
191 $meta->around_hook(
193 build => sub {
194 my $orig = shift;
195 # around hooks are useful for setting environment variables
197 local $ENV{CPPFLAGS} = '-I/foo/include';
198 $orig->(@_);
200 },
201 );
202 }
203 Testing plugins
205 You can and should write tests for your plugin. The best way to do
206 this is using Test::Alien::Build, which allows you to write an inline
207 alienfile in your test. Here is an example:
208 use Test::V0;
210 use Test::Alien::Build;
211 my $build = alienfile_ok q{
213 use alienfile;
214 plugin 'Build::MyPlugin' => (
215 arg1 => 'override for arg1',
216 arg2 => [ 'something', 'else' ],
217 );
218 ...
219 };
220 # you can interrogate $build, it is an instance of L<Alien::Build>.
222 my $alien = alien_build_ok;
224 # you can interrogate $alien, it is an instance of L<Alien::Base>.
226 Negotiator plugins
228 A Negotiator plugin doesn't itself typically implement anything on its
229 own, but picks the best plugin to achieve a particular goal.
230 The "best" plugin can in some cases vary depending on the platform or
232 tools that are available. For example The download negotiator might
233 choose to use the fetch plugin that relies on the command line "curl",
234 or it might choose the fetch plugin that relies on the Perl module
235 HTTP::Tiny depending on the platform and what is already installed.
236 (For either to be useful they have to support SSL).
237 The Negotiator plugin is by convention named something like
239 "Alien::Build::Plugin::*::Negotiate", but is typically invoked without
240 the "::Negotiate" suffix. For example:
241 plugin 'Download'; # is short for Alien::Build::Plugin::Download::Negotiator
243 Here is a simple example of a negotiator which picks "curl" if already
245 installed and HTTP::Tiny otherwise. (The actual download plugin is a
246 lot smarter and complicated than this, but this is a good simplified
247 example).
248 package Alien::Build::Plugin::Download::Negotiate;
250 use strict;
252 use warnings;
253 use Alien::Build::Plugin;
254 use File::Which qw( which );
255 sub init
257 {
258 my($self, $meta) = @_;
259 if(which('curl')) {
261 $meta->apply_plugin('Fetch::Curl');
262 } else {
263 $meta->apply_plugin('Fetch::HTTPTiny');
264 }
265 }
266 Hooks
268 The remainder of this document is a reference for the hooks that you
269 can register. Generally speaking you can register any hook that you
270 like, but some care must be taken as some hooks have default behavior
271 that will be overridden when you register a hook. The hooks are
272 presented in alphabetical order. The execution order is shown in the
273 flowchart above (if you are browsing the HTML version of this
274 document), or the Perlish pseudo code in the synopsis section.
275
277 build hook
278 $meta->register_hook( build => sub {
279 my($build) = @_;
280 ...
281 });
282 This does the main build of the alienized project and installs it into
284 the staging area. The current directory is the build root. You need
285 to run whatever tools are necessary for the project, and install them
286 into "$build-"install_prop->{prefix}> ("%{.install.prefix}").
287 build_ffi hook
289 $meta->register_hook( build_ffi => sub {
290 my($build) = @_;
291 ...
292 });
293 This is the same as build, except it fires only on a FFI build.
295 decode hook
297 $meta->register_hook( decode => sub {
298 my($build, $res) = @_;
299 ...
300 }
301 This hook takes a response hash reference from the "fetch" hook above
303 with a type of "html" or "dir_listing" and converts it into a response
304 hash reference of type "list". In short it takes an HTML or FTP file
305 listing response from a fetch hook and converts it into a list of
306 filenames and links that can be used by the prefer hook to choose the
307 correct file to download. See the fetch hook for the specification of
308 the input and response hash references.
309 check_digest hook
311 # implement the well known FOO-92 digest
312 $meta->register_hook( check_digest => sub {
313 my($build, $file, $algorithm, $digest) = @_;
314 if($algorithm ne 'FOO92') {
315 return 0;
316 }
317 my $actual = foo92_hex_digest($file);
318 if($actual eq $digest) {
319 return 1;
320 } else {
321 die "Digest FOO92 does not match: got $actual, expected $digest";
322 }
323 });
324 This hook should check the given $file (the format is the same as used
326 by the fetch hook) matches the given $digest using the given
327 $algorithm. If the plugin does not support the given algorithm, then
328 it should return a false value. If the digest does not match, it
329 should throw an exception. If the digest matches, it should return a
330 true value.
331 clean_install
333 $meta->register_hook( clean_install => sub {
334 my($build) = @_;
335 });
336 This hook allows you to remove files from the final install location
338 before the files are installed by the installer layer (examples:
339 Alien::Build::MM, Alien::Build::MB or App::af). This hook is not
340 called by default, and must be enabled via the interface to the
341 installer layer (example: "clean_install" in Alien::Build::MM).
342 This hook SHOULD NOT remove the "_alien" directory or its content from
344 the install location.
345 The default implementation removes all the files EXCEPT the "_alien"
347 directory and its content.
348 download hook
350 $meta->register_hook( download => sub {
351 my($build) = @_;
352 ...
353 });
354 This hook is used to download from the internet the source. Either as
356 an archive (like tar, zip, etc), or as a directory of files ("git
357 clone", etc). When the hook is called, the current working directory
358 will be a new empty directory, so you can save the download to the
359 current directory. If you store a single file in the directory,
360 Alien::Build will assume that it is an archive, which will be processed
361 by the extract hook. If you store multiple files, Alien::Build will
362 assume the current directory is the source root. If no files are
363 stored at all, an exception with an appropriate diagnostic will be
364 thrown.
365 Note: If you register this hook, then the fetch, decode and prefer
367 hooks will NOT be called, unless you call them yourself from this hook.
368 extract hook
370 $meta->register_hook( extract => sub {
371 my($build, $archive) = @_;
372 ...
373 });
374 This hook is used to extract an archive that has already been
376 downloaded. Alien::Build already has plugins for the most common
377 archive formats, so you will likely only need this to add support for
378 new or novel archive formats. When this hook is called, the current
379 working directory will be a new empty directory, so you can save the
380 content of the archive to the current directory. If a single directory
381 is written to the current directory, Alien::Build will assume that is
382 the root directory of the package. If multiple files and/or
383 directories are present, that will indicate that the current working
384 directory is the root of the package. The logic typically handles
385 correctly the default behavior for tar (where packages are typically
386 extracted to a subdirectory) and for zip (where packages are typically
387 extracted to the current directory).
388 fetch hook
390 package Alien::Build::Plugin::MyPlugin;
391 use strict;
393 use warnings;
394 use Alien::Build::Plugin;
395 use Carp ();
396 has '+url' => sub { Carp::croak "url is required property" };
398 sub init
400 {
401 my($self, $meta) = @_;
402 $meta->register_hook( fetch => sub {
404 my($build, $url, %options) = @_;
405 ...
406 }
407 }
408 1;
410 Used to fetch a resource. The first time it will be called without an
412 argument (or with $url set to "undef", so the configuration used to
413 find the resource should be specified by the plugin's properties. On
414 subsequent calls the first argument will be a URL.
415 The %options hash may contain these options:
417 http_headers
419 HTTP request headers, if an appropriate protocol is being used.
420 The headers are provided as an array reference of key/value pairs,
421 which allows for duplicate header keys with multiple values.
422 If a non-HTTP protocol is used, or if the plugin cannot otherwise
424 send HTTP request headers, the plugin SHOULD issue a warning using
425 the "$build->log" method, but because this option wasn't part of
426 the original spec, the plugin MAY no issue that warning while
427 ignoring it.
428 Note that versions of Alien::Build prior to 2.39 did not pass the
430 options hash into the fetch plugin.
431 Normally the first fetch will be to either a file or a directory
433 listing. If it is a file then the content should be returned as a hash
434 reference with the following keys:
435 # content of file stored in Perl
437 return {
438 type => 'file',
439 filename => $filename,
440 content => $content,
441 version => $version, # optional, if known
442 protocol => $protocol, # AB 2.60 optional, but recommended
443 };
444 # content of file stored in the filesystem
446 return {
447 type => 'file',
448 filename => $filename,
449 path => $path, # full file system path to file
450 version => $version, # optional, if known
451 tmp => $tmp, # optional
452 protocol => $protocol, # AB 2.60 optional, but recommended
453 };
454 $tmp if set will indicate if the file is temporary or not, and can be
456 used by Alien::Build to save a copy in some cases. The default is
457 true, so Alien::Build assumes the file or directory is temporary if you
458 don't tell it otherwise. Probably the most common situation when you
459 would set "tmp" to false, is when the file is bundled inside the Alien
460 distribution. See Alien::Build::Plugin::Fetch::Local for example.
461 If the URL points to a directory listing you should return it as either
463 a hash reference containing a list of files:
464 return {
466 type => 'list',
467 list => [
468 # filename: each filename should be just the
469 # filename portion, no path or url.
470 # url: each url should be the complete url
471 # needed to fetch the file.
472 # version: OPTIONAL, may be provided by some fetch or prefer
473 { filename => $filename1, url => $url1, version => $version1 },
474 { filename => $filename2, url => $url2, version => $version2 },
475 ],
476 protocol => $protocol, # AB 2.60 optional, but recommended
477 };
478 or if the listing is in HTML format as a hash reference containing the
480 HTML information:
481 return {
483 type => 'html',
484 charset => $charset, # optional
485 base => $base, # the base URL: used for computing relative URLs
486 content => $content, # the HTML content
487 protocol => $protocol, # optional, but recommended
488 };
489 or a directory listing (usually produced by an FTP servers) as a hash
491 reference:
492 return {
494 type => 'dir_listing',
495 base => $base,
496 content => $content,
497 protocol => $protocol, # AB 2.60 optional, but recommended
498 };
499 [version 2.60]
501 For all of these responses $protocol is optional, since it was not part
503 of the original spec, however it is strongly recommended that you
504 include this field, because future versions of Alien::Build will use
505 this to determine if a file was downloaded securely (that is via a
506 secure protocol such as SSL).
507 Some plugins (like decode plugins ) trans late a file hash from one
509 type to another, they should maintain the $protocol from the old to the
510 new representation of the file.
511 gather_ffi hook
513 $meta->register_hook( gather_ffi => sub {
514 my($build) = @_;
515 $build->runtime_prop->{cflags} = ...;
516 $build->runtime_prop->{libs} = ...;
517 $build->runtime_prop->{version} = ...;
518 });
519 This hook is called for a FFI build to determine the properties
521 necessary for using the library or tool. These properties should be
522 stored in the runtime_prop hash as shown above. Typical properties
523 that are needed for libraries are cflags and libs. If at all possible
524 you should also try to determine the version of the library or tool.
525 gather_share hook
527 $meta->register_hook( gather_share => sub {
528 my($build) = @_;
529 $build->runtime_prop->{cflags} = ...;
530 $build->runtime_prop->{libs} = ...;
531 $build->runtime_prop->{version} = ...;
532 });
533 This hook is called for a share install to determine the properties
535 necessary for using the library or tool. These properties should be
536 stored in the runtime_prop hash as shown above. Typical properties
537 that are needed for libraries are cflags and libs. If at all possible
538 you should also try to determine the version of the library or tool.
539 gather_system hook
541 $meta->register_hook( gather_system => sub {
542 my($build) = @_;
543 $build->runtime_prop->{cflags} = ...;
544 $build->runtime_prop->{libs} = ...;
545 $build->runtime_prop->{version} = ...;
546 });
547 This hook is called for a system install to determine the properties
549 necessary for using the library or tool. These properties should be
550 stored in the runtime_prop hash as shown above. Typical properties
551 that are needed for libraries are cflags and libs. If at all possible
552 you should also try to determine the version of the library or tool.
553 override hook
555 $meta->register_hook( override => sub {
556 my($build) = @_;
557 return $ENV{ALIEN_INSTALL_TYPE} || '';
558 });
559 This allows you to alter the override logic. It should return one of
561 "share", "system", "default" or ''. The default implementation is
562 shown above. Alien::Build::Plugin::Probe::Override and
563 Alien::Build::Plugin::Probe::OverrideCI are examples of how you can use
564 this hook.
565 patch hook
567 $meta->register_hook( patch => sub {
568 my($build) = @_;
569 ...
570 });
571 This hook is completely optional. If registered, it will be triggered
573 after extraction and before build. It allows you to apply any patches
574 or make any modifications to the source if they are necessary.
575 patch_ffi hook
577 $meta->register_hook( patch_ffi => sub {
578 my($build) = @_;
579 ...
580 });
581 This hook is exactly like the patch hook, except it fires only on an
583 FFI build.
584 prefer hook
586 $meta->register_hook( prefer => sub {
587 my($build, $res) = @_;
588 return {
589 type => 'list',
590 list => [sort @{ $res->{list} }],
591 };
592 }
593 This hook sorts candidates from a listing generated from either the
595 "fetch" or "decode" hooks. It should return a new list hash reference
596 with the candidates sorted from best to worst. It may also remove
597 candidates that are totally unacceptable.
598 probe hook
600 $meta->register_hook( probe => sub {
601 my($build) = @_;
602 return 'system' if ...; # system install
603 return 'share'; # otherwise
604 });
605 $meta->register_hook( probe => [ $command ] );
607 This hook should return the string "system" if the operating system
609 provides the library or tool. It should return "share" otherwise.
610 You can also use a command that returns true when the tool or library
612 is available. For example for use with "pkg-config":
613 $meta->register_hook( probe =>
615 [ '%{pkgconf} --exists libfoo' ] );
616 Or if you needed a minimum version:
618 $meta->register_hook( probe =>
620 [ '%{pkgconf} --atleast-version=1.00 libfoo' ] );
621 Note that this hook SHOULD NOT gather system properties, such as
623 cflags, libs, versions, etc, because the probe hook will be skipped in
624 the event the environment variable "ALIEN_INSTALL_TYPE" is set. The
625 detection of these properties should instead be done by the
626 gather_system hook.
627 Multiple probe hooks can be given. These will be used in sequence,
629 stopping at the first that detects a system installation.
630
632 Alien::Build::Manual
633 Other Alien::Build manuals.
634
636 Author: Graham Ollis <plicease@cpan.org>
637 Contributors:
639 Diab Jerius (DJERIUS)
641 Roy Storey (KIWIROY)
643 Ilya Pavlov
645 David Mertens (run4flat)
647 Mark Nunberg (mordy, mnunberg)
649 Christian Walde (Mithaldu)
651 Brian Wightman (MidLifeXis)
653 Zaki Mughal (zmughal)
655 mohawk (mohawk2, ETJ)
657 Vikas N Kumar (vikasnkumar)
659 Flavio Poletti (polettix)
661 Salvador Fandiño (salva)
663 Gianni Ceccarelli (dakkar)
665 Pavel Shaydo (zwon, trinitum)
667 Kang-min Liu (劉康民, gugod)
669 Nicholas Shipp (nshp)
671 Juan Julián Merelo Guervós (JJ)
673 Joel Berger (JBERGER)
675 Petr Písař (ppisar)
677 Lance Wicks (LANCEW)
679 Ahmad Fatoum (a3f, ATHREEF)
681 José Joaquín Atria (JJATRIA)
683 Duke Leto (LETO)
685 Shoichi Kaji (SKAJI)
687 Shawn Laffan (SLAFFAN)
689 Paul Evans (leonerd, PEVANS)
691 Håkon Hægland (hakonhagland, HAKONH)
693 nick nauwelaerts (INPHOBIA)
695 Florian Weimer
697
699 This software is copyright (c) 2011-2022 by Graham Ollis.
700 This is free software; you can redistribute it and/or modify it under
702 the same terms as the Perl 5 programming language system itself.
703perl v5.36.1 2023-05-A1l5ien::Build::Manual::PluginAuthor(3)