Upgrade to Module-Build-0.2801.
[p5sagit/p5-mst-13.2.git] / lib / Module / Build / Cookbook.pm
1 package Module::Build::Cookbook;
2
3
4 =head1 NAME
5
6 Module::Build::Cookbook - Examples of Module::Build Usage
7
8
9 =head1 DESCRIPTION
10
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,
15 "Write A Cookbook."
16
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.
19
20
21 =head1 BASIC RECIPES
22
23
24 =head2 The basic installation recipe for modules that use Module::Build
25
26 In most cases, you can just issue the following commands:
27
28   perl Build.PL
29   ./Build
30   ./Build test
31   ./Build install
32
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.
36
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
40 directories like so:
41
42   /usr/bin/perl5.8.1 Build.PL
43   ./Build
44   ./Build test
45   ./Build install
46
47 If you're on Windows where the current directory is always searched
48 first for scripts, you'll probably do something like this:
49
50   perl Build.PL
51   Build
52   Build test
53   Build install
54
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.
59
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.
64
65
66 =head2 Making a CPAN.pm-compatible distribution
67
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:
71
72 Create a file in your distribution named F<Makefile.PL>, with the
73 following contents:
74
75   use Module::Build::Compat;
76   Module::Build::Compat->run_build_pl(args => \@ARGV);
77   Module::Build::Compat->write_makefile();
78
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.
82
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.
89
90
91 =head2 Installing modules using the programmatic interface
92
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
98 actions.
99
100   my $build = Module::Build->new
101     (
102      module_name => 'Foo::Bar',
103      license     => 'perl',
104      requires    => { 'Some::Module'   => '1.23' },
105     );
106   $build->dispatch('build');
107   $build->dispatch('test', verbose => 1);
108   $build->dispatch('install');
109
110 The first argument to C<dispatch()> is the name of the action, and any
111 following arguments are named parameters.
112
113 This is the interface we use to test Module::Build itself in the
114 regression tests.
115
116
117 =head2 Installing to a temporary directory
118
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:
123
124   ./Build install --destdir /tmp/my-package-1.003
125
126 This essentially just prepends all the installation paths with the
127 F</tmp/my-package-1.003> directory.
128
129
130 =head2 Installing to a non-standard directory
131
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>:
135
136   ./Build install --install_base /foo/bar
137
138 See L<Module::Build/"INSTALL PATHS"> for a much more complete
139 discussion of how installation paths are determined.
140
141
142 =head2 Installing in the same location as ExtUtils::MakeMaker
143
144 With the introduction of C<--prefix> in Module::Build 0.28 and
145 C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both
146 to install to the same locations.
147
148 First, ensure you have at least version 0.28 of Module::Build
149 installed and 6.31 of ExtUtils::MakeMaker.  Prior versions have
150 differing installation behaviors.
151
152 The following installation flags are equivalent between
153 ExtUtils::MakeMaker and Module::Build.
154
155     MakeMaker             Module::Build
156     PREFIX=...            --prefix ...
157     INSTALL_BASE=...      --install_base ...
158     DESTDIR=...           --destdir ...
159     LIB=...               --install_path lib=...
160     INSTALLDIRS=...       --installdirs ...
161     INSTALLDIRS=perl      --installdirs core
162     UNINST=...            --uninst ...
163     INC=...               --extra_compiler_flags ...
164     POLLUTE=1             --extra_compiler_flags -DPERL_POLLUTE
165
166 For example, if you are currently installing MakeMaker modules with
167 this command:
168
169     perl Makefile.PL PREFIX=~
170     make test
171     make install UNINST=1
172
173 You can install into the same location with Module::Build using this:
174
175     perl Build.PL --prefix ~
176     ./Build test
177     ./Build install --uninst 1
178
179 =head3 C<prefix> vs C<install_base>
180
181 The behavior of C<prefix> is complicated and depends closely on
182 how your Perl is configured.  The resulting installation locations
183 will vary from machine to machine and even different installations of
184 Perl on the same machine.  Because of this, its difficult to document
185 where C<prefix> will place your modules.
186
187 In contrast, C<install_base> has predictable, easy to explain
188 installation locations.  Now that Module::Build and MakeMaker both
189 have C<install_base> there is little reason to use C<prefix> other
190 than to preserve your existing installation locations.  If you are
191 starting a fresh Perl installation we encourage you to use
192 C<install_base>.  If you have an existing installation installed via
193 C<prefix>, consider moving it to an installation structure matching
194 C<install_base> and using that instead.
195
196
197 =head2 Running a single test file
198
199 C<Module::Build> supports running a single test, which enables you to
200 track down errors more quickly.  Use the following format:
201
202   ./Build test --test_files t/mytest.t
203
204 In addition, you may want to run the test in verbose mode to get more
205 informative output:
206
207   ./Build test --test_files t/mytest.t --verbose 1
208
209 I run this so frequently that I actually define the following shell alias:
210
211   alias t './Build test --verbose 1 --test_files'
212
213 So then I can just execute C<t t/mytest.t> to run a single test.
214
215
216 =head1 ADVANCED RECIPES
217
218
219 =head2 Changing the order of the build process
220
221 The C<build_elements> property specifies the steps C<Module::Build>
222 will take when building a distribution.  To change the build order,
223 change the order of the entries in that property:
224
225   # Process pod files first
226   my @e = @{$build->build_elements};
227   my $i = grep {$e[$_] eq 'pod'} 0..$#e;
228   unshift @e, splice @e, $i, 1;
229
230 Currently, C<build_elements> has the following default value:
231
232   [qw( PL support pm xs pod script )]
233
234 Do take care when altering this property, since there may be
235 non-obvious (and non-documented!) ordering dependencies in the
236 C<Module::Build> code.
237
238
239 =head2 Adding new file types to the build process
240
241 Sometimes you might have extra types of files that you want to install
242 alongside the standard types like F<.pm> and F<.pod> files.  For
243 instance, you might have a F<Bar.dat> file containing some data
244 related to the C<Foo::Bar> module.  Assuming the data doesn't need to
245 be created on the fly, the best place for it to end up is probably as
246 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
247 access it easily at runtime.  The following code from a sample
248 C<Build.PL> file demonstrates how to accomplish this:
249
250   use Module::Build;
251   my $build = Module::Build->new
252     (
253      module_name => 'Foo::Bar',
254      ...other stuff here...
255     );
256   $build->add_build_element('dat');
257   $build->create_build_script;
258
259 This will find all F<.dat> files in the F<lib/> directory, copy them
260 to the F<blib/lib/> directory during the C<build> action, and install
261 them during the C<install> action.
262
263 If your extra files aren't in the C<lib/> directory, you can
264 explicitly say where they are, just as you'd do with F<.pm> or F<.pod>
265 files:
266
267   use Module::Build;
268   my $build = new Module::Build
269     (
270      module_name => 'Foo::Bar',
271      dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
272      ...other stuff here...
273     );
274   $build->add_build_element('dat');
275   $build->create_build_script;
276
277 If your extra files actually need to be created on the user's machine,
278 or if they need some other kind of special processing, you'll probably
279 want to create a special method to do so, named
280 C<process_${kind}_files()>:
281
282   use Module::Build;
283   my $class = Module::Build->subclass(code => <<'EOF');
284     sub process_dat_files {
285       my $self = shift;
286       ... locate and process *.dat files,
287       ... and create something in blib/lib/
288     }
289   EOF
290   my $build = $class->new
291     (
292      module_name => 'Foo::Bar',
293      ...other stuff here...
294     );
295   $build->add_build_element('dat');
296   $build->create_build_script;
297
298 If your extra files don't go in F<lib/> but in some other place, see
299 L<"Adding new elements to the install process"> for how to actually
300 get them installed.
301
302 Please note that these examples use some capabilities of Module::Build
303 that first appeared in version 0.26.  Before that it could certainly
304 still be done, but the simple cases took a bit more work.
305
306
307 =head2 Adding new elements to the install process
308
309 By default, Module::Build creates seven subdirectories of the F<blib/>
310 directory during the build process: F<lib/>, F<arch/>, F<bin/>,
311 F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be
312 missing or empty if there's nothing to go in them).  Anything copied
313 to these directories during the build will eventually be installed
314 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
315
316 If you need to create a new type of installable element, e.g. C<conf>,
317 then you need to tell Module::Build where things in F<blib/conf/>
318 should be installed.  To do this, use the C<install_path> parameter to
319 the C<new()> method:
320
321   my $build = Module::Build->new
322     (
323      ...other stuff here...
324      install_path => { conf => $installation_path }
325     );
326
327 Or you can call the C<install_path()> method later:
328
329   $build->install_path->{conf} || $installation_path;
330
331 (Sneakily, or perhaps uglily, C<install_path()> returns a reference to
332 a hash of install paths, and you can modify that hash to your heart's
333 content.)
334
335 The user may also specify the path on the command line:
336
337   perl Build.PL --install_path conf=/foo/path/etc
338
339 The important part, though, is that I<somehow> the install path needs
340 to be set, or else nothing in the F<blib/conf/> directory will get
341 installed.
342
343 See also L<"Adding new file types to the build process"> for how to
344 create the stuff in F<blib/conf/> in the first place.
345
346
347 =head1 EXAMPLES ON CPAN
348
349 Several distributions on CPAN are making good use of various features
350 of Module::Build.  They can serve as real-world examples for others.
351
352
353 =head2 SVN-Notify-Mirror
354
355 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
356
357 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
358
359 =over 4
360
361 =item 1. Using C<auto_features>, I check to see whether two optional
362 modules are available - SVN::Notify::Config and Net::SSH;
363
364 =item 2. If the S::N::Config module is loaded, I automatically
365 generate testfiles for it during Build (using the C<PL_files>
366 property).
367
368 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
369 to perform the ssh tests (since it requires a little preliminary
370 setup);
371
372 =item 4. Only if the user has C<ssh_feature> and answers yes to the
373 testing, do I generate a test file.
374
375 I'm sure I could not have handled this complexity with EU::MM, but it
376 was very easy to do with M::B.
377
378 =back 4
379
380
381 =head2 Modifying an action
382
383 Sometimes you might need an to have an action, say C<./Build install>,
384 do something unusual.  For instance, you might need to change the
385 ownership of a file or do something else peculiar to your application.
386
387 You can subclass C<Module::Build> on the fly using the C<subclass()>
388 method and override the methods that perform the actions. You may need
389 to read through C<Module::Build::Authoring> to find the methods you
390 want to override, but the general pattern is C<ACTION_> followed by
391 the name of the action you want to modify.  Here's an example of how
392 it would work for C<install>:
393
394   # Build.PL
395   use Module::Build;
396   my $class = Module::Build->subclass(
397       class => "Module::Build::Custom",
398       code => <<'SUBCLASS' );
399
400   sub ACTION_install {
401       my $self = shift;
402       # YOUR CODE HERE
403       $self->SUPER::ACTION_install;
404   }
405   SUBCLASS
406
407   $class->new(
408       module_name => 'Your::Module',
409       # rest of the usual Module::Build parameters
410   )->create_build_script;
411
412 See the L<Module::Build::Authoring> pod in 0.27 or above for more
413 complete documentation on this.
414
415
416 =head1 AUTHOR
417
418 Ken Williams <ken@cpan.org>
419
420
421 =head1 COPYRIGHT
422
423 Copyright (c) 2001-2005 Ken Williams.  All rights reserved.
424
425 This library is free software; you can redistribute it and/or
426 modify it under the same terms as Perl itself.
427
428
429 =head1 SEE ALSO
430
431 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
432 L<Module::Build::API>(3)
433
434 =cut