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.40
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
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 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 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 Hooks get the Alien::Build instance as their first argument, and
70 depending on the hook may get additional arguments.
71 You can also modify hooks using "before_hook", "around_hook" and
73 "after_hook":
74 sub init
76 {
77 my($self, $meta) = @_;
78 $meta->before_hook(
80 build => sub {
81 my($build) = @_;
82 $build->log('this runs before the build');
83 },
84 );
85 $meta->after_hook(
87 build => sub {
88 my($build) = @_;
89 $build->log('this runs after the build');
90 },
91 );
92 $meta->around_hook(
94 build => sub {
95 my $orig = shift;
96 # around hooks are useful for setting environment variables
98 local $ENV{CPPFLAGS} = '-I/foo/include';
99 $orig->(@_);
101 },
102 );
103 }
104 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 use Test::V0;
110 use Test::Alien::Build;
111 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 # you can interrogate $build, it is an instance of L<Alien::Build>.
122 my $alien = alien_build_ok;
124 # you can interrogate $alien, it is an instance of L<Alien::Base>.
126
128 probe hook
129 $meta->register_hook( probe => sub {
130 my($build) = @_;
131 return 'system' if ...; # system install
132 return 'share'; # otherwise
133 });
134 $meta->register_hook( probe => [ $command ] );
136 This hook should return the string "system" if the operating system
138 provides the library or tool. It should return "share" otherwise.
139 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 $meta->register_hook( probe =>
144 [ '%{pkgconf} --exists libfoo' ] );
145 Or if you needed a minimum version:
147 $meta->register_hook( probe =>
149 [ '%{pkgconf} --atleast-version=1.00 libfoo' ] );
150 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 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 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 download hook
172 $meta->register_hook( download => sub {
173 my($build) = @_;
174 ...
175 });
176 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 Note: If you register this hook, then the fetch, decode and prefer
189 hooks will NOT be called.
190 fetch hook
192 package Alien::Build::Plugin::MyPlugin;
193 use strict;
195 use warnings;
196 use Alien::Build::Plugin;
197 use Carp ();
198 has '+url' => sub { Carp::croak "url is required property" };
200 sub init
202 {
203 my($self, $meta) = @_;
204 $meta->register_hook( fetch => sub {
206 my($build, $url, %options) = @_;
207 ...
208 }
209 }
210 1;
212 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 The %options hash may contain these options:
219 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 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 Note that versions of Alien::Build prior to 2.39 did not pass the
232 options hash into the fetch plugin.
233 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 # 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 # 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 $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 If the URL points to a directory listing you should return it as either
261 a hash reference containing a list of files:
262 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 or if the listing is in HTML format as a hash reference containing the
277 HTML information:
278 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 or a directory listing (usually produced by ftp servers) as a hash
287 reference:
288 return {
290 type => 'dir_listing',
291 base => $base,
292 content => $content,
293 };
294 decode hook
296 sub init
297 {
298 my($self, $meta) = @_;
299 $meta->register_hook( decode => sub {
301 my($build, $res) = @_;
302 ...
303 }
304 }
305 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 prefer hook
315 sub init
316 {
317 my($self, $meta) = @_;
318 $meta->register_hook( prefer => sub {
320 my($build, $res) = @_;
321 return {
322 type => 'list',
323 list => [sort @{ $res->{list} }],
324 };
325 }
326 }
327 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 extract hook
334 $meta->register_hook( extract => sub {
335 my($build, $archive) = @_;
336 ...
337 });
338 patch hook
340 $meta->register_hook( patch => sub {
341 my($build) = @_;
342 ...
343 });
344 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 patch_ffi hook
350 $meta->register_hook( patch_ffi => sub {
351 my($build) = @_;
352 ...
353 });
354 This hook is exactly like the "patch" hook, except it fires only on an
356 FFI build.
357 build hook
359 $meta->register_hook( build => sub {
360 my($build) = @_;
361 ...
362 });
363 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 build_ffi hook
370 $meta->register_hook( build_ffi => sub {
371 my($build) = @_;
372 ...
373 });
374 This is the same as "build", except it fires only on a FFI build.
376 gather_share hook
378 $meta->register_hook( gather_share => sub {
379 my($build) = @_;
380 ...
381 });
382 This is the same as "gather_system", except it fires after a "share"
384 install.
385 gather_ffi hook
387 $meta->register_hook( gather_ffi => sub {
388 my($build) = @_;
389 ...
390 });
391 This is the same as "gather_share", except it fires after a "share" FFI
393 install.
394 override hook
396 $meta->register_hook( override => sub {
397 my($build) = @_;
398 });
399 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 return $ENV{ALIEN_INSTALL_TYPE} || '';
405 clean_install
407 $meta->register_hook( clean_install => sub {
408 my($build) = @_;
409 });
410 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 This hook SHOULD NOT remove the "_alien" directory or its content from
418 the install location.
419 The default implementation removes all the files EXCEPT the "_alien"
421 directory and its content.
422
424 Author: Graham Ollis <plicease@cpan.org>
425 Contributors:
427 Diab Jerius (DJERIUS)
429 Roy Storey (KIWIROY)
431 Ilya Pavlov
433 David Mertens (run4flat)
435 Mark Nunberg (mordy, mnunberg)
437 Christian Walde (Mithaldu)
439 Brian Wightman (MidLifeXis)
441 Zaki Mughal (zmughal)
443 mohawk (mohawk2, ETJ)
445 Vikas N Kumar (vikasnkumar)
447 Flavio Poletti (polettix)
449 Salvador Fandiño (salva)
451 Gianni Ceccarelli (dakkar)
453 Pavel Shaydo (zwon, trinitum)
455 Kang-min Liu (劉康民, gugod)
457 Nicholas Shipp (nshp)
459 Juan Julián Merelo Guervós (JJ)
461 Joel Berger (JBERGER)
463 Petr Pisar (ppisar)
465 Lance Wicks (LANCEW)
467 Ahmad Fatoum (a3f, ATHREEF)
469 José Joaquín Atria (JJATRIA)
471 Duke Leto (LETO)
473 Shoichi Kaji (SKAJI)
475 Shawn Laffan (SLAFFAN)
477 Paul Evans (leonerd, PEVANS)
479 Håkon Hægland (hakonhagland, HAKONH)
481
483 This software is copyright (c) 2011-2020 by Graham Ollis.
484 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.
487perl v5.32.1 2021-05-A1l3ien::Build::Manual::PluginAuthor(3)