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.38
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) = @_;
207 ...
208 }
209 }
210 1;
212 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 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 # 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 # 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 $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 If the URL points to a directory listing you should return it as either
245 a hash reference containing a list of files:
246 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 or if the listing is in HTML format as a hash reference containing the
261 HTML information:
262 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 or a directory listing (usually produced by ftp servers) as a hash
271 reference:
272 return {
274 type => 'dir_listing',
275 base => $base,
276 content => $content,
277 };
278 decode hook
280 sub init
281 {
282 my($self, $meta) = @_;
283 $meta->register_hook( decode => sub {
285 my($build, $res) = @_;
286 ...
287 }
288 }
289 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 prefer hook
299 sub init
300 {
301 my($self, $meta) = @_;
302 $meta->register_hook( prefer => sub {
304 my($build, $res) = @_;
305 return {
306 type => 'list',
307 list => [sort @{ $res->{list} }],
308 };
309 }
310 }
311 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 extract hook
318 $meta->register_hook( extract => sub {
319 my($build, $archive) = @_;
320 ...
321 });
322 patch hook
324 $meta->register_hook( patch => sub {
325 my($build) = @_;
326 ...
327 });
328 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 patch_ffi hook
334 $meta->register_hook( patch_ffi => sub {
335 my($build) = @_;
336 ...
337 });
338 This hook is exactly like the "patch" hook, except it fires only on an
340 FFI build.
341 build hook
343 $meta->register_hook( build => sub {
344 my($build) = @_;
345 ...
346 });
347 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 build_ffi hook
354 $meta->register_hook( build_ffi => sub {
355 my($build) = @_;
356 ...
357 });
358 This is the same as "build", except it fires only on a FFI build.
360 gather_share hook
362 $meta->register_hook( gather_share => sub {
363 my($build) = @_;
364 ...
365 });
366 This is the same as "gather_system", except it fires after a "share"
368 install.
369 gather_ffi hook
371 $meta->register_hook( gather_ffi => sub {
372 my($build) = @_;
373 ...
374 });
375 This is the same as "gather_share", except it fires after a "share" FFI
377 install.
378 override hook
380 $meta->register_hook( override => sub {
381 my($build) = @_;
382 });
383 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 return $ENV{ALIEN_INSTALL_TYPE} || '';
389 clean_install
391 $meta->register_hook( clean_install => sub {
392 my($build) = @_;
393 });
394 This hook allows you to remove files from the final install location
396 before the files are installed by the installer layer (examples:
397 Alien::Build::MM, Alien::Build::MB or App::af). This hook is never
398 called by default, and must be enabled via the interface to the
399 installer layer.
400 This hook SHOULD NOT remove the "_alien" directory or its content from
402 the install location.
403 The default implementation removes all the files EXCEPT the "_alien"
405 directory and its content.
406
408 Author: Graham Ollis <plicease@cpan.org>
409 Contributors:
411 Diab Jerius (DJERIUS)
413 Roy Storey (KIWIROY)
415 Ilya Pavlov
417 David Mertens (run4flat)
419 Mark Nunberg (mordy, mnunberg)
421 Christian Walde (Mithaldu)
423 Brian Wightman (MidLifeXis)
425 Zaki Mughal (zmughal)
427 mohawk (mohawk2, ETJ)
429 Vikas N Kumar (vikasnkumar)
431 Flavio Poletti (polettix)
433 Salvador Fandiño (salva)
435 Gianni Ceccarelli (dakkar)
437 Pavel Shaydo (zwon, trinitum)
439 Kang-min Liu (劉康民, gugod)
441 Nicholas Shipp (nshp)
443 Juan Julián Merelo Guervós (JJ)
445 Joel Berger (JBERGER)
447 Petr Pisar (ppisar)
449 Lance Wicks (LANCEW)
451 Ahmad Fatoum (a3f, ATHREEF)
453 José Joaquín Atria (JJATRIA)
455 Duke Leto (LETO)
457 Shoichi Kaji (SKAJI)
459 Shawn Laffan (SLAFFAN)
461 Paul Evans (leonerd, PEVANS)
463 Håkon Hægland (hakonhagland, HAKONH)
465
467 This software is copyright (c) 2011-2020 by Graham Ollis.
468 This is free software; you can redistribute it and/or modify it under
470 the same terms as the Perl 5 programming language system itself.
471perl v5.32.0 2021-01-A1l2ien::Build::Manual::PluginAuthor(3)