This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Emergency fix for /tmp dir cleanup's for smokers.
[perl5.git] / lib / Module / Build / Cookbook.pm
CommitLineData
bb4e9162
YST
1package Module::Build::Cookbook;
2
3
4=head1 NAME
5
6Module::Build::Cookbook - Examples of Module::Build Usage
7
8
9=head1 DESCRIPTION
10
11C<Module::Build> isn't conceptually very complicated, but examples are
12always helpful. I got the idea for writing this cookbook when
13attending Brian Ingerson's "Extreme Programming Tools for Module
14Authors" presentation at YAPC 2003, when he said, straightforwardly,
15"Write A Cookbook."
16
17The definitional of how stuff works is in the main C<Module::Build>
18documentation. 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
26In most cases, you can just issue the following commands:
27
28 perl Build.PL
29 ./Build
30 ./Build test
31 ./Build install
32
33There's nothing complicated here - first you're running a script
34called F<Build.PL>, then you're running a (newly-generated) script
35called F<Build> and passing it various arguments.
36
37The exact commands may vary a bit depending on how you invoke perl
38scripts on your system. For instance, if you have multiple versions
39of perl installed, you can install to one particular perl's library
40directories like so:
41
42 /usr/bin/perl5.8.1 Build.PL
43 ./Build
44 ./Build test
45 ./Build install
46
47If you're on Windows where the current directory is always searched
48first for scripts, you'll probably do something like this:
49
50 perl Build.PL
51 Build
52 Build test
53 Build install
54
55On the old Mac OS (version 9 or lower) using MacPerl, you can
56double-click on the F<Build.PL> script to create the F<Build> script,
57then double-click on the F<Build> script to run its C<build>, C<test>,
58and C<install> actions.
59
60The F<Build> script knows what perl was used to run C<Build.PL>, so
61you don't need to re-invoke the F<Build> script with the complete perl
62path each time. If you invoke it with the I<wrong> perl path, you'll
63get a warning or a fatal error.
64
65
66=head2 Making a CPAN.pm-compatible distribution
67
68New versions of CPAN.pm understand how to use a F<Build.PL> script,
69but old versions don't. If you want to help users who have old
70versions, do the following:
71
72Create a file in your distribution named F<Makefile.PL>, with the
73following contents:
74
75 use Module::Build::Compat;
76 Module::Build::Compat->run_build_pl(args => \@ARGV);
77 Module::Build::Compat->write_makefile();
78
79Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make
80test`, and `make install`, provided the end-user already has
81C<Module::Build> installed.
82
83If the end-user might not have C<Module::Build> installed, it's
84probably best to supply a "traditional" F<Makefile.PL>. The
85C<Module::Build::Compat> module has some very helpful tools for
86keeping a F<Makefile.PL> in sync with a F<Build.PL>. See its
87documentation, and also the C<create_makefile_pl> parameter to the
88C<< Module::Build->new() >> method.
89
90
91=head2 Installing modules using the programmatic interface
92
93If you need to build, test, and/or install modules from within some
94other perl code (as opposed to having the user type installation
95commands at the shell), you can use the programmatic interface.
96Create a Module::Build object (or an object of a custom Module::Build
97subclass) and then invoke its C<dispatch()> method to run various
98actions.
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
110The first argument to C<dispatch()> is the name of the action, and any
111following arguments are named parameters.
112
113This is the interface we use to test Module::Build itself in the
114regression tests.
115
116
117=head2 Installing to a temporary directory
118
119To create packages for package managers like RedHat's C<rpm> or
120Debian's C<deb>, you may need to install to a temporary directory
121first and then create the package from that temporary installation.
122To do this, specify the C<destdir> parameter to the C<install> action:
123
124 ./Build install --destdir /tmp/my-package-1.003
125
126This essentially just prepends all the installation paths with the
127F</tmp/my-package-1.003> directory.
128
dc8021d3 129
bb4e9162
YST
130=head2 Installing to a non-standard directory
131
132To install to a non-standard directory (for example, if you don't have
133permission to install in the system-wide directories), you can use the
f943a5bf 134C<install_base>:
bb4e9162
YST
135
136 ./Build install --install_base /foo/bar
bb4e9162
YST
137
138See L<Module::Build/"INSTALL PATHS"> for a much more complete
139discussion of how installation paths are determined.
140
dc8021d3 141
f943a5bf
SP
142=head2 Installing in the same location as ExtUtils::MakeMaker
143
144With the introduction of C<--prefix> in Module::Build 0.28 and
145C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both
146to install to the same locations.
147
148First, ensure you have at least version 0.28 of Module::Build
149installed and 6.31 of ExtUtils::MakeMaker. Prior versions have
150differing installation behaviors.
151
152The following installation flags are equivalent between
153ExtUtils::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
166For example, if you are currently installing MakeMaker modules with
167this command:
168
169 perl Makefile.PL PREFIX=~
170 make test
171 make install UNINST=1
172
173You 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
181The behavior of C<prefix> is complicated and depends closely on
182how your Perl is configured. The resulting installation locations
183will vary from machine to machine and even different installations of
184Perl on the same machine. Because of this, its difficult to document
185where C<prefix> will place your modules.
186
187In contrast, C<install_base> has predictable, easy to explain
188installation locations. Now that Module::Build and MakeMaker both
189have C<install_base> there is little reason to use C<prefix> other
190than to preserve your existing installation locations. If you are
191starting a fresh Perl installation we encourage you to use
192C<install_base>. If you have an existing installation installed via
193C<prefix>, consider moving it to an installation structure matching
194C<install_base> and using that instead.
195
196
bb4e9162
YST
197=head2 Running a single test file
198
dc8021d3 199C<Module::Build> supports running a single test, which enables you to
bb4e9162
YST
200track down errors more quickly. Use the following format:
201
202 ./Build test --test_files t/mytest.t
203
204In addition, you may want to run the test in verbose mode to get more
205informative output:
206
207 ./Build test --test_files t/mytest.t --verbose 1
208
209I run this so frequently that I actually define the following shell alias:
210
211 alias t './Build test --verbose 1 --test_files'
212
213So 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
221The C<build_elements> property specifies the steps C<Module::Build>
222will take when building a distribution. To change the build order,
223change 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
230Currently, C<build_elements> has the following default value:
231
232 [qw( PL support pm xs pod script )]
233
234Do take care when altering this property, since there may be
235non-obvious (and non-documented!) ordering dependencies in the
236C<Module::Build> code.
237
238
239=head2 Adding new file types to the build process
240
241Sometimes you might have extra types of files that you want to install
242alongside the standard types like F<.pm> and F<.pod> files. For
243instance, you might have a F<Bar.dat> file containing some data
244related to the C<Foo::Bar> module. Assuming the data doesn't need to
245be created on the fly, the best place for it to end up is probably as
246F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
247access it easily at runtime. The following code from a sample
248C<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
259This will find all F<.dat> files in the F<lib/> directory, copy them
260to the F<blib/lib/> directory during the C<build> action, and install
261them during the C<install> action.
262
263If your extra files aren't in the C<lib/> directory, you can
264explicitly say where they are, just as you'd do with F<.pm> or F<.pod>
265files:
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
277If your extra files actually need to be created on the user's machine,
278or if they need some other kind of special processing, you'll probably
279want to create a special method to do so, named
280C<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
298If your extra files don't go in F<lib/> but in some other place, see
299L<"Adding new elements to the install process"> for how to actually
300get them installed.
301
302Please note that these examples use some capabilities of Module::Build
303that first appeared in version 0.26. Before that it could certainly
304still be done, but the simple cases took a bit more work.
305
306
307=head2 Adding new elements to the install process
308
309By default, Module::Build creates seven subdirectories of the F<blib/>
310directory during the build process: F<lib/>, F<arch/>, F<bin/>,
311F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be
312missing or empty if there's nothing to go in them). Anything copied
313to these directories during the build will eventually be installed
314during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
315
316If you need to create a new type of installable element, e.g. C<conf>,
317then you need to tell Module::Build where things in F<blib/conf/>
318should be installed. To do this, use the C<install_path> parameter to
319the C<new()> method:
320
321 my $build = Module::Build->new
322 (
323 ...other stuff here...
324 install_path => { conf => $installation_path }
325 );
326
327Or 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
332a hash of install paths, and you can modify that hash to your heart's
333content.)
334
335The user may also specify the path on the command line:
336
337 perl Build.PL --install_path conf=/foo/path/etc
338
339The important part, though, is that I<somehow> the install path needs
340to be set, or else nothing in the F<blib/conf/> directory will get
341installed.
342
343See also L<"Adding new file types to the build process"> for how to
344create the stuff in F<blib/conf/> in the first place.
345
346
347=head1 EXAMPLES ON CPAN
348
349Several distributions on CPAN are making good use of various features
350of Module::Build. They can serve as real-world examples for others.
351
352
353=head2 SVN-Notify-Mirror
354
355L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
356
357John 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
362modules are available - SVN::Notify::Config and Net::SSH;
363
364=item 2. If the S::N::Config module is loaded, I automatically
365generate testfiles for it during Build (using the C<PL_files>
366property).
367
368=item 3. If the C<ssh_feature> is available, I ask if the user wishes
369to perform the ssh tests (since it requires a little preliminary
370setup);
371
372=item 4. Only if the user has C<ssh_feature> and answers yes to the
373testing, do I generate a test file.
374
375I'm sure I could not have handled this complexity with EU::MM, but it
376was very easy to do with M::B.
377
378=back 4
379
380
47f13fd5
SP
381=head2 Modifying an action
382
383Sometimes you might need an to have an action, say C<./Build install>,
384do something unusual. For instance, you might need to change the
385ownership of a file or do something else peculiar to your application.
386
387You can subclass C<Module::Build> on the fly using the C<subclass()>
388method and override the methods that perform the actions. You may need
389to read through C<Module::Build::Authoring> to find the methods you
390want to override, but the general pattern is C<ACTION_> followed by
391the name of the action you want to modify. Here's an example of how
392it 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' );
dc8021d3 399
47f13fd5
SP
400 sub ACTION_install {
401 my $self = shift;
402 # YOUR CODE HERE
403 $self->SUPER::ACTION_install;
404 }
405 SUBCLASS
dc8021d3 406
47f13fd5
SP
407 $class->new(
408 module_name => 'Your::Module',
409 # rest of the usual Module::Build parameters
410 )->create_build_script;
411
dc8021d3 412See the L<Module::Build::Authoring> pod in 0.27 or above for more
47f13fd5
SP
413complete documentation on this.
414
dc8021d3 415
bb4e9162
YST
416=head1 AUTHOR
417
77e96e88 418Ken Williams <kwilliams@cpan.org>
bb4e9162
YST
419
420
421=head1 COPYRIGHT
422
77e96e88 423Copyright (c) 2001-2006 Ken Williams. All rights reserved.
bb4e9162
YST
424
425This library is free software; you can redistribute it and/or
426modify it under the same terms as Perl itself.
427
428
429=head1 SEE ALSO
430
dc8021d3
SP
431perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
432L<Module::Build::API>(3)
bb4e9162
YST
433
434=cut