1Alien::Build(3) User Contributed Perl Documentation Alien::Build(3)
2
6 Alien::Build - Build external dependencies for use in CPAN
7
9 version 2.17
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::Alien
34 A broad overview of "Alien-Build" and its ecosystem.
35 Alien::Build::Manual::AlienUser
37 For users of an "Alien::libfoo" that is implemented using
38 Alien::Base. (The developer of "Alien::libfoo" should provide the
39 documentation necessary, but if not, this is the place to start).
40 Alien::Build::Manual::AlienAuthor
42 If you are writing your own Alien based on Alien::Build and
43 Alien::Base.
44 Alien::Build::Manual::FAQ
46 If you have a common question that has already been answered, like
47 "How do I use alienfile with some build system".
48 Alien::Build::Manual::PluginAuthor
50 This is for the brave souls who want to write plugins that will
51 work with Alien::Build + alienfile.
52 Note that you will not usually create a Alien::Build instance directly,
54 but rather be using a thin installer layer, such as Alien::Build::MM
55 (for use with ExtUtils::MakeMaker) or Alien::Build::MB (for use with
56 Module::Build). One of the goals of this project is to remain
57 installer agnostic.
58
60 new
61 my $build = Alien::Build->new;
62 This creates a new empty instance of Alien::Build. Normally you will
64 want to use "load" below to create an instance of Alien::Build from an
65 alienfile recipe.
66 load
68 my $build = Alien::Build->load($alienfile);
69 This creates an Alien::Build instance with the given alienfile recipe.
71 resume
73 my $build = Alien::Build->resume($alienfile, $root);
74 Load a checkpointed Alien::Build instance. You will need the original
76 alienfile and the build root (usually "_alien"), and a build that had
77 been properly checkpointed using the "checkpoint" method below.
78
80 There are three main properties for Alien::Build. There are a number
81 of properties documented here with a specific usage. Note that these
82 properties may need to be serialized into something primitive like JSON
83 that does not support: regular expressions, code references of blessed
84 objects.
85 If you are writing a plugin (Alien::Build::Plugin) you should use a
87 prefix like "plugin_name" (where name is the name of your plugin) so
88 that it does not interfere with other plugin or future versions of
89 Alien::Build. For example, if you were writing
90 "Alien::Build::Plugin::Fetch::NewProtocol", please use the prefix
91 "plugin_fetch_newprotocol":
92 sub init
94 {
95 my($self, $meta) = @_;
96 $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
98 $meta->register_hook(
100 some_hook => sub {
101 my($build) = @_;
102 $build->install_prop->{plugin_fetch_newprotocol_bar} = 'some other value';
103 $build->runtime_prop->{plugin_fetch_newprotocol_baz} = 'and another value';
104 }
105 );
106 }
107 If you are writing a alienfile recipe please use the prefix "my_":
109 use alienfile;
111 meta_prop->{my_foo} = 'some value';
113 probe sub {
115 my($build) = @_;
116 $build->install_prop->{my_bar} = 'some other value';
117 $build->install_prop->{my_baz} = 'and another value';
118 };
119 Any property may be used from a command:
121 probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
123 probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
124 probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
125 probe [ 'some command %{.meta.my_foo}' ];
126 probe [ 'some command %{.install.my_bar}' ];
127 probe [ 'some command %{.runtime.my_baz}' ];
128 meta_prop
130 my $href = $build->meta_prop;
131 my $href = Alien::Build->meta_prop;
132 Meta properties have to do with the recipe itself, and not any
134 particular instance that probes or builds that recipe. Meta properties
135 can be changed from within an alienfile using the "meta_prop"
136 directive, or from a plugin from its "init" method (though should NOT
137 be modified from any hooks registered within that "init" method). This
138 is not strictly enforced, but if you do not follow this rule your
139 recipe will likely be broken.
140 arch
142 This is a hint to an installer like Alien::Build::MM or
143 Alien::Build::MB, that the library or tool contains architecture
144 dependent files and so should be stored in an architecture
145 dependent location. If not specified by your alienfile then it
146 will be set to true.
147 destdir
149 Use the "DESTDIR" environment variable to stage your install before
150 copying the files into "blib". This is the preferred method of
151 installing libraries because it improves reliability. This
152 technique is supported by "autoconf" and others.
153 destdir_filter
155 Regular expression for the files that should be copied from the
156 "DESTDIR" into the stage directory. If not defined, then all files
157 will be copied.
158 destdir_ffi_filter
160 Same as "destdir_filter" except applies to "build_ffi" instead of
161 "build".
162 env Environment variables to override during the build stage.
164 env_interpolate
166 Environment variable values will be interpolated with helpers.
167 Example:
168 meta->prop->{env_interpolate} = 1;
170 meta->prop->{env}->{PERL} = '%{perl}';
171 local_source
173 Set to true if source code package is available locally. (that is
174 not fetched over the internet). This is computed by default based
175 on the "start_url" property. Can be set by an alienfile or plugin.
176 platform
178 Hash reference. Contains information about the platform beyond
179 just $^O.
180 compiler_type
182 Refers to the type of flags that the compiler accepts. May be
183 expanded in the future, but for now, will be one of:
184 microsoft
186 On Windows when using Microsoft Visual C++
187 unix
189 Virtually everything else, including gcc on windows.
190 The main difference is that with Visual C++ "-LIBPATH" should
192 be used instead of "-L", and static libraries should have the
193 ".LIB" suffix instead of ".a".
194 system_type
196 $^O is frequently good enough to make platform specific logic
197 in your alienfile, this handles the case when $^O can cover
198 platforms that provide multiple environments that Perl might
199 run under. The main example is windows, but others may be
200 added in the future.
201 unix
203 vms
204 windows-activestate
205 windows-microsoft
206 windows-mingw
207 windows-strawberry
208 windows-unknown
209 Note that "cygwin" and "msys" are considered "unix" even though
211 they run on windows!
212 out_of_source
214 Build in a different directory from the where the source code is
215 stored. In autoconf this is referred to as a "VPATH" build.
216 Everyone else calls this an "out-of-source" build. When this
217 property is true, instead of extracting to the source build root,
218 the downloaded source will be extracted to an source extraction
219 directory and the source build root will be empty. You can use the
220 "extract" install property to get the location of the extracted
221 source.
222 network
224 True if a network fetch is available. This should NOT be set by an
225 alienfile or plugin. This is computed based on the
226 "ALIEN_INSTALL_NETWORK" environment variables.
227 start_url
229 The default or start URL used by fetch plugins.
230 install_prop
232 my $href = $build->install_prop;
233 Install properties are used during the install phase (either under
235 "share" or "system" install). They are remembered for the entire
236 install phase, but not kept around during the runtime phase. Thus they
237 cannot be accessed from your Alien::Base based module.
238 autoconf_prefix
240 The prefix as understood by autoconf. This is only different on
241 Windows Where MSYS is used and paths like "C:/foo" are represented
242 as "/C/foo" which are understood by the MSYS tools, but not by
243 Perl. You should only use this if you are using
244 Alien::Build::Plugin::Autoconf in your alienfile.
245 download
247 The location of the downloaded archive (tar.gz, or similar) or
248 directory.
249 env Environment variables to override during the build stage.
251 extract
253 The location of the last source extraction. For a "out-of-source"
254 build (see the "out_of_source" meta property above), this will only
255 be set once. For other types of builds, the source code may be
256 extracted multiple times, and thus this property may change.
257 old Hash containing information on a previously installed Alien of the
259 same name, if available. This may be useful in cases where you
260 want to reuse the previous install if it is still sufficient.
261 prefix
263 The prefix for the previous install. Versions prior to 1.42
264 unfortunately had this in typo form of "preifx".
265 runtime
267 The runtime properties from the previous install.
268 patch
270 Directory with patches.
271 prefix
273 The install time prefix. Under a "destdir" install this is the
274 same as the runtime or final install location. Under a
275 non-"destdir" install this is the "stage" directory (usually the
276 appropriate share directory under "blib").
277 root
279 The build root directory. This will be an absolute path. It is
280 the absolute form of "./_alien" by default.
281 stage
283 The stage directory where files will be copied. This is usually
284 the root of the blib share directory.
285 runtime_prop
287 my $href = $build->runtime_prop;
288 Runtime properties are used during the install and runtime phases
290 (either under "share" or "system" install). This should include
291 anything that you will need to know to use the library or tool during
292 runtime, and shouldn't include anything that is no longer relevant once
293 the install process is complete.
294 alien_build_version
296 The version of Alien::Build used to install the library or tool.
297 alt Alternate configurations. If the alienized package has multiple
299 libraries this could be used to store the different compiler or
300 linker flags for each library.
301 cflags
303 The compiler flags
304 cflags_static
306 The static compiler flags
307 command
309 The command name for tools where the name my differ from platform
310 to platform. For example, the GNU version of make is usually
311 "make" in Linux and "gmake" on FreeBSD.
312 ffi_name
314 The name DLL or shared object "name" to use when searching for
315 dynamic libraries at runtime. This is passed into FFI::CheckLib,
316 so if your library is something like "libarchive.so" or
317 "archive.dll" you would set this to "archive". This may be a
318 string or an array of strings.
319 ffi_checklib
321 This property contains two sub properties:
322 share
324 $build->runtime_prop->{ffi_checklib}->{share} = [ ... ];
325 Array of additional FFI::CheckLib flags to pass in to
327 "find_lib" for a "share" install.
328 system
330 Array of additional FFI::CheckLib flags to pass in to
331 "find_lib" for a "system" install.
332 Among other things, useful for specifying the
334 "try_linker_script" flag:
335 $build->runtime_prop->{ffi_checklib}->{system} = [ try_linker_script => 1 ];
337 install_type
339 The install type. Is one of:
340 system
342 For when the library or tool is provided by the operating
343 system, can be detected by Alien::Build, and is considered
344 satisfactory by the "alienfile" recipe.
345 share
347 For when a system install is not possible, the library source
348 will be downloaded from the internet or retrieved in another
349 appropriate fashion and built.
350 libs
352 The library flags
353 libs_static
355 The static library flags
356 perl_module_version
358 The version of the Perl module used to install the alien (if
359 available). For example if Alien::curl is installing "libcurl"
360 this would be the version of Alien::curl used during the install
361 step.
362 prefix
364 The final install root. This is usually they share directory.
365 version
367 The version of the library or tool
368 hook_prop
370 my $href = $build->hook_prop;
371 Hook properties are for the currently running (if any) hook. They are
373 used only during the execution of each hook and are discarded after.
374 If no hook is currently running then "hook_prop" will return "undef".
375 name
377 The name of the currently running hook.
378 version (probe)
380 Probe and PkgConfig plugins may set this property indicating the
381 version of the alienized package. Not all plugins and
382 configurations may be able to provide this.
383
385 checkpoint
386 $build->checkpoint;
387 Save any install or runtime properties so that they can be reloaded on
389 a subsequent run in a separate process. This is useful if your build
390 needs to be done in multiple stages from a "Makefile", such as with
391 ExtUtils::MakeMaker. Once checkpointed you can use the "resume"
392 constructor (documented above) to resume the probe/build/install]
393 process.
394 root
396 my $dir = $build->root;
397 This is just a shortcut for:
399 my $root = $build->install_prop->{root};
401 Except that it will be created if it does not already exist.
403 install_type
405 my $type = $build->install_type;
406 This will return the install type. (See the like named install
408 property above for details). This method will call "probe" if it has
409 not already been called.
410 set_prefix
412 $build->set_prefix($prefix);
413 Set the final (unstaged) prefix. This is normally only called by
415 Alien::Build::MM and similar modules. It is not intended for use from
416 plugins or from an alienfile.
417 set_stage
419 $build->set_stage($dir);
420 Sets the stage directory. This is normally only called by
422 Alien::Build::MM and similar modules. It is not intended for use from
423 plugins or from an alienfile.
424 requires
426 my $hash = $build->requires($phase);
427 Returns a hash reference of the modules required for the given phase.
429 Phases include:
430 configure
432 These modules must already be available when the alienfile is read.
433 any These modules are used during either a "system" or "share" install.
435 share
437 These modules are used during the build phase of a "share" install.
438 system
440 These modules are used during the build phase of a "system"
441 install.
442 load_requires
444 $build->load_requires($phase);
445 This loads the appropriate modules for the given phase (see "requires"
447 above for a description of the phases).
448 probe
450 my $install_type = $build->probe;
451 Attempts to determine if the operating system has the library or tool
453 already installed. If so, then the string "system" will be returned
454 and a system install will be performed. If not, then the string
455 "share" will be installed and the tool or library will be downloaded
456 and built from source.
457 If the environment variable "ALIEN_INSTALL_TYPE" is set, then that will
459 force a specific type of install. If the detection logic cannot
460 accommodate the install type requested then it will fail with an
461 exception.
462 download
464 $build->download;
465 Download the source, usually as a tarball, usually from the internet.
467 Under a "system" install this does not do anything.
469 fetch
471 my $res = $build->fetch;
472 my $res = $build->fetch($url);
473 Fetch a resource using the fetch hook. Returns the same hash structure
475 described below in the hook documentation.
476 decode
478 my $decoded_res = $build->decode($res);
479 Decode the HTML or file listing returned by "fetch". Returns the same
481 hash structure described below in the hook documentation.
482 prefer
484 my $sorted_res = $build->prefer($res);
485 Filter and sort candidates. The preferred candidate will be returned
487 first in the list. The worst candidate will be returned last. Returns
488 the same hash structure described below in the hook documentation.
489 extract
491 my $dir = $build->extract;
492 my $dir = $build->extract($archive);
493 Extracts the given archive into a fresh directory. This is normally
495 called internally to Alien::Build, and for normal usage is not needed
496 from a plugin or alienfile.
497 build
499 $build->build;
500 Run the build step. It is expected that "probe" and "download" have
502 already been performed. What it actually does depends on the type of
503 install:
504 share
506 The source is extracted, and built as determined by the alienfile
507 recipe. If there is a "gather_share" that will be executed last.
508 system
510 The "gather_system" hook will be executed.
511 test
513 $build->test;
514 Run the test phase
516 clean_install
518 $build->clean_install
519 Clean files from the final install location. The default
521 implementation removes all files recursively except for the "_alien"
522 directory. This is helpful when you have an old install with files
523 that may break the new build.
524 For a non-share install this doesn't do anything.
526 system
528 $build->system($command);
529 $build->system($command, @args);
530 Interpolates the command and arguments and run the results using the
532 Perl "system" command.
533 log
535 $build->log($message);
536 Send a message to the log. By default this prints to "STDOUT".
538 meta
540 my $meta = Alien::Build->meta;
541 my $meta = $build->meta;
542 Returns the meta object for your Alien::Build class or instance. The
544 meta object is a way to manipulate the recipe, and so any changes to
545 the meta object should be made before the "probe", "download" or
546 "build" steps.
547
549 prop
550 my $href = $build->meta->prop;
551 Meta properties. This is the same as calling "meta_prop" on the class
553 or Alien::Build instance.
554 add_requires
556 Alien::Build->meta->add_requires($phase, $module => $version, ...);
557 Add the requirement to the given phase. Phase should be one of:
559 configure
561 any
562 share
563 system
564 interpolator
566 my $interpolator = $build->meta->interpolator;
567 my $interpolator = Alien::Build->interpolator;
568 Returns the Alien::Build::Interpolate instance for the Alien::Build
570 class.
571 has_hook
573 my $bool = $build->meta->has_hook($name);
574 my $bool = Alien::Build->has_hook($name);
575 Returns if there is a usable hook registered with the given name.
577 register_hook
579 $build->meta->register_hook($name, $instructions);
580 Alien::Build->meta->register_hook($name, $instructions);
581 Register a hook with the given name. $instruction should be either a
583 code reference, or a command sequence, which is an array reference.
584 default_hook
586 $build->meta->default_hook($name, $instructions);
587 Alien::Build->meta->default_hook($name, $instructions);
588 Register a default hook, which will be used if the alienfile does not
590 register its own hook with that name.
591 around_hook
593 $build->meta->around_hook($hook, $code);
594 Alien::Build->meta->around_hook($name, $code);
595 Wrap the given hook with a code reference. This is similar to a Moose
597 method modifier, except that it wraps around the given hook instead of
598 a method. For example, this will add a probe system requirement:
599 $build->meta->around_hook(
601 probe => sub {
602 my $orig = shift;
603 my $build = shift;
604 my $type = $orig->($build, @_);
605 return $type unless $type eq 'system';
606 # also require a configuration file
607 if(-f '/etc/foo.conf')
608 {
609 return 'system';
610 }
611 else
612 {
613 return 'share';
614 }
615 },
616 );
617 apply_plugin
619 Alien::Build->meta->apply_plugin($name);
620 Alien::Build->meta->apply_plugin($name, @args);
621 Apply the given plugin with the given arguments.
623
625 Alien::Build responds to these environment variables:
626 ALIEN_INSTALL_NETWORK
628 If set to true (the default), then network fetch will be allowed.
629 If set to false, then network fetch will not be allowed.
630 What constitutes a local vs. network fetch is determined based on
632 the "start_url" and "local_source" meta properties. An alienfile
633 or plugin "could" override this detection (possibly
634 inappropriately), so this variable is not a substitute for properly
635 auditing of Perl modules for environments that require that.
636 ALIEN_INSTALL_TYPE
638 If set to "share" or "system", it will override the system
639 detection logic. If set to "default", it will use the default
640 setting for the alienfile. The behavior of other values is
641 undefined.
642 Although the recommended way for a consumer to use an Alien::Base
644 based Alien is to declare it as a static configure and build-time
645 dependency, some consumers may prefer to fallback on using an Alien
646 only when the consumer itself cannot detect the necessary package.
647 In some cases the consumer may want the user to opt-in to using an
648 Alien before requiring it.
649 To keep the interface consistent among Aliens, the consumer of the
651 fallback opt-in Alien may fallback on the Alien if the environment
652 variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is
653 that by setting this environment variable the user is aware that
654 Alien modules may be installed and have indicated consent. The
655 actual implementation of this, by its nature would have to be in
656 the consuming CPAN module.
657 ALIEN_BUILD_LOG
659 The default log class used. See Alien::Build::Log and
660 <Alien:Build::Log::Default>.
661 ALIEN_BUILD_RC
663 Perl source file which can override some global defaults for
664 Alien::Build, by, for example, setting preload and postload
665 plugins.
666 ALIEN_BUILD_PKG_CONFIG
668 Override the logic in Alien::Build::Plugin::PkgConfig::Negotiate
669 which chooses the best "pkg-config" plugin.
670 ALIEN_BUILD_PRELOAD
672 semicolon separated list of plugins to automatically load before
673 parsing your alienfile.
674 ALIEN_BUILD_POSTLOAD
676 semicolon separated list of plugins to automatically load after
677 parsing your alienfile.
678 DESTDIR
680 This environment variable will be manipulated during a destdir
681 install.
682 PKG_CONFIG
684 This environment variable can be used to override the program name
685 for "pkg-config" when using the command line plugin:
686 Alien::Build::Plugin::PkgConfig::CommandLine.
687 ftp_proxy, all_proxy
689 If these environment variables are set, it may influence the
690 Download negotiation plugin
691 Alien::Build::Plugin::Downaload::Negotiate. Other proxy variables
692 may be used by some Fetch plugins, if they support it.
693
695 The intent of the "Alien-Build" team is to support as best as possible
696 all Perls from 5.8.1 to the latest production version. So long as they
697 are also supported by the Perl toolchain.
698 Please feel encouraged to report issues that you encounter to the
700 project GitHub Issue tracker:
701 <https://github.com/Perl5-Alien/Alien-Build/issues>
703 Better if you can fix the issue yourself, please feel encouraged to
705 open pull-request on the project GitHub:
706 <https://github.com/Perl5-Alien/Alien-Build/pulls>
708 If you are confounded and have questions, join us on the "#native"
710 channel on irc.perl.org. The "Alien-Build" developers frequent this
711 channel and can probably help point you in the right direction. If you
712 don't have an IRC client handy, you can use this web interface:
713 <https://chat.mibbit.com/?channel=%23native&server=irc.perl.org>
715
717 Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser,
718 Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ,
719 Alien::Build::Manual::PluginAuthor
720 alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
722
724 Alien::Base was originally written by Joel Berger, the rest of this
725 project would not have been possible without him getting the project
726 started. Thanks to his support I have been able to augment the
727 original Alien::Base system with a reliable set of tools (Alien::Build,
728 alienfile, Test::Alien), which make up this toolset.
729 The original Alien::Base is still copyright (c) 2012-2020 Joel Berger.
731 It has the same license as the rest of the Alien::Build and related
732 tools distributed as "Alien-Build". Joel Berger thanked a number of
733 people who helped in in the development of Alien::Base, in the
734 documentation for that module.
735 I would also like to acknowledge the other members of the Perl5-Alien
737 github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk
738 (ETJ). Also important in the early development of Alien::Build were
739 the early adopters Chase Whitener (genio, CAPOEIRAB, author of
740 Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author
741 of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF,
742 author of Alien::libudev and Alien::LibUSB).
743 The Alien ecosystem owes a debt to Dan Book, who goes by Grinnz on IRC,
745 for answering question about how to use Alien::Build and friends.
746
748 Author: Graham Ollis <plicease@cpan.org>
749 Contributors:
751 Diab Jerius (DJERIUS)
753 Roy Storey (KIWIROY)
755 Ilya Pavlov
757 David Mertens (run4flat)
759 Mark Nunberg (mordy, mnunberg)
761 Christian Walde (Mithaldu)
763 Brian Wightman (MidLifeXis)
765 Zaki Mughal (zmughal)
767 mohawk (mohawk2, ETJ)
769 Vikas N Kumar (vikasnkumar)
771 Flavio Poletti (polettix)
773 Salvador Fandiño (salva)
775 Gianni Ceccarelli (dakkar)
777 Pavel Shaydo (zwon, trinitum)
779 Kang-min Liu (劉康民, gugod)
781 Nicholas Shipp (nshp)
783 Juan Julián Merelo Guervós (JJ)
785 Joel Berger (JBERGER)
787 Petr Pisar (ppisar)
789 Lance Wicks (LANCEW)
791 Ahmad Fatoum (a3f, ATHREEF)
793 José Joaquín Atria (JJATRIA)
795 Duke Leto (LETO)
797 Shoichi Kaji (SKAJI)
799 Shawn Laffan (SLAFFAN)
801 Paul Evans (leonerd, PEVANS)
803
805 This software is copyright (c) 2011-2020 by Graham Ollis.
806 This is free software; you can redistribute it and/or modify it under
808 the same terms as the Perl 5 programming language system itself.
809perl v5.30.2 2020-03-20 Alien::Build(3)