1Alien::Base::ModuleBuilUds(e3r)Contributed Perl DocumentAaltiieonn::Base::ModuleBuild(3)
2
6 Alien::Base::ModuleBuild - A Module::Build subclass for building
7 Alien:: modules and their libraries
8
10 version 1.17
11
13 In your Build.PL:
14 use Alien::Base::ModuleBuild;
16 my $builder = Alien::Base::ModuleBuild->new(
18 module_name => 'Alien::MyLibrary',
19 configure_requires => {
21 'Alien::Base::ModuleBuild' => '0.005',
22 'Module::Build' => '0.28'
23 },
24 requires => {
25 'Alien::Base' => '0.005',
26 },
27 alien_name => 'mylibrary', # the pkg-config name if you want
29 # to use pkg-config to discover
30 # system version of the mylibrary
31 alien_repository => {
33 protocol => 'https',
34 host => 'myhost.org',
35 location => '/path/to/tarballs',
36 pattern => qr{^mylibrary-([0-9\.]+)\.tar\.gz$},
37 },
38 # this is the default:
40 alien_build_commands => [
41 "%c --prefix=%s", # %c is a platform independent version of ./configure
42 "make",
43 ],
44 # this is the default for install:
46 alien_install_commands => [
47 "make install",
48 ],
49 alien_isolate_dynamic => 1,
51 );
52
54 NOTE: Please consider for new development of Aliens that you use
55 Alien::Build and alienfile instead. Like this module they work with
56 Alien::Base. Unlike this module they are more easily customized and
57 handle a number of corner cases better. For a good place to start,
58 please see Alien::Build::Manual::AlienAuthor. Although the Alien-Base
59 / Alien-Build team will continue to maintain this module, (we will
60 continue to fix bugs where appropriate), we aren't adding any new
61 features to this module.
62 This is a subclass of Module::Build, that with Alien::Base allows for
64 easy creation of Alien distributions. This module is used during the
65 build step of your distribution. When properly configured it will
66 use pkg-config to find and use the system version of the library
68 download, build and install the library if the system does not provide
69 it
70
72 alien_check_installed_version
73 [version 0.001]
74 my $version = $abmb->alien_check_installed_version;
76 This function determines if the library is already installed as part of
78 the operating system, and returns the version as a string. If it can't
79 be detected then it should return empty list.
80 The default implementation relies on "pkg-config", but you will
82 probably want to override this with your own implementation if the
83 package you are building does not use "pkg-config".
84 alien_check_built_version
86 [version 0.006]
87 my $version = $amb->alien_check_built_version;
89 This function determines the version of the library after it has been
91 built from source. This function only gets called if the operating
92 system version can not be found and the package is successfully built.
93 The version is returned on success. If the version can't be detected
94 then it should return empty list. Note that failing to detect a
95 version is considered a failure and the corresponding "./Build" action
96 will fail!
97 Any string is valid as a version as far as Alien::Base is concerned.
99 The most useful value would be a number or dotted decimal that most
100 software developers recognize and that software tools can
101 differentiate. In some cases packages will not have a clear version
102 number, in which case the string "unknown" would be a reasonable
103 choice.
104 The default implementation relies on "pkg-config", and other
106 heuristics, but you will probably want to override this with your own
107 implementation if the package you are building does not use
108 "pkg-config".
109 When this method is called, the current working directory will be the
111 build root.
112 If you see an error message like this:
114 Library looks like it installed, but no version was determined
116 After the package is built from source code then you probably need to
118 provide an implementation for this method.
119 alien_extract_archive
121 [version 0.024]
122 my $dir = $amb->alien_extract_archive($filename);
124 This function unpacks the given archive and returns the directory
126 containing the unpacked files.
127 The default implementation relies on Archive::Extract that is able to
129 handle most common formats. In order to handle other formats or
130 archives requiring some special treatment you may want to override this
131 method.
132 alien_do_system
134 [version 0.024]
135 my %result = $amb->alien_do_system($cmd)
137 Similar to Module::Build's do_system, also sets the path and several
139 environment variables in accordance to the object configuration (i.e.
140 "alien_bin_requires") and performs the interpolation of the patterns
141 described in "COMMAND INTERPOLATION" in Alien::Base::ModuleBuild::API.
142 Returns a set of key value pairs including "stdout", "stderr",
144 "success" and "command".
145 alien_do_commands
147 $amb->alien_do_commands($phase);
148 Executes the commands for the given phase.
150 alien_interpolate
152 my $string = $amb->alien_interpolate($string);
153 Takes the input string and interpolates the results.
155 alien_install_network
157 [version 1.16]
158 my $bool = $amb->alien_install_network;
160 Returns true if downloading source from the internet is allowed. This
162 is true unless "ALIEN_INSTALL_NETWORK" is defined and false.
163 alien_download_rule
165 [version 1.16]
166 my $rule = $amb->alien_download_rule;
168 This will return one of "warn", "digest", "encrypt",
170 "digest_or_encrypt" or "digest_and_encrypt". This is based on the
171 "ALIEN_DOWNLOAD_RULE" environment variable.
172
174 The documentation for "Module::Build" is broken up into sections:
175 General Usage (Module::Build)
177 This is the landing document for Alien::Base::ModuleBuild's parent
178 class. It describes basic usage and background information. Its
179 main purpose is to assist the user who wants to learn how to invoke
180 and control "Module::Build" scripts at the command line.
181 It also lists the extra documentation for its use. Users and
183 authors of Alien:: modules should familiarize themselves with these
184 documents. Module::Build::API is of particular importance to
185 authors.
186 Alien-Specific Usage (Alien::Base::ModuleBuild)
188 This is the document you are currently reading.
189 Authoring Reference (Alien::Base::Authoring)
191 This document describes the structure and organization of
192 "Alien::Base" based projects, beyond that contained in
193 "Module::Build::Authoring", and the relevant concepts needed by
194 authors who are writing Build.PL scripts for a distribution or
195 controlling "Alien::Base::ModuleBuild" processes programmatically.
196 Note that as it contains information both for the build and use
198 phases of Alien::Base projects, it is located in the upper
199 namespace.
200 API Reference (Alien::Base::ModuleBuild::API)
202 This is a reference to the "Alien::Base::ModuleBuild" API beyond
203 that contained in "Module::Build::API".
204 Using the resulting Alien (Alien::Build::Manual::AlienUser)
206 Once you have an Alien you or your users can review this manual for
207 how to use it. Generally speaking you should have some useful
208 usage information in your Alien's POD, but some authors choose to
209 direct their users to this manual instead.
210 Using Alien::Build instead (Alien::Build::Manual)
212 As mentioned at the top, you are encouraged to use the Alien::Build
213 and alienfile system instead. This manual is a starting point for
214 the other Alien::Build documentation.
215
217 ALIEN_ARCH
218 Set to a true value to install to an arch-specific directory.
219 ALIEN_DOWNLOAD_RULE
221 This controls security options for fetching alienized packages over
222 the internet. The legal values are:
223 "warn"
225 Warn if the package is either unencrypted or lacks a digest.
226 This is currently the default, but will change in the near
227 future.
228 "digest"
230 Fetch will not happen unless there is a digest for the
231 alienized package.
232 "encrypt"
234 Fetch will not happen unless via an encrypted protocol like
235 "https", or if the package is bundled with the Alien.
236 "digest_or_encrypt"
238 Fetch will only happen if the alienized package has a
239 cryptographic signature digest, or if an encrypted protocol
240 like "https" is used, or if the package is bundled with the
241 Alien. This will be the default in the near future.
242 "digest_and_encrypt"
244 Fetch will only happen if the alienized package has a
245 cryptographic signature digest, and is fetched via a secure
246 protocol (like "https"). Bundled packages are also considered
247 fetch via a secure protocol, but will still require a digest.
248 ALIEN_FORCE
250 Skips checking for an installed version and forces reinstalling the
251 Alien target.
252 ALIEN_INSTALL_NETWORK
254 If true (the default if not defined), then network installs will be
255 allowed. Set to 0 or another false value to turn off network
256 installs.
257 ALIEN_INSTALL_TYPE
259 Set to "share" or "system" to override the install type. Set to
260 "default" or unset to restore the default.
261 ALIEN_VERBOSE
263 Enables verbose output from M::B::do_system.
264 ALIEN_${MODULENAME}_REPO_${PROTOCOL}_${KEY}
266 Overrides $KEY in the given module's repository configuration
267 matching $PROTOCOL. For example,
268 "ALIEN_OPENSSL_REPO_FTP_HOST=ftp.example.com".
269
271 Alien::Build
272 alienfile
273 Alien::Build::Manual::AlienAuthor
274 Alien
275
277 Thanks also to
278 Christian Walde (Mithaldu)
280 For productive conversations about component interoperability.
281 kmx For writing Alien::Tidyp from which I drew many of my initial
283 ideas.
284 David Mertens (run4flat)
286 For productive conversations about implementation.
287 Mark Nunberg (mordy, mnunberg)
289 For graciously teaching me about rpath and dynamic loading,
290
292 Original author: Joel A Berger <joel.a.berger@gmail.com>
293 Current maintainer: Graham Ollis <plicease@cpan.org>
295 Contributors:
297 David Mertens (run4flat)
299 Mark Nunberg (mordy, mnunberg)
301 Christian Walde (Mithaldu)
303 Brian Wightman (MidLifeXis)
305 Graham Ollis (plicease)
307 Zaki Mughal (zmughal)
309 mohawk2
311 Vikas N Kumar (vikasnkumar)
313 Flavio Poletti (polettix)
315 Salvador Fandiño (salva)
317 Gianni Ceccarelli (dakkar)
319 Pavel Shaydo (zwon, trinitum)
321 Kang-min Liu (劉康民, gugod)
323 Nicholas Shipp (nshp)
325 Petr Písař (ppisar)
327 Alberto Simões (ambs)
329
331 This software is copyright (c) 2012-2022 by Joel A Berger.
332 This is free software; you can redistribute it and/or modify it under
334 the same terms as the Perl 5 programming language system itself.
335perl v5.36.0 2023-01-19 Alien::Base::ModuleBuild(3)