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. The following recipes should help developers and/or
13 installers put together the pieces from the other parts of the
20 =head2 Installing modules that use Module::Build
22 In most cases, you can just issue the following commands:
29 There's nothing complicated here - first you're running a script
30 called F<Build.PL>, then you're running a (newly-generated) script
31 called F<Build> and passing it various arguments.
33 The exact commands may vary a bit depending on how you invoke perl
34 scripts on your system. For instance, if you have multiple versions
35 of perl installed, you can install to one particular perl's library
38 /usr/bin/perl5.8.1 Build.PL
43 If you're on Windows where the current directory is always searched
44 first for scripts, you'll probably do something like this:
51 On the old Mac OS (version 9 or lower) using MacPerl, you can
52 double-click on the F<Build.PL> script to create the F<Build> script,
53 then double-click on the F<Build> script to run its C<build>, C<test>,
54 and C<install> actions.
56 The F<Build> script knows what perl was used to run F<Build.PL>, so
57 you don't need to re-invoke the F<Build> script with the complete perl
58 path each time. If you invoke it with the I<wrong> perl path, you'll
59 get a warning or a fatal error.
61 =head2 Modifying Config.pm values
63 C<Module::Build> relies heavily on various values from perl's
64 C<Config.pm> to do its work. For example, default installation paths
65 are given by C<installsitelib> and C<installvendorman3dir> and
66 friends, C linker & compiler settings are given by C<ld>,
67 C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure
68 you know what you're doing>, you can tell C<Module::Build> to pretend
69 there are different values in F<Config.pm> than what's really there,
70 by passing arguments for the C<--config> parameter on the command
73 perl Build.PL --config cc=gcc --config ld=gcc
75 Inside the C<Build.PL> script the same thing can be accomplished by
76 passing values for the C<config> parameter to C<new()>:
78 my $build = Module::Build->new
81 config => { cc => 'gcc', ld => 'gcc' },
85 In custom build code, the same thing can be accomplished by calling
86 the L<Module::Build/config> method:
88 $build->config( cc => 'gcc' ); # Set
89 $build->config( ld => 'gcc' ); # Set
91 my $linker = $build->config('ld'); # Get
94 =head2 Installing modules using the programmatic interface
96 If you need to build, test, and/or install modules from within some
97 other perl code (as opposed to having the user type installation
98 commands at the shell), you can use the programmatic interface.
99 Create a Module::Build object (or an object of a custom Module::Build
100 subclass) and then invoke its C<dispatch()> method to run various
103 my $build = Module::Build->new
105 module_name => 'Foo::Bar',
107 requires => { 'Some::Module' => '1.23' },
109 $build->dispatch('build');
110 $build->dispatch('test', verbose => 1);
111 $build->dispatch('install');
113 The first argument to C<dispatch()> is the name of the action, and any
114 following arguments are named parameters.
116 This is the interface we use to test Module::Build itself in the
120 =head2 Installing to a temporary directory
122 To create packages for package managers like RedHat's C<rpm> or
123 Debian's C<deb>, you may need to install to a temporary directory
124 first and then create the package from that temporary installation.
125 To do this, specify the C<destdir> parameter to the C<install> action:
127 ./Build install --destdir /tmp/my-package-1.003
129 This essentially just prepends all the installation paths with the
130 F</tmp/my-package-1.003> directory.
133 =head2 Installing to a non-standard directory
135 To install to a non-standard directory (for example, if you don't have
136 permission to install in the system-wide directories), you can use the
137 C<install_base> or C<prefix> parameters:
139 ./Build install --install_base /foo/bar
141 See L<Module::Build/"INSTALL PATHS"> for a much more complete
142 discussion of how installation paths are determined.
145 =head2 Installing in the same location as ExtUtils::MakeMaker
147 With the introduction of C<--prefix> in Module::Build 0.28 and
148 C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both
149 to install to the same locations.
151 First, ensure you have at least version 0.28 of Module::Build
152 installed and 6.31 of ExtUtils::MakeMaker. Prior versions have
153 differing (and in some cases quite strange) installation behaviors.
155 The following installation flags are equivalent between
156 ExtUtils::MakeMaker and Module::Build.
158 MakeMaker Module::Build
159 PREFIX=... --prefix ...
160 INSTALL_BASE=... --install_base ...
161 DESTDIR=... --destdir ...
162 LIB=... --install_path lib=...
163 INSTALLDIRS=... --installdirs ...
164 INSTALLDIRS=perl --installdirs core
165 UNINST=... --uninst ...
166 INC=... --extra_compiler_flags ...
167 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
169 For example, if you are currently installing MakeMaker modules with
172 perl Makefile.PL PREFIX=~
174 make install UNINST=1
176 You can install into the same location with Module::Build using this:
178 perl Build.PL --prefix ~
180 ./Build install --uninst 1
182 =head3 C<prefix> vs C<install_base>
184 The behavior of C<prefix> is complicated and depends on
185 how your Perl is configured. The resulting installation locations
186 will vary from machine to machine and even different installations of
187 Perl on the same machine. Because of this, it's difficult to document
188 where C<prefix> will place your modules.
190 In contrast, C<install_base> has predictable, easy to explain
191 installation locations. Now that Module::Build and MakeMaker both
192 have C<install_base> there is little reason to use C<prefix> other
193 than to preserve your existing installation locations. If you are
194 starting a fresh Perl installation we encourage you to use
195 C<install_base>. If you have an existing installation installed via
196 C<prefix>, consider moving it to an installation structure matching
197 C<install_base> and using that instead.
200 =head2 Running a single test file
202 C<Module::Build> supports running a single test, which enables you to
203 track down errors more quickly. Use the following format:
205 ./Build test --test_files t/mytest.t
207 In addition, you may want to run the test in verbose mode to get more
210 ./Build test --test_files t/mytest.t --verbose 1
212 I run this so frequently that I define the following shell alias:
214 alias t './Build test --verbose 1 --test_files'
216 So then I can just execute C<t t/mytest.t> to run a single test.
219 =head1 ADVANCED RECIPES
222 =head2 Making a CPAN.pm-compatible distribution
224 New versions of CPAN.pm understand how to use a F<Build.PL> script,
225 but old versions don't. If authors want to help users who have old
226 versions, some form of F<Makefile.PL> should be supplied. The easiest
227 way to accomplish this is to use the C<create_makefile_pl> parameter to
228 C<< Module::Build->new() >> in the C<Build.PL> script, which can
229 create various flavors of F<Makefile.PL> during the C<dist> action.
231 As a best practice, we recommend using the "traditional" style of
232 F<Makefile.PL> unless your distribution has needs that can't be
233 accomplished that way.
235 The C<Module::Build::Compat> module, which is part of
236 C<Module::Build>'s distribution, is responsible for creating these
237 F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details.
240 =head2 Changing the order of the build process
242 The C<build_elements> property specifies the steps C<Module::Build>
243 will take when building a distribution. To change the build order,
244 change the order of the entries in that property:
246 # Process pod files first
247 my @e = @{$build->build_elements};
248 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
249 unshift @e, splice @e, $i, 1;
251 Currently, C<build_elements> has the following default value:
253 [qw( PL support pm xs pod script )]
255 Do take care when altering this property, since there may be
256 non-obvious (and non-documented!) ordering dependencies in the
257 C<Module::Build> code.
260 =head2 Adding new file types to the build process
262 Sometimes you might have extra types of files that you want to install
263 alongside the standard types like F<.pm> and F<.pod> files. For
264 instance, you might have a F<Bar.dat> file containing some data
265 related to the C<Foo::Bar> module and you'd like for it to end up as
266 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
267 access it easily at runtime. The following code from a sample
268 C<Build.PL> file demonstrates how to accomplish this:
271 my $build = Module::Build->new
273 module_name => 'Foo::Bar',
274 ...other stuff here...
276 $build->add_build_element('dat');
277 $build->create_build_script;
279 This will find all F<.dat> files in the F<lib/> directory, copy them
280 to the F<blib/lib/> directory during the C<build> action, and install
281 them during the C<install> action.
283 If your extra files aren't located in the C<lib/> directory in your
284 distribution, you can explicitly say where they are, just as you'd do
285 with F<.pm> or F<.pod> files:
288 my $build = new Module::Build
290 module_name => 'Foo::Bar',
291 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
292 ...other stuff here...
294 $build->add_build_element('dat');
295 $build->create_build_script;
297 If your extra files actually need to be created on the user's machine,
298 or if they need some other kind of special processing, you'll probably
299 want to subclass C<Module::Build> and create a special method to
300 process them, named C<process_${kind}_files()>:
303 my $class = Module::Build->subclass(code => <<'EOF');
304 sub process_dat_files {
306 ... locate and process *.dat files,
307 ... and create something in blib/lib/
310 my $build = $class->new
312 module_name => 'Foo::Bar',
313 ...other stuff here...
315 $build->add_build_element('dat');
316 $build->create_build_script;
318 If your extra files don't go in F<lib/> but in some other place, see
319 L<"Adding new elements to the install process"> for how to actually
322 Please note that these examples use some capabilities of Module::Build
323 that first appeared in version 0.26. Before that it could
324 still be done, but the simple cases took a bit more work.
327 =head2 Adding new elements to the install process
329 By default, Module::Build creates seven subdirectories of the F<blib>
330 directory during the build process: F<lib>, F<arch>, F<bin>,
331 F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
332 missing or empty if there's nothing to go in them). Anything copied
333 to these directories during the build will eventually be installed
334 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
336 If you need to create a new custom type of installable element, e.g. C<conf>,
337 then you need to tell Module::Build where things in F<blib/conf/>
338 should be installed. To do this, use the C<install_path> parameter to
341 my $build = Module::Build->new
343 ...other stuff here...
344 install_path => { conf => $installation_path }
347 Or you can call the C<install_path()> method later:
349 $build->install_path(conf => $installation_path);
351 The user may also specify the path on the command line:
353 perl Build.PL --install_path conf=/foo/path/etc
355 The important part, though, is that I<somehow> the install path needs
356 to be set, or else nothing in the F<blib/conf/> directory will get
357 installed, and a runtime error during the C<install> action will
360 See also L<"Adding new file types to the build process"> for how to
361 create the stuff in F<blib/conf/> in the first place.
364 =head1 EXAMPLES ON CPAN
366 Several distributions on CPAN are making good use of various features
367 of Module::Build. They can serve as real-world examples for others.
370 =head2 SVN-Notify-Mirror
372 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
374 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
378 =item 1. Using C<auto_features>, I check to see whether two optional
379 modules are available - SVN::Notify::Config and Net::SSH;
381 =item 2. If the S::N::Config module is loaded, I automatically
382 generate testfiles for it during Build (using the C<PL_files>
385 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
386 to perform the ssh tests (since it requires a little preliminary
389 =item 4. Only if the user has C<ssh_feature> and answers yes to the
390 testing, do I generate a test file.
392 I'm sure I could not have handled this complexity with EU::MM, but it
393 was very easy to do with M::B.
398 =head2 Modifying an action
400 Sometimes you might need an to have an action, say C<./Build install>,
401 do something unusual. For instance, you might need to change the
402 ownership of a file or do something else peculiar to your application.
404 You can subclass C<Module::Build> on the fly using the C<subclass()>
405 method and override the methods that perform the actions. You may
406 need to read through C<Module::Build::Authoring> and
407 C<Module::Build::API> to find the methods you want to override. All
408 "action" methods are implemented by a method called "ACTION_" followed
409 by the action's name, so here's an example of how it would work for
410 the C<install> action:
414 my $class = Module::Build->subclass(
415 class => "Module::Build::Custom",
416 code => <<'SUBCLASS' );
421 $self->SUPER::ACTION_install;
426 module_name => 'Your::Module',
427 # rest of the usual Module::Build parameters
428 )->create_build_script;
433 Ken Williams <kwilliams@cpan.org>
438 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
440 This library is free software; you can redistribute it and/or
441 modify it under the same terms as Perl itself.
446 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
447 L<Module::Build::API>(3)