1Alien::Base::ModuleBuilUds:e:rAPCIo(n3t)ributed Perl DocAulmieennt:a:tBiaosne::ModuleBuild::API(3)
2
3
4

NAME

6       Alien::Base::ModuleBuild::API - API Reference for Alien:: Authors
7

VERSION

9       version 1.17
10

DESCRIPTION

12       NOTE: Please consider for new development of Aliens that you use
13       Alien::Build and alienfile instead.  Like Alien::Base::ModuleBuild they
14       work with Alien::Base.  Unlike Alien::Base::ModuleBuild they are more
15       easily customized and handle a number of corner cases better.  For a
16       good place to start, please see Alien::Build::Manual::AlienAuthor.
17       Although the Alien-Base / Alien-Build team will continue to maintain
18       this module, (we will continue to fix bugs where appropriate), we
19       aren't adding any new features to this module.
20
21       A list of extra properties and methods provided by
22       Alien::Base::ModuleBuild beyond those contained in Module::Build::API.
23       Note that all property and method names are prefixed with "alien_" to
24       prevent future collisions Module::Build builtins.
25
26   CONSTRUCTOR
27       Alien::Base::ModuleBuild adds several parameters to the new constructor
28       in Module::Build. Unless otherwise specified all of the parameters
29       listed in Module::Build::API are available and behave identically to
30       the description contained therein.
31
32       alien_arch
33           [version 0.019]
34
35           Install module into an architecture specific directory.  This is
36           off by default, unless $ENV{ALIEN_ARCH} is true.  Most Alien
37           distributions will be installing binary code.  If you are an
38           integrator where the @INC path is shared by multiple Perls in a
39           non-homogeneous environment you can set $ENV{ALIEN_ARCH} to 1 and
40           Alien modules will be installed in architecture specific
41           directories.
42
43       alien_autoconf_with_pic
44           [version 0.005]
45
46           Add "--with-pic" option to autoconf style "configure" script when
47           called.  This is the default, and normally a good practice.
48           Normally autoconf will ignore this and any other options that it
49           does not recognize, but some non-autoconf "configure" scripts may
50           complain.
51
52       alien_bin_requires
53           [version 0.006]
54
55           Hash reference of modules (keys) and versions (values) that
56           specifies "Alien" modules that provide binary tools that are
57           required to build.  Any Alien::Base module that includes binaries
58           should work.  Also supported are Alien::MSYS, Alien::CMake,
59           Alien::TinyCC and Alien::Autotools.
60
61           [version 0.007]
62
63           These only become required for building if Alien::Base::ModuleBuild
64           determines that a source code build is required.
65
66       alien_build_commands
67           [version 0.001]
68
69           An arrayref of commands used to build the library in the directory
70           specified in "alien_temp_dir". Each command is first passed through
71           the command interpolation engine, so those variables may be used.
72           The default is tailored to the GNU toolchain, i.e. AutoConf and
73           Make; it is "[ '%c --prefix=%s', 'make' ]".
74
75           [version 0.009]
76
77           Each command may be either a string or an array reference.  If the
78           array reference form is used then the multiple argument form of
79           "system" is used.  Prior to version 0.009, only the string form was
80           supported.
81
82       alien_env
83           [version 0.027]
84
85           Environment overrides.  Allows you to set environment variables as
86           a hash reference that will override environment variables.  You can
87           use the same interpolated escape sequences and helpers that
88           commands use.  Set to undef to remove the variable.
89
90            ...
91            Alien::Base::ModuleBuild->new(
92              ...
93              alien_env => {
94                PERL => '%X',     # sets the environment variable PERL to the location
95                                  # of the Perl interpreter.
96                PERCENT => '%%',  # evaluates to '%'
97                REMOVE => undef,  # remove the environment variable if it is defined
98              },
99              ...
100            );
101            ...
102
103           Please keep in mind that frequently users have a good reason to
104           have set environment variables, and you should not override them
105           without a good reason.  An example of a good justification would be
106           if a project has a Makefile that interacts badly with common
107           environment variables.  This can sometimes be a problem since
108           Makefile variables can be overridden with environment variables.
109
110           A useful pattern is to use a helper to only override an environment
111           variable if it is not already set.
112
113            ...
114            Alien::Base::ModuleBuild->new(
115              ...
116              alien_helper => {
117                foo => '$ENV{FOO}||"my preferred value if not already set"'
118              },
119              alien_env => {
120                FOO => '%{foo}',
121              },
122              ...
123            );
124            ...
125
126           A common pitfall with environment variables is that setting one to
127           the empty string ('') is not portable.  On Unix it works fine as
128           you would expect, but in Windows it actually unsets the environment
129           variable, which may not be what you intend.
130
131            ...
132            Alien::Base::ModuleBuild->new(
133              ...
134              alien_env => {
135                # is allowed, but may not do what you intend
136                # on some platforms!
137                FOO => '',
138              },
139            );
140            ...
141
142       alien_extra_site_config
143           [version 0.030]
144
145           Append extra values to the "config.site" file when using autoconf.
146
147           When <autoconf> is detected, a "config.site" file is created with
148           values appropriate for building software that can link against the
149           Perl that you are building with.  This is important on some
150           platforms, for example 64 bit systems where the compilers generate
151           32 bit code by default.  You can also add values to the
152           "config.site" file using this directive.
153
154           For values that are already provided by "Alien::Base::ModuleBuild",
155           your value will be appended after the existing value.  For values
156           that aren't provided, it will simply use your value by itself.
157
158           For example if you needed to add a define to a CFLAGS, you might do
159           something like this:
160
161            ...
162            Alien::Base::ModuleBuild->new(
163              ...
164              alien_extra_site_config => {
165                # CFLAGS is usually specified by A::B::MB
166                CFLAGS => '-DFOO=1',
167                # BAR usually is not.
168                BAR => 'baz',
169              },
170              ...
171            );
172            ...
173
174           And the actual value for CFLAGS in the "config.site" might have
175           values like this:
176
177            CFLAGS=-O3 -g -DFOO=1
178            BAR=baz
179
180       alien_ffi_name
181           [version 0.007]
182
183           The name of the shared library for use with FFI.  Provided for
184           situations where the shared library name cannot be determined from
185           the "pkg-config" name specified with "alien_name".  For example
186           "libxml2" has a "pkg-config" of "libxml-2.0", but a shared library
187           name of "xml2".  By default alien_name is used with any "lib"
188           prefix removed.  For example "libarchive" to be translated into
189           "archive" which is what you want for that package.
190
191       alien_helper
192           [version 0.020]
193
194           Provide helpers to generate commands or arguments at build or
195           install time.  This property is a hash reference.  The keys are the
196           helper names and the values are strings containing Perl code that
197           will be evaluated and interpolated into the command before
198           execution.  Because helpers are only needed when building a package
199           from the source code, any dependency may be specified as an
200           "alien_bin_requires".  For example:
201
202            ...
203            Alien::Base::ModuleBuild->new(
204              ...
205              alien_bin_requires => {
206                'Alien::foo' => 0,
207              },
208              alien_helper => {
209                'foocommand'  => 'Alien::foo->some_command',
210                'fooargument' => 'Alien::foo->some_argument',
211              },
212              alien_build_commands => [
213                '%{foocommand} %{fooargument}',
214              ],
215              ...
216            );
217
218           [version 0.022]
219
220           One helper that you get for free is "%{pkg_config}" which will be
221           the pkg-config implementation chosen by Alien::Base::ModuleBuild.
222           This will either be the real pkg-config provided by the operating
223           system (preferred) or PkgConfig, the pure perl implementation found
224           on CPAN.
225
226       alien_inline_auto_include
227           [version 0.006]
228
229           Array reference containing the list of header files to be used
230           automatically by "Inline::C" and "Inline::CPP".
231
232       alien_install_commands
233           [version 0.001]
234
235           An arrayref of commands used to install it to the share directory
236           specified by interpolation var %s. Each command is first passed
237           through the command interpolation engine, so those variables may be
238           used. The default is tailored to the GNU toolchain, i.e. AutoConf
239           and Make; it is "[ 'make install' ]".
240
241           [version 0.009]
242
243           Each command may be either a string or an array reference.  If the
244           array reference form is used then the multiple argument form of
245           "system" is used.  Prior to version 0.009, only the string form was
246           supported.
247
248       alien_install_type
249           [version 1.08]
250
251           Set the install type.  Legal values are "system" and "share".  The
252           environment variable "ALIEN_INSTALL_TYPE" and "ALIEN_FORCE" will be
253           used in preference over this property.
254
255       alien_isolate_dynamic
256           [version 0.005]
257
258           If set to true, then dynamic libraries will be moved from the "lib"
259           directory to a separate "dynamic" directory.  This makes them
260           available for FFI modules (see FFI::Platypus), while preferring
261           static libraries when creating XS extensions.
262
263       alien_msys
264           [version 0.006]
265
266           On windows wrap build and install commands in an "MSYS" environment
267           using Alien::MSYS.  This option will automatically add Alien::MSYS
268           as a build requirement when building on Windows.
269
270       alien_name
271           [version 0.001]
272
273           The name of the primary library which will be provided. This should
274           be in the form to be passed to "pkg-config". This name is available
275           in the command interpolation as %n.
276
277       alien_provides_cflags
278       alien_provides_libs
279           [version 0.001]
280
281           These parameters, if specified, augment the information found by
282           pkg-config. If no package config data is found, these are used to
283           generate the necessary information. In that case, if these are not
284           specified, they are attempted to be created from found shared-
285           object files and header files. They both are empty by default.
286
287       alien_repository
288           [version 0.001]
289
290           A hashref or arrayref of hashrefs defining the repositories used to
291           find and fetch library tarballs (or zipballs etc.). These
292           attributes are used to create
293           "Alien::Base::ModuleBuild::Repository" objects (or more likely,
294           subclasses thereof). Which class is created is governed by the
295           "protocol" attribute and the "alien_repository_class" property
296           below. Available attributes are:
297
298           protocol
299               One of "ftp", "http" "https" or "local". The first three are
300               obvious, "local" allows packaging a tarball with the Alien::
301               module.
302
303               If your repository is going to need "https", make sure that you
304               specify that, because it will inform Alien::Base::ModuleBuild
305               that you will need the prereqs for SSL (namely Net::SSLeay and
306               IO::Socket::SSL).
307
308           protocol_class
309               Defines the protocol handler class. Defaults to 'Net::FTP' or
310               'HTTP::Tiny' as appropriate.
311
312           host
313               This is either the root server address for the FTP and HTTP
314               classes (i.e. "my.server.com")
315
316           location
317               This key is protocol specific. For FTP this contains the name
318               of the folder to search. For HTTP this is the page to be
319               searched for links; this is specified as a path relative to the
320               "host". For a local file, this specifies the folder containing
321               the tarball relative to the "base_dir".
322
323           pattern
324               This is a "qr" regex matching acceptable files found in the
325               "location". If the pattern contains a capture group, the
326               captured string is interpreted as the version number. N.B. if
327               no versions are found, the files are sorted by filename using
328               version semantics, this mechanism is not likely to be as
329               accurate as specifying a capture group.
330
331           exact_filename
332               This key may be specified in place of "pattern" when the
333               filename of the tarball is known, in which case such a file is
334               downloaded from the given "host" and "location". Note that, in
335               general, specifying a "pattern" gives more flexibility, but
336               there may be cases when you find more convenient to use
337               "exact_filename".
338
339           exact_version
340               This key may be specified with the "exact_filename" key when
341               the version of the tarball is known.
342
343           platform
344               This attribute is a string telling the repository validator
345               which platform the repository serves. This may be the string
346               "src" (the default) for platform-independent source files, or a
347               string which matches the Module::Build method "os_type" (e.g.
348               "Windows", "Unix", "MacOS", "VMS").
349
350           c_compiler_required
351               If true (the default), then a C compiler is required to build
352               from source.
353
354       alien_repository_class
355           [version 0.001]
356
357           As the repositories in "alien_repository" are converted to objects,
358           this hash controls the type of object that is created. The keys are
359           the relevant protocol. This allows for easy subclassing any or all
360           protocol classes. The defaults are as follows.
361
362            http    => 'Alien::Base::ModuleBuild::Repository::HTTP',
363            ftp     => 'Alien::Base::ModuleBuild::Repository::FTP',
364            local   => 'Alien::Base::ModuleBuild::Repository::Local',
365            default => 'Alien::Base::ModuleBuild::Repository',
366
367           Unlike most Module::Build parameters, authors may specify only
368           those keys which are to be overridden. If any of the above keys are
369           not specified, the above defaults will be used.
370
371       alien_repository_default
372           [version 0.001]
373
374           This property is a shortcut for specifying multiple repositories
375           with similar attributes. If a repository attribute is not defined
376           in its "alien_repository" hashref, but that attribute is defined
377           here, then this value will be used. This hashref is empty by
378           default.
379
380       alien_selection_method
381           [not yet implemented]
382
383           This is intended to choose the mechanism for selecting one file
384           from many. The default name is "newest".
385
386       alien_share_dir
387           [version 0.001]
388
389           The name of the folder which will both serve a stub share directory
390           via Module::Build's "share_dir"/"dist_dir" parameter. This
391           directory is added in a smart manner which attempts not to
392           interfere with other author-defined "share_dir"s. The default name
393           is "_share". This folder will hold a README file which is then
394           installed to the target installed share location. It is THAT
395           location that the library will be installed to.
396
397       alien_stage_install
398           It might be tempting to use this option if you have a library or
399           tool that hard codes paths from the install location inside the
400           executable or library code.  However, using this option relies on
401           blib detection which is not very reliable, and can leave your
402           install in an broken state if the package install step fails.  If
403           you really need this option, please consider instead migrating to
404           Alien::Build, which has a much more reliable way of staging
405           installs correctly.
406
407           [version 0.016]
408
409           Alien packages are installed directly into the blib directory by
410           the `./Build' command rather than to the final location during the
411           `./Build install` step.
412
413           [version 0.017]
414
415           As of 0.017 this is the default.
416
417       alien_temp_dir
418           [version 0.001]
419
420           The name of the temporary folder which will house the library when
421           it is downloaded and built. The default name is "_alien".
422
423       alien_test_commands
424           [version 0.001]
425
426           An arrayref of commands used to test the library.  Each command is
427           first passed through the command interpolation engine, so those
428           variables may be used.  The default is to do no tests.  The most
429           common command used by the GNU toolchain is "[ 'make check' ]", but
430           beware that is not supported by all packages.
431
432           [version 0.009]
433
434           Each command may be either a string or an array reference.  If the
435           array reference form is used, then the multiple argument form of
436           system is used.
437
438       alien_version_check
439           [version 0.001]
440
441           A command to run to check the version of the library installed on
442           the system. The default is "pkg-config --modversion %n".
443
444   PACKAGE AND ENVIRONMENT VARIABLES
445       A few global variables are used to set gross behavior. For each pair of
446       variables, if both are set, the environment variable takes precedence.
447
448       $ENV{ALIEN_ARCH}
449           [version 0.017]
450
451           Setting this changes the default for alien_arch above.  If the
452           module specifies its own alien_arch in its "Build.PL" file then it
453           will override this setting.  Typically installing into an
454           architecture specific directory is what you want to do, since most
455           Alien::Base based distributions provide architecture specific
456           binary code, so you should consider carefully before installing
457           modules with this environment variable set to 0.  This may be
458           useful for integrators creating a single non-architecture specific
459           RPM, .deb or similar package.  In this case the integrator should
460           ensure that the Alien package be installed with a system
461           install_type and use the system package.
462
463       $ENV{ALIEN_BLIB}
464           Setting this to true indicates that you don't intend to actually
465           install your Alien::Base subclass, but rather use it from the built
466           blib directory. This behavior is mostly to support automated
467           testing from CPANtesters and should be automagically determined. If
468           by chance you happen to trip the behavior accidentally, setting
469           this environment variable to false (0) before building should
470           prevent problems.
471
472       $Alien::Base::ModuleBuild::Force
473       $ENV{ALIEN_FORCE}
474           Setting either to a true value will cause the builder to ignore a
475           system-wide installation and build a local version of the library.
476           This is the equivalent to setting $ENV{ALIEN_INSTALL_TYPE} to
477           'share'.  $ENV{ALIEN_INSTALL_TYPE} takes precedence.
478
479       $ENV{ALIEN_INSTALL_TYPE}
480           Setting to "share" will ignore a system-wide installation and build
481           a local version of the library.  Setting to "system" will only use
482           a system-wide installation and die if it cannot be found.
483
484       $Alien::Base::ModuleBuild::Verbose
485       $ENV{ALIEN_VERBOSE}
486           Setting the either to a true value will output a little more info
487           from within the module itself. At this point Alien::Base is going
488           to be fairly verbose without this enabled.
489
490   CONFIG DATA
491       The Alien::Base system needs to store some data to be used in other
492       phases of the build and eventual use. This is done via the mechanism
493       provided by Module::Build::ConfigData. During the build-phase this
494       information is mutable and is available through the
495       "Module::Build::config_data" method. As the build-phase ends the data
496       is serialized and stored as "Alien::MyModule::ConfigData" (assuming you
497       are authoring "Alien::MyModule"). Then during the use-phase, the
498       "Alien::MyModule::ConfigData::config" method (via the
499       "Alien::MyModule::config" wrapper) is used to query the information.
500       This data is not strictly immutable, but it changing it involves file
501       permissions and is best left alone.
502
503       Config keys of interest are:
504
505       name
506           Holder for "alien_name" as needed by pkg-config.
507
508       install_type
509           Remembers if the library was found system-wide (value: "system") or
510           was installed during build (value: "share").
511
512       pkgconfig
513           A hashref of Alien::Base::PkgConfig objects created from .pc files
514           found in "working_directory". One extra object (whose key is
515           "_manual" is created from the "alien_provides_*" information.
516
517       version
518           The version number installed or available.
519
520       working_directory
521           Holder for the full path to the extracted source of the library.
522           This is used to munge the pkg-config data later on.
523
524   COMMAND INTERPOLATION
525       Before Alien::Base::ModuleBuild executes system commands, it replaces a
526       few special escape sequences with useful data. This is needed
527       especially for referencing the full path to the "alien_share_dir"
528       before this path is known. The available sequences are:
529
530       %{helper}
531           [version 0.020]
532
533           Call the given helper, either provided by the "alien_helper" or
534           "alien_bin_requires" property.  See Alien::Base#alien_helper.
535
536       %c  Platform independent incantation for running autoconf "configure"
537           script.  On *nix systems this is "./configure", on Windows this is
538           "sh configure".  On windows Alien::MSYS is injected as a dependency
539           and all commands are executed in an "MSYS" environment.
540
541       %n  Shortcut for the name stored in "alien_name"
542
543            pkg-config --modversion %n
544
545       %p  deprecated
546
547           Platform independent "local command prefix". On *nix systems this
548           is "./", on Windows it is an empty string.
549
550            %pconfigure
551
552           Please note that this only works to run scripts on Unix, and does
553           not work on Windows.  It is thus, not fit for purpose and should
554           not be used.  As an alternative:
555
556           autoconf "configure"
557               If you are trying to invoke the autoconf configure script, use
558               %c instead.  This will use the correct incantation on either
559               Unix like systems and on Windows.
560
561           Some other script
562               Invoke the interpreter directly.  For example, if you have a
563               Python script use "python foo.py", if you have a Perl script
564               use "%X foo.pl", if you have an sh script use "sh foo.sh".
565               These are all portable.  For sh, be sure to set the
566               "alien_msys" property so that it will work on Windows.
567
568       %s  The full path to the installed location of the the share directory
569           (builder method "alien_library_destination").  This is where the
570           library should install itself; for autoconf style installs this
571           will look like
572
573            --prefix=%s
574
575           This will be the local blib directory location if
576           "alien_stage_install" is true (which is the default as of 0.17.
577           This will be the final install location if "alien_stage_install" is
578           false (which was the default prior to 0.17).  Please see the
579           documentation above on "alien_stage_install" which includes some
580           caveats before you consider changing this option.
581
582       %v  Captured version of the original archive.
583
584       %x  The current Perl interpreter (aka $^X)
585
586       %X  [version 0.027]
587
588           The current Perl interpreter using the Unix style path separator
589           "/" instead of the native Windows "\".
590
591       %%  A literal "%".
592

SEE ALSO

594       •   Module::Build::API
595

AUTHOR

597       Original author: Joel A Berger <joel.a.berger@gmail.com>
598
599       Current maintainer: Graham Ollis <plicease@cpan.org>
600
601       Contributors:
602
603       David Mertens (run4flat)
604
605       Mark Nunberg (mordy, mnunberg)
606
607       Christian Walde (Mithaldu)
608
609       Brian Wightman (MidLifeXis)
610
611       Graham Ollis (plicease)
612
613       Zaki Mughal (zmughal)
614
615       mohawk2
616
617       Vikas N Kumar (vikasnkumar)
618
619       Flavio Poletti (polettix)
620
621       Salvador Fandiño (salva)
622
623       Gianni Ceccarelli (dakkar)
624
625       Pavel Shaydo (zwon, trinitum)
626
627       Kang-min Liu (劉康民, gugod)
628
629       Nicholas Shipp (nshp)
630
631       Petr Písař (ppisar)
632
633       Alberto Simões (ambs)
634
636       This software is copyright (c) 2012-2022 by Joel A Berger.
637
638       This is free software; you can redistribute it and/or modify it under
639       the same terms as the Perl 5 programming language system itself.
640
641
642
643perl v5.36.0                      2023-01-19  Alien::Base::ModuleBuild::API(3)
Impressum