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

DESCRIPTION

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

AUTHOR

568       Original author: Joel Berger, <joel.a.berger@gmail.com>
569
570       Current maintainer: Graham Ollis <plicease@cpan.org> and the
571       Alien::Base team
572

SEE ALSO

574       ยท   Module::Build::API
575
577       Copyright (C) 2012-2017 by Joel Berger
578
579       This library is free software; you can redistribute it and/or modify it
580       under the same terms as Perl itself.
581
582
583
584perl v5.28.1                      2018-12-19  Alien::Base::ModuleBuild::API(3)
Impressum