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. 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 actions.
91 my $build = Module::Build->new
93 (
94 module_name => 'Foo::Bar',
95 license => 'perl',
96 requires => { 'Some::Module' => '1.23' },
97 );
98 $build->dispatch('build');
99 $build->dispatch('test', verbose => 1);
100 $build->dispatch('install');
101 The first argument to dispatch() is the name of the action, and any
103 following arguments are named parameters.
104 This is the interface we use to test Module::Build itself in the
106 regression tests.
107 Installing to a temporary directory
109 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,
112 specify 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
121 permission to install in the system-wide directories), you can use the
122 "install_base" or "prefix" parameters:
123 ./Build install --install_base /foo/bar
125 See "INSTALL PATHS" in Module::Build for a much more complete
127 discussion of how installation paths are determined.
128 Installing in the same location as ExtUtils::MakeMaker
130 With the introduction of "--prefix" in Module::Build 0.28 and
131 "INSTALL_BASE" in "ExtUtils::MakeMaker" 6.31 its easy to get them both
132 to install to the same locations.
133 First, ensure you have at least version 0.28 of Module::Build installed
135 and 6.31 of "ExtUtils::MakeMaker". Prior versions have differing (and
136 in some cases quite strange) installation behaviors.
137 The following installation flags are equivalent between
139 "ExtUtils::MakeMaker" and "Module::Build".
140 MakeMaker Module::Build
142 PREFIX=... --prefix ...
143 INSTALL_BASE=... --install_base ...
144 DESTDIR=... --destdir ...
145 LIB=... --install_path lib=...
146 INSTALLDIRS=... --installdirs ...
147 INSTALLDIRS=perl --installdirs core
148 UNINST=... --uninst ...
149 INC=... --extra_compiler_flags ...
150 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
151 For example, if you are currently installing "MakeMaker" modules with
153 this command:
154 perl Makefile.PL PREFIX=~
156 make test
157 make install UNINST=1
158 You can install into the same location with Module::Build using this:
160 perl Build.PL --prefix ~
162 ./Build test
163 ./Build install --uninst 1
164 "prefix" vs "install_base"
166 The behavior of "prefix" is complicated and depends on how your Perl is
168 configured. The resulting installation locations will vary from
169 machine to machine and even different installations of Perl on the same
170 machine. Because of this, it's difficult to document where "prefix"
171 will place your modules.
172 In contrast, "install_base" has predictable, easy to explain
174 installation locations. Now that "Module::Build" and "MakeMaker" both
175 have "install_base" there is little reason to use "prefix" other than
176 to preserve your existing installation locations. If you are starting
177 a fresh Perl installation we encourage you to use "install_base". If
178 you have an existing installation installed via "prefix", consider
179 moving it to an installation structure matching "install_base" and
180 using that instead.
181 Running a single test file
183 "Module::Build" supports running a single test, which enables you to
184 track down errors more quickly. Use the following format:
185 ./Build test --test_files t/mytest.t
187 In addition, you may want to run the test in verbose mode to get more
189 informative output:
190 ./Build test --test_files t/mytest.t --verbose 1
192 I run this so frequently that I define the following shell alias:
194 alias t './Build test --verbose 1 --test_files'
196 So then I can just execute "t t/mytest.t" to run a single test.
198
200 Making a CPAN.pm-compatible distribution
201 New versions of CPAN.pm understand how to use a Build.PL script, but
202 old versions don't. If authors want to help users who have old
203 versions, some form of Makefile.PL should be supplied. The easiest way
204 to accomplish this is to use the "create_makefile_pl" parameter to
205 "Module::Build->new()" in the "Build.PL" script, which can create
206 various flavors of Makefile.PL during the "dist" action.
207 As a best practice, we recommend using the "traditional" style of
209 Makefile.PL unless your distribution has needs that can't be
210 accomplished that way.
211 The "Module::Build::Compat" module, which is part of "Module::Build"'s
213 distribution, is responsible for creating these Makefile.PLs. Please
214 see Module::Build::Compat for the details.
215 Changing the order of the build process
217 The "build_elements" property specifies the steps "Module::Build" will
218 take when building a distribution. To change the build order, change
219 the order of the entries in that property:
220 # Process pod files first
222 my @e = @{$build->build_elements};
223 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
224 unshift @e, splice @e, $i, 1;
225 Currently, "build_elements" has the following default value:
227 [qw( PL support pm xs pod script )]
229 Do take care when altering this property, since there may be non-
231 obvious (and non-documented!) ordering dependencies in the
232 "Module::Build" code.
233 Adding new file types to the build process
235 Sometimes you might have extra types of files that you want to install
236 alongside the standard types like .pm and .pod files. For instance,
237 you might have a Bar.dat file containing some data related to the
238 "Foo::Bar" module and you'd like for it to end up as Foo/Bar.dat
239 somewhere in perl's @INC path so "Foo::Bar" can access it easily at
240 runtime. The following code from a sample "Build.PL" file demonstrates
241 how to accomplish this:
242 use Module::Build;
244 my $build = Module::Build->new
245 (
246 module_name => 'Foo::Bar',
247 ...other stuff here...
248 );
249 $build->add_build_element('dat');
250 $build->create_build_script;
251 This will find all .dat files in the lib/ directory, copy them to the
253 blib/lib/ directory during the "build" action, and install them during
254 the "install" action.
255 If your extra files aren't located in the "lib/" directory in your
257 distribution, you can explicitly say where they are, just as you'd do
258 with .pm or .pod files:
259 use Module::Build;
261 my $build = new Module::Build
262 (
263 module_name => 'Foo::Bar',
264 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
265 ...other stuff here...
266 );
267 $build->add_build_element('dat');
268 $build->create_build_script;
269 If your extra files actually need to be created on the user's machine,
271 or if they need some other kind of special processing, you'll probably
272 want to subclass "Module::Build" and create a special method to process
273 them, named "process_${kind}_files()":
274 use Module::Build;
276 my $class = Module::Build->subclass(code => <<'EOF');
277 sub process_dat_files {
278 my $self = shift;
279 ... locate and process *.dat files,
280 ... and create something in blib/lib/
281 }
282 EOF
283 my $build = $class->new
284 (
285 module_name => 'Foo::Bar',
286 ...other stuff here...
287 );
288 $build->add_build_element('dat');
289 $build->create_build_script;
290 If your extra files don't go in lib/ but in some other place, see
292 "Adding new elements to the install process" for how to actually get
293 them installed.
294 Please note that these examples use some capabilities of Module::Build
296 that first appeared in version 0.26. Before that it could still be
297 done, but the simple cases took a bit more work.
298 Adding new elements to the install process
300 By default, Module::Build creates seven subdirectories of the blib
301 directory during the build process: lib, arch, bin, script, bindoc,
302 libdoc, and html (some of these may be missing or empty if there's
303 nothing to go in them). Anything copied to these directories during
304 the build will eventually be installed during the "install" action (see
305 "INSTALL PATHS" in Module::Build.
306 If you need to create a new custom type of installable element, e.g.
308 "conf", then you need to tell Module::Build where things in blib/conf/
309 should be installed. To do this, use the "install_path" parameter to
310 the new() method:
311 my $build = Module::Build->new
313 (
314 ...other stuff here...
315 install_path => { conf => $installation_path }
316 );
317 Or you can call the install_path() method later:
319 $build->install_path(conf => $installation_path);
321 The user may also specify the path on the command line:
323 perl Build.PL --install_path conf=/foo/path/etc
325 The important part, though, is that somehow the install path needs to
327 be set, or else nothing in the blib/conf/ directory will get installed,
328 and a runtime error during the "install" action will result.
329 See also "Adding new file types to the build process" for how to create
331 the stuff in blib/conf/ in the first place.
332
334 Several distributions on CPAN are making good use of various features
335 of Module::Build. They can serve as real-world examples for others.
336 SVN-Notify-Mirror
338 <http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
339 John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
341 1. Using "auto_features", I check to see whether two optional modules
343 are available - SVN::Notify::Config and Net::SSH;
344 2. If the S::N::Config module is loaded, I automatically generate test
345 files for it during Build (using the "PL_files" property).
346 3. If the "ssh_feature" is available, I ask if the user wishes to
347 perform the ssh tests (since it requires a little preliminary setup);
348 4. Only if the user has "ssh_feature" and answers yes to the testing,
349 do I generate a test file.
350 I'm sure I could not have handled this complexity with EU::MM, but
351 it was very easy to do with M::B.
352 Modifying an action
354 Sometimes you might need an to have an action, say "./Build install",
355 do something unusual. For instance, you might need to change the
356 ownership of a file or do something else peculiar to your application.
357 You can subclass "Module::Build" on the fly using the subclass() method
359 and override the methods that perform the actions. You may need to
360 read through "Module::Build::Authoring" and "Module::Build::API" to
361 find the methods you want to override. All "action" methods are
362 implemented by a method called "ACTION_" followed by the action's name,
363 so here's an example of how it would work for the "install" action:
364 # Build.PL
366 use Module::Build;
367 my $class = Module::Build->subclass(
368 class => "Module::Build::Custom",
369 code => <<'SUBCLASS' );
370 sub ACTION_install {
372 my $self = shift;
373 # YOUR CODE HERE
374 $self->SUPER::ACTION_install;
375 }
376 SUBCLASS
377 $class->new(
379 module_name => 'Your::Module',
380 # rest of the usual Module::Build parameters
381 )->create_build_script;
382 Adding an action
384 You can add a new "./Build" action simply by writing the method for it
385 in your subclass. Use "depends_on" to declare that another action must
386 have been run before your action.
387 For example, let's say you wanted to be able to write "./Build commit"
389 to test your code and commit it to Subversion.
390 # Build.PL
392 use Module::Build;
393 my $class = Module::Build->subclass(
394 class => "Module::Build::Custom",
395 code => <<'SUBCLASS' );
396 sub ACTION_commit {
398 my $self = shift;
399 $self->depends_on("test");
401 $self->do_system(qw(svn commit));
402 }
403 SUBCLASS
404 Bundling Module::Build
406 Note: This section probably needs an update as the technology improves
407 (see contrib/bundle.pl in the distribution).
408 Suppose you want to use some new-ish features of Module::Build, e.g.
410 newer than the version of Module::Build your users are likely to
411 already have installed on their systems. The first thing you should do
412 is set "configure_requires" to your minimum version of Module::Build.
413 See Module::Build::Authoring.
414 But not every build system honors "configure_requires" yet. Here's how
416 you can ship a copy of Module::Build, but still use a newer installed
417 version to take advantage of any bug fixes and upgrades.
418 First, install Module::Build into Your-Project/inc/Module-Build. CPAN
420 will not index anything in the inc directory so this copy will not show
421 up in CPAN searches.
422 cd Module-Build
424 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
425 ./Build test
426 ./Build install
427 You should now have all the Module::Build .pm files in
429 Your-Project/inc/Module-Build/lib/perl5.
430 Next, add this to the top of your Build.PL.
432 my $Bundled_MB = 0.30; # or whatever version it was.
434 # Find out what version of Module::Build is installed or fail quietly.
436 # This should be cross-platform.
437 my $Installed_MB =
438 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1"`;
439 # some operating systems put a newline at the end of every print.
441 chomp $Installed_MB;
442 $Installed_MB = 0 if $?;
444 # Use our bundled copy of Module::Build if it's newer than the installed.
446 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
447 require Module::Build;
449 And write the rest of your Build.PL normally. Module::Build will
451 remember your change to @INC and use it when you run ./Build.
452 In the future, we hope to provide a more automated solution for this
454 scenario; see "inc/latest.pm" in the Module::Build distribution for one
455 indication of the direction we're moving.
456
458 Ken Williams <kwilliams@cpan.org>
459
461 Copyright (c) 2001-2008 Ken Williams. All rights reserved.
462 This library is free software; you can redistribute it and/or modify it
464 under the same terms as Perl itself.
465
467 perl(1), Module::Build(3), Module::Build::Authoring(3),
468 Module::Build::API(3)
469perl v5.36.0 2023-01-20 Module::Build::Cookbook(3)