1Module::Build::CookbookU(s3e)r Contributed Perl DocumentaMtoidounle::Build::Cookbook(3)
2
6 Module::Build::Cookbook - Examples of Module::Build Usage
7
9 "Module::Build" isn't conceptually very complicated, but examples are
10 always helpful. I got the idea for writing this cookbook when attend‐
11 ing Brian Ingerson's "Extreme Programming Tools for Module Authors"
12 presentation at YAPC 2003, when he said, straightforwardly, "Write A
13 Cookbook."
14 The definitional of how stuff works is in the main "Module::Build" doc‐
16 umentation. It's best to get familiar with that too.
17
19 The basic installation recipe for modules that use Module::Build
20 In most cases, you can just issue the following commands:
22 perl Build.PL
24 ./Build
25 ./Build test
26 ./Build install
27 There's nothing complicated here - first you're running a script called
29 Build.PL, then you're running a (newly-generated) script called Build
30 and passing it various arguments.
31 The exact commands may vary a bit depending on how you invoke perl
33 scripts on your system. For instance, if you have multiple versions of
34 perl installed, you can install to one particular perl's library direc‐
35 tories like so:
36 /usr/bin/perl5.8.1 Build.PL
38 ./Build
39 ./Build test
40 ./Build install
41 If you're on Windows where the current directory is always searched
43 first for scripts, you'll probably do something like this:
44 perl Build.PL
46 Build
47 Build test
48 Build install
49 On the old Mac OS (version 9 or lower) using MacPerl, you can double-
51 click on the Build.PL script to create the Build script, then double-
52 click on the Build script to run its "build", "test", and "install"
53 actions.
54 The Build script knows what perl was used to run "Build.PL", so you
56 don't need to re-invoke the Build script with the complete perl path
57 each time. If you invoke it with the wrong perl path, you'll get a
58 warning or a fatal error.
59 Making a CPAN.pm-compatible distribution
61 New versions of CPAN.pm understand how to use a Build.PL script, but
63 old versions don't. If you want to help users who have old versions,
64 do the following:
65 Create a file in your distribution named Makefile.PL, with the follow‐
67 ing contents:
68 use Module::Build::Compat;
70 Module::Build::Compat->run_build_pl(args => \@ARGV);
71 Module::Build::Compat->write_makefile();
72 Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make
74 test`, and `make install`, provided the end-user already has "Mod‐
75 ule::Build" installed.
76 If the end-user might not have "Module::Build" installed, it's probably
78 best to supply a "traditional" Makefile.PL. The "Module::Build::Com‐
79 pat" module has some very helpful tools for keeping a Makefile.PL in
80 sync with a Build.PL. See its documentation, and also the "cre‐
81 ate_makefile_pl" parameter to the "Module::Build->new()" method.
82 Installing modules using the programmatic interface
84 If you need to build, test, and/or install modules from within some
86 other perl code (as opposed to having the user type installation com‐
87 mands at the shell), you can use the programmatic interface. Create a
88 Module::Build object (or an object of a custom Module::Build subclass)
89 and then invoke its "dispatch()" method to run various actions.
90 my $build = Module::Build->new
92 (
93 module_name => 'Foo::Bar',
94 license => 'perl',
95 requires => { 'Some::Module' => '1.23' },
96 );
97 $build->dispatch('build');
98 $build->dispatch('test', verbose => 1);
99 $build->dispatch('install');
100 The first argument to "dispatch()" is the name of the action, and any
102 following arguments are named parameters.
103 This is the interface we use to test Module::Build itself in the
105 regression tests.
106 Installing to a temporary directory
108 To create packages for package managers like RedHat's "rpm" or Debian's
110 "deb", you may need to install to a temporary directory first and then
111 create the package from that temporary installation. To do this, spec‐
112 ify the "destdir" parameter to the "install" action:
113 ./Build install --destdir /tmp/my-package-1.003
115 This essentially just prepends all the installation paths with the
117 /tmp/my-package-1.003 directory.
118 Installing to a non-standard directory
120 To install to a non-standard directory (for example, if you don't have
122 permission to install in the system-wide directories), you can use the
123 "install_base":
124 ./Build install --install_base /foo/bar
126 See "INSTALL PATHS" in Module::Build for a much more complete discus‐
128 sion of how installation paths are determined.
129 Installing in the same location as ExtUtils::MakeMaker
131 With the introduction of "--prefix" in Module::Build 0.28 and
133 "INSTALL_BASE" in ExtUtils::MakeMaker 6.31 its easy to get them both to
134 install to the same locations.
135 First, ensure you have at least version 0.28 of Module::Build installed
137 and 6.31 of ExtUtils::MakeMaker. Prior versions have differing instal‐
138 lation behaviors.
139 The following installation flags are equivalent between ExtUtils::Make‐
141 Maker and Module::Build.
142 MakeMaker Module::Build
144 PREFIX=... --prefix ...
145 INSTALL_BASE=... --install_base ...
146 DESTDIR=... --destdir ...
147 LIB=... --install_path lib=...
148 INSTALLDIRS=... --installdirs ...
149 INSTALLDIRS=perl --installdirs core
150 UNINST=... --uninst ...
151 INC=... --extra_compiler_flags ...
152 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
153 For example, if you are currently installing MakeMaker modules with
155 this command:
156 perl Makefile.PL PREFIX=~
158 make test
159 make install UNINST=1
160 You can install into the same location with Module::Build using this:
162 perl Build.PL --prefix ~
164 ./Build test
165 ./Build install --uninst 1
166 "prefix" vs "install_base"
168 The behavior of "prefix" is complicated and depends closely on how your
170 Perl is configured. The resulting installation locations will vary
171 from machine to machine and even different installations of Perl on the
172 same machine. Because of this, its difficult to document where "pre‐
173 fix" will place your modules.
174 In contrast, "install_base" has predictable, easy to explain installa‐
176 tion locations. Now that Module::Build and MakeMaker both have
177 "install_base" there is little reason to use "prefix" other than to
178 preserve your existing installation locations. If you are starting a
179 fresh Perl installation we encourage you to use "install_base". If you
180 have an existing installation installed via "prefix", consider moving
181 it to an installation structure matching "install_base" and using that
182 instead.
183 Running a single test file
185 "Module::Build" supports running a single test, which enables you to
187 track down errors more quickly. Use the following format:
188 ./Build test --test_files t/mytest.t
190 In addition, you may want to run the test in verbose mode to get more
192 informative output:
193 ./Build test --test_files t/mytest.t --verbose 1
195 I run this so frequently that I actually define the following shell
197 alias:
198 alias t './Build test --verbose 1 --test_files'
200 So then I can just execute "t t/mytest.t" to run a single test.
202
204 Changing the order of the build process
205 The "build_elements" property specifies the steps "Module::Build" will
207 take when building a distribution. To change the build order, change
208 the order of the entries in that property:
209 # Process pod files first
211 my @e = @{$build->build_elements};
212 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
213 unshift @e, splice @e, $i, 1;
214 Currently, "build_elements" has the following default value:
216 [qw( PL support pm xs pod script )]
218 Do take care when altering this property, since there may be non-obvi‐
220 ous (and non-documented!) ordering dependencies in the "Module::Build"
221 code.
222 Adding new file types to the build process
224 Sometimes you might have extra types of files that you want to install
226 alongside the standard types like .pm and .pod files. For instance,
227 you might have a Bar.dat file containing some data related to the
228 "Foo::Bar" module. Assuming the data doesn't need to be created on the
229 fly, the best place for it to end up is probably as Foo/Bar.dat some‐
230 where in perl's @INC path so "Foo::Bar" can access it easily at run‐
231 time. The following code from a sample "Build.PL" file demonstrates
232 how to accomplish this:
233 use Module::Build;
235 my $build = Module::Build->new
236 (
237 module_name => 'Foo::Bar',
238 ...other stuff here...
239 );
240 $build->add_build_element('dat');
241 $build->create_build_script;
242 This will find all .dat files in the lib/ directory, copy them to the
244 blib/lib/ directory during the "build" action, and install them during
245 the "install" action.
246 If your extra files aren't in the "lib/" directory, you can explicitly
248 say where they are, just as you'd do with .pm or .pod files:
249 use Module::Build;
251 my $build = new Module::Build
252 (
253 module_name => 'Foo::Bar',
254 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
255 ...other stuff here...
256 );
257 $build->add_build_element('dat');
258 $build->create_build_script;
259 If your extra files actually need to be created on the user's machine,
261 or if they need some other kind of special processing, you'll probably
262 want to create a special method to do so, named
263 "process_${kind}_files()":
264 use Module::Build;
266 my $class = Module::Build->subclass(code => <<'EOF');
267 sub process_dat_files {
268 my $self = shift;
269 ... locate and process *.dat files,
270 ... and create something in blib/lib/
271 }
272 EOF
273 my $build = $class->new
274 (
275 module_name => 'Foo::Bar',
276 ...other stuff here...
277 );
278 $build->add_build_element('dat');
279 $build->create_build_script;
280 If your extra files don't go in lib/ but in some other place, see
282 "Adding new elements to the install process" for how to actually get
283 them installed.
284 Please note that these examples use some capabilities of Module::Build
286 that first appeared in version 0.26. Before that it could certainly
287 still be done, but the simple cases took a bit more work.
288 Adding new elements to the install process
290 By default, Module::Build creates seven subdirectories of the blib/
292 directory during the build process: lib/, arch/, bin/, script/,
293 bindoc/, libdoc/, and html/ (some of these may be missing or empty if
294 there's nothing to go in them). Anything copied to these directories
295 during the build will eventually be installed during the "install"
296 action (see "INSTALL PATHS" in Module::Build.
297 If you need to create a new type of installable element, e.g. "conf",
299 then you need to tell Module::Build where things in blib/conf/ should
300 be installed. To do this, use the "install_path" parameter to the
301 "new()" method:
302 my $build = Module::Build->new
304 (
305 ...other stuff here...
306 install_path => { conf => $installation_path }
307 );
308 Or you can call the "install_path()" method later:
310 $build->install_path->{conf} ⎪⎪ $installation_path;
312 (Sneakily, or perhaps uglily, "install_path()" returns a reference to a
314 hash of install paths, and you can modify that hash to your heart's
315 content.)
316 The user may also specify the path on the command line:
318 perl Build.PL --install_path conf=/foo/path/etc
320 The important part, though, is that somehow the install path needs to
322 be set, or else nothing in the blib/conf/ directory will get installed.
323 See also "Adding new file types to the build process" for how to create
325 the stuff in blib/conf/ in the first place.
326
328 Several distributions on CPAN are making good use of various features
329 of Module::Build. They can serve as real-world examples for others.
330 SVN-Notify-Mirror
332 <http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
334 John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
336 1. Using "auto_features", I check to see whether two optional modules
338 are available - SVN::Notify::Config and Net::SSH;
339 2. If the S::N::Config module is loaded, I automatically generate test‐
340 files for it during Build (using the "PL_files" property).
341 3. If the "ssh_feature" is available, I ask if the user wishes to per‐
342 form the ssh tests (since it requires a little preliminary setup);
343 4. Only if the user has "ssh_feature" and answers yes to the testing,
344 do I generate a test file.
345 I'm sure I could not have handled this complexity with EU::MM, but
346 it was very easy to do with M::B.
347 Modifying an action
349 Sometimes you might need an to have an action, say "./Build install",
351 do something unusual. For instance, you might need to change the own‐
352 ership of a file or do something else peculiar to your application.
353 You can subclass "Module::Build" on the fly using the "subclass()"
355 method and override the methods that perform the actions. You may need
356 to read through "Module::Build::Authoring" to find the methods you want
357 to override, but the general pattern is "ACTION_" followed by the name
358 of the action you want to modify. Here's an example of how it would
359 work for "install":
360 # Build.PL
362 use Module::Build;
363 my $class = Module::Build->subclass(
364 class => "Module::Build::Custom",
365 code => <<'SUBCLASS' );
366 sub ACTION_install {
368 my $self = shift;
369 # YOUR CODE HERE
370 $self->SUPER::ACTION_install;
371 }
372 SUBCLASS
373 $class->new(
375 module_name => 'Your::Module',
376 # rest of the usual Module::Build parameters
377 )->create_build_script;
378 See the Module::Build::Authoring pod in 0.27 or above for more complete
380 documentation on this.
381
383 Ken Williams <kwilliams@cpan.org>
384
386 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
387 This library is free software; you can redistribute it and/or modify it
389 under the same terms as Perl itself.
390
392 perl(1), Module::Build(3), Module::Build::Authoring(3), Mod‐
393 ule::Build::API(3)
394perl v5.8.8 2007-04-02 Module::Build::Cookbook(3)