alienfile(3pm)

1alienfile(3)          User Contributed Perl Documentation         alienfile(3)
2
3
4

NAME

6       alienfile - Specification for defining an external dependency for CPAN
7

VERSION

9       version 2.77
10

SYNOPSIS

12       Do-it-yourself approach:
13
14        use alienfile;
15
16        probe [ 'pkg-config --exists libarchive' ];
17
18        share {
19
20          start_url 'http://libarchive.org/downloads/libarchive-3.2.2.tar.gz';
21
22          # the first one which succeeds will be used
23          download [ 'wget %{.meta.start_url}' ];
24          download [ 'curl -o %{.meta.start_url}' ];
25
26          extract [ 'tar xf %{.install.download}' ];
27
28          build [
29            # Note: will not work on Windows, better to use Build::Autoconf plugin
30            # if you need windows support
31            './configure --prefix=%{.install.prefix} --disable-shared',
32            '%{make}',
33            '%{make} install',
34          ];
35        }
36
37        gather [
38          [ 'pkg-config', '--modversion', 'libarchive', \'%{.runtime.version}' ],
39          [ 'pkg-config', '--cflags',     'libarchive', \'%{.runtime.cflags}'  ],
40          [ 'pkg-config', '--libs',       'libarchive', \'%{.runtime.libs}'    ],
41        ];
42
43       With plugins (better):
44
45        use alienfile;
46
47        plugin 'PkgConfig' => 'libarchive';
48
49        share {
50          start_url 'http://libarchive.org/downloads/';
51          plugin Download => (
52            filter => qr/^libarchive-.*\.tar\.gz$/,
53            version => qr/([0-9\.]+)/,
54          );
55          plugin Extract => 'tar.gz';
56          plugin 'Build::Autoconf';
57          plugin 'Gather::IsolateDynamic';
58          build [
59            '%{configure}',
60            '%{make}',
61            '%{make} install',
62          ];
63        };
64

DESCRIPTION

66       An alienfile is a recipe used by Alien::Build to, probe for system
67       libraries or download from the internet, and build source for those
68       libraries.  This document acts as reference for the alienfile system,
69       but if you are starting out writing your own Alien you should read
70       Alien::Build::Manual::AlienAuthor, which will teach you how to write
71       your own complete Alien using alienfile + Alien::Build +
72       ExtUtils::MakeMaker.  Special attention should be taken to the section
73       "a note about dynamic vs. static libraries".
74

DIRECTIVES

76   requires
77       "any" requirement (either share or system):
78
79        requires $module;
80        requires $module => $version;
81
82       configure time requirement:
83
84        configure {
85          requires $module;
86          requires $module => $version;
87        };
88
89       system requirement:
90
91        sys {
92          requires $module;
93          requires $module => $version;
94        };
95
96       share requirement:
97
98        share {
99          requires $module;
100          requires $module => $version;
101        };
102
103       specifies a requirement.  Alien::Build takes advantage of dynamic
104       requirements, so only modules that are needed for the specific type of
105       install need to be loaded.  Here are the different types of
106       requirements:
107
108       configure
109           Configure requirements should already be installed before the
110           alienfile is loaded.
111
112       any "Any" requirements are those that are needed either for the probe
113           stage, or in either the system or share installs.
114
115       share
116           Share requirements are those modules needed when downloading and
117           building from source.
118
119       system
120           System requirements are those modules needed when the system
121           provides the library or tool.
122
123   plugin
124        plugin $name => (%args);
125        plugin $name => $arg;
126
127       Load the given plugin.  If you prefix the plugin name with an "=" sign,
128       then it will be assumed to be a fully qualified path name.  Otherwise
129       the plugin will be assumed to live in the "Alien::Build::Plugin"
130       namespace.  If there is an appropriate negotiate plugin, that one will
131       be loaded.  Examples:
132
133        # Loads Alien::Build::Plugin::Fetch::Negotiate
134        # which will pick the best Alien::Build::Plugin::Fetch
135        # plugin based on the URL, and system configuration
136        plugin 'Fetch' => 'http://ftp.gnu.org/gnu/gcc';
137
138        # loads the plugin with the badly named class!
139        plugin '=Badly::Named::Plugin::Not::In::Alien::Build::Namespace';
140
141        # explicitly loads Alien::Build::Plugin::Prefer::SortVersions
142        plugin 'Prefer::SortVersions' => (
143          filter => qr/^gcc-.*\.tar\.gz$/,
144          version => qr/([0-9\.]+)/,
145        );
146
147   probe
148        probe \&code;
149        probe \@commandlist;
150
151       Instructions for the probe stage.  May be either a code reference, or a
152       command list.  Multiple probes and probe plugins can be given.  These
153       will be used in sequence, stopping at the first that detects a system
154       installation.  Alien::Build will use a share install if no system
155       installation is detected by the probes.
156
157   configure
158        configure {
159          ...
160        };
161
162       Configure block.  The only directive allowed in a configure block is
163       requires.
164
165   sys
166        sys {
167          ...
168        };
169
170       System block.  Allowed directives are: requires and gather.
171
172   share
173        share {
174          ...
175        };
176
177       System block.  Allowed directives are: download, fetch, decode, prefer,
178       extract, build, gather.
179
180   start_url
181        share {
182          start_url $url;
183        };
184
185       Set the start URL for download.  This should be the URL to an index
186       page, or the actual tarball of the source.
187
188   digest
189       [experimental]
190
191        share {
192          digest $algorithm, $digest;
193        };
194
195       Check fetched and downloaded files against the given algorithm and
196       digest.  Typically you will want to use SHA256 as the algorithm.
197
198   download
199        share {
200          download \&code;
201          download \@commandlist;
202        };
203
204       Instructions for the download stage.  May be either a code reference,
205       or a command list.
206
207   fetch
208        share {
209          fetch \&code;
210          fetch \@commandlist;
211        };
212
213       Instructions for the fetch stage.  May be either a code reference, or a
214       command list.
215
216   decode
217        share {
218          decode \&code;
219          decode \@commandlist;
220        };
221
222       Instructions for the decode stage.  May be either a code reference, or
223       a command list.
224
225   prefer
226        share {
227          prefer \&code;
228          prefer \@commandlist;
229        };
230
231       Instructions for the prefer stage.  May be either a code reference, or
232       a command list.
233
234   extract
235        share {
236          extract \&code;
237          extract \@commandlist;
238        };
239
240       Instructions for the extract stage.  May be either a code reference, or
241       a command list.
242
243   patch
244        share {
245          patch \&code;
246          patch \@commandlist;
247        };
248
249       Instructions for the patch stage.  May be either a code reference, or a
250       command list.
251
252   patch_ffi
253        share {
254          patch_ffi \&code;
255          patch_ffi \@commandlist;
256        };
257
258       [DEPRECATED]
259
260       Instructions for the patch_ffi stage.  May be either a code reference,
261       or a command list.
262
263   build
264        share {
265          build \&code;
266          build \@commandlist;
267        };
268
269       Instructions for the build stage.  May be either a code reference, or a
270       command list.
271
272   build_ffi
273        share {
274          build \&code;
275          build \@commandlist;
276        };
277
278       [DEPRECATED]
279
280       Instructions for the build FFI stage.  Builds shared libraries instead
281       of static.  This is optional, and is only necessary if a fresh and
282       separate build needs to be done for FFI.
283
284   gather
285        gather \&code;
286        gather \@commandlist;
287
288        share {
289          gather \&code;
290          gather \@commandlist;
291        };
292
293        sys {
294          gather \&code;
295          gather \@commandlist;
296        };
297
298       Instructions for the gather stage.  May be either a code reference, or
299       a command list.  In the root block of the alienfile it will trigger in
300       both share and system build.  In the share or sys block it will only
301       trigger in the corresponding build.
302
303   gather_ffi
304        share {
305          gather_ffi \&code;
306          gather_ffi \@commandlist;
307        }
308
309       [DEPRECATED]
310
311       Gather specific to "build_ffi".  Not usually necessary.
312
313   ffi
314        share {
315          ffi {
316            patch \&code;
317            patch \@commandlist;
318            build \&code;
319            build \@commandlist;
320            gather \&code;
321            gather \@commandlist;
322          }
323        }
324
325       Specify patch, build or gather stages related to FFI.
326
327   meta_prop
328        my $hash = meta_prop;
329
330       Get the meta_prop hash reference.
331
332   meta
333        my $meta = meta;
334
335       Returns the meta object for your alienfile.  For methods that can be
336       used on the meta object, see "META METHODS" in Alien::Build.
337
338   log
339        log($message);
340
341       Prints the given log to stdout.
342
343   test
344        share {
345          test \&code;
346          test \@commandlist;
347        };
348        sys {
349          test \&code;
350          test \@commandlist;
351        };
352
353       Run the tests
354
355   before
356        before $stage => \&code;
357
358       Execute the given code before the given stage.  Stage should be one of
359       "probe", "download", "fetch", "decode", "prefer", "extract", "patch",
360       "build", "test", and "gather".
361
362       The before directive is only legal in the same blocks as the stage
363       would normally be legal in.  For example, you can't do this:
364
365        use alienfile;
366
367        sys {
368          before 'build' => sub {
369            ...
370          };
371        };
372
373       Because a "build" wouldn't be legal inside a "sys" block.
374
375   after
376        after $stage => \&code;
377
378       Execute the given code after the given stage.  Stage should be one of
379       "probe", "download", "fetch", "decode", "prefer", "extract", "patch",
380       "build", "test", and "gather".
381
382       The after directive is only legal in the same blocks as the stage would
383       normally be legal in.  For example, you can't do this:
384
385        use alienfile;
386
387        sys {
388          after 'build' => sub {
389            ...
390          };
391        };
392
393       Because a "build" wouldn't be legal inside a "sys" block.
394

AUTHOR

402       Author: Graham Ollis <plicease@cpan.org>
403
404       Contributors:
405
406       Diab Jerius (DJERIUS)
407
408       Roy Storey (KIWIROY)
409
410       Ilya Pavlov
411
412       David Mertens (run4flat)
413
414       Mark Nunberg (mordy, mnunberg)
415
416       Christian Walde (Mithaldu)
417
418       Brian Wightman (MidLifeXis)
419
420       Zaki Mughal (zmughal)
421
422       mohawk (mohawk2, ETJ)
423
424       Vikas N Kumar (vikasnkumar)
425
426       Flavio Poletti (polettix)
427
428       Salvador Fandiño (salva)
429
430       Gianni Ceccarelli (dakkar)
431
432       Pavel Shaydo (zwon, trinitum)
433
434       Kang-min Liu (劉康民, gugod)
435
436       Nicholas Shipp (nshp)
437
438       Juan Julián Merelo Guervós (JJ)
439
440       Joel Berger (JBERGER)
441
442       Petr Písař (ppisar)
443
444       Lance Wicks (LANCEW)
445
446       Ahmad Fatoum (a3f, ATHREEF)
447
448       José Joaquín Atria (JJATRIA)
449
450       Duke Leto (LETO)
451
452       Shoichi Kaji (SKAJI)
453
454       Shawn Laffan (SLAFFAN)
455
456       Paul Evans (leonerd, PEVANS)
457
458       Håkon Hægland (hakonhagland, HAKONH)
459
460       nick nauwelaerts (INPHOBIA)
461
462       Florian Weimer
463

COPYRIGHT AND LICENSE

465       This software is copyright (c) 2011-2022 by Graham Ollis.
466
467       This is free software; you can redistribute it and/or modify it under
468       the same terms as the Perl 5 programming language system itself.
469
470
471
472perl v5.36.0                      2023-01-20                      alienfile(3)