1 package Module::Build::Cookbook;
6 Module::Build::Cookbook - Examples of Module::Build Usage
11 C<Module::Build> isn't conceptually very complicated, but examples are
12 always helpful. I got the idea for writing this cookbook when
13 attending Brian Ingerson's "Extreme Programming Tools for Module
14 Authors" presentation at YAPC 2003, when he said, straightforwardly,
17 The definitional of how stuff works is in the main C<Module::Build>
18 documentation. It's best to get familiar with that too.
24 =head2 The basic installation recipe for modules that use Module::Build
26 In most cases, you can just issue the following commands:
33 There's nothing complicated here - first you're running a script
34 called F<Build.PL>, then you're running a (newly-generated) script
35 called F<Build> and passing it various arguments.
37 The exact commands may vary a bit depending on how you invoke perl
38 scripts on your system. For instance, if you have multiple versions
39 of perl installed, you can install to one particular perl's library
42 /usr/bin/perl5.8.1 Build.PL
47 If you're on Windows where the current directory is always searched
48 first for scripts, you'll probably do something like this:
55 On the old Mac OS (version 9 or lower) using MacPerl, you can
56 double-click on the F<Build.PL> script to create the F<Build> script,
57 then double-click on the F<Build> script to run its C<build>, C<test>,
58 and C<install> actions.
60 The F<Build> script knows what perl was used to run C<Build.PL>, so
61 you don't need to re-invoke the F<Build> script with the complete perl
62 path each time. If you invoke it with the I<wrong> perl path, you'll
63 get a warning or a fatal error.
66 =head2 Making a CPAN.pm-compatible distribution
68 New versions of CPAN.pm understand how to use a F<Build.PL> script,
69 but old versions don't. If you want to help users who have old
70 versions, do the following:
72 Create a file in your distribution named F<Makefile.PL>, with the
75 use Module::Build::Compat;
76 Module::Build::Compat->run_build_pl(args => \@ARGV);
77 Module::Build::Compat->write_makefile();
79 Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make
80 test`, and `make install`, provided the end-user already has
81 C<Module::Build> installed.
83 If the end-user might not have C<Module::Build> installed, it's
84 probably best to supply a "traditional" F<Makefile.PL>. The
85 C<Module::Build::Compat> module has some very helpful tools for
86 keeping a F<Makefile.PL> in sync with a F<Build.PL>. See its
87 documentation, and also the C<create_makefile_pl> parameter to the
88 C<< Module::Build->new() >> method.
91 =head2 Installing modules using the programmatic interface
93 If you need to build, test, and/or install modules from within some
94 other perl code (as opposed to having the user type installation
95 commands at the shell), you can use the programmatic interface.
96 Create a Module::Build object (or an object of a custom Module::Build
97 subclass) and then invoke its C<dispatch()> method to run various
100 my $build = Module::Build->new
102 module_name => 'Foo::Bar',
104 requires => { 'Some::Module' => '1.23' },
106 $build->dispatch('build');
107 $build->dispatch('test', verbose => 1);
108 $build->dispatch('install');
110 The first argument to C<dispatch()> is the name of the action, and any
111 following arguments are named parameters.
113 This is the interface we use to test Module::Build itself in the
117 =head2 Installing to a temporary directory
119 To create packages for package managers like RedHat's C<rpm> or
120 Debian's C<deb>, you may need to install to a temporary directory
121 first and then create the package from that temporary installation.
122 To do this, specify the C<destdir> parameter to the C<install> action:
124 ./Build install --destdir /tmp/my-package-1.003
126 This essentially just prepends all the installation paths with the
127 F</tmp/my-package-1.003> directory.
130 =head2 Installing to a non-standard directory
132 To install to a non-standard directory (for example, if you don't have
133 permission to install in the system-wide directories), you can use the
134 C<install_base> or C<prefix> parameters:
136 ./Build install --install_base /foo/bar
138 ./Build install --prefix /foo/bar
140 Note that these have somewhat different effects - C<prefix> is an
141 emulation of C<ExtUtils::MakeMaker>'s old C<PREFIX> setting, and
142 inherits all its nasty gotchas. C<install_base> is more predictable,
143 and newer versions of C<ExtUtils::MakeMaker> also support it, so it's
144 often your best choice.
146 See L<Module::Build/"INSTALL PATHS"> for a much more complete
147 discussion of how installation paths are determined.
150 =head2 Running a single test file
152 C<Module::Build> supports running a single test, which enables you to
153 track down errors more quickly. Use the following format:
155 ./Build test --test_files t/mytest.t
157 In addition, you may want to run the test in verbose mode to get more
160 ./Build test --test_files t/mytest.t --verbose 1
162 I run this so frequently that I actually define the following shell alias:
164 alias t './Build test --verbose 1 --test_files'
166 So then I can just execute C<t t/mytest.t> to run a single test.
169 =head1 ADVANCED RECIPES
172 =head2 Changing the order of the build process
174 The C<build_elements> property specifies the steps C<Module::Build>
175 will take when building a distribution. To change the build order,
176 change the order of the entries in that property:
178 # Process pod files first
179 my @e = @{$build->build_elements};
180 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
181 unshift @e, splice @e, $i, 1;
183 Currently, C<build_elements> has the following default value:
185 [qw( PL support pm xs pod script )]
187 Do take care when altering this property, since there may be
188 non-obvious (and non-documented!) ordering dependencies in the
189 C<Module::Build> code.
192 =head2 Adding new file types to the build process
194 Sometimes you might have extra types of files that you want to install
195 alongside the standard types like F<.pm> and F<.pod> files. For
196 instance, you might have a F<Bar.dat> file containing some data
197 related to the C<Foo::Bar> module. Assuming the data doesn't need to
198 be created on the fly, the best place for it to end up is probably as
199 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
200 access it easily at runtime. The following code from a sample
201 C<Build.PL> file demonstrates how to accomplish this:
204 my $build = Module::Build->new
206 module_name => 'Foo::Bar',
207 ...other stuff here...
209 $build->add_build_element('dat');
210 $build->create_build_script;
212 This will find all F<.dat> files in the F<lib/> directory, copy them
213 to the F<blib/lib/> directory during the C<build> action, and install
214 them during the C<install> action.
216 If your extra files aren't in the C<lib/> directory, you can
217 explicitly say where they are, just as you'd do with F<.pm> or F<.pod>
221 my $build = new Module::Build
223 module_name => 'Foo::Bar',
224 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
225 ...other stuff here...
227 $build->add_build_element('dat');
228 $build->create_build_script;
230 If your extra files actually need to be created on the user's machine,
231 or if they need some other kind of special processing, you'll probably
232 want to create a special method to do so, named
233 C<process_${kind}_files()>:
236 my $class = Module::Build->subclass(code => <<'EOF');
237 sub process_dat_files {
239 ... locate and process *.dat files,
240 ... and create something in blib/lib/
243 my $build = $class->new
245 module_name => 'Foo::Bar',
246 ...other stuff here...
248 $build->add_build_element('dat');
249 $build->create_build_script;
251 If your extra files don't go in F<lib/> but in some other place, see
252 L<"Adding new elements to the install process"> for how to actually
255 Please note that these examples use some capabilities of Module::Build
256 that first appeared in version 0.26. Before that it could certainly
257 still be done, but the simple cases took a bit more work.
260 =head2 Adding new elements to the install process
262 By default, Module::Build creates seven subdirectories of the F<blib/>
263 directory during the build process: F<lib/>, F<arch/>, F<bin/>,
264 F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be
265 missing or empty if there's nothing to go in them). Anything copied
266 to these directories during the build will eventually be installed
267 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
269 If you need to create a new type of installable element, e.g. C<conf>,
270 then you need to tell Module::Build where things in F<blib/conf/>
271 should be installed. To do this, use the C<install_path> parameter to
274 my $build = Module::Build->new
276 ...other stuff here...
277 install_path => { conf => $installation_path }
280 Or you can call the C<install_path()> method later:
282 $build->install_path->{conf} || $installation_path;
284 (Sneakily, or perhaps uglily, C<install_path()> returns a reference to
285 a hash of install paths, and you can modify that hash to your heart's
288 The user may also specify the path on the command line:
290 perl Build.PL --install_path conf=/foo/path/etc
292 The important part, though, is that I<somehow> the install path needs
293 to be set, or else nothing in the F<blib/conf/> directory will get
296 See also L<"Adding new file types to the build process"> for how to
297 create the stuff in F<blib/conf/> in the first place.
300 =head1 EXAMPLES ON CPAN
302 Several distributions on CPAN are making good use of various features
303 of Module::Build. They can serve as real-world examples for others.
306 =head2 SVN-Notify-Mirror
308 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
310 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
314 =item 1. Using C<auto_features>, I check to see whether two optional
315 modules are available - SVN::Notify::Config and Net::SSH;
317 =item 2. If the S::N::Config module is loaded, I automatically
318 generate testfiles for it during Build (using the C<PL_files>
321 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
322 to perform the ssh tests (since it requires a little preliminary
325 =item 4. Only if the user has C<ssh_feature> and answers yes to the
326 testing, do I generate a test file.
328 I'm sure I could not have handled this complexity with EU::MM, but it
329 was very easy to do with M::B.
334 =head2 Modifying an action
336 Sometimes you might need an to have an action, say C<./Build install>,
337 do something unusual. For instance, you might need to change the
338 ownership of a file or do something else peculiar to your application.
340 You can subclass C<Module::Build> on the fly using the C<subclass()>
341 method and override the methods that perform the actions. You may need
342 to read through C<Module::Build::Authoring> to find the methods you
343 want to override, but the general pattern is C<ACTION_> followed by
344 the name of the action you want to modify. Here's an example of how
345 it would work for C<install>:
349 my $class = Module::Build->subclass(
350 class => "Module::Build::Custom",
351 code => <<'SUBCLASS' );
356 $self->SUPER::ACTION_install;
361 module_name => 'Your::Module',
362 # rest of the usual Module::Build parameters
363 )->create_build_script;
365 See the L<Module::Build::Authoring> pod in 0.27 or above for more
366 complete documentation on this.
371 Ken Williams <ken@cpan.org>
376 Copyright (c) 2001-2005 Ken Williams. All rights reserved.
378 This library is free software; you can redistribute it and/or
379 modify it under the same terms as Perl itself.
384 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
385 L<Module::Build::API>(3)