1Alien::Build(3) User Contributed Perl Documentation Alien::Build(3)
2
6 Alien::Build - Build external dependencies for use in CPAN
7
9 version 1.55
10
12 my $build = Alien::Build->load('./alienfile');
13 $build->load_requires('configure');
14 $build->set_prefix('/usr/local');
15 $build->set_stage('/foo/mystage'); # needs to be absolute
16 $build->load_requires($build->install_type);
17 $build->download;
18 $build->build;
19 # files are now in /foo/mystage, it is your job (or
20 # ExtUtils::MakeMaker, Module::Build, etc) to copy
21 # those files into /usr/local
22
24 This module provides tools for building external (non-CPAN)
25 dependencies for CPAN. It is mainly designed to be used at install
26 time of a CPAN client, and work closely with Alien::Base which is used
27 at runtime.
28 This is the detailed documentation for the Alien::Build class. If you
30 are starting out you probably want to do so from one of these
31 documents:
32 Alien::Build::Manual::AlienUser
34 For users of an "Alien::libfoo" that is implemented using
35 Alien::Base. (The developer of "Alien::libfoo" should provide the
36 documentation necessary, but if not, this is the place to start).
37 Alien::Build::Manual::AlienAuthor
39 If you are writing your own Alien based on Alien::Build and
40 Alien::Base.
41 Alien::Build::Manual::FAQ
43 If you have a common question that has already been answered, like
44 "How do I use alienfile with some build system".
45 Alien::Build::Manual::PluginAuthor
47 This is for the brave souls who want to write plugins that will
48 work with Alien::Build + alienfile.
49 Note that you will not usually create a Alien::Build instance directly,
51 but rather be using a thin installer layer, such as Alien::Build::MM
52 (for use with ExtUtils::MakeMaker) or Alien::Build::MB (for use with
53 Module::Build). One of the goals of this project is to remain
54 installer agnostic.
55
57 new
58 my $build = Alien::Build->new;
59 This creates a new empty instance of Alien::Build. Normally you will
61 want to use "load" below to create an instance of Alien::Build from an
62 alienfile recipe.
63
65 There are three main properties for Alien::Build. There are a number
66 of properties documented here with a specific usage. Note that these
67 properties may need to be serialized into something primitive like JSON
68 that does not support: regular expressions, code references of blessed
69 objects.
70 If you are writing a plugin (Alien::Build::Plugin) you should use a
72 prefix like "plugin_name" (where name is the name of your plugin) so
73 that it does not interfere with other plugin or future versions of
74 Alien::Build. For example, if you were writing
75 "Alien::Build::Plugin::Fetch::NewProtocol", please use the prefix
76 "plugin_fetch_newprotocol":
77 sub init
79 {
80 my($self, $meta) = @_;
81 $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
83 $meta->register_hook(
85 some_hook => sub {
86 my($build) = @_;
87 $build->install_prop->{plugin_fetch_newprotocol_bar} = 'some other value';
88 $build->runtime_prop->{plugin_fetch_newprotocol_baz} = 'and another value';
89 }
90 );
91 }
92 If you are writing a alienfile recipe please use the prefix "my_":
94 use alienfile;
96 meta_prop->{my_foo} = 'some value';
98 probe sub {
100 my($build) = @_;
101 $build->install_prop->{my_bar} = 'some other value';
102 $build->install_prop->{my_baz} = 'and another value';
103 };
104 Any property may be used from a command:
106 probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
108 probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
109 probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
110 probe [ 'some command %{.meta.my_foo}' ];
111 probe [ 'some command %{.install.my_bar}' ];
112 probe [ 'some command %{.runtime.my_baz}' ];
113 meta_prop
115 my $href = $build->meta_prop;
116 my $href = Alien::Build->meta_prop;
117 Meta properties have to do with the recipe itself, and not any
119 particular instance that probes or builds that recipe. Meta properties
120 can be changed from within an alienfile using the "meta_prop"
121 directive, or from a plugin from its "init" method (though should NOT
122 be modified from any hooks registered within that "init" method). This
123 is not strictly enforced, but if you do not follow this rule your
124 recipe will likely be broken.
125 arch
127 This is a hint to an installer like Alien::Build::MM or
128 Alien::Build::MB, that the library or tool contains architecture
129 dependent files and so should be stored in an architecture
130 dependent location. If not specified by your alienfile then it
131 will be set to true.
132 destdir
134 Use the "DESTDIR" environment variable to stage your install before
135 copying the files into "blib". This is the preferred method of
136 installing libraries because it improves reliability. This
137 technique is supported by "autoconf" and others.
138 destdir_filter
140 Regular expression for the files that should be copied from the
141 "DESTDIR" into the stage directory. If not defined, then all files
142 will be copied.
143 destdir_ffi_filter
145 Same as "destdir_filter" except applies to "build_ffi" instead of
146 "build".
147 env Environment variables to override during the build stage.
149 env_interpolate
151 Environment variable values will be interpolated with helpers.
152 Example:
153 meta->prop->{env_interpolate} = 1;
155 meta->prop->{env}->{PERL} = '%{perl}';
156 local_source
158 Set to true if source code package is available locally. (that is
159 not fetched over the internet). This is computed by default based
160 on the "start_url" property. Can be set by an alienfile or plugin.
161 platform
163 Hash reference. Contains information about the platform beyond
164 just $^O.
165 compiler_type
167 Refers to the type of flags that the compiler accepts. May be
168 expanded in the future, but for now, will be one of:
169 microsoft
171 On Windows when using Microsoft Visual C++
172 unix
174 Virtually everything else, including gcc on windows.
175 The main difference is that with Visual C++ "-LIBPATH" should
177 be used instead of "-L", and static libraries should have the
178 ".LIB" suffix instead of ".a".
179 system_type
181 $^O is frequently good enough to make platform specific logic
182 in your alienfile, this handles the case when $^O can cover
183 platforms that provide multiple environments that Perl might
184 run under. The main example is windows, but others may be
185 added in the future.
186 unix
188 vms
189 windows-activestate
190 windows-microsoft
191 windows-mingw
192 windows-strawberry
193 windows-unknown
194 Note that "cygwin" and "msys" are considered "unix" even though
196 they run on windows!
197 out_of_source
199 Build in a different directory from the where the source code is
200 stored. In autoconf this is referred to as a "VPATH" build.
201 Everyone else calls this an "out-of-source" build. When this
202 property is true, instead of extracting to the source build root,
203 the downloaded source will be extracted to an source extraction
204 directory and the source build root will be empty. You can use the
205 "extract" install property to get the location of the extracted
206 source.
207 network
209 True if a network fetch is available. This should NOT be set by an
210 alienfile or plugin. This is computed based on the
211 "ALIEN_INSTALL_NETWORK" environment variables.
212 start_url
214 The default or start URL used by fetch plugins.
215 install_prop
217 my $href = $build->install_prop;
218 Install properties are used during the install phase (either under
220 "share" or "system" install). They are remembered for the entire
221 install phase, but not kept around during the runtime phase. Thus they
222 cannot be accessed from your Alien::Base based module.
223 autoconf_prefix
225 The prefix as understood by autoconf. This is only different on
226 Windows Where MSYS is used and paths like "C:/foo" are represented
227 as "/C/foo" which are understood by the MSYS tools, but not by
228 Perl. You should only use this if you are using
229 Alien::Build::Plugin::Autoconf in your alienfile.
230 download
232 The location of the downloaded archive (tar.gz, or similar) or
233 directory.
234 env Environment variables to override during the build stage.
236 extract
238 The location of the last source extraction. For a "out-of-source"
239 build (see the "out_of_source" meta property above), this will only
240 be set once. For other types of builds, the source code may be
241 extracted multiple times, and thus this property may change.
242 old Hash containing information on a previously installed Alien of the
244 same name, if available. This may be useful in cases where you
245 want to reuse the previous install if it is still sufficient.
246 prefix
248 The prefix for the previous install. Versions prior to 1.42
249 unfortunately had this in typo form of "preifx".
250 runtime
252 The runtime properties from the previous install.
253 patch
255 Directory with patches.
256 prefix
258 The install time prefix. Under a "destdir" install this is the
259 same as the runtime or final install location. Under a
260 non-"destdir" install this is the "stage" directory (usually the
261 appropriate share directory under "blib").
262 root
264 The build root directory. This will be an absolute path. It is
265 the absolute form of "./_alien" by default.
266 stage
268 The stage directory where files will be copied. This is usually
269 the root of the blib share directory.
270 runtime_prop
272 my $href = $build->runtime_prop;
273 Runtime properties are used during the install and runtime phases
275 (either under "share" or "system" install). This should include
276 anything that you will need to know to use the library or tool during
277 runtime, and shouldn't include anything that is no longer relevant once
278 the install process is complete.
279 alien_build_version
281 The version of Alien::Build used to install the library or tool.
282 alt Alternate configurations. If the alienized package has multiple
284 libraries this could be used to store the different compiler or
285 linker flags for each library.
286 cflags
288 The compiler flags
289 cflags_static
291 The static compiler flags
292 command
294 The command name for tools where the name my differ from platform
295 to platform. For example, the GNU version of make is usually
296 "make" in Linux and "gmake" on FreeBSD.
297 ffi_name
299 The name DLL or shared object "name" to use when searching for
300 dynamic libraries at runtime. This is passed into FFI::CheckLib,
301 so if your library is something like "libarchive.so" or
302 "archive.dll" you would set this to "archive". This may be a
303 string or an array of strings.
304 install_type
306 The install type. Is one of:
307 system
309 For when the library or tool is provided by the operating
310 system, can be detected by Alien::Build, and is considered
311 satisfactory by the "alienfile" recipe.
312 share
314 For when a system install is not possible, the library source
315 will be downloaded from the internet or retrieved in another
316 appropriate fashion and built.
317 libs
319 The library flags
320 libs_static
322 The static library flags
323 perl_module_version
325 The version of the Perl module used to install the alien (if
326 available). For example if Alien::curl is installing "libcurl"
327 this would be the version of Alien::curl used during the install
328 step.
329 prefix
331 The final install root. This is usually they share directory.
332 version
334 The version of the library or tool
335 hook_prop
337 my $href = $build->hook_prop;
338 Hook properties are for the currently running (if any) hook. They are
340 used only during the execution of each hook and are discarded after.
341 If no hook is currently running then "hook_prop" will return "undef".
342 name
344 The name of the currently running hook.
345
347 load
348 my $build = Alien::Build->load($alienfile);
349 This creates an Alien::Build instance with the given alienfile recipe.
351 checkpoint
353 $build->checkpoint;
354 Save any install or runtime properties so that they can be reloaded on
356 a subsequent run. This is useful if your build needs to be done in
357 multiple stages from a "Makefile", such as with ExtUtils::MakeMaker.
358 resume
360 my $build = Alien::Build->resume($alienfile, $root);
361 Load a checkpointed Alien::Build instance. You will need the original
363 alienfile and the build root (usually "_alien").
364 root
366 my $dir = $build->root;
367 This is just a shortcut for:
369 my $root = $build->install_prop->{root};
371 Except that it will be created if it does not already exist.
373 install_type
375 my $type = $build->install_type;
376 This will return the install type. (See the like named install
378 property above for details). This method will call "probe" if it has
379 not already been called.
380 set_prefix
382 $build->set_prefix($prefix);
383 Set the final (unstaged) prefix. This is normally only called by
385 Alien::Build::MM and similar modules. It is not intended for use from
386 plugins or from an alienfile.
387 set_stage
389 $build->set_stage($dir);
390 Sets the stage directory. This is normally only called by
392 Alien::Build::MM and similar modules. It is not intended for use from
393 plugins or from an alienfile.
394 requires
396 my $hash = $build->requires($phase);
397 Returns a hash reference of the modules required for the given phase.
399 Phases include:
400 configure
402 These modules must already be available when the alienfile is read.
403 any These modules are used during either a "system" or "share" install.
405 share
407 These modules are used during the build phase of a "share" install.
408 system
410 These modules are used during the build phase of a "system"
411 install.
412 load_requires
414 $build->load_requires($phase);
415 This loads the appropriate modules for the given phase (see "requires"
417 above for a description of the phases).
418 probe
420 my $install_type = $build->probe;
421 Attempts to determine if the operating system has the library or tool
423 already installed. If so, then the string "system" will be returned
424 and a system install will be performed. If not, then the string
425 "share" will be installed and the tool or library will be downloaded
426 and built from source.
427 If the environment variable "ALIEN_INSTALL_TYPE" is set, then that will
429 force a specific type of install. If the detection logic cannot
430 accommodate the install type requested then it will fail with an
431 exception.
432 download
434 $build->download;
435 Download the source, usually as a tarball, usually from the internet.
437 Under a "system" install this does not do anything.
439 fetch
441 my $res = $build->fetch;
442 my $res = $build->fetch($url);
443 Fetch a resource using the fetch hook. Returns the same hash structure
445 described below in the hook documentation.
446 decode
448 my $decoded_res = $build->decode($res);
449 Decode the HTML or file listing returned by "fetch". Returns the same
451 hash structure described below in the hook documentation.
452 prefer
454 my $sorted_res = $build->prefer($res);
455 Filter and sort candidates. The preferred candidate will be returned
457 first in the list. The worst candidate will be returned last. Returns
458 the same hash structure described below in the hook documentation.
459 extract
461 my $dir = $build->extract;
462 my $dir = $build->extract($archive);
463 Extracts the given archive into a fresh directory. This is normally
465 called internally to Alien::Build, and for normal usage is not needed
466 from a plugin or alienfile.
467 build
469 $build->build;
470 Run the build step. It is expected that "probe" and "download" have
472 already been performed. What it actually does depends on the type of
473 install:
474 share
476 The source is extracted, and built as determined by the alienfile
477 recipe. If there is a "gather_share" that will be executed last.
478 system
480 The "gather_system" hook will be executed.
481 test
483 $build->test;
484 Run the test phase
486 system
488 $build->system($command);
489 $build->system($command, @args);
490 Interpolates the command and arguments and run the results using the
492 Perl "system" command.
493 log
495 $build->log($message);
496 Send a message to the log. By default this prints to "STDOUT".
498 meta
500 my $meta = Alien::Build->meta;
501 my $meta = $build->meta;
502 Returns the meta object for your Alien::Build class or instance. The
504 meta object is a way to manipulate the recipe, and so any changes to
505 the meta object should be made before the "probe", "download" or
506 "build" steps.
507
509 prop
510 my $href = $build->meta->prop;
511 Meta properties. This is the same as calling "meta_prop" on the class
513 or Alien::Build instance.
514 add_requires
516 Alien::Build->meta->add_requires($phase, $module => $version, ...);
517 Add the requirement to the given phase. Phase should be one of:
519 configure
521 any
522 share
523 system
524 interpolator
526 my $interpolator = $build->meta->interpolator;
527 my $interpolator = Alien::Build->interpolator;
528 Returns the Alien::Build::Interpolate instance for the Alien::Build
530 class.
531 has_hook
533 my $bool = $build->meta->has_hook($name);
534 my $bool = Alien::Build->has_hook($name);
535 Returns if there is a usable hook registered with the given name.
537 register_hook
539 $build->meta->register_hook($name, $instructions);
540 Alien::Build->meta->register_hook($name, $instructions);
541 Register a hook with the given name. $instruction should be either a
543 code reference, or a command sequence, which is an array reference.
544 default_hook
546 $build->meta->default_hook($name, $instructions);
547 Alien::Build->meta->default_hook($name, $instructions);
548 Register a default hook, which will be used if the alienfile does not
550 register its own hook with that name.
551 around_hook
553 $build->meta->around_hook($hook, $code);
554 Alien::Build->meta->around_hook($name, $code);
555 Wrap the given hook with a code reference. This is similar to a Moose
557 method modifier, except that it wraps around the given hook instead of
558 a method. For example, this will add a probe system requirement:
559 $build->meta->around_hook(
561 probe => sub {
562 my $orig = shift;
563 my $build = shift;
564 my $type = $orig->($build, @_);
565 return $type unless $type eq 'system';
566 # also require a configuration file
567 if(-f '/etc/foo.conf')
568 {
569 return 'system';
570 }
571 else
572 {
573 return 'share';
574 }
575 },
576 );
577 apply_plugin
579 Alien::Build->meta->apply_plugin($name);
580 Alien::Build->meta->apply_plugin($name, @args);
581 Apply the given plugin with the given arguments.
583
585 Alien::Build responds to these environment variables:
586 ALIEN_INSTALL_NETWORK
588 If set to true (the default), then network fetch will be allowed.
589 If set to false, then network fetch will not be allowed.
590 What constitutes a local vs. network fetch is determined based on
592 the "start_url" and "local_source" meta properties. An alienfile
593 or plugin "could" override this detection (possibly
594 inappropriately), so this variable is not a substitute for properly
595 auditing of Perl modules for environments that require that.
596 ALIEN_INSTALL_TYPE
598 If set to "share" or "system", it will override the system
599 detection logic. If set to "default", it will use the default
600 setting for the alienfile. The behavior of other values is
601 undefined.
602 ALIEN_BUILD_RC
604 Perl source file which can override some global defaults for
605 Alien::Build, by, for example, setting preload and postload
606 plugins.
607 ALIEN_BUILD_PKG_CONFIG
609 Override the logic in Alien::Build::Plugin::PkgConfig::Negotiate
610 which chooses the best "pkg-config" plugin.
611 ALIEN_BUILD_PRELOAD
613 semicolon separated list of plugins to automatically load before
614 parsing your alienfile.
615 ALIEN_BUILD_POSTLOAD
617 semicolon separated list of plugins to automatically load after
618 parsing your alienfile.
619 DESTDIR
621 This environment variable will be manipulated during a destdir
622 install.
623 PKG_CONFIG
625 This environment variable can be used to override the program name
626 for "pkg-config" when using the command line plugin:
627 Alien::Build::Plugin::PkgConfig::CommandLine.
628 ftp_proxy, all_proxy
630 If these environment variables are set, it may influence the
631 Download negotiation plugin
632 Alien::Build::Plugin::Downaload::Negotiate. Other proxy variables
633 may be used by some Fetch plugins, if they support it.
634
636 The intent of the "Alien-Build" team is to support as best as possible
637 all Perls from 5.8.1 to the latest production version. So long as they
638 are also supported by the Perl toolchain.
639 Please feel encouraged to report issues that you encounter to the
641 project GitHub Issue tracker:
642 <https://github.com/Perl5-Alien/Alien-Build/issues>
644 Better if you can fix the issue yourself, please feel encouraged to
646 open pull-request on the project GitHub:
647 <https://github.com/Perl5-Alien/Alien-Build/pulls>
649 If you are confounded and have questions, join us on the "#native"
651 channel on irc.perl.org. The "Alien-Build" developers frequent this
652 channel and can probably help point you in the right direction. If you
653 don't have an IRC client handy, you can use this web interface:
654 <https://chat.mibbit.com/?channel=%23native&server=irc.perl.org>
656
658 Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser,
659 Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ,
660 Alien::Build::Manual::PluginAuthor
661 alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
663
665 Alien::Base was originally written by Joel Berger, the rest of this
666 project would not have been possible without him getting the project
667 started. Thanks to his support I have been able to augment the
668 original Alien::Base system with a reliable set of tools (Alien::Build,
669 alienfile, Test::Alien), which make up this toolset.
670 The original Alien::Base is still copyright (c) 2012-2017 Joel Berger.
672 It has the same license as the rest of the Alien::Build and related
673 tools distributed as "Alien-Build". Joel Berger thanked a number of
674 people who helped in in the development of Alien::Base, in the
675 documentation for that module.
676 I would also like to acknowledge the other members of the Perl5-Alien
678 github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk
679 (ETJ). Also important in the early development of Alien::Build were
680 the early adopters Chase Whitener (genio, CAPOEIRAB, author of
681 Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author
682 of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF,
683 author of Alien::libudev and Alien::LibUSB).
684
686 Author: Graham Ollis <plicease@cpan.org>
687 Contributors:
689 Diab Jerius (DJERIUS)
691 Roy Storey
693 Ilya Pavlov
695 David Mertens (run4flat)
697 Mark Nunberg (mordy, mnunberg)
699 Christian Walde (Mithaldu)
701 Brian Wightman (MidLifeXis)
703 Zaki Mughal (zmughal)
705 mohawk (mohawk2, ETJ)
707 Vikas N Kumar (vikasnkumar)
709 Flavio Poletti (polettix)
711 Salvador Fandiño (salva)
713 Gianni Ceccarelli (dakkar)
715 Pavel Shaydo (zwon, trinitum)
717 Kang-min Liu (劉康民, gugod)
719 Nicholas Shipp (nshp)
721 Juan Julián Merelo Guervós (JJ)
723 Joel Berger (JBERGER)
725 Petr Pisar (ppisar)
727 Lance Wicks (LANCEW)
729 Ahmad Fatoum (a3f, ATHREEF)
731 José Joaquín Atria (JJATRIA)
733 Duke Leto (LETO)
735 Shoichi Kaji (SKAJI)
737 Shawn Laffan (SLAFFAN)
739 Paul Evans (leonerd, PEVANS)
741
743 This software is copyright (c) 2011-2018 by Graham Ollis.
744 This is free software; you can redistribute it and/or modify it under
746 the same terms as the Perl 5 programming language system itself.
747perl v5.28.1 2019-02-24 Alien::Build(3)