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.
129 =head2 Installing to a non-standard directory
131 To install to a non-standard directory (for example, if you don't have
132 permission to install in the system-wide directories), you can use the
133 C<install_base> or C<prefix> parameters:
135 ./Build install --install_base /foo/bar
137 ./Build install --prefix /foo/bar
139 Note that these have somewhat different effects - C<prefix> is an
140 emulation of C<ExtUtils::MakeMaker>'s old C<PREFIX> setting, and
141 inherits all its nasty gotchas. C<install_base> is more predictable,
142 and newer versions of C<ExtUtils::MakeMaker> also support it, so it's
143 often your best choice.
145 See L<Module::Build/"INSTALL PATHS"> for a much more complete
146 discussion of how installation paths are determined.
148 =head2 Running a single test file
150 C<Module::Builde> supports running a single test, which enables you to
151 track down errors more quickly. Use the following format:
153 ./Build test --test_files t/mytest.t
155 In addition, you may want to run the test in verbose mode to get more
158 ./Build test --test_files t/mytest.t --verbose 1
160 I run this so frequently that I actually define the following shell alias:
162 alias t './Build test --verbose 1 --test_files'
164 So then I can just execute C<t t/mytest.t> to run a single test.
167 =head1 ADVANCED RECIPES
170 =head2 Changing the order of the build process
172 The C<build_elements> property specifies the steps C<Module::Build>
173 will take when building a distribution. To change the build order,
174 change the order of the entries in that property:
176 # Process pod files first
177 my @e = @{$build->build_elements};
178 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
179 unshift @e, splice @e, $i, 1;
181 Currently, C<build_elements> has the following default value:
183 [qw( PL support pm xs pod script )]
185 Do take care when altering this property, since there may be
186 non-obvious (and non-documented!) ordering dependencies in the
187 C<Module::Build> code.
190 =head2 Adding new file types to the build process
192 Sometimes you might have extra types of files that you want to install
193 alongside the standard types like F<.pm> and F<.pod> files. For
194 instance, you might have a F<Bar.dat> file containing some data
195 related to the C<Foo::Bar> module. Assuming the data doesn't need to
196 be created on the fly, the best place for it to end up is probably as
197 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
198 access it easily at runtime. The following code from a sample
199 C<Build.PL> file demonstrates how to accomplish this:
202 my $build = Module::Build->new
204 module_name => 'Foo::Bar',
205 ...other stuff here...
207 $build->add_build_element('dat');
208 $build->create_build_script;
210 This will find all F<.dat> files in the F<lib/> directory, copy them
211 to the F<blib/lib/> directory during the C<build> action, and install
212 them during the C<install> action.
214 If your extra files aren't in the C<lib/> directory, you can
215 explicitly say where they are, just as you'd do with F<.pm> or F<.pod>
219 my $build = new Module::Build
221 module_name => 'Foo::Bar',
222 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
223 ...other stuff here...
225 $build->add_build_element('dat');
226 $build->create_build_script;
228 If your extra files actually need to be created on the user's machine,
229 or if they need some other kind of special processing, you'll probably
230 want to create a special method to do so, named
231 C<process_${kind}_files()>:
234 my $class = Module::Build->subclass(code => <<'EOF');
235 sub process_dat_files {
237 ... locate and process *.dat files,
238 ... and create something in blib/lib/
241 my $build = $class->new
243 module_name => 'Foo::Bar',
244 ...other stuff here...
246 $build->add_build_element('dat');
247 $build->create_build_script;
249 If your extra files don't go in F<lib/> but in some other place, see
250 L<"Adding new elements to the install process"> for how to actually
253 Please note that these examples use some capabilities of Module::Build
254 that first appeared in version 0.26. Before that it could certainly
255 still be done, but the simple cases took a bit more work.
258 =head2 Adding new elements to the install process
260 By default, Module::Build creates seven subdirectories of the F<blib/>
261 directory during the build process: F<lib/>, F<arch/>, F<bin/>,
262 F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be
263 missing or empty if there's nothing to go in them). Anything copied
264 to these directories during the build will eventually be installed
265 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
267 If you need to create a new type of installable element, e.g. C<conf>,
268 then you need to tell Module::Build where things in F<blib/conf/>
269 should be installed. To do this, use the C<install_path> parameter to
272 my $build = Module::Build->new
274 ...other stuff here...
275 install_path => { conf => $installation_path }
278 Or you can call the C<install_path()> method later:
280 $build->install_path->{conf} || $installation_path;
282 (Sneakily, or perhaps uglily, C<install_path()> returns a reference to
283 a hash of install paths, and you can modify that hash to your heart's
286 The user may also specify the path on the command line:
288 perl Build.PL --install_path conf=/foo/path/etc
290 The important part, though, is that I<somehow> the install path needs
291 to be set, or else nothing in the F<blib/conf/> directory will get
294 See also L<"Adding new file types to the build process"> for how to
295 create the stuff in F<blib/conf/> in the first place.
298 =head1 EXAMPLES ON CPAN
300 Several distributions on CPAN are making good use of various features
301 of Module::Build. They can serve as real-world examples for others.
304 =head2 SVN-Notify-Mirror
306 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
308 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
312 =item 1. Using C<auto_features>, I check to see whether two optional
313 modules are available - SVN::Notify::Config and Net::SSH;
315 =item 2. If the S::N::Config module is loaded, I automatically
316 generate testfiles for it during Build (using the C<PL_files>
319 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
320 to perform the ssh tests (since it requires a little preliminary
323 =item 4. Only if the user has C<ssh_feature> and answers yes to the
324 testing, do I generate a test file.
326 I'm sure I could not have handled this complexity with EU::MM, but it
327 was very easy to do with M::B.
334 Ken Williams <ken@cpan.org>
339 Copyright (c) 2001-2005 Ken Williams. All rights reserved.
341 This library is free software; you can redistribute it and/or
342 modify it under the same terms as Perl itself.
347 perl(1), Module::Build(3)