README
1NAME
2
3 Alien::Base::ModuleBuild - A Module::Build subclass for building
4 Alien:: modules and their libraries
5
6VERSION
7
8 version 1.15
9
10SYNOPSIS
11
12 In your Build.PL:
13
14 use Alien::Base::ModuleBuild;
15
16 my $builder = Alien::Base::ModuleBuild->new(
17 module_name => 'Alien::MyLibrary',
18
19 configure_requires => {
20 'Alien::Base::ModuleBuild' => '0.005',
21 'Module::Build' => '0.28'
22 },
23 requires => {
24 'Alien::Base' => '0.005',
25 },
26
27 alien_name => 'mylibrary', # the pkg-config name if you want
28 # to use pkg-config to discover
29 # system version of the mylibrary
30
31 alien_repository => {
32 protocol => 'http',
33 host => 'myhost.org',
34 location => '/path/to/tarballs',
35 pattern => qr{^mylibrary-([0-9\.]+)\.tar\.gz$},
36 },
37
38 # this is the default:
39 alien_build_commands => [
40 "%c --prefix=%s", # %c is a platform independent version of ./configure
41 "make",
42 ],
43
44 # this is the default for install:
45 alien_install_commands => [
46 "make install",
47 ],
48
49 alien_isolate_dynamic => 1,
50 );
51
52DESCRIPTION
53
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
63 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
67 use pkg-config to find and use the system version of the library
68
69 download, build and install the library if the system does not provide
70 it
71
72METHODS
73
74 alien_check_installed_version
75
76 [version 0.001]
77
78 my $version = $abmb->alien_check_installed_version;
79
80 This function determines if the library is already installed as part of
81 the operating system, and returns the version as a string. If it can't
82 be detected then it should return empty list.
83
84 The default implementation relies on pkg-config, but you will probably
85 want to override this with your own implementation if the package you
86 are building does not use pkg-config.
87
88 alien_check_built_version
89
90 [version 0.006]
91
92 my $version = $amb->alien_check_built_version;
93
94 This function determines the version of the library after it has been
95 built from source. This function only gets called if the operating
96 system version can not be found and the package is successfully built.
97 The version is returned on success. If the version can't be detected
98 then it should return empty list. Note that failing to detect a version
99 is considered a failure and the corresponding ./Build action will fail!
100
101 Any string is valid as a version as far as Alien::Base is concerned.
102 The most useful value would be a number or dotted decimal that most
103 software developers recognize and that software tools can
104 differentiate. In some cases packages will not have a clear version
105 number, in which case the string unknown would be a reasonable choice.
106
107 The default implementation relies on pkg-config, and other heuristics,
108 but you will probably want to override this with your own
109 implementation if the package you are building does not use pkg-config.
110
111 When this method is called, the current working directory will be the
112 build root.
113
114 If you see an error message like this:
115
116 Library looks like it installed, but no version was determined
117
118 After the package is built from source code then you probably need to
119 provide an implementation for this method.
120
121 alien_extract_archive
122
123 [version 0.024]
124
125 my $dir = $amb->alien_extract_archive($filename);
126
127 This function unpacks the given archive and returns the directory
128 containing the unpacked files.
129
130 The default implementation relies on Archive::Extract that is able to
131 handle most common formats. In order to handle other formats or
132 archives requiring some special treatment you may want to override this
133 method.
134
135 alien_do_system
136
137 [version 0.024]
138
139 my %result = $amb->alien_do_system($cmd)
140
141 Similar to Module::Build::do_system, also sets the path and several
142 environment variables in accordance to the object configuration (i.e.
143 alien_bin_requires) and performs the interpolation of the patterns
144 described in "COMMAND INTERPOLATION" in Alien::Base::ModuleBuild::API.
145
146 Returns a set of key value pairs including stdout, stderr, success and
147 command.
148
149 alien_do_commands
150
151 $amb->alien_do_commands($phase);
152
153 Executes the commands for the given phase.
154
155 alien_interpolate
156
157 my $string = $amb->alien_interpolate($string);
158
159 Takes the input string and interpolates the results.
160
161GUIDE TO DOCUMENTATION
162
163 The documentation for Module::Build is broken up into sections:
164
165 General Usage (Module::Build)
166
167 This is the landing document for Alien::Base::ModuleBuild's parent
168 class. It describes basic usage and background information. Its main
169 purpose is to assist the user who wants to learn how to invoke and
170 control Module::Build scripts at the command line.
171
172 It also lists the extra documentation for its use. Users and authors
173 of Alien:: modules should familiarize themselves with these
174 documents. Module::Build::API is of particular importance to authors.
175
176 Alien-Specific Usage (Alien::Base::ModuleBuild)
177
178 This is the document you are currently reading.
179
180 Authoring Reference (Alien::Base::Authoring)
181
182 This document describes the structure and organization of Alien::Base
183 based projects, beyond that contained in Module::Build::Authoring,
184 and the relevant concepts needed by authors who are writing Build.PL
185 scripts for a distribution or controlling Alien::Base::ModuleBuild
186 processes programmatically.
187
188 Note that as it contains information both for the build and use
189 phases of Alien::Base projects, it is located in the upper namespace.
190
191 API Reference (Alien::Base::ModuleBuild::API)
192
193 This is a reference to the Alien::Base::ModuleBuild API beyond that
194 contained in Module::Build::API.
195
196ENVIRONMENT
197
198 ALIEN_VERBOSE
199
200 Enables verbose output from M::B::do_system.
201
202 ALIEN_FORCE
203
204 Skips checking for an installed version and forces reinstalling the
205 Alien target.
206
207 ALIEN_INSTALL_TYPE
208
209 Set to 'share' or 'system' to override the install type. Set to
210 'default' or unset to restore the default.
211
212 ALIEN_ARCH
213
214 Set to a true value to install to an arch-specific directory.
215
216 ALIEN_${MODULENAME}_REPO_${PROTOCOL}_${KEY}
217
218 Overrides $KEY in the given module's repository configuration
219 matching $PROTOCOL. For example,
220 ALIEN_OPENSSL_REPO_FTP_HOST=ftp.example.com.
221
222SEE ALSO
223
224 Alien::Build
225
226 alienfile
227
228 Alien::Build::Manual::AlienAuthor
229
230 Alien
231
232THANKS
233
234 Thanks also to
235
236 Christian Walde (Mithaldu)
237
238 For productive conversations about component interoperability.
239
240 kmx
241
242 For writing Alien::Tidyp from which I drew many of my initial ideas.
243
244 David Mertens (run4flat)
245
246 For productive conversations about implementation.
247
248 Mark Nunberg (mordy, mnunberg)
249
250 For graciously teaching me about rpath and dynamic loading,
251
252AUTHOR
253
254 Original author: Joel A Berger <joel.a.berger@gmail.com>
255
256 Current maintainer: Graham Ollis <plicease@cpan.org>
257
258 Contributors:
259
260 David Mertens (run4flat)
261
262 Mark Nunberg (mordy, mnunberg)
263
264 Christian Walde (Mithaldu)
265
266 Brian Wightman (MidLifeXis)
267
268 Graham Ollis (plicease)
269
270 Zaki Mughal (zmughal)
271
272 mohawk2
273
274 Vikas N Kumar (vikasnkumar)
275
276 Flavio Poletti (polettix)
277
278 Salvador Fandiño (salva)
279
280 Gianni Ceccarelli (dakkar)
281
282 Pavel Shaydo (zwon, trinitum)
283
284 Kang-min Liu (劉康民, gugod)
285
286 Nicholas Shipp (nshp)
287
288 Petr Pisar (ppisar)
289
290 Alberto Simões (ambs)
291
292COPYRIGHT AND LICENSE
293
294 This software is copyright (c) 2012-2020 by Joel A Berger.
295
296 This is free software; you can redistribute it and/or modify it under
297 the same terms as the Perl 5 programming language system itself.
298
299