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.77
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 Alien::Build::Manual::Security
54 If you are concerned that Aliens might be downloading tarballs off
55 the internet, then this is the place for you. This will discuss
56 some of the risks of downloading (really any) software off the
57 internet and will give you some tools to remediate these risks.
58 Note that you will not usually create a Alien::Build instance directly,
60 but rather be using a thin installer layer, such as Alien::Build::MM
61 (for use with ExtUtils::MakeMaker) or Alien::Build::MB (for use with
62 Module::Build). One of the goals of this project is to remain
63 installer agnostic.
64
66 new
67 my $build = Alien::Build->new;
68 This creates a new empty instance of Alien::Build. Normally you will
70 want to use "load" below to create an instance of Alien::Build from an
71 alienfile recipe.
72 load
74 my $build = Alien::Build->load($alienfile);
75 This creates an Alien::Build instance with the given alienfile recipe.
77 resume
79 my $build = Alien::Build->resume($alienfile, $root);
80 Load a checkpointed Alien::Build instance. You will need the original
82 alienfile and the build root (usually "_alien"), and a build that had
83 been properly checkpointed using the "checkpoint" method below.
84
86 There are three main properties for Alien::Build. There are a number
87 of properties documented here with a specific usage. Note that these
88 properties may need to be serialized into something primitive like JSON
89 that does not support: regular expressions, code references of blessed
90 objects.
91 If you are writing a plugin (Alien::Build::Plugin) you should use a
93 prefix like "plugin_name" (where name is the name of your plugin) so
94 that it does not interfere with other plugin or future versions of
95 Alien::Build. For example, if you were writing
96 "Alien::Build::Plugin::Fetch::NewProtocol", please use the prefix
97 "plugin_fetch_newprotocol":
98 sub init
100 {
101 my($self, $meta) = @_;
102 $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
104 $meta->register_hook(
106 some_hook => sub {
107 my($build) = @_;
108 $build->install_prop->{plugin_fetch_newprotocol_bar} = 'some other value';
109 $build->runtime_prop->{plugin_fetch_newprotocol_baz} = 'and another value';
110 }
111 );
112 }
113 If you are writing a alienfile recipe please use the prefix "my_":
115 use alienfile;
117 meta_prop->{my_foo} = 'some value';
119 probe sub {
121 my($build) = @_;
122 $build->install_prop->{my_bar} = 'some other value';
123 $build->install_prop->{my_baz} = 'and another value';
124 };
125 Any property may be used from a command:
127 probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
129 probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
130 probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
131 probe [ 'some command %{.meta.my_foo}' ];
132 probe [ 'some command %{.install.my_bar}' ];
133 probe [ 'some command %{.runtime.my_baz}' ];
134 meta_prop
136 my $href = $build->meta_prop;
137 my $href = Alien::Build->meta_prop;
138 Meta properties have to do with the recipe itself, and not any
140 particular instance that probes or builds that recipe. Meta properties
141 can be changed from within an alienfile using the "meta_prop"
142 directive, or from a plugin from its "init" method (though should NOT
143 be modified from any hooks registered within that "init" method). This
144 is not strictly enforced, but if you do not follow this rule your
145 recipe will likely be broken.
146 arch
148 This is a hint to an installer like Alien::Build::MM or
149 Alien::Build::MB, that the library or tool contains architecture
150 dependent files and so should be stored in an architecture
151 dependent location. If not specified by your alienfile then it
152 will be set to true.
153 check_digest
155 True if cryptographic digest should be checked when files are
156 fetched or downloaded. This is set by Digest negotiator plugin.
157 destdir
159 Some plugins (Alien::Build::Plugin::Build::Autoconf for example)
160 support installing via "DESTDIR". They will set this property to
161 true if they plan on doing such an install. This helps
162 Alien::Build find the staged install files and how to locate them.
163 If available, "DESTDIR" is used to stage install files in a sub
165 directory before copying the files into "blib". This is generally
166 preferred method if available.
167 destdir_filter
169 Regular expression for the files that should be copied from the
170 "DESTDIR" into the stage directory. If not defined, then all files
171 will be copied.
172 destdir_ffi_filter
174 Same as "destdir_filter" except applies to "build_ffi" instead of
175 "build".
176 digest
178 This properties contains the cryptographic digests (if any) that
179 should be used when verifying any fetched and downloaded files. It
180 is a hash reference where the key is the filename and the value is
181 an array reference containing a pair of values, the first being the
182 algorithm ('SHA256' is recommended) and the second is the actual
183 digest. The special filename "*" may be specified to indicate that
184 any downloaded file should match that digest. If there are both
185 real filenames and the "*" placeholder, the real filenames will be
186 used for filenames that match and any other files will use the
187 placeholder. Example:
188 $build->meta_prop->{digest} = {
190 'foo-1.00.tar.gz' => [ SHA256 => '9feac593aa49a44eb837de52513a57736457f1ea70078346c60f0bfc5f24f2c1' ],
191 'foo-1.01.tar.gz' => [ SHA256 => '6bbde6a7f10ae5924cf74afc26ff5b7bc4b4f9dfd85c6b534c51bd254697b9e7' ],
192 '*' => [ SHA256 => '33a20aae3df6ecfbe812b48082926d55391be4a57d858d35753ab1334b9fddb3' ],
193 };
194 Cryptographic signatures will only be checked if the check_digest
196 meta property is set and if the Digest negotiator plugin is loaded.
197 (The Digest negotiator can be used directly, but is also loaded
198 automatically if you use the digest directive is used by the
199 alienfile).
200 env Environment variables to override during the build stage.
202 env_interpolate
204 Environment variable values will be interpolated with helpers.
205 Example:
206 meta->prop->{env_interpolate} = 1;
208 meta->prop->{env}->{PERL} = '%{perl}';
209 local_source
211 Set to true if source code package is available locally. (that is
212 not fetched over the internet). This is computed by default based
213 on the "start_url" property. Can be set by an alienfile or plugin.
214 platform
216 Hash reference. Contains information about the platform beyond
217 just $^O.
218 platform.compiler_type
220 Refers to the type of flags that the compiler accepts. May be
221 expanded in the future, but for now, will be one of:
222 microsoft
224 On Windows when using Microsoft Visual C++
225 unix
227 Virtually everything else, including gcc on windows.
228 The main difference is that with Visual C++ "-LIBPATH" should
230 be used instead of "-L", and static libraries should have the
231 ".LIB" suffix instead of ".a".
232 platform.system_type
234 $^O is frequently good enough to make platform specific logic
235 in your alienfile, this handles the case when $^O can cover
236 platforms that provide multiple environments that Perl might
237 run under. The main example is windows, but others may be
238 added in the future.
239 unix
241 vms
242 windows-activestate
243 windows-microsoft
244 windows-mingw
245 windows-strawberry
246 windows-unknown
247 Note that "cygwin" and "msys" are considered "unix" even though
249 they run on windows!
250 platform.cpu.count
252 Contains a non-negative integer of available (possibly virtual)
253 CPUs on the system. This can be used by build plugins to build
254 in parallel. The environment variable "ALIEN_CPU_COUNT" can be
255 set to override the CPU count.
256 platform.cpu.arch.name
258 Contains a normalized name for the architecture of the current
259 Perl. This can be used by fetch plugins to determine which
260 binary packages to download. The value may be one of the
261 following, but this list will be expanded as needed.
262 "armel"
264 32-bit ARM soft-float
265 "armhf"
267 32-bit ARM hard-float
268 "aarch64"
270 64-bit ARM
271 "ppc"
273 32-bit PowerPC (big-endian)
274 "ppc64"
276 64-bit PowerPC (big-endian)
277 "x86"
279 32-bit Intel (i386, i486, i686)
280 "x86_64"
282 64-bit Intel (AMD64)
283 "unknown"
285 Unable to detect architecture. Please report this if
286 needed.
287 out_of_source
289 Build in a different directory from the where the source code is
290 stored. In autoconf this is referred to as a "VPATH" build.
291 Everyone else calls this an "out-of-source" build. When this
292 property is true, instead of extracting to the source build root,
293 the downloaded source will be extracted to an source extraction
294 directory and the source build root will be empty. You can use the
295 "extract" install property to get the location of the extracted
296 source.
297 network
299 True if a network fetch is available. This should NOT be set by an
300 alienfile or plugin. This is computed based on the
301 "ALIEN_INSTALL_NETWORK" environment variables.
302 start_url
304 The default or start URL used by fetch plugins.
305 install_prop
307 my $href = $build->install_prop;
308 Install properties are used during the install phase (either under
310 "share" or "system" install). They are remembered for the entire
311 install phase, but not kept around during the runtime phase. Thus they
312 cannot be accessed from your Alien::Base based module.
313 autoconf_prefix
315 The prefix as understood by autoconf. This is only different on
316 Windows Where MSYS is used and paths like "C:/foo" are represented
317 as "/C/foo" which are understood by the MSYS tools, but not by
318 Perl. You should only use this if you are using
319 Alien::Build::Plugin::Build::Autoconf in your alienfile. This is
320 set during before the build hook is run.
321 download
323 The location of the downloaded archive (tar.gz, or similar) or
324 directory. This will be undefined until the archive is actually
325 downloaded.
326 download_detail
328 This property contains optional details about a downloaded file.
329 This property is populated by Alien::Build core. This property is
330 a hash reference. The key is the path to the file that has been
331 downloaded and the value is a hash reference with additional
332 detail. All fields are optional.
333 download_detail.digest
335 This, if available, with the cryptographic signature that was
336 successfully matched against the downloaded file. It is an
337 array reference with a pair of values, the algorithm (typically
338 something like "SHA256") and the digest.
339 download_detail.protocol
341 This, if available, will be the URL protocol used to fetch the
342 downloaded file.
343 env Environment variables to override during the build stage. Plugins
345 are free to set additional overrides using this hash.
346 extract
348 The location of the last source extraction. For a "out-of-source"
349 build (see the "out_of_source" meta property above), this will only
350 be set once. For other types of builds, the source code may be
351 extracted multiple times, and thus this property may change.
352 old [deprecated]
354 Hash containing information on a previously installed Alien of the
356 same name, if available. This may be useful in cases where you
357 want to reuse the previous install if it is still sufficient.
358 old.prefix
360 [deprecated]
361 The prefix for the previous install. Versions prior to 1.42
363 unfortunately had this in typo form of "preifx".
364 old.runtime
366 [deprecated]
367 The runtime properties from the previous install.
369 patch
371 Directory with patches, if available. This will be "undef" if
372 there are no patches. When initially installing an alien this will
373 usually be a sibling of the "alienfile", a directory called
374 "patch". Once installed this will be in the share directory called
375 "_alien/patch". The former is useful for rebuilding an alienized
376 package using af.
377 prefix
379 The install time prefix. Under a "destdir" install this is the
380 same as the runtime or final install location. Under a
381 non-"destdir" install this is the "stage" directory (usually the
382 appropriate share directory under "blib").
383 root
385 The build root directory. This will be an absolute path. It is
386 the absolute form of "./_alien" by default.
387 stage
389 The stage directory where files will be copied. This is usually
390 the root of the blib share directory.
391 system_probe_class
393 After the probe step this property may contain the plugin class
394 that performed the system probe. It shouldn't be filled in
395 directly by the plugin (instead if should use the hook property
396 "probe_class", see below). This is optional, and not all probe
397 plugins will provide this information.
398 system_probe_instance_id
400 After the probe step this property may contain the plugin instance
401 id that performed the system probe. It shouldn't be filled in
402 directly by the plugin (instead if should use the hook property
403 "probe_instance_id", see below). This is optional, and not all
404 probe plugins will provide this information.
405 plugin_instance_prop
407 my $href = $build->plugin_instance_prop($plugin);
408 This returns the private plugin instance properties for a given plugin.
410 This method should usually only be called internally by plugins
411 themselves to keep track of internal state. Because the content can be
412 used arbitrarily by the owning plugin because it is private to the
413 plugin, and thus is not part of the Alien::Build spec.
414 runtime_prop
416 my $href = $build->runtime_prop;
417 Runtime properties are used during the install and runtime phases
419 (either under "share" or "system" install). This should include
420 anything that you will need to know to use the library or tool during
421 runtime, and shouldn't include anything that is no longer relevant once
422 the install process is complete.
423 alien_build_version
425 The version of Alien::Build used to install the library or tool.
426 alt Alternate configurations. If the alienized package has multiple
428 libraries this could be used to store the different compiler or
429 linker flags for each library. Typically this will be set by a
430 plugin in the gather stage (for either share or system installs).
431 cflags
433 The compiler flags. This is typically set by a plugin in the
434 gather stage (for either share or system installs).
435 cflags_static
437 The static compiler flags. This is typically set by a plugin in
438 the gather stage (for either share or system installs).
439 command
441 The command name for tools where the name my differ from platform
442 to platform. For example, the GNU version of make is usually
443 "make" in Linux and "gmake" on FreeBSD. This is typically set by a
444 plugin in the gather stage (for either share or system installs).
445 ffi_name
447 The name DLL or shared object "name" to use when searching for
448 dynamic libraries at runtime. This is passed into FFI::CheckLib,
449 so if your library is something like "libarchive.so" or
450 "archive.dll" you would set this to "archive". This may be a
451 string or an array of strings. This is typically set by a plugin
452 in the gather stage (for either share or system installs).
453 ffi_checklib
455 This property contains two sub properties:
456 ffi_checklib.share
458 $build->runtime_prop->{ffi_checklib}->{share} = [ ... ];
459 Array of additional FFI::CheckLib flags to pass in to
461 "find_lib" for a "share" install.
462 ffi_checklib.system
464 Array of additional FFI::CheckLib flags to pass in to
465 "find_lib" for a "system" install.
466 Among other things, useful for specifying the
468 "try_linker_script" flag:
469 $build->runtime_prop->{ffi_checklib}->{system} = [ try_linker_script => 1 ];
471 This is typically set by a plugin in the gather stage (for either
473 share or system installs).
474 inline_auto_include
476 [version 2.53]
477 This property is an array reference of C code that will be passed
479 into Inline::C to make sure that appropriate headers are
480 automatically included. See "auto_include" in Inline::C for
481 details.
482 install_type
484 The install type. This is set by AB core after the probe hook is
485 executed. Is one of:
486 system
488 For when the library or tool is provided by the operating
489 system, can be detected by Alien::Build, and is considered
490 satisfactory by the "alienfile" recipe.
491 share
493 For when a system install is not possible, the library source
494 will be downloaded from the internet or retrieved in another
495 appropriate fashion and built.
496 libs
498 The library flags. This is typically set by a plugin in the gather
499 stage (for either share or system installs).
500 libs_static
502 The static library flags. This is typically set by a plugin in the
503 gather stage (for either share or system installs).
504 perl_module_version
506 The version of the Perl module used to install the alien (if
507 available). For example if Alien::curl is installing "libcurl"
508 this would be the version of Alien::curl used during the install
509 step.
510 prefix
512 The final install root. This is usually they share directory.
513 version
515 The version of the library or tool. This is typically set by a
516 plugin in the gather stage (for either share or system installs).
517 hook_prop
519 my $href = $build->hook_prop;
520 Hook properties are for the currently running (if any) hook. They are
522 used only during the execution of each hook and are discarded after.
523 If no hook is currently running then "hook_prop" will return "undef".
524 name
526 The name of the currently running hook.
527 version (probe)
529 Probe and PkgConfig plugins may set this property indicating the
530 version of the alienized package. Not all plugins and
531 configurations may be able to provide this.
532 probe_class (probe)
534 Probe and PkgConfig plugins may set this property indicating the
535 plugin class that made the probe. If the probe results in a system
536 install this will be propagated to "system_probe_class" for later
537 use.
538 probe_instance_id (probe)
540 Probe and PkgConfig plugins may set this property indicating the
541 plugin instance id that made the probe. If the probe results in a
542 system install this will be propagated to
543 "system_probe_instance_id" for later use.
544
546 checkpoint
547 $build->checkpoint;
548 Save any install or runtime properties so that they can be reloaded on
550 a subsequent run in a separate process. This is useful if your build
551 needs to be done in multiple stages from a "Makefile", such as with
552 ExtUtils::MakeMaker. Once checkpointed you can use the "resume"
553 constructor (documented above) to resume the probe/build/install]
554 process.
555 root
557 my $dir = $build->root;
558 This is just a shortcut for:
560 my $root = $build->install_prop->{root};
562 Except that it will be created if it does not already exist.
564 install_type
566 my $type = $build->install_type;
567 This will return the install type. (See the like named install
569 property above for details). This method will call "probe" if it has
570 not already been called.
571 download_rule
573 my $rule = $build->download_rule;
574 This returns install rule as a string. This is determined by the
576 environment and should be one of:
577 "warn"
579 Warn only if fetching via non secure source (secure sources include
580 "https", and bundled files, may include other encrypted protocols
581 in the future).
582 "digest"
584 Require that any downloaded source package have a cryptographic
585 signature in the alienfile and that signature matches what was
586 downloaded.
587 "encrypt"
589 Require that any downloaded source package is fetched via secure
590 source.
591 "digest_or_encrypt"
593 Require that any downloaded source package is either fetched via a
594 secure source or has a cryptographic signature in the alienfile and
595 that signature matches what was downloaded.
596 "digest_and_encrypt"
598 Require that any downloaded source package is both fetched via a
599 secure source and has a cryptographic signature in the alienfile
600 and that signature matches what was downloaded.
601 The current default is "warn", but in the near future this will be
603 upgraded to "digest_or_encrypt".
604 set_prefix
606 $build->set_prefix($prefix);
607 Set the final (unstaged) prefix. This is normally only called by
609 Alien::Build::MM and similar modules. It is not intended for use from
610 plugins or from an alienfile.
611 set_stage
613 $build->set_stage($dir);
614 Sets the stage directory. This is normally only called by
616 Alien::Build::MM and similar modules. It is not intended for use from
617 plugins or from an alienfile.
618 requires
620 my $hash = $build->requires($phase);
621 Returns a hash reference of the modules required for the given phase.
623 Phases include:
624 configure
626 These modules must already be available when the alienfile is read.
627 any These modules are used during either a "system" or "share" install.
629 share
631 These modules are used during the build phase of a "share" install.
632 system
634 These modules are used during the build phase of a "system"
635 install.
636 load_requires
638 $build->load_requires($phase);
639 This loads the appropriate modules for the given phase (see "requires"
641 above for a description of the phases).
642 probe
644 my $install_type = $build->probe;
645 Attempts to determine if the operating system has the library or tool
647 already installed. If so, then the string "system" will be returned
648 and a system install will be performed. If not, then the string
649 "share" will be installed and the tool or library will be downloaded
650 and built from source.
651 If the environment variable "ALIEN_INSTALL_TYPE" is set, then that will
653 force a specific type of install. If the detection logic cannot
654 accommodate the install type requested then it will fail with an
655 exception.
656 download
658 $build->download;
659 Download the source, usually as a tarball, usually from the internet.
661 Under a "system" install this does not do anything.
663 fetch
665 my $res = $build->fetch;
666 my $res = $build->fetch($url, %options);
667 Fetch a resource using the fetch hook. Returns the same hash structure
669 described below in the fetch hook documentation.
670 [version 2.39]
672 As of Alien::Build 2.39, these options are supported:
674 http_headers
676 my $res = $build->fetch($url, http_headers => [ $key1 => $value1, $key2 => $value 2, ... ]);
677 Set the HTTP request headers on all outgoing HTTP requests. Note
679 that not all protocols or fetch plugins support setting request
680 headers, but the ones that do not should issue a warning if you try
681 to set request headers and they are not supported.
682 check_digest
684 [experimental]
685 my $bool = $build->check_digest($path);
687 Checks any cryptographic signatures for the given file. The file is
689 specified by $path which may be one of:
690 string
692 Containing the path to the file to be checked.
693 Path::Tiny
695 Containing the path to the file to be checked.
696 "HASH"
698 A Hash reference containing information about a file. See the
699 fetch hook for details on the format.
700 Returns true if the cryptographic signature matches, false if
702 cryptographic signatures are disabled. Will throw an exception if the
703 signature does not match, or if no plugin provides the correct
704 algorithm for checking the signature.
705 decode
707 my $decoded_res = $build->decode($res);
708 Decode the HTML or file listing returned by "fetch". Returns the same
710 hash structure described below in the decode hook documentation.
711 prefer
713 my $sorted_res = $build->prefer($res);
714 Filter and sort candidates. The preferred candidate will be returned
716 first in the list. The worst candidate will be returned last. Returns
717 the same hash structure described below in the prefer hook
718 documentation.
719 extract
721 my $dir = $build->extract;
722 my $dir = $build->extract($archive);
723 Extracts the given archive into a fresh directory. This is normally
725 called internally to Alien::Build, and for normal usage is not needed
726 from a plugin or alienfile.
727 build
729 $build->build;
730 Run the build step. It is expected that "probe" and "download" have
732 already been performed. What it actually does depends on the type of
733 install:
734 share
736 The source is extracted, and built as determined by the alienfile
737 recipe. If there is a "gather_share" that will be executed last.
738 system
740 The gather_system hook will be executed.
741 test
743 $build->test;
744 Run the test phase
746 clean_install
748 $build->clean_install
749 Clean files from the final install location. The default
751 implementation removes all files recursively except for the "_alien"
752 directory. This is helpful when you have an old install with files
753 that may break the new build.
754 For a non-share install this doesn't do anything.
756 system
758 $build->system($command);
759 $build->system($command, @args);
760 Interpolates the command and arguments and run the results using the
762 Perl "system" command.
763 log
765 $build->log($message);
766 Send a message to the log. By default this prints to "STDOUT".
768 meta
770 my $meta = Alien::Build->meta;
771 my $meta = $build->meta;
772 Returns the meta object for your Alien::Build class or instance. The
774 meta object is a way to manipulate the recipe, and so any changes to
775 the meta object should be made before the "probe", "download" or
776 "build" steps.
777
779 prop
780 my $href = $build->meta->prop;
781 Meta properties. This is the same as calling "meta_prop" on the class
783 or Alien::Build instance.
784 add_requires
786 Alien::Build->meta->add_requires($phase, $module => $version, ...);
787 Add the requirement to the given phase. Phase should be one of:
789 configure
791 any
792 share
793 system
794 interpolator
796 my $interpolator = $build->meta->interpolator;
797 my $interpolator = Alien::Build->interpolator;
798 Returns the Alien::Build::Interpolate instance for the Alien::Build
800 class.
801 has_hook
803 my $bool = $build->meta->has_hook($name);
804 my $bool = Alien::Build->has_hook($name);
805 Returns if there is a usable hook registered with the given name.
807 register_hook
809 $build->meta->register_hook($name, $instructions);
810 Alien::Build->meta->register_hook($name, $instructions);
811 Register a hook with the given name. $instruction should be either a
813 code reference, or a command sequence, which is an array reference.
814 default_hook
816 $build->meta->default_hook($name, $instructions);
817 Alien::Build->meta->default_hook($name, $instructions);
818 Register a default hook, which will be used if the alienfile does not
820 register its own hook with that name.
821 around_hook
823 $build->meta->around_hook($hook_name, $code);
824 Alien::Build->meta->around_hook($hook_name, $code);
825 Wrap the given hook with a code reference. This is similar to a Moose
827 method modifier, except that it wraps around the given hook instead of
828 a method. For example, this will add a probe system requirement:
829 $build->meta->around_hook(
831 probe => sub {
832 my $orig = shift;
833 my $build = shift;
834 my $type = $orig->($build, @_);
835 return $type unless $type eq 'system';
836 # also require a configuration file
837 if(-f '/etc/foo.conf')
838 {
839 return 'system';
840 }
841 else
842 {
843 return 'share';
844 }
845 },
846 );
847 after_hook
849 $build->meta->after_hook($hook_name, sub {
850 my(@args) = @_;
851 ...
852 });
853 Execute the given code reference after the hook. The original
855 arguments are passed into the code reference.
856 before_hook
858 $build->meta->before_hook($hook_name, sub {
859 my(@args) = @_;
860 ...
861 });
862 Execute the given code reference before the hook. The original
864 arguments are passed into the code reference.
865 apply_plugin
867 Alien::Build->meta->apply_plugin($name);
868 Alien::Build->meta->apply_plugin($name, @args);
869 Apply the given plugin with the given arguments.
871
873 Alien::Build responds to these environment variables:
874 ALIEN_BUILD_LOG
876 The default log class used. See Alien::Build::Log and
877 Alien::Build::Log::Default.
878 ALIEN_BUILD_PKG_CONFIG
880 Override the logic in Alien::Build::Plugin::PkgConfig::Negotiate
881 which chooses the best "pkg-config" plugin.
882 ALIEN_BUILD_POSTLOAD
884 semicolon separated list of plugins to automatically load after
885 parsing your alienfile.
886 ALIEN_BUILD_PRELOAD
888 semicolon separated list of plugins to automatically load before
889 parsing your alienfile.
890 ALIEN_BUILD_RC
892 Perl source file which can override some global defaults for
893 Alien::Build, by, for example, setting preload and postload
894 plugins.
895 ALIEN_DOWNLOAD_RULE
897 This value determines the rules by which types of downloads are
898 allowed. The legal values listed under "download_rule", plus
899 "default" which will be the default for the current version of
900 Alien::Build. For this version that default is "warn".
901 ALIEN_INSTALL_NETWORK
903 If set to true (the default), then network fetch will be allowed.
904 If set to false, then network fetch will not be allowed.
905 What constitutes a local vs. network fetch is determined based on
907 the "start_url" and "local_source" meta properties. An alienfile
908 or plugin "could" override this detection (possibly
909 inappropriately), so this variable is not a substitute for properly
910 auditing of Perl modules for environments that require that.
911 ALIEN_INSTALL_TYPE
913 If set to "share" or "system", it will override the system
914 detection logic. If set to "default", it will use the default
915 setting for the alienfile. The behavior of other values is
916 undefined.
917 Although the recommended way for a consumer to use an Alien::Base
919 based Alien is to declare it as a static configure and build-time
920 dependency, some consumers may prefer to fallback on using an Alien
921 only when the consumer itself cannot detect the necessary package.
922 In some cases the consumer may want the user to opt-in to using an
923 Alien before requiring it.
924 To keep the interface consistent among Aliens, the consumer of the
926 fallback opt-in Alien may fallback on the Alien if the environment
927 variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is
928 that by setting this environment variable the user is aware that
929 Alien modules may be installed and have indicated consent. The
930 actual implementation of this, by its nature would have to be in
931 the consuming CPAN module.
932 DESTDIR
934 This environment variable will be manipulated during a destdir
935 install.
936 PKG_CONFIG
938 This environment variable can be used to override the program name
939 for "pkg-config" when using the command line plugin:
940 Alien::Build::Plugin::PkgConfig::CommandLine.
941 ftp_proxy, all_proxy
943 If these environment variables are set, it may influence the
944 Download negotiation plugin
945 Alien::Build::Plugin::Download::Negotiate. Other proxy variables
946 may be used by some Fetch plugins, if they support it.
947
949 The intent of the "Alien-Build" team is to support as best as possible
950 all Perls from 5.8.4 to the latest production version. So long as they
951 are also supported by the Perl toolchain.
952 Please feel encouraged to report issues that you encounter to the
954 project GitHub Issue tracker:
955 <https://github.com/PerlAlien/Alien-Build/issues>
957 Better if you can fix the issue yourself, please feel encouraged to
959 open pull-request on the project GitHub:
960 <https://github.com/PerlAlien/Alien-Build/pulls>
962 If you are confounded and have questions, join us on the "#native"
964 channel on irc.perl.org. The "Alien-Build" developers frequent this
965 channel and can probably help point you in the right direction. If you
966 don't have an IRC client handy, you can use this web interface:
967 <https://chat.mibbit.com/?channel=%23native&server=irc.perl.org>
969
971 Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser,
972 Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ,
973 Alien::Build::Manual::PluginAuthor
974 alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
976
978 Alien::Base was originally written by Joel Berger, the rest of this
979 project would not have been possible without him getting the project
980 started. Thanks to his support I have been able to augment the
981 original Alien::Base system with a reliable set of tools (Alien::Build,
982 alienfile, Test::Alien), which make up this toolset.
983 The original Alien::Base is still copyright (c) 2012-2020 Joel Berger.
985 It has the same license as the rest of the Alien::Build and related
986 tools distributed as "Alien-Build". Joel Berger thanked a number of
987 people who helped in in the development of Alien::Base, in the
988 documentation for that module.
989 I would also like to acknowledge the other members of the PerlAlien
991 github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk
992 (ETJ). Also important in the early development of Alien::Build were
993 the early adopters Chase Whitener (genio, CAPOEIRAB, author of
994 Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author
995 of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF,
996 author of Alien::libudev and Alien::LibUSB).
997 The Alien ecosystem owes a debt to Dan Book, who goes by Grinnz on IRC,
999 for answering question about how to use Alien::Build and friends.
1000
1002 Author: Graham Ollis <plicease@cpan.org>
1003 Contributors:
1005 Diab Jerius (DJERIUS)
1007 Roy Storey (KIWIROY)
1009 Ilya Pavlov
1011 David Mertens (run4flat)
1013 Mark Nunberg (mordy, mnunberg)
1015 Christian Walde (Mithaldu)
1017 Brian Wightman (MidLifeXis)
1019 Zaki Mughal (zmughal)
1021 mohawk (mohawk2, ETJ)
1023 Vikas N Kumar (vikasnkumar)
1025 Flavio Poletti (polettix)
1027 Salvador Fandiño (salva)
1029 Gianni Ceccarelli (dakkar)
1031 Pavel Shaydo (zwon, trinitum)
1033 Kang-min Liu (劉康民, gugod)
1035 Nicholas Shipp (nshp)
1037 Juan Julián Merelo Guervós (JJ)
1039 Joel Berger (JBERGER)
1041 Petr Písař (ppisar)
1043 Lance Wicks (LANCEW)
1045 Ahmad Fatoum (a3f, ATHREEF)
1047 José Joaquín Atria (JJATRIA)
1049 Duke Leto (LETO)
1051 Shoichi Kaji (SKAJI)
1053 Shawn Laffan (SLAFFAN)
1055 Paul Evans (leonerd, PEVANS)
1057 Håkon Hægland (hakonhagland, HAKONH)
1059 nick nauwelaerts (INPHOBIA)
1061 Florian Weimer
1063
1065 This software is copyright (c) 2011-2022 by Graham Ollis.
1066 This is free software; you can redistribute it and/or modify it under
1068 the same terms as the Perl 5 programming language system itself.
1069perl v5.36.0 2023-01-20 Alien::Build(3)