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 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 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 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 alien_arch
30 [version 0.019]
31 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 alien_autoconf_with_pic
41 [version 0.005]
42 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 alien_bin_requires
50 [version 0.006]
51 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 [version 0.007]
59 These only become required for building if Alien::Base::ModuleBuild
61 determines that a source code build is required.
62 alien_build_commands
64 [version 0.001]
65 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 [version 0.009]
73 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 alien_env
80 [version 0.027]
81 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 ...
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 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 A useful pattern is to use a helper to only override an environment
108 variable if it is not already set.
109 ...
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 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 ...
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 alien_extra_site_config
140 [version 0.030]
141 Append extra values to the "config.site" file when using autoconf.
143 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 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 For example if you needed to add a define to a CFLAGS, you might do
156 something like this:
157 ...
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 And the actual value for CFLAGS in the "config.site" might have
172 values like this:
173 CFLAGS=-O3 -g -DFOO=1
175 BAR=baz
176 alien_ffi_name
178 [version 0.007]
179 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 alien_helper
189 [version 0.020]
190 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 ...
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 [version 0.022]
216 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 alien_inline_auto_include
224 [version 0.006]
225 Array reference containing the list of header files to be used
227 automatically by "Inline::C" and "Inline::CPP".
228 alien_install_commands
230 [version 0.001]
231 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 [version 0.009]
239 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 alien_install_type
246 [version 1.08]
247 Set the install type. Legal values are "system" and "share". The
249 environment variable "ALIEN_INSTALL_TYPE" and "ALIEN_FORCE" will be
250 used in preference over this property.
251 alien_isolate_dynamic
253 [version 0.005]
254 If set to true, then dynamic libraries will be moved from the "lib"
256 directory to a separate "dynamic" directory. This makes them
257 available for FFI modules (see FFI::Platypus), while preferring
258 static libraries when creating XS extensions.
259 alien_msys
261 [version 0.006]
262 On windows wrap build and install commands in an "MSYS" environment
264 using Alien::MSYS. This option will automatically add Alien::MSYS
265 as a build requirement when building on Windows.
266 alien_name
268 [version 0.001]
269 The name of the primary library which will be provided. This should
271 be in the form to be passed to "pkg-config". This name is available
272 in the command interpolation as %n.
273 alien_provides_cflags
275 alien_provides_libs
276 [version 0.001]
277 These parameters, if specified, augment the information found by
279 pkg-config. If no package config data is found, these are used to
280 generate the necessary information. In that case, if these are not
281 specified, they are attempted to be created from found shared-
282 object files and header files. They both are empty by default.
283 alien_repository
285 [version 0.001]
286 A hashref or arrayref of hashrefs defining the repositories used to
288 find and fetch library tarballs (or zipballs etc.). These
289 attributes are used to create
290 "Alien::Base::ModuleBuild::Repository" objects (or more likely,
291 subclasses thereof). Which class is created is governed by the
292 "protocol" attribute and the "alien_repository_class" property
293 below. Available attributes are:
294 protocol
296 One of "ftp", "http" "https" or "local". The first three are
297 obvious, "local" allows packaging a tarball with the Alien::
298 module.
299 If your repository is going to need "https", make sure that you
301 specify that, because it will inform Alien::Base::ModuleBuild
302 that you will need the prereqs for SSL (namely Net::SSLeay and
303 IO::Socket::SSL).
304 protocol_class
306 Defines the protocol handler class. Defaults to 'Net::FTP' or
307 'HTTP::Tiny' as appropriate.
308 host
310 This is either the root server address for the FTP and HTTP
311 classes (i.e. "my.server.com")
312 location
314 This key is protocol specific. For FTP this contains the name
315 of the folder to search. For HTTP this is the page to be
316 searched for links; this is specified as a path relative to the
317 "host". For a local file, this specifies the folder containing
318 the tarball relative to the "base_dir".
319 pattern
321 This is a "qr" regex matching acceptable files found in the
322 "location". If the pattern contains a capture group, the
323 captured string is interpreted as the version number. N.B. if
324 no versions are found, the files are sorted by filename using
325 version semantics, this mechanism is not likely to be as
326 accurate as specifying a capture group.
327 exact_filename
329 This key may be specified in place of "pattern" when the
330 filename of the tarball is known, in which case such a file is
331 downloaded from the given "host" and "location". Note that, in
332 general, specifying a "pattern" gives more flexibility, but
333 there may be cases when you find more convenient to use
334 "exact_filename".
335 exact_version
337 This key may be specified with the "exact_filename" key when
338 the version of the tarball is known.
339 platform
341 This attribute is a string telling the repository validator
342 which platform the repository serves. This may be the string
343 "src" (the default) for platform-independent source files, or a
344 string which matches the Module::Build method "os_type" (e.g.
345 "Windows", "Unix", "MacOS", "VMS").
346 c_compiler_required
348 If true (the default), then a C compiler is required to build
349 from source.
350 alien_repository_class
352 [version 0.001]
353 As the repositories in "alien_repository" are converted to objects,
355 this hash controls the type of object that is created. The keys are
356 the relevant protocol. This allows for easy subclassing any or all
357 protocol classes. The defaults are as follows.
358 http => 'Alien::Base::ModuleBuild::Repository::HTTP',
360 ftp => 'Alien::Base::ModuleBuild::Repository::FTP',
361 local => 'Alien::Base::ModuleBuild::Repository::Local',
362 default => 'Alien::Base::ModuleBuild::Repository',
363 Unlike most Module::Build parameters, authors may specify only
365 those keys which are to be overridden. If any of the above keys are
366 not specified, the above defaults will be used.
367 alien_repository_default
369 [version 0.001]
370 This property is a shortcut for specifying multiple repositories
372 with similar attributes. If a repository attribute is not defined
373 in its "alien_repository" hashref, but that attribute is defined
374 here, then this value will be used. This hashref is empty by
375 default.
376 alien_selection_method
378 [not yet implemented]
379 This is intended to choose the mechanism for selecting one file
381 from many. The default name is "newest".
382 alien_share_dir
384 [version 0.001]
385 The name of the folder which will both serve a stub share directory
387 via Module::Build's "share_dir"/"dist_dir" parameter. This
388 directory is added in a smart manner which attempts not to
389 interfere with other author-defined "share_dir"s. The default name
390 is "_share". This folder will hold a README file which is then
391 installed to the target installed share location. It is THAT
392 location that the library will be installed to.
393 alien_stage_install
395 It might be tempting to use this option if you have a library or
396 tool that hard codes paths from the install location inside the
397 executable or library code. However, using this option relies on
398 blib detection which is not very reliable, and can leave your
399 install in an broken state if the package install step fails. If
400 you really need this option, please consider instead migrating to
401 Alien::Build, which has a much more reliable way of staging
402 installs correctly.
403 [version 0.016]
405 Alien packages are installed directly into the blib directory by
407 the `./Build' command rather than to the final location during the
408 `./Build install` step.
409 [version 0.017]
411 As of 0.017 this is the default.
413 alien_temp_dir
415 [version 0.001]
416 The name of the temporary folder which will house the library when
418 it is downloaded and built. The default name is "_alien".
419 alien_test_commands
421 [version 0.001]
422 An arrayref of commands used to test the library. Each command is
424 first passed through the command interpolation engine, so those
425 variables may be used. The default is to do no tests. The most
426 common command used by the GNU toolchain is "[ 'make check' ]", but
427 beware that is not supported by all packages.
428 [version 0.009]
430 Each command may be either a string or an array reference. If the
432 array reference form is used, then the multiple argument form of
433 system is used.
434 alien_version_check
436 [version 0.001]
437 A command to run to check the version of the library installed on
439 the system. The default is "pkg-config --modversion %n".
440 PACKAGE AND ENVIRONMENT VARIABLES
442 A few global variables are used to set gross behavior. For each pair of
443 variables, if both are set, the environment variable takes precedence.
444 $ENV{ALIEN_ARCH}
446 [version 0.017]
447 Setting this changes the default for alien_arch above. If the
449 module specifies its own alien_arch in its "Build.PL" file then it
450 will override this setting. Typically installing into an
451 architecture specific directory is what you want to do, since most
452 Alien::Base based distributions provide architecture specific
453 binary code, so you should consider carefully before installing
454 modules with this environment variable set to 0. This may be
455 useful for integrators creating a single non-architecture specific
456 RPM, .dep or similar package. In this case the integrator should
457 ensure that the Alien package be installed with a system
458 install_type and use the system package.
459 $ENV{ALIEN_BLIB}
461 Setting this to true indicates that you don't intend to actually
462 install your Alien::Base subclass, but rather use it from the built
463 blib directory. This behavior is mostly to support automated
464 testing from CPANtesters and should be automagically determined. If
465 by chance you happen to trip the behavior accidentally, setting
466 this environment variable to false (0) before building should
467 prevent problems.
468 $Alien::Base::ModuleBuild::Force
470 $ENV{ALIEN_FORCE}
471 Setting either to a true value will cause the builder to ignore a
472 system-wide installation and build a local version of the library.
473 This is the equivalent to setting $ENV{ALIEN_INSTALL_TYPE} to
474 'share'. $ENV{ALIEN_INSTALL_TYPE} takes precedence.
475 $ENV{ALIEN_INSTALL_TYPE}
477 Setting to "share" will ignore a system-wide installation and build
478 a local version of the library. Setting to "system" will only use
479 a system-wide installation and die if it cannot be found.
480 $Alien::Base::ModuleBuild::Verbose
482 $ENV{ALIEN_VERBOSE}
483 Setting the either to a true value will output a little more info
484 from within the module itself. At this point Alien::Base is going
485 to be fairly verbose without this enabled.
486 CONFIG DATA
488 The Alien::Base system needs to store some data to be used in other
489 phases of the build and eventual use. This is done via the mechanism
490 provided by Module::Build::ConfigData. During the build-phase this
491 information is mutable and is available through the
492 "Module::Build::config_data" method. As the build-phase ends the data
493 is serialized and stored as "Alien::MyModule::ConfigData" (assuming you
494 are authoring "Alien::MyModule"). Then during the use-phase, the
495 "Alien::MyModule::ConfigData::config" method (via the
496 "Alien::MyModule::config" wrapper) is used to query the information.
497 This data is not strictly immutable, but it changing it involves file
498 permissions and is best left alone.
499 Config keys of interest are:
501 name
503 Holder for "alien_name" as needed by pkg-config.
504 install_type
506 Remembers if the library was found system-wide (value: "system") or
507 was installed during build (value: "share").
508 pkgconfig
510 A hashref of Alien::Base::PkgConfig objects created from .pc files
511 found in "working_directory". One extra object (whose key is
512 "_manual" is created from the "alien_provides_*" information.
513 version
515 The version number installed or available.
516 working_directory
518 Holder for the full path to the extracted source of the library.
519 This is used to munge the pkg-config data later on.
520 COMMAND INTERPOLATION
522 Before Alien::Base::ModuleBuild executes system commands, it replaces a
523 few special escape sequences with useful data. This is needed
524 especially for referencing the full path to the "alien_share_dir"
525 before this path is known. The availble sequences are:
526 %{helper}
528 [version 0.020]
529 Call the given helper, either provided by the "alien_helper" or
531 "alien_bin_requires" property. See Alien::Base#alien_helper.
532 %c Platform independent incantation for running autoconf "configure"
534 script. On *nix systems this is "./configure", on Windows this is
535 "sh configure". On windows Alien::MSYS is injected as a dependency
536 and all commands are executed in an "MSYS" environment.
537 %n Shortcut for the name stored in "alien_name"
539 pkg-config --modversion %n
541 %p deprecated
543 Platform independent "local command prefix". On *nix systems this
545 is "./", on Windows it is an empty string.
546 %pconfigure
548 Please note that this only works to run scripts on Unix, and does
550 not work on Windows. It is thus, not fit for purpose and should
551 not be used. As an alternative:
552 autoconf "configure"
554 If you are trying to invoke the autoconf configure script, use
555 %c instead. This will use the correct incantation on either
556 Unix like systems and on Windows.
557 Some other script
559 Invoke the interpreter directly. For example, if you have a
560 python script use "python foo.py", if you have a Perl script
561 use "%X foo.pl", if you have an sh script use "sh foo.sh".
562 These are all portable. For sh, be sure to set the
563 "alien_msys" property so that it will work on Windows.
564 %s The full path to the installed location of the the share directory
566 (builder method "alien_library_destination"). This is where the
567 library should install itself; for autoconf style installs this
568 will look like
569 --prefix=%s
571 This will be the local blib directory location if
573 "alien_stage_install" is true (which is the default as of 0.17.
574 This will be the final install location if "alien_stage_install" is
575 false (which was the default prior to 0.17). Please see the
576 documentation above on "alien_stage_install" which includes some
577 caveats before you consider changing this option.
578 %v Captured version of the original archive.
580 %x The current Perl interpreter (aka $^X)
582 %X [version 0.027]
584 The current Perl interpreter using the Unix style path separator
586 "/" instead of the native Windows "\".
587 %% A literal "%".
589
591 Original author: Joel Berger, <joel.a.berger@gmail.com>
592 Current maintainer: Graham Ollis <plicease@cpan.org> and the
594 Alien::Base team
595
597 ยท Module::Build::API
598
600 Copyright (C) 2012-2017 by Joel Berger
601 This library is free software; you can redistribute it and/or modify it
603 under the same terms as Perl itself.
604perl v5.30.1 2019-11-28 Alien::Base::ModuleBuild::API(3)