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.45
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.
153
154   configure
155        configure {
156          ...
157        };
158
159       Configure block.  The only directive allowed in a configure block is
160       requires.
161
162   sys
163        sys {
164          ...
165        };
166
167       System block.  Allowed directives are: requires and gather.
168
169   share
170        share {
171          ...
172        };
173
174       System block.  Allowed directives are: download, fetch, decode, prefer,
175       extract, build, gather.
176
177   start_url
178        share {
179          start_url $url;
180        };
181
182       Set the start URL for download.  This should be the URL to an index
183       page, or the actual tarball of the source.
184
185   download
186        share {
187          download \&code;
188          download \@commandlist;
189        };
190
191       Instructions for the download stage.  May be either a code reference,
192       or a command list.
193
194   fetch
195        share {
196          fetch \&code;
197          fetch \@commandlist;
198        };
199
200       Instructions for the fetch stage.  May be either a code reference, or a
201       command list.
202
203   decode
204        share {
205          decode \&code;
206          decode \@commandlist;
207        };
208
209       Instructions for the decode stage.  May be either a code reference, or
210       a command list.
211
212   prefer
213        share {
214          prefer \&code;
215          prefer \@commandlist;
216        };
217
218       Instructions for the prefer stage.  May be either a code reference, or
219       a command list.
220
221   extract
222        share {
223          extract \&code;
224          extract \@commandlist;
225        };
226
227       Instructions for the extract stage.  May be either a code reference, or
228       a command list.
229
230   patch
231        share {
232          patch \&code;
233          patch \@commandlist;
234        };
235
236       Instructions for the patch stage.  May be either a code reference, or a
237       command list.
238
239   patch_ffi
240        share {
241          patch_ffi \&code;
242          patch_ffi \@commandlist;
243        };
244
245       [DEPRECATED]
246
247       Instructions for the patch_ffi stage.  May be either a code reference,
248       or a command list.
249
250   build
251        share {
252          build \&code;
253          build \@commandlist;
254        };
255
256       Instructions for the build stage.  May be either a code reference, or a
257       command list.
258
259   build_ffi
260        share {
261          build \&code;
262          build \@commandlist;
263        };
264
265       [DEPRECATED]
266
267       Instructions for the build FFI stage.  Builds shared libraries instead
268       of static.  This is optional, and is only necessary if a fresh and
269       separate build needs to be done for FFI.
270
271   gather
272        gather \&code;
273        gather \@commandlist;
274
275        share {
276          gather \&code;
277          gather \@commandlist;
278        };
279
280        sys {
281          gather \&code;
282          gather \@commandlist;
283        };
284
285       Instructions for the gather stage.  May be either a code reference, or
286       a command list.  In the root block of the alienfile it will trigger in
287       both share and system build.  In the share or sys block it will only
288       trigger in the corresponding build.
289
290   gather_ffi
291        share {
292          gather_ffi \&code;
293          gather_ffi \@commandlist;
294        }
295
296       [DEPRECATED]
297
298       Gather specific to "build_ffi".  Not usually necessary.
299
300   ffi
301        share {
302          ffi {
303            patch \&code;
304            patch \@commandlist;
305            build \&code;
306            build \@commandlist;
307            gather \&code;
308            gather \@commandlist;
309          }
310        }
311
312       Specify patch, build or gather stages related to FFI.
313
314   meta_prop
315        my $hash = meta_prop;
316
317       Get the meta_prop hash reference.
318
319   meta
320        my $meta = meta;
321
322       Returns the meta object for your alienfile.
323
324   log
325        log($message);
326
327       Prints the given log to stdout.
328
329   test
330        share {
331          test \&code;
332          test \@commandlist;
333        };
334        sys {
335          test \&code;
336          test \@commandlist;
337        };
338
339       Run the tests
340
341   before
342        before $stage => \&code;
343
344       Execute the given code before the given stage.  Stage should be one of
345       "probe", "download", "fetch", "decode", "prefer", "extract", "patch",
346       "build", "test", and "gather".
347
348       The before directive is only legal in the same blocks as the stage
349       would normally be legal in.  For example, you can't do this:
350
351        use alienfile;
352
353        sys {
354          before 'build' => sub {
355            ...
356          };
357        };
358
359       Because a "build" wouldn't be legal inside a "sys" block.
360
361   after
362        after $stage => \&code;
363
364       Execute the given code after the given stage.  Stage should be one of
365       "probe", "download", "fetch", "decode", "prefer", "extract", "patch",
366       "build", "test", and "gather".
367
368       The after directive is only legal in the same blocks as the stage would
369       normally be legal in.  For example, you can't do this:
370
371        use alienfile;
372
373        sys {
374          after 'build' => sub {
375            ...
376          };
377        };
378
379       Because a "build" wouldn't be legal inside a "sys" block.
380

AUTHOR

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

COPYRIGHT AND LICENSE

449       This software is copyright (c) 2011-2020 by Graham Ollis.
450
451       This is free software; you can redistribute it and/or modify it under
452       the same terms as the Perl 5 programming language system itself.
453
454
455
456perl v5.34.0                      2021-10-29                      alienfile(3)