1Alien::Base::ModuleBuilUds:e:rAPCIo(n3t)ributed Perl DocAulmieennt:a:tBiaosne::ModuleBuild::API(3)
2
6 Alien::Base::ModuleBuild::API - API Reference for Alien:: Authors
7
9 version 1.17
10
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 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 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 alien_arch
33 [version 0.019]
34 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 alien_autoconf_with_pic
44 [version 0.005]
45 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 alien_bin_requires
53 [version 0.006]
54 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 [version 0.007]
62 These only become required for building if Alien::Base::ModuleBuild
64 determines that a source code build is required.
65 alien_build_commands
67 [version 0.001]
68 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 [version 0.009]
76 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 alien_env
83 [version 0.027]
84 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 ...
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 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 A useful pattern is to use a helper to only override an environment
111 variable if it is not already set.
112 ...
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 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 ...
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 alien_extra_site_config
143 [version 0.030]
144 Append extra values to the "config.site" file when using autoconf.
146 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 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 For example if you needed to add a define to a CFLAGS, you might do
159 something like this:
160 ...
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 And the actual value for CFLAGS in the "config.site" might have
175 values like this:
176 CFLAGS=-O3 -g -DFOO=1
178 BAR=baz
179 alien_ffi_name
181 [version 0.007]
182 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 alien_helper
192 [version 0.020]
193 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 ...
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 [version 0.022]
219 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 alien_inline_auto_include
227 [version 0.006]
228 Array reference containing the list of header files to be used
230 automatically by "Inline::C" and "Inline::CPP".
231 alien_install_commands
233 [version 0.001]
234 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 [version 0.009]
242 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 alien_install_type
249 [version 1.08]
250 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 alien_isolate_dynamic
256 [version 0.005]
257 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 alien_msys
264 [version 0.006]
265 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 alien_name
271 [version 0.001]
272 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 alien_provides_cflags
278 alien_provides_libs
279 [version 0.001]
280 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 alien_repository
288 [version 0.001]
289 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 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 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 protocol_class
309 Defines the protocol handler class. Defaults to 'Net::FTP' or
310 'HTTP::Tiny' as appropriate.
311 host
313 This is either the root server address for the FTP and HTTP
314 classes (i.e. "my.server.com")
315 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 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 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 exact_version
340 This key may be specified with the "exact_filename" key when
341 the version of the tarball is known.
342 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 c_compiler_required
351 If true (the default), then a C compiler is required to build
352 from source.
353 alien_repository_class
355 [version 0.001]
356 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 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 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 alien_repository_default
372 [version 0.001]
373 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 alien_selection_method
381 [not yet implemented]
382 This is intended to choose the mechanism for selecting one file
384 from many. The default name is "newest".
385 alien_share_dir
387 [version 0.001]
388 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 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 [version 0.016]
408 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 [version 0.017]
414 As of 0.017 this is the default.
416 alien_temp_dir
418 [version 0.001]
419 The name of the temporary folder which will house the library when
421 it is downloaded and built. The default name is "_alien".
422 alien_test_commands
424 [version 0.001]
425 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 [version 0.009]
433 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 alien_version_check
439 [version 0.001]
440 A command to run to check the version of the library installed on
442 the system. The default is "pkg-config --modversion %n".
443 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 $ENV{ALIEN_ARCH}
449 [version 0.017]
450 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 $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 $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 $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 $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 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 Config keys of interest are:
504 name
506 Holder for "alien_name" as needed by pkg-config.
507 install_type
509 Remembers if the library was found system-wide (value: "system") or
510 was installed during build (value: "share").
511 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 version
518 The version number installed or available.
519 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 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 %{helper}
531 [version 0.020]
532 Call the given helper, either provided by the "alien_helper" or
534 "alien_bin_requires" property. See Alien::Base#alien_helper.
535 %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 %n Shortcut for the name stored in "alien_name"
542 pkg-config --modversion %n
544 %p deprecated
546 Platform independent "local command prefix". On *nix systems this
548 is "./", on Windows it is an empty string.
549 %pconfigure
551 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 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 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 %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 --prefix=%s
574 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 %v Captured version of the original archive.
583 %x The current Perl interpreter (aka $^X)
585 %X [version 0.027]
587 The current Perl interpreter using the Unix style path separator
589 "/" instead of the native Windows "\".
590 %% A literal "%".
592
594 • Module::Build::API
595
597 Original author: Joel A Berger <joel.a.berger@gmail.com>
598 Current maintainer: Graham Ollis <plicease@cpan.org>
600 Contributors:
602 David Mertens (run4flat)
604 Mark Nunberg (mordy, mnunberg)
606 Christian Walde (Mithaldu)
608 Brian Wightman (MidLifeXis)
610 Graham Ollis (plicease)
612 Zaki Mughal (zmughal)
614 mohawk2
616 Vikas N Kumar (vikasnkumar)
618 Flavio Poletti (polettix)
620 Salvador Fandiño (salva)
622 Gianni Ceccarelli (dakkar)
624 Pavel Shaydo (zwon, trinitum)
626 Kang-min Liu (劉康民, gugod)
628 Nicholas Shipp (nshp)
630 Petr Písař (ppisar)
632 Alberto Simões (ambs)
634
636 This software is copyright (c) 2012-2022 by Joel A Berger.
637 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.
640perl v5.36.0 2023-01-19 Alien::Base::ModuleBuild::API(3)