1 package Module::Build::Cookbook;
9 Module::Build::Cookbook - Examples of Module::Build Usage
13 C<Module::Build> isn't conceptually very complicated, but examples are
14 always helpful. The following recipes should help developers and/or
15 installers put together the pieces from the other parts of the
22 =head2 Installing modules that use Module::Build
24 In most cases, you can just issue the following commands:
31 There's nothing complicated here - first you're running a script
32 called F<Build.PL>, then you're running a (newly-generated) script
33 called F<Build> and passing it various arguments.
35 The exact commands may vary a bit depending on how you invoke perl
36 scripts on your system. For instance, if you have multiple versions
37 of perl installed, you can install to one particular perl's library
40 /usr/bin/perl5.8.1 Build.PL
45 If you're on Windows where the current directory is always searched
46 first for scripts, you'll probably do something like this:
53 On the old Mac OS (version 9 or lower) using MacPerl, you can
54 double-click on the F<Build.PL> script to create the F<Build> script,
55 then double-click on the F<Build> script to run its C<build>, C<test>,
56 and C<install> actions.
58 The F<Build> script knows what perl was used to run F<Build.PL>, so
59 you don't need to re-invoke the F<Build> script with the complete perl
60 path each time. If you invoke it with the I<wrong> perl path, you'll
61 get a warning or a fatal error.
63 =head2 Modifying Config.pm values
65 C<Module::Build> relies heavily on various values from perl's
66 C<Config.pm> to do its work. For example, default installation paths
67 are given by C<installsitelib> and C<installvendorman3dir> and
68 friends, C linker & compiler settings are given by C<ld>,
69 C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure
70 you know what you're doing>, you can tell C<Module::Build> to pretend
71 there are different values in F<Config.pm> than what's really there,
72 by passing arguments for the C<--config> parameter on the command
75 perl Build.PL --config cc=gcc --config ld=gcc
77 Inside the C<Build.PL> script the same thing can be accomplished by
78 passing values for the C<config> parameter to C<new()>:
80 my $build = Module::Build->new
83 config => { cc => 'gcc', ld => 'gcc' },
87 In custom build code, the same thing can be accomplished by calling
88 the L<Module::Build/config> method:
90 $build->config( cc => 'gcc' ); # Set
91 $build->config( ld => 'gcc' ); # Set
93 my $linker = $build->config('ld'); # Get
96 =head2 Installing modules using the programmatic interface
98 If you need to build, test, and/or install modules from within some
99 other perl code (as opposed to having the user type installation
100 commands at the shell), you can use the programmatic interface.
101 Create a Module::Build object (or an object of a custom Module::Build
102 subclass) and then invoke its C<dispatch()> method to run various
105 my $build = Module::Build->new
107 module_name => 'Foo::Bar',
109 requires => { 'Some::Module' => '1.23' },
111 $build->dispatch('build');
112 $build->dispatch('test', verbose => 1);
113 $build->dispatch('install');
115 The first argument to C<dispatch()> is the name of the action, and any
116 following arguments are named parameters.
118 This is the interface we use to test Module::Build itself in the
122 =head2 Installing to a temporary directory
124 To create packages for package managers like RedHat's C<rpm> or
125 Debian's C<deb>, you may need to install to a temporary directory
126 first and then create the package from that temporary installation.
127 To do this, specify the C<destdir> parameter to the C<install> action:
129 ./Build install --destdir /tmp/my-package-1.003
131 This essentially just prepends all the installation paths with the
132 F</tmp/my-package-1.003> directory.
135 =head2 Installing to a non-standard directory
137 To install to a non-standard directory (for example, if you don't have
138 permission to install in the system-wide directories), you can use the
139 C<install_base> or C<prefix> parameters:
141 ./Build install --install_base /foo/bar
143 See L<Module::Build/"INSTALL PATHS"> for a much more complete
144 discussion of how installation paths are determined.
147 =head2 Installing in the same location as ExtUtils::MakeMaker
149 With the introduction of C<--prefix> in Module::Build 0.28 and
150 C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both
151 to install to the same locations.
153 First, ensure you have at least version 0.28 of Module::Build
154 installed and 6.31 of C<ExtUtils::MakeMaker>. Prior versions have
155 differing (and in some cases quite strange) installation behaviors.
157 The following installation flags are equivalent between
158 C<ExtUtils::MakeMaker> and C<Module::Build>.
160 MakeMaker Module::Build
161 PREFIX=... --prefix ...
162 INSTALL_BASE=... --install_base ...
163 DESTDIR=... --destdir ...
164 LIB=... --install_path lib=...
165 INSTALLDIRS=... --installdirs ...
166 INSTALLDIRS=perl --installdirs core
167 UNINST=... --uninst ...
168 INC=... --extra_compiler_flags ...
169 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
171 For example, if you are currently installing C<MakeMaker> modules with
174 perl Makefile.PL PREFIX=~
176 make install UNINST=1
178 You can install into the same location with Module::Build using this:
180 perl Build.PL --prefix ~
182 ./Build install --uninst 1
184 =head3 C<prefix> vs C<install_base>
186 The behavior of C<prefix> is complicated and depends on
187 how your Perl is configured. The resulting installation locations
188 will vary from machine to machine and even different installations of
189 Perl on the same machine. Because of this, it's difficult to document
190 where C<prefix> will place your modules.
192 In contrast, C<install_base> has predictable, easy to explain
193 installation locations. Now that C<Module::Build> and C<MakeMaker> both
194 have C<install_base> there is little reason to use C<prefix> other
195 than to preserve your existing installation locations. If you are
196 starting a fresh Perl installation we encourage you to use
197 C<install_base>. If you have an existing installation installed via
198 C<prefix>, consider moving it to an installation structure matching
199 C<install_base> and using that instead.
202 =head2 Running a single test file
204 C<Module::Build> supports running a single test, which enables you to
205 track down errors more quickly. Use the following format:
207 ./Build test --test_files t/mytest.t
209 In addition, you may want to run the test in verbose mode to get more
212 ./Build test --test_files t/mytest.t --verbose 1
214 I run this so frequently that I define the following shell alias:
216 alias t './Build test --verbose 1 --test_files'
218 So then I can just execute C<t t/mytest.t> to run a single test.
221 =head1 ADVANCED RECIPES
224 =head2 Making a CPAN.pm-compatible distribution
226 New versions of CPAN.pm understand how to use a F<Build.PL> script,
227 but old versions don't. If authors want to help users who have old
228 versions, some form of F<Makefile.PL> should be supplied. The easiest
229 way to accomplish this is to use the C<create_makefile_pl> parameter to
230 C<< Module::Build->new() >> in the C<Build.PL> script, which can
231 create various flavors of F<Makefile.PL> during the C<dist> action.
233 As a best practice, we recommend using the "traditional" style of
234 F<Makefile.PL> unless your distribution has needs that can't be
235 accomplished that way.
237 The C<Module::Build::Compat> module, which is part of
238 C<Module::Build>'s distribution, is responsible for creating these
239 F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details.
242 =head2 Changing the order of the build process
244 The C<build_elements> property specifies the steps C<Module::Build>
245 will take when building a distribution. To change the build order,
246 change the order of the entries in that property:
248 # Process pod files first
249 my @e = @{$build->build_elements};
250 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
251 unshift @e, splice @e, $i, 1;
253 Currently, C<build_elements> has the following default value:
255 [qw( PL support pm xs pod script )]
257 Do take care when altering this property, since there may be
258 non-obvious (and non-documented!) ordering dependencies in the
259 C<Module::Build> code.
262 =head2 Adding new file types to the build process
264 Sometimes you might have extra types of files that you want to install
265 alongside the standard types like F<.pm> and F<.pod> files. For
266 instance, you might have a F<Bar.dat> file containing some data
267 related to the C<Foo::Bar> module and you'd like for it to end up as
268 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
269 access it easily at runtime. The following code from a sample
270 C<Build.PL> file demonstrates how to accomplish this:
273 my $build = Module::Build->new
275 module_name => 'Foo::Bar',
276 ...other stuff here...
278 $build->add_build_element('dat');
279 $build->create_build_script;
281 This will find all F<.dat> files in the F<lib/> directory, copy them
282 to the F<blib/lib/> directory during the C<build> action, and install
283 them during the C<install> action.
285 If your extra files aren't located in the C<lib/> directory in your
286 distribution, you can explicitly say where they are, just as you'd do
287 with F<.pm> or F<.pod> files:
290 my $build = new Module::Build
292 module_name => 'Foo::Bar',
293 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
294 ...other stuff here...
296 $build->add_build_element('dat');
297 $build->create_build_script;
299 If your extra files actually need to be created on the user's machine,
300 or if they need some other kind of special processing, you'll probably
301 want to subclass C<Module::Build> and create a special method to
302 process them, named C<process_${kind}_files()>:
305 my $class = Module::Build->subclass(code => <<'EOF');
306 sub process_dat_files {
308 ... locate and process *.dat files,
309 ... and create something in blib/lib/
312 my $build = $class->new
314 module_name => 'Foo::Bar',
315 ...other stuff here...
317 $build->add_build_element('dat');
318 $build->create_build_script;
320 If your extra files don't go in F<lib/> but in some other place, see
321 L<"Adding new elements to the install process"> for how to actually
324 Please note that these examples use some capabilities of Module::Build
325 that first appeared in version 0.26. Before that it could
326 still be done, but the simple cases took a bit more work.
329 =head2 Adding new elements to the install process
331 By default, Module::Build creates seven subdirectories of the F<blib>
332 directory during the build process: F<lib>, F<arch>, F<bin>,
333 F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
334 missing or empty if there's nothing to go in them). Anything copied
335 to these directories during the build will eventually be installed
336 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
338 If you need to create a new custom type of installable element, e.g. C<conf>,
339 then you need to tell Module::Build where things in F<blib/conf/>
340 should be installed. To do this, use the C<install_path> parameter to
343 my $build = Module::Build->new
345 ...other stuff here...
346 install_path => { conf => $installation_path }
349 Or you can call the C<install_path()> method later:
351 $build->install_path(conf => $installation_path);
353 The user may also specify the path on the command line:
355 perl Build.PL --install_path conf=/foo/path/etc
357 The important part, though, is that I<somehow> the install path needs
358 to be set, or else nothing in the F<blib/conf/> directory will get
359 installed, and a runtime error during the C<install> action will
362 See also L<"Adding new file types to the build process"> for how to
363 create the stuff in F<blib/conf/> in the first place.
366 =head1 EXAMPLES ON CPAN
368 Several distributions on CPAN are making good use of various features
369 of Module::Build. They can serve as real-world examples for others.
372 =head2 SVN-Notify-Mirror
374 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
376 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
380 =item 1. Using C<auto_features>, I check to see whether two optional
381 modules are available - SVN::Notify::Config and Net::SSH;
383 =item 2. If the S::N::Config module is loaded, I automatically
384 generate test files for it during Build (using the C<PL_files>
387 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
388 to perform the ssh tests (since it requires a little preliminary
391 =item 4. Only if the user has C<ssh_feature> and answers yes to the
392 testing, do I generate a test file.
394 I'm sure I could not have handled this complexity with EU::MM, but it
395 was very easy to do with M::B.
400 =head2 Modifying an action
402 Sometimes you might need an to have an action, say C<./Build install>,
403 do something unusual. For instance, you might need to change the
404 ownership of a file or do something else peculiar to your application.
406 You can subclass C<Module::Build> on the fly using the C<subclass()>
407 method and override the methods that perform the actions. You may
408 need to read through C<Module::Build::Authoring> and
409 C<Module::Build::API> to find the methods you want to override. All
410 "action" methods are implemented by a method called "ACTION_" followed
411 by the action's name, so here's an example of how it would work for
412 the C<install> action:
416 my $class = Module::Build->subclass(
417 class => "Module::Build::Custom",
418 code => <<'SUBCLASS' );
423 $self->SUPER::ACTION_install;
428 module_name => 'Your::Module',
429 # rest of the usual Module::Build parameters
430 )->create_build_script;
433 =head2 Adding an action
435 You can add a new C<./Build> action simply by writing the method for
436 it in your subclass. Use C<depends_on> to declare that another action
437 must have been run before your action.
439 For example, let's say you wanted to be able to write C<./Build
440 commit> to test your code and commit it to Subversion.
444 my $class = Module::Build->subclass(
445 class => "Module::Build::Custom",
446 code => <<'SUBCLASS' );
451 $self->depends_on("test");
452 $self->do_system(qw(svn commit));
457 =head2 Bundling Module::Build
459 Note: This section probably needs an update as the technology improves
460 (see contrib/bundle.pl in the distribution).
462 Suppose you want to use some new-ish features of Module::Build,
463 e.g. newer than the version of Module::Build your users are likely to
464 already have installed on their systems. The first thing you should
465 do is set C<configure_requires> to your minimum version of
466 Module::Build. See L<Module::Build::Authoring>.
468 But not every build system honors C<configure_requires> yet. Here's
469 how you can ship a copy of Module::Build, but still use a newer
470 installed version to take advantage of any bug fixes and upgrades.
472 First, install Module::Build into F<Your-Project/inc/Module-Build>.
473 CPAN will not index anything in the F<inc> directory so this copy will
474 not show up in CPAN searches.
477 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
481 You should now have all the Module::Build .pm files in
482 F<Your-Project/inc/Module-Build/lib/perl5>.
484 Next, add this to the top of your F<Build.PL>.
486 my $Bundled_MB = 0.30; # or whatever version it was.
488 # Find out what version of Module::Build is installed or fail quietly.
489 # This should be cross-platform.
491 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1";
493 # some operating systems put a newline at the end of every print.
496 $Installed_MB = 0 if $?;
498 # Use our bundled copy of Module::Build if it's newer than the installed.
499 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
501 require Module::Build;
503 And write the rest of your F<Build.PL> normally. Module::Build will
504 remember your change to C<@INC> and use it when you run F<./Build>.
506 In the future, we hope to provide a more automated solution for this
507 scenario; see C<inc/latest.pm> in the Module::Build distribution for
508 one indication of the direction we're moving.
513 Ken Williams <kwilliams@cpan.org>
518 Copyright (c) 2001-2008 Ken Williams. All rights reserved.
520 This library is free software; you can redistribute it and/or
521 modify it under the same terms as Perl itself.
526 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
527 L<Module::Build::API>(3)