1 package Module::Build::Cookbook;
9 Module::Build::Cookbook - Examples of Module::Build Usage
14 C<Module::Build> isn't conceptually very complicated, but examples are
15 always helpful. The following recipes should help developers and/or
16 installers put together the pieces from the other parts of the
23 =head2 Installing modules that use Module::Build
25 In most cases, you can just issue the following commands:
32 There's nothing complicated here - first you're running a script
33 called F<Build.PL>, then you're running a (newly-generated) script
34 called F<Build> and passing it various arguments.
36 The exact commands may vary a bit depending on how you invoke perl
37 scripts on your system. For instance, if you have multiple versions
38 of perl installed, you can install to one particular perl's library
41 /usr/bin/perl5.8.1 Build.PL
46 If you're on Windows where the current directory is always searched
47 first for scripts, you'll probably do something like this:
54 On the old Mac OS (version 9 or lower) using MacPerl, you can
55 double-click on the F<Build.PL> script to create the F<Build> script,
56 then double-click on the F<Build> script to run its C<build>, C<test>,
57 and C<install> actions.
59 The F<Build> script knows what perl was used to run F<Build.PL>, so
60 you don't need to re-invoke the F<Build> script with the complete perl
61 path each time. If you invoke it with the I<wrong> perl path, you'll
62 get a warning or a fatal error.
64 =head2 Modifying Config.pm values
66 C<Module::Build> relies heavily on various values from perl's
67 C<Config.pm> to do its work. For example, default installation paths
68 are given by C<installsitelib> and C<installvendorman3dir> and
69 friends, C linker & compiler settings are given by C<ld>,
70 C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure
71 you know what you're doing>, you can tell C<Module::Build> to pretend
72 there are different values in F<Config.pm> than what's really there,
73 by passing arguments for the C<--config> parameter on the command
76 perl Build.PL --config cc=gcc --config ld=gcc
78 Inside the C<Build.PL> script the same thing can be accomplished by
79 passing values for the C<config> parameter to C<new()>:
81 my $build = Module::Build->new
84 config => { cc => 'gcc', ld => 'gcc' },
88 In custom build code, the same thing can be accomplished by calling
89 the L<Module::Build/config> method:
91 $build->config( cc => 'gcc' ); # Set
92 $build->config( ld => 'gcc' ); # Set
94 my $linker = $build->config('ld'); # Get
97 =head2 Installing modules using the programmatic interface
99 If you need to build, test, and/or install modules from within some
100 other perl code (as opposed to having the user type installation
101 commands at the shell), you can use the programmatic interface.
102 Create a Module::Build object (or an object of a custom Module::Build
103 subclass) and then invoke its C<dispatch()> method to run various
106 my $build = Module::Build->new
108 module_name => 'Foo::Bar',
110 requires => { 'Some::Module' => '1.23' },
112 $build->dispatch('build');
113 $build->dispatch('test', verbose => 1);
114 $build->dispatch('install');
116 The first argument to C<dispatch()> is the name of the action, and any
117 following arguments are named parameters.
119 This is the interface we use to test Module::Build itself in the
123 =head2 Installing to a temporary directory
125 To create packages for package managers like RedHat's C<rpm> or
126 Debian's C<deb>, you may need to install to a temporary directory
127 first and then create the package from that temporary installation.
128 To do this, specify the C<destdir> parameter to the C<install> action:
130 ./Build install --destdir /tmp/my-package-1.003
132 This essentially just prepends all the installation paths with the
133 F</tmp/my-package-1.003> directory.
136 =head2 Installing to a non-standard directory
138 To install to a non-standard directory (for example, if you don't have
139 permission to install in the system-wide directories), you can use the
140 C<install_base> or C<prefix> parameters:
142 ./Build install --install_base /foo/bar
144 See L<Module::Build/"INSTALL PATHS"> for a much more complete
145 discussion of how installation paths are determined.
148 =head2 Installing in the same location as ExtUtils::MakeMaker
150 With the introduction of C<--prefix> in Module::Build 0.28 and
151 C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both
152 to install to the same locations.
154 First, ensure you have at least version 0.28 of Module::Build
155 installed and 6.31 of ExtUtils::MakeMaker. Prior versions have
156 differing (and in some cases quite strange) installation behaviors.
158 The following installation flags are equivalent between
159 ExtUtils::MakeMaker and Module::Build.
161 MakeMaker Module::Build
162 PREFIX=... --prefix ...
163 INSTALL_BASE=... --install_base ...
164 DESTDIR=... --destdir ...
165 LIB=... --install_path lib=...
166 INSTALLDIRS=... --installdirs ...
167 INSTALLDIRS=perl --installdirs core
168 UNINST=... --uninst ...
169 INC=... --extra_compiler_flags ...
170 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
172 For example, if you are currently installing MakeMaker modules with
175 perl Makefile.PL PREFIX=~
177 make install UNINST=1
179 You can install into the same location with Module::Build using this:
181 perl Build.PL --prefix ~
183 ./Build install --uninst 1
185 =head3 C<prefix> vs C<install_base>
187 The behavior of C<prefix> is complicated and depends on
188 how your Perl is configured. The resulting installation locations
189 will vary from machine to machine and even different installations of
190 Perl on the same machine. Because of this, it's difficult to document
191 where C<prefix> will place your modules.
193 In contrast, C<install_base> has predictable, easy to explain
194 installation locations. Now that Module::Build and MakeMaker both
195 have C<install_base> there is little reason to use C<prefix> other
196 than to preserve your existing installation locations. If you are
197 starting a fresh Perl installation we encourage you to use
198 C<install_base>. If you have an existing installation installed via
199 C<prefix>, consider moving it to an installation structure matching
200 C<install_base> and using that instead.
203 =head2 Running a single test file
205 C<Module::Build> supports running a single test, which enables you to
206 track down errors more quickly. Use the following format:
208 ./Build test --test_files t/mytest.t
210 In addition, you may want to run the test in verbose mode to get more
213 ./Build test --test_files t/mytest.t --verbose 1
215 I run this so frequently that I define the following shell alias:
217 alias t './Build test --verbose 1 --test_files'
219 So then I can just execute C<t t/mytest.t> to run a single test.
222 =head1 ADVANCED RECIPES
225 =head2 Making a CPAN.pm-compatible distribution
227 New versions of CPAN.pm understand how to use a F<Build.PL> script,
228 but old versions don't. If authors want to help users who have old
229 versions, some form of F<Makefile.PL> should be supplied. The easiest
230 way to accomplish this is to use the C<create_makefile_pl> parameter to
231 C<< Module::Build->new() >> in the C<Build.PL> script, which can
232 create various flavors of F<Makefile.PL> during the C<dist> action.
234 As a best practice, we recommend using the "traditional" style of
235 F<Makefile.PL> unless your distribution has needs that can't be
236 accomplished that way.
238 The C<Module::Build::Compat> module, which is part of
239 C<Module::Build>'s distribution, is responsible for creating these
240 F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details.
243 =head2 Changing the order of the build process
245 The C<build_elements> property specifies the steps C<Module::Build>
246 will take when building a distribution. To change the build order,
247 change the order of the entries in that property:
249 # Process pod files first
250 my @e = @{$build->build_elements};
251 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
252 unshift @e, splice @e, $i, 1;
254 Currently, C<build_elements> has the following default value:
256 [qw( PL support pm xs pod script )]
258 Do take care when altering this property, since there may be
259 non-obvious (and non-documented!) ordering dependencies in the
260 C<Module::Build> code.
263 =head2 Adding new file types to the build process
265 Sometimes you might have extra types of files that you want to install
266 alongside the standard types like F<.pm> and F<.pod> files. For
267 instance, you might have a F<Bar.dat> file containing some data
268 related to the C<Foo::Bar> module and you'd like for it to end up as
269 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
270 access it easily at runtime. The following code from a sample
271 C<Build.PL> file demonstrates how to accomplish this:
274 my $build = Module::Build->new
276 module_name => 'Foo::Bar',
277 ...other stuff here...
279 $build->add_build_element('dat');
280 $build->create_build_script;
282 This will find all F<.dat> files in the F<lib/> directory, copy them
283 to the F<blib/lib/> directory during the C<build> action, and install
284 them during the C<install> action.
286 If your extra files aren't located in the C<lib/> directory in your
287 distribution, you can explicitly say where they are, just as you'd do
288 with F<.pm> or F<.pod> files:
291 my $build = new Module::Build
293 module_name => 'Foo::Bar',
294 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
295 ...other stuff here...
297 $build->add_build_element('dat');
298 $build->create_build_script;
300 If your extra files actually need to be created on the user's machine,
301 or if they need some other kind of special processing, you'll probably
302 want to subclass C<Module::Build> and create a special method to
303 process them, named C<process_${kind}_files()>:
306 my $class = Module::Build->subclass(code => <<'EOF');
307 sub process_dat_files {
309 ... locate and process *.dat files,
310 ... and create something in blib/lib/
313 my $build = $class->new
315 module_name => 'Foo::Bar',
316 ...other stuff here...
318 $build->add_build_element('dat');
319 $build->create_build_script;
321 If your extra files don't go in F<lib/> but in some other place, see
322 L<"Adding new elements to the install process"> for how to actually
325 Please note that these examples use some capabilities of Module::Build
326 that first appeared in version 0.26. Before that it could
327 still be done, but the simple cases took a bit more work.
330 =head2 Adding new elements to the install process
332 By default, Module::Build creates seven subdirectories of the F<blib>
333 directory during the build process: F<lib>, F<arch>, F<bin>,
334 F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
335 missing or empty if there's nothing to go in them). Anything copied
336 to these directories during the build will eventually be installed
337 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
339 If you need to create a new custom type of installable element, e.g. C<conf>,
340 then you need to tell Module::Build where things in F<blib/conf/>
341 should be installed. To do this, use the C<install_path> parameter to
344 my $build = Module::Build->new
346 ...other stuff here...
347 install_path => { conf => $installation_path }
350 Or you can call the C<install_path()> method later:
352 $build->install_path(conf => $installation_path);
354 The user may also specify the path on the command line:
356 perl Build.PL --install_path conf=/foo/path/etc
358 The important part, though, is that I<somehow> the install path needs
359 to be set, or else nothing in the F<blib/conf/> directory will get
360 installed, and a runtime error during the C<install> action will
363 See also L<"Adding new file types to the build process"> for how to
364 create the stuff in F<blib/conf/> in the first place.
367 =head1 EXAMPLES ON CPAN
369 Several distributions on CPAN are making good use of various features
370 of Module::Build. They can serve as real-world examples for others.
373 =head2 SVN-Notify-Mirror
375 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
377 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
381 =item 1. Using C<auto_features>, I check to see whether two optional
382 modules are available - SVN::Notify::Config and Net::SSH;
384 =item 2. If the S::N::Config module is loaded, I automatically
385 generate testfiles for it during Build (using the C<PL_files>
388 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
389 to perform the ssh tests (since it requires a little preliminary
392 =item 4. Only if the user has C<ssh_feature> and answers yes to the
393 testing, do I generate a test file.
395 I'm sure I could not have handled this complexity with EU::MM, but it
396 was very easy to do with M::B.
401 =head2 Modifying an action
403 Sometimes you might need an to have an action, say C<./Build install>,
404 do something unusual. For instance, you might need to change the
405 ownership of a file or do something else peculiar to your application.
407 You can subclass C<Module::Build> on the fly using the C<subclass()>
408 method and override the methods that perform the actions. You may
409 need to read through C<Module::Build::Authoring> and
410 C<Module::Build::API> to find the methods you want to override. All
411 "action" methods are implemented by a method called "ACTION_" followed
412 by the action's name, so here's an example of how it would work for
413 the C<install> action:
417 my $class = Module::Build->subclass(
418 class => "Module::Build::Custom",
419 code => <<'SUBCLASS' );
424 $self->SUPER::ACTION_install;
429 module_name => 'Your::Module',
430 # rest of the usual Module::Build parameters
431 )->create_build_script;
434 =head2 Adding an action
436 You can add a new C<./Build> action simply by writing the method for
437 it in your subclass. Use C<depends_on> to declare that another action
438 must have been run before your action.
440 For example, let's say you wanted to be able to write C<./Build
441 commit> to test your code and commit it to Subversion.
445 my $class = Module::Build->subclass(
446 class => "Module::Build::Custom",
447 code => <<'SUBCLASS' );
452 $self->depends_on("test");
453 $self->do_system(qw(svn commit));
458 =head2 Bundling Module::Build
460 Note: This section probably needs an update as the technology improves
461 (see scripts/bundle.pl in the distribution).
463 Suppose you want to use some new-ish features of Module::Build,
464 e.g. newer than the version of Module::Build your users are likely to
465 already have installed on their systems. The first thing you should
466 do is set C<configure_requires> to your minimum version of
467 Module::Build. See L<Module::Build::Authoring>.
469 But not every build system honors C<configure_requires> yet. Here's
470 how you can ship a copy of Module::Build, but still use a newer
471 installed version to take advantage of any bug fixes and upgrades.
473 First, install Module::Build into F<Your-Project/inc/Module-Build>.
474 CPAN will not index anything in the F<inc> directory so this copy will
475 not show up in CPAN searches.
478 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
482 You should now have all the Module::Build .pm files in
483 F<Your-Project/inc/Module-Build/lib/perl5>.
485 Next, add this to the top of your F<Build.PL>.
487 my $Bundled_MB = 0.30; # or whatever version it was.
489 # Find out what version of Module::Build is installed or fail quietly.
490 # This should be cross-platform.
492 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1";
494 # some operating systems put a newline at the end of every print.
497 $Installed_MB = 0 if $?;
499 # Use our bundled copy of Module::Build if it's newer than the installed.
500 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
502 require Module::Build;
504 And write the rest of your F<Build.PL> normally. Module::Build will
505 remember your change to C<@INC> and use it when you run F<./Build>.
507 In the future, we hope to provide a more automated solution for this
508 scenario; see C<inc/latest.pm> in the Module::Build distribution for
509 one indication of the direction we're moving.
514 Ken Williams <kwilliams@cpan.org>
519 Copyright (c) 2001-2008 Ken Williams. All rights reserved.
521 This library is free software; you can redistribute it and/or
522 modify it under the same terms as Perl itself.
527 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
528 L<Module::Build::API>(3)