1Module::Build::Cookbook(P3eprml)Programmers Reference GMuoidduele::Build::Cookbook(3pm)
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. The following recipes should help developers and/or
11 installers put together the pieces from the other parts of the
12 documentation.
13
15 Installing modules that use Module::Build
16 In most cases, you can just issue the following commands:
17 perl Build.PL
19 ./Build
20 ./Build test
21 ./Build install
22 There's nothing complicated here - first you're running a script called
24 Build.PL, then you're running a (newly-generated) script called Build
25 and passing it various arguments.
26 The exact commands may vary a bit depending on how you invoke perl
28 scripts on your system. For instance, if you have multiple versions of
29 perl installed, you can install to one particular perl's library
30 directories like so:
31 /usr/bin/perl5.8.1 Build.PL
33 ./Build
34 ./Build test
35 ./Build install
36 If you're on Windows where the current directory is always searched
38 first for scripts, you'll probably do something like this:
39 perl Build.PL
41 Build
42 Build test
43 Build install
44 On the old Mac OS (version 9 or lower) using MacPerl, you can double-
46 click on the Build.PL script to create the Build script, then double-
47 click on the Build script to run its "build", "test", and "install"
48 actions.
49 The Build script knows what perl was used to run Build.PL, so you don't
51 need to re-invoke the Build script with the complete perl path each
52 time. If you invoke it with the wrong perl path, you'll get a warning
53 or a fatal error.
54 Modifying Config.pm values
56 "Module::Build" relies heavily on various values from perl's
57 "Config.pm" to do its work. For example, default installation paths
58 are given by "installsitelib" and "installvendorman3dir" and friends, C
59 linker & compiler settings are given by "ld", "lddlflags", "cc",
60 "ccflags", and so on. If you're pretty sure you know what you're
61 doing, you can tell "Module::Build" to pretend there are different
62 values in Config.pm than what's really there, by passing arguments for
63 the "--config" parameter on the command line:
64 perl Build.PL --config cc=gcc --config ld=gcc
66 Inside the "Build.PL" script the same thing can be accomplished by
68 passing values for the "config" parameter to "new()":
69 my $build = Module::Build->new
71 (
72 ...
73 config => { cc => 'gcc', ld => 'gcc' },
74 ...
75 );
76 In custom build code, the same thing can be accomplished by calling the
78 "config" in Module::Build method:
79 $build->config( cc => 'gcc' ); # Set
81 $build->config( ld => 'gcc' ); # Set
82 ...
83 my $linker = $build->config('ld'); # Get
84 Installing modules using the programmatic interface
86 If you need to build, test, and/or install modules from within some
87 other perl code (as opposed to having the user type installation
88 commands at the shell), you can use the programmatic interface. Create
89 a Module::Build object (or an object of a custom Module::Build
90 subclass) and then invoke its "dispatch()" method to run various
91 actions.
92 my $build = Module::Build->new
94 (
95 module_name => 'Foo::Bar',
96 license => 'perl',
97 requires => { 'Some::Module' => '1.23' },
98 );
99 $build->dispatch('build');
100 $build->dispatch('test', verbose => 1);
101 $build->dispatch('install');
102 The first argument to "dispatch()" is the name of the action, and any
104 following arguments are named parameters.
105 This is the interface we use to test Module::Build itself in the
107 regression tests.
108 Installing to a temporary directory
110 To create packages for package managers like RedHat's "rpm" or Debian's
111 "deb", you may need to install to a temporary directory first and then
112 create the package from that temporary installation. To do this,
113 specify the "destdir" parameter to the "install" action:
114 ./Build install --destdir /tmp/my-package-1.003
116 This essentially just prepends all the installation paths with the
118 /tmp/my-package-1.003 directory.
119 Installing to a non-standard directory
121 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" or "prefix" parameters:
124 ./Build install --install_base /foo/bar
126 See "INSTALL PATHS" in Module::Build for a much more complete
128 discussion 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
132 "INSTALL_BASE" in "ExtUtils::MakeMaker" 6.31 its easy to get them both
133 to install to the same locations.
134 First, ensure you have at least version 0.28 of Module::Build installed
136 and 6.31 of "ExtUtils::MakeMaker". Prior versions have differing (and
137 in some cases quite strange) installation behaviors.
138 The following installation flags are equivalent between
140 "ExtUtils::MakeMaker" and "Module::Build".
141 MakeMaker Module::Build
143 PREFIX=... --prefix ...
144 INSTALL_BASE=... --install_base ...
145 DESTDIR=... --destdir ...
146 LIB=... --install_path lib=...
147 INSTALLDIRS=... --installdirs ...
148 INSTALLDIRS=perl --installdirs core
149 UNINST=... --uninst ...
150 INC=... --extra_compiler_flags ...
151 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
152 For example, if you are currently installing "MakeMaker" modules with
154 this command:
155 perl Makefile.PL PREFIX=~
157 make test
158 make install UNINST=1
159 You can install into the same location with Module::Build using this:
161 perl Build.PL --prefix ~
163 ./Build test
164 ./Build install --uninst 1
165 "prefix" vs "install_base"
167 The behavior of "prefix" is complicated and depends on how your Perl is
169 configured. The resulting installation locations will vary from
170 machine to machine and even different installations of Perl on the same
171 machine. Because of this, it's difficult to document where "prefix"
172 will place your modules.
173 In contrast, "install_base" has predictable, easy to explain
175 installation locations. Now that "Module::Build" and "MakeMaker" both
176 have "install_base" there is little reason to use "prefix" other than
177 to preserve your existing installation locations. If you are starting
178 a fresh Perl installation we encourage you to use "install_base". If
179 you have an existing installation installed via "prefix", consider
180 moving it to an installation structure matching "install_base" and
181 using that instead.
182 Running a single test file
184 "Module::Build" supports running a single test, which enables you to
185 track down errors more quickly. Use the following format:
186 ./Build test --test_files t/mytest.t
188 In addition, you may want to run the test in verbose mode to get more
190 informative output:
191 ./Build test --test_files t/mytest.t --verbose 1
193 I run this so frequently that I define the following shell alias:
195 alias t './Build test --verbose 1 --test_files'
197 So then I can just execute "t t/mytest.t" to run a single test.
199
201 Making a CPAN.pm-compatible distribution
202 New versions of CPAN.pm understand how to use a Build.PL script, but
203 old versions don't. If authors want to help users who have old
204 versions, some form of Makefile.PL should be supplied. The easiest way
205 to accomplish this is to use the "create_makefile_pl" parameter to
206 "Module::Build->new()" in the "Build.PL" script, which can create
207 various flavors of Makefile.PL during the "dist" action.
208 As a best practice, we recommend using the "traditional" style of
210 Makefile.PL unless your distribution has needs that can't be
211 accomplished that way.
212 The "Module::Build::Compat" module, which is part of "Module::Build"'s
214 distribution, is responsible for creating these Makefile.PLs. Please
215 see Module::Build::Compat for the details.
216 Changing the order of the build process
218 The "build_elements" property specifies the steps "Module::Build" will
219 take when building a distribution. To change the build order, change
220 the order of the entries in that property:
221 # Process pod files first
223 my @e = @{$build->build_elements};
224 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
225 unshift @e, splice @e, $i, 1;
226 Currently, "build_elements" has the following default value:
228 [qw( PL support pm xs pod script )]
230 Do take care when altering this property, since there may be non-
232 obvious (and non-documented!) ordering dependencies in the
233 "Module::Build" code.
234 Adding new file types to the build process
236 Sometimes you might have extra types of files that you want to install
237 alongside the standard types like .pm and .pod files. For instance,
238 you might have a Bar.dat file containing some data related to the
239 "Foo::Bar" module and you'd like for it to end up as Foo/Bar.dat
240 somewhere in perl's @INC path so "Foo::Bar" can access it easily at
241 runtime. The following code from a sample "Build.PL" file demonstrates
242 how to accomplish this:
243 use Module::Build;
245 my $build = Module::Build->new
246 (
247 module_name => 'Foo::Bar',
248 ...other stuff here...
249 );
250 $build->add_build_element('dat');
251 $build->create_build_script;
252 This will find all .dat files in the lib/ directory, copy them to the
254 blib/lib/ directory during the "build" action, and install them during
255 the "install" action.
256 If your extra files aren't located in the "lib/" directory in your
258 distribution, you can explicitly say where they are, just as you'd do
259 with .pm or .pod files:
260 use Module::Build;
262 my $build = new Module::Build
263 (
264 module_name => 'Foo::Bar',
265 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
266 ...other stuff here...
267 );
268 $build->add_build_element('dat');
269 $build->create_build_script;
270 If your extra files actually need to be created on the user's machine,
272 or if they need some other kind of special processing, you'll probably
273 want to subclass "Module::Build" and create a special method to process
274 them, named "process_${kind}_files()":
275 use Module::Build;
277 my $class = Module::Build->subclass(code => <<'EOF');
278 sub process_dat_files {
279 my $self = shift;
280 ... locate and process *.dat files,
281 ... and create something in blib/lib/
282 }
283 EOF
284 my $build = $class->new
285 (
286 module_name => 'Foo::Bar',
287 ...other stuff here...
288 );
289 $build->add_build_element('dat');
290 $build->create_build_script;
291 If your extra files don't go in lib/ but in some other place, see
293 "Adding new elements to the install process" for how to actually get
294 them installed.
295 Please note that these examples use some capabilities of Module::Build
297 that first appeared in version 0.26. Before that it could still be
298 done, but the simple cases took a bit more work.
299 Adding new elements to the install process
301 By default, Module::Build creates seven subdirectories of the blib
302 directory during the build process: lib, arch, bin, script, bindoc,
303 libdoc, and html (some of these may be missing or empty if there's
304 nothing to go in them). Anything copied to these directories during
305 the build will eventually be installed during the "install" action (see
306 "INSTALL PATHS" in Module::Build.
307 If you need to create a new custom type of installable element, e.g.
309 "conf", then you need to tell Module::Build where things in blib/conf/
310 should be installed. To do this, use the "install_path" parameter to
311 the "new()" method:
312 my $build = Module::Build->new
314 (
315 ...other stuff here...
316 install_path => { conf => $installation_path }
317 );
318 Or you can call the "install_path()" method later:
320 $build->install_path(conf => $installation_path);
322 The user may also specify the path on the command line:
324 perl Build.PL --install_path conf=/foo/path/etc
326 The important part, though, is that somehow the install path needs to
328 be set, or else nothing in the blib/conf/ directory will get installed,
329 and a runtime error during the "install" action will result.
330 See also "Adding new file types to the build process" for how to create
332 the stuff in blib/conf/ in the first place.
333
335 Several distributions on CPAN are making good use of various features
336 of Module::Build. They can serve as real-world examples for others.
337 SVN-Notify-Mirror
339 http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/
340 <http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
341 John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
343 1. Using "auto_features", I check to see whether two optional modules
345 are available - SVN::Notify::Config and Net::SSH;
346 2. If the S::N::Config module is loaded, I automatically generate test
347 files for it during Build (using the "PL_files" property).
348 3. If the "ssh_feature" is available, I ask if the user wishes to
349 perform the ssh tests (since it requires a little preliminary setup);
350 4. Only if the user has "ssh_feature" and answers yes to the testing,
351 do I generate a test file.
352 I'm sure I could not have handled this complexity with EU::MM, but
353 it was very easy to do with M::B.
354 Modifying an action
356 Sometimes you might need an to have an action, say "./Build install",
357 do something unusual. For instance, you might need to change the
358 ownership of a file or do something else peculiar to your application.
359 You can subclass "Module::Build" on the fly using the "subclass()"
361 method and override the methods that perform the actions. You may need
362 to read through "Module::Build::Authoring" and "Module::Build::API" to
363 find the methods you want to override. All "action" methods are
364 implemented by a method called "ACTION_" followed by the action's name,
365 so here's an example of how it would work for the "install" action:
366 # Build.PL
368 use Module::Build;
369 my $class = Module::Build->subclass(
370 class => "Module::Build::Custom",
371 code => <<'SUBCLASS' );
372 sub ACTION_install {
374 my $self = shift;
375 # YOUR CODE HERE
376 $self->SUPER::ACTION_install;
377 }
378 SUBCLASS
379 $class->new(
381 module_name => 'Your::Module',
382 # rest of the usual Module::Build parameters
383 )->create_build_script;
384 Adding an action
386 You can add a new "./Build" action simply by writing the method for it
387 in your subclass. Use "depends_on" to declare that another action must
388 have been run before your action.
389 For example, let's say you wanted to be able to write "./Build commit"
391 to test your code and commit it to Subversion.
392 # Build.PL
394 use Module::Build;
395 my $class = Module::Build->subclass(
396 class => "Module::Build::Custom",
397 code => <<'SUBCLASS' );
398 sub ACTION_commit {
400 my $self = shift;
401 $self->depends_on("test");
403 $self->do_system(qw(svn commit));
404 }
405 SUBCLASS
406 Bundling Module::Build
408 Note: This section probably needs an update as the technology improves
409 (see contrib/bundle.pl in the distribution).
410 Suppose you want to use some new-ish features of Module::Build, e.g.
412 newer than the version of Module::Build your users are likely to
413 already have installed on their systems. The first thing you should do
414 is set "configure_requires" to your minimum version of Module::Build.
415 See Module::Build::Authoring.
416 But not every build system honors "configure_requires" yet. Here's how
418 you can ship a copy of Module::Build, but still use a newer installed
419 version to take advantage of any bug fixes and upgrades.
420 First, install Module::Build into Your-Project/inc/Module-Build. CPAN
422 will not index anything in the inc directory so this copy will not show
423 up in CPAN searches.
424 cd Module-Build
426 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
427 ./Build test
428 ./Build install
429 You should now have all the Module::Build .pm files in
431 Your-Project/inc/Module-Build/lib/perl5.
432 Next, add this to the top of your Build.PL.
434 my $Bundled_MB = 0.30; # or whatever version it was.
436 # Find out what version of Module::Build is installed or fail quietly.
438 # This should be cross-platform.
439 my $Installed_MB =
440 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1";
441 # some operating systems put a newline at the end of every print.
443 chomp $Installed_MB;
444 $Installed_MB = 0 if $?;
446 # Use our bundled copy of Module::Build if it's newer than the installed.
448 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
449 require Module::Build;
451 And write the rest of your Build.PL normally. Module::Build will
453 remember your change to @INC and use it when you run ./Build.
454 In the future, we hope to provide a more automated solution for this
456 scenario; see "inc/latest.pm" in the Module::Build distribution for one
457 indication of the direction we're moving.
458
460 Ken Williams <kwilliams@cpan.org>
461
463 Copyright (c) 2001-2008 Ken Williams. All rights reserved.
464 This library is free software; you can redistribute it and/or modify it
466 under the same terms as Perl itself.
467
469 perl(1), Module::Build(3), Module::Build::Authoring(3),
470 Module::Build::API(3)
471perl v5.12.4 2011-06-07 Module::Build::Cookbook(3pm)