1Alien::Build(3)       User Contributed Perl Documentation      Alien::Build(3)
2
3
4

NAME

6       Alien::Build - Build external dependencies for use in CPAN
7

VERSION

9       version 2.80
10

SYNOPSIS

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

DESCRIPTION

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
29       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
33       Alien::Build::Manual::Alien
34           A broad overview of "Alien-Build" and its ecosystem.
35
36       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
41       Alien::Build::Manual::AlienAuthor
42           If you are writing your own Alien based on Alien::Build and
43           Alien::Base.
44
45       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
49       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
53       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
59       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

CONSTRUCTORS

66   new
67        my $build = Alien::Build->new;
68
69       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
73   load
74        my $build = Alien::Build->load($alienfile);
75
76       This creates an Alien::Build instance with the given alienfile recipe.
77
78   resume
79        my $build = Alien::Build->resume($alienfile, $root);
80
81       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

PROPERTIES

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
92       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
99        sub init
100        {
101          my($self, $meta) = @_;
102
103          $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
104
105          $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
114       If you are writing a alienfile recipe please use the prefix "my_":
115
116        use alienfile;
117
118        meta_prop->{my_foo} = 'some value';
119
120        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
126       Any property may be used from a command:
127
128        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
135   meta_prop
136        my $href = $build->meta_prop;
137        my $href = Alien::Build->meta_prop;
138
139       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
147       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
154       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
158       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
164           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
168       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
173       destdir_ffi_filter
174           Same as "destdir_filter" except applies to "build_ffi" instead of
175           "build".
176
177       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
189            $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
195           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
201       env Environment variables to override during the build stage.
202
203       env_interpolate
204           Environment variable values will be interpolated with helpers.
205           Example:
206
207            meta->prop->{env_interpolate} = 1;
208            meta->prop->{env}->{PERL} = '%{perl}';
209
210       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
215       platform
216           Hash reference.  Contains information about the platform beyond
217           just $^O.
218
219           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
223               microsoft
224                   On Windows when using Microsoft Visual C++
225
226               unix
227                   Virtually everything else, including gcc on windows.
228
229               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
233           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
240               unix
241               vms
242               windows-activestate
243               windows-microsoft
244               windows-mingw
245               windows-strawberry
246               windows-unknown
247
248               Note that "cygwin" and "msys" are considered "unix" even though
249               they run on windows!
250
251           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
257           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
263               "armel"
264                   32-bit ARM soft-float
265
266               "armhf"
267                   32-bit ARM hard-float
268
269               "aarch64"
270                   64-bit ARM
271
272               "ppc"
273                   32-bit PowerPC (big-endian)
274
275               "ppc64"
276                   64-bit PowerPC (big-endian)
277
278               "x86"
279                   32-bit Intel (i386, i486, i686)
280
281               "x86_64"
282                   64-bit Intel (AMD64)
283
284               "unknown"
285                   Unable to detect architecture. Please report this if
286                   needed.
287
288       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
298       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
303       start_url
304           The default or start URL used by fetch plugins.
305
306   install_prop
307        my $href = $build->install_prop;
308
309       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
314       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
322       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
327       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
334           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
340           download_detail.protocol
341               This, if available, will be the URL protocol used to fetch the
342               downloaded file.
343
344       env Environment variables to override during the build stage.  Plugins
345           are free to set additional overrides using this hash.
346
347       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
353       old [deprecated]
354
355           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
359           old.prefix
360               [deprecated]
361
362               The prefix for the previous install.  Versions prior to 1.42
363               unfortunately had this in typo form of "preifx".
364
365           old.runtime
366               [deprecated]
367
368               The runtime properties from the previous install.
369
370       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
378       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
384       root
385           The build root directory.  This will be an absolute path.  It is
386           the absolute form of "./_alien" by default.
387
388       stage
389           The stage directory where files will be copied.  This is usually
390           the root of the blib share directory.
391
392       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
399       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
406   plugin_instance_prop
407        my $href = $build->plugin_instance_prop($plugin);
408
409       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
415   runtime_prop
416        my $href = $build->runtime_prop;
417
418       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
424       alien_build_version
425           The version of Alien::Build used to install the library or tool.
426
427       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
432       cflags
433           The compiler flags.  This is typically set by a plugin in the
434           gather stage (for either share or system installs).
435
436       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
440       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
446       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
454       ffi_checklib
455           This property contains two sub properties:
456
457           ffi_checklib.share
458                $build->runtime_prop->{ffi_checklib}->{share} = [ ... ];
459
460               Array of additional FFI::CheckLib flags to pass in to
461               "find_lib" for a "share" install.
462
463           ffi_checklib.system
464               Array of additional FFI::CheckLib flags to pass in to
465               "find_lib" for a "system" install.
466
467               Among other things, useful for specifying the
468               "try_linker_script" flag:
469
470                $build->runtime_prop->{ffi_checklib}->{system} = [ try_linker_script => 1 ];
471
472           This is typically set by a plugin in the gather stage (for either
473           share or system installs).
474
475       inline_auto_include
476           [version 2.53]
477
478           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
483       install_type
484           The install type.  This is set by AB core after the probe hook is
485           executed.  Is one of:
486
487           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
492           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
497       libs
498           The library flags.  This is typically set by a plugin in the gather
499           stage (for either share or system installs).
500
501       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
505       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
511       prefix
512           The final install root.  This is usually they share directory.
513
514       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
518   hook_prop
519        my $href = $build->hook_prop;
520
521       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
525       name
526           The name of the currently running hook.
527
528       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
533       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
539       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

METHODS

546   checkpoint
547        $build->checkpoint;
548
549       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
556   root
557        my $dir = $build->root;
558
559       This is just a shortcut for:
560
561        my $root = $build->install_prop->{root};
562
563       Except that it will be created if it does not already exist.
564
565   install_type
566        my $type = $build->install_type;
567
568       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
572   download_rule
573        my $rule = $build->download_rule;
574
575       This returns install rule as a string.  This is determined by the
576       environment and should be one of:
577
578       "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
583       "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
588       "encrypt"
589           Require that any downloaded source package is fetched via secure
590           source.
591
592       "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
597       "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
602       The current default is "warn", but in the near future this will be
603       upgraded to "digest_or_encrypt".
604
605   set_prefix
606        $build->set_prefix($prefix);
607
608       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
612   set_stage
613        $build->set_stage($dir);
614
615       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
619   requires
620        my $hash = $build->requires($phase);
621
622       Returns a hash reference of the modules required for the given phase.
623       Phases include:
624
625       configure
626           These modules must already be available when the alienfile is read.
627
628       any These modules are used during either a "system" or "share" install.
629
630       share
631           These modules are used during the build phase of a "share" install.
632
633       system
634           These modules are used during the build phase of a "system"
635           install.
636
637   load_requires
638        $build->load_requires($phase);
639
640       This loads the appropriate modules for the given phase (see "requires"
641       above for a description of the phases).
642
643   probe
644        my $install_type = $build->probe;
645
646       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
652       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
657   download
658        $build->download;
659
660       Download the source, usually as a tarball, usually from the internet.
661
662       Under a "system" install this does not do anything.
663
664   fetch
665        my $res = $build->fetch;
666        my $res = $build->fetch($url, %options);
667
668       Fetch a resource using the fetch hook.  Returns the same hash structure
669       described below in the fetch hook documentation.
670
671       [version 2.39]
672
673       As of Alien::Build 2.39, these options are supported:
674
675       http_headers
676            my $res = $build->fetch($url, http_headers => [ $key1 => $value1, $key2 => $value 2, ... ]);
677
678           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
683   check_digest
684       [experimental]
685
686        my $bool = $build->check_digest($path);
687
688       Checks any cryptographic signatures for the given file.  The file is
689       specified by $path which may be one of:
690
691       string
692           Containing the path to the file to be checked.
693
694       Path::Tiny
695           Containing the path to the file to be checked.
696
697       "HASH"
698           A Hash reference containing information about a file.  See the
699           fetch hook for details on the format.
700
701       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
706   decode
707        my $decoded_res = $build->decode($res);
708
709       Decode the HTML or file listing returned by "fetch".  Returns the same
710       hash structure described below in the decode hook documentation.
711
712   prefer
713        my $sorted_res = $build->prefer($res);
714
715       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
720   extract
721        my $dir = $build->extract;
722        my $dir = $build->extract($archive);
723
724       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
728   build
729        $build->build;
730
731       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
735       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
739       system
740           The gather_system hook will be executed.
741
742   test
743        $build->test;
744
745       Run the test phase
746
747   clean_install
748        $build->clean_install
749
750       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
755       For a non-share install this doesn't do anything.
756
757   system
758        $build->system($command);
759        $build->system($command, @args);
760
761       Interpolates the command and arguments and run the results using the
762       Perl "system" command.
763
764   log
765        $build->log($message);
766
767       Send a message to the log.  By default this prints to "STDOUT".
768
769   meta
770        my $meta = Alien::Build->meta;
771        my $meta = $build->meta;
772
773       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

META METHODS

779   prop
780        my $href = $build->meta->prop;
781
782       Meta properties.  This is the same as calling "meta_prop" on the class
783       or Alien::Build instance.
784
785   add_requires
786        Alien::Build->meta->add_requires($phase, $module => $version, ...);
787
788       Add the requirement to the given phase.  Phase should be one of:
789
790       configure
791       any
792       share
793       system
794
795   interpolator
796        my $interpolator = $build->meta->interpolator;
797        my $interpolator = Alien::Build->interpolator;
798
799       Returns the Alien::Build::Interpolate instance for the Alien::Build
800       class.
801
802   has_hook
803        my $bool = $build->meta->has_hook($name);
804        my $bool = Alien::Build->has_hook($name);
805
806       Returns if there is a usable hook registered with the given name.
807
808   register_hook
809        $build->meta->register_hook($name, $instructions);
810        Alien::Build->meta->register_hook($name, $instructions);
811
812       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
815   default_hook
816        $build->meta->default_hook($name, $instructions);
817        Alien::Build->meta->default_hook($name, $instructions);
818
819       Register a default hook, which will be used if the alienfile does not
820       register its own hook with that name.
821
822   around_hook
823        $build->meta->around_hook($hook_name, $code);
824        Alien::Build->meta->around_hook($hook_name, $code);
825
826       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
830        $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
848   after_hook
849        $build->meta->after_hook($hook_name, sub {
850          my(@args) = @_;
851          ...
852        });
853
854       Execute the given code reference after the hook.  The original
855       arguments are passed into the code reference.
856
857   before_hook
858        $build->meta->before_hook($hook_name, sub {
859          my(@args) = @_;
860          ...
861        });
862
863       Execute the given code reference before the hook.  The original
864       arguments are passed into the code reference.
865
866   apply_plugin
867        Alien::Build->meta->apply_plugin($name);
868        Alien::Build->meta->apply_plugin($name, @args);
869
870       Apply the given plugin with the given arguments.
871

ENVIRONMENT

873       Alien::Build responds to these environment variables:
874
875       ALIEN_BUILD_LOG
876           The default log class used.  See Alien::Build::Log and
877           Alien::Build::Log::Default.
878
879       ALIEN_BUILD_PKG_CONFIG
880           Override the logic in Alien::Build::Plugin::PkgConfig::Negotiate
881           which chooses the best "pkg-config" plugin.
882
883       ALIEN_BUILD_POSTLOAD
884           semicolon separated list of plugins to automatically load after
885           parsing your alienfile.
886
887       ALIEN_BUILD_PRELOAD
888           semicolon separated list of plugins to automatically load before
889           parsing your alienfile.
890
891       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
896       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
902       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
906           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
912       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
918           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
925           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
933       DESTDIR
934           This environment variable will be manipulated during a destdir
935           install.
936
937       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
942       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

SUPPORT

949       The intent of the "Alien-Build" team is to support the same versions of
950       Perl that are supported by the Perl toolchain.  As of this writing that
951       means 5.16 and better.
952
953       Please feel encouraged to report issues that you encounter to the
954       project GitHub Issue tracker:
955
956       <https://github.com/PerlAlien/Alien-Build/issues>
957
958       Better if you can fix the issue yourself, please feel encouraged to
959       open pull-request on the project GitHub:
960
961       <https://github.com/PerlAlien/Alien-Build/pulls>
962
963       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
968       <https://chat.mibbit.com/?channel=%23native&server=irc.perl.org>
969

SEE ALSO

971       Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser,
972       Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ,
973       Alien::Build::Manual::PluginAuthor
974
975       alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
976

THANKS

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
984       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
990       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
998       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

AUTHOR

1002       Author: Graham Ollis <plicease@cpan.org>
1003
1004       Contributors:
1005
1006       Diab Jerius (DJERIUS)
1007
1008       Roy Storey (KIWIROY)
1009
1010       Ilya Pavlov
1011
1012       David Mertens (run4flat)
1013
1014       Mark Nunberg (mordy, mnunberg)
1015
1016       Christian Walde (Mithaldu)
1017
1018       Brian Wightman (MidLifeXis)
1019
1020       Zaki Mughal (zmughal)
1021
1022       mohawk (mohawk2, ETJ)
1023
1024       Vikas N Kumar (vikasnkumar)
1025
1026       Flavio Poletti (polettix)
1027
1028       Salvador Fandiño (salva)
1029
1030       Gianni Ceccarelli (dakkar)
1031
1032       Pavel Shaydo (zwon, trinitum)
1033
1034       Kang-min Liu (劉康民, gugod)
1035
1036       Nicholas Shipp (nshp)
1037
1038       Juan Julián Merelo Guervós (JJ)
1039
1040       Joel Berger (JBERGER)
1041
1042       Petr Písař (ppisar)
1043
1044       Lance Wicks (LANCEW)
1045
1046       Ahmad Fatoum (a3f, ATHREEF)
1047
1048       José Joaquín Atria (JJATRIA)
1049
1050       Duke Leto (LETO)
1051
1052       Shoichi Kaji (SKAJI)
1053
1054       Shawn Laffan (SLAFFAN)
1055
1056       Paul Evans (leonerd, PEVANS)
1057
1058       Håkon Hægland (hakonhagland, HAKONH)
1059
1060       nick nauwelaerts (INPHOBIA)
1061
1062       Florian Weimer
1063
1065       This software is copyright (c) 2011-2022 by Graham Ollis.
1066
1067       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.
1069
1070
1071
1072perl v5.38.0                      2023-07-20                   Alien::Build(3)
Impressum