This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Module-Build to CPAN version 0.4201
[perl5.git] / cpan / Module-Build / lib / Module / Build / Cookbook.pm
CommitLineData
bb4e9162 1package Module::Build::Cookbook;
738349a8
SH
2use strict;
3use vars qw($VERSION);
d320cf40 4$VERSION = '0.4201';
bb4e9162
YST
5
6
7=head1 NAME
8
9Module::Build::Cookbook - Examples of Module::Build Usage
10
bb4e9162
YST
11=head1 DESCRIPTION
12
13C<Module::Build> isn't conceptually very complicated, but examples are
7a827510
RGS
14always helpful. The following recipes should help developers and/or
15installers put together the pieces from the other parts of the
16documentation.
bb4e9162
YST
17
18
19=head1 BASIC RECIPES
20
21
7a827510 22=head2 Installing modules that use Module::Build
bb4e9162
YST
23
24In most cases, you can just issue the following commands:
25
26 perl Build.PL
27 ./Build
28 ./Build test
29 ./Build install
30
31There's nothing complicated here - first you're running a script
32called F<Build.PL>, then you're running a (newly-generated) script
33called F<Build> and passing it various arguments.
34
35The exact commands may vary a bit depending on how you invoke perl
36scripts on your system. For instance, if you have multiple versions
37of perl installed, you can install to one particular perl's library
38directories like so:
39
40 /usr/bin/perl5.8.1 Build.PL
41 ./Build
42 ./Build test
43 ./Build install
44
45If you're on Windows where the current directory is always searched
46first for scripts, you'll probably do something like this:
47
48 perl Build.PL
49 Build
50 Build test
51 Build install
52
53On the old Mac OS (version 9 or lower) using MacPerl, you can
54double-click on the F<Build.PL> script to create the F<Build> script,
55then double-click on the F<Build> script to run its C<build>, C<test>,
56and C<install> actions.
57
7a827510 58The F<Build> script knows what perl was used to run F<Build.PL>, so
bb4e9162
YST
59you don't need to re-invoke the F<Build> script with the complete perl
60path each time. If you invoke it with the I<wrong> perl path, you'll
61get a warning or a fatal error.
62
7a827510 63=head2 Modifying Config.pm values
bb4e9162 64
7a827510
RGS
65C<Module::Build> relies heavily on various values from perl's
66C<Config.pm> to do its work. For example, default installation paths
67are given by C<installsitelib> and C<installvendorman3dir> and
68friends, C linker & compiler settings are given by C<ld>,
69C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure
70you know what you're doing>, you can tell C<Module::Build> to pretend
71there are different values in F<Config.pm> than what's really there,
72by passing arguments for the C<--config> parameter on the command
73line:
bb4e9162 74
7a827510 75 perl Build.PL --config cc=gcc --config ld=gcc
bb4e9162 76
7a827510
RGS
77Inside the C<Build.PL> script the same thing can be accomplished by
78passing values for the C<config> parameter to C<new()>:
bb4e9162 79
7a827510
RGS
80 my $build = Module::Build->new
81 (
82 ...
83 config => { cc => 'gcc', ld => 'gcc' },
84 ...
85 );
bb4e9162 86
7a827510
RGS
87In custom build code, the same thing can be accomplished by calling
88the L<Module::Build/config> method:
bb4e9162 89
7a827510
RGS
90 $build->config( cc => 'gcc' ); # Set
91 $build->config( ld => 'gcc' ); # Set
92 ...
93 my $linker = $build->config('ld'); # Get
bb4e9162
YST
94
95
96=head2 Installing modules using the programmatic interface
97
98If you need to build, test, and/or install modules from within some
99other perl code (as opposed to having the user type installation
100commands at the shell), you can use the programmatic interface.
101Create a Module::Build object (or an object of a custom Module::Build
102subclass) and then invoke its C<dispatch()> method to run various
103actions.
104
105 my $build = Module::Build->new
106 (
107 module_name => 'Foo::Bar',
108 license => 'perl',
109 requires => { 'Some::Module' => '1.23' },
110 );
111 $build->dispatch('build');
112 $build->dispatch('test', verbose => 1);
113 $build->dispatch('install');
114
115The first argument to C<dispatch()> is the name of the action, and any
116following arguments are named parameters.
117
118This is the interface we use to test Module::Build itself in the
119regression tests.
120
121
122=head2 Installing to a temporary directory
123
124To create packages for package managers like RedHat's C<rpm> or
125Debian's C<deb>, you may need to install to a temporary directory
126first and then create the package from that temporary installation.
127To do this, specify the C<destdir> parameter to the C<install> action:
128
129 ./Build install --destdir /tmp/my-package-1.003
130
131This essentially just prepends all the installation paths with the
132F</tmp/my-package-1.003> directory.
133
dc8021d3 134
bb4e9162
YST
135=head2 Installing to a non-standard directory
136
137To install to a non-standard directory (for example, if you don't have
138permission to install in the system-wide directories), you can use the
7a827510 139C<install_base> or C<prefix> parameters:
bb4e9162
YST
140
141 ./Build install --install_base /foo/bar
bb4e9162
YST
142
143See L<Module::Build/"INSTALL PATHS"> for a much more complete
144discussion of how installation paths are determined.
145
dc8021d3 146
f943a5bf
SP
147=head2 Installing in the same location as ExtUtils::MakeMaker
148
149With the introduction of C<--prefix> in Module::Build 0.28 and
23837600 150C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both
f943a5bf
SP
151to install to the same locations.
152
153First, ensure you have at least version 0.28 of Module::Build
23837600 154installed and 6.31 of C<ExtUtils::MakeMaker>. Prior versions have
7a827510 155differing (and in some cases quite strange) installation behaviors.
f943a5bf
SP
156
157The following installation flags are equivalent between
23837600 158C<ExtUtils::MakeMaker> and C<Module::Build>.
f943a5bf
SP
159
160 MakeMaker Module::Build
161 PREFIX=... --prefix ...
162 INSTALL_BASE=... --install_base ...
163 DESTDIR=... --destdir ...
164 LIB=... --install_path lib=...
165 INSTALLDIRS=... --installdirs ...
166 INSTALLDIRS=perl --installdirs core
167 UNINST=... --uninst ...
168 INC=... --extra_compiler_flags ...
169 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
170
23837600 171For example, if you are currently installing C<MakeMaker> modules with
f943a5bf
SP
172this command:
173
174 perl Makefile.PL PREFIX=~
175 make test
176 make install UNINST=1
177
178You can install into the same location with Module::Build using this:
179
180 perl Build.PL --prefix ~
181 ./Build test
182 ./Build install --uninst 1
183
184=head3 C<prefix> vs C<install_base>
185
7a827510 186The behavior of C<prefix> is complicated and depends on
f943a5bf
SP
187how your Perl is configured. The resulting installation locations
188will vary from machine to machine and even different installations of
7a827510 189Perl on the same machine. Because of this, it's difficult to document
f943a5bf
SP
190where C<prefix> will place your modules.
191
192In contrast, C<install_base> has predictable, easy to explain
23837600 193installation locations. Now that C<Module::Build> and C<MakeMaker> both
f943a5bf
SP
194have C<install_base> there is little reason to use C<prefix> other
195than to preserve your existing installation locations. If you are
196starting a fresh Perl installation we encourage you to use
197C<install_base>. If you have an existing installation installed via
198C<prefix>, consider moving it to an installation structure matching
199C<install_base> and using that instead.
200
201
bb4e9162
YST
202=head2 Running a single test file
203
dc8021d3 204C<Module::Build> supports running a single test, which enables you to
bb4e9162
YST
205track down errors more quickly. Use the following format:
206
207 ./Build test --test_files t/mytest.t
208
209In addition, you may want to run the test in verbose mode to get more
210informative output:
211
212 ./Build test --test_files t/mytest.t --verbose 1
213
7a827510 214I run this so frequently that I define the following shell alias:
bb4e9162
YST
215
216 alias t './Build test --verbose 1 --test_files'
217
218So then I can just execute C<t t/mytest.t> to run a single test.
219
220
221=head1 ADVANCED RECIPES
222
223
7a827510
RGS
224=head2 Making a CPAN.pm-compatible distribution
225
226New versions of CPAN.pm understand how to use a F<Build.PL> script,
227but old versions don't. If authors want to help users who have old
228versions, some form of F<Makefile.PL> should be supplied. The easiest
229way to accomplish this is to use the C<create_makefile_pl> parameter to
230C<< Module::Build->new() >> in the C<Build.PL> script, which can
231create various flavors of F<Makefile.PL> during the C<dist> action.
232
233As a best practice, we recommend using the "traditional" style of
234F<Makefile.PL> unless your distribution has needs that can't be
235accomplished that way.
236
237The C<Module::Build::Compat> module, which is part of
238C<Module::Build>'s distribution, is responsible for creating these
239F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details.
240
241
bb4e9162
YST
242=head2 Changing the order of the build process
243
244The C<build_elements> property specifies the steps C<Module::Build>
245will take when building a distribution. To change the build order,
246change the order of the entries in that property:
247
248 # Process pod files first
249 my @e = @{$build->build_elements};
738349a8 250 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
bb4e9162
YST
251 unshift @e, splice @e, $i, 1;
252
253Currently, C<build_elements> has the following default value:
254
255 [qw( PL support pm xs pod script )]
256
257Do take care when altering this property, since there may be
258non-obvious (and non-documented!) ordering dependencies in the
259C<Module::Build> code.
260
261
262=head2 Adding new file types to the build process
263
264Sometimes you might have extra types of files that you want to install
265alongside the standard types like F<.pm> and F<.pod> files. For
266instance, you might have a F<Bar.dat> file containing some data
7a827510 267related to the C<Foo::Bar> module and you'd like for it to end up as
bb4e9162
YST
268F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
269access it easily at runtime. The following code from a sample
270C<Build.PL> file demonstrates how to accomplish this:
271
272 use Module::Build;
273 my $build = Module::Build->new
274 (
275 module_name => 'Foo::Bar',
276 ...other stuff here...
277 );
278 $build->add_build_element('dat');
279 $build->create_build_script;
280
281This will find all F<.dat> files in the F<lib/> directory, copy them
282to the F<blib/lib/> directory during the C<build> action, and install
283them during the C<install> action.
284
7a827510
RGS
285If your extra files aren't located in the C<lib/> directory in your
286distribution, you can explicitly say where they are, just as you'd do
287with F<.pm> or F<.pod> files:
bb4e9162
YST
288
289 use Module::Build;
290 my $build = new Module::Build
291 (
292 module_name => 'Foo::Bar',
293 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
294 ...other stuff here...
295 );
296 $build->add_build_element('dat');
297 $build->create_build_script;
298
299If your extra files actually need to be created on the user's machine,
300or if they need some other kind of special processing, you'll probably
7a827510
RGS
301want to subclass C<Module::Build> and create a special method to
302process them, named C<process_${kind}_files()>:
bb4e9162
YST
303
304 use Module::Build;
305 my $class = Module::Build->subclass(code => <<'EOF');
306 sub process_dat_files {
307 my $self = shift;
308 ... locate and process *.dat files,
309 ... and create something in blib/lib/
310 }
311 EOF
312 my $build = $class->new
313 (
314 module_name => 'Foo::Bar',
315 ...other stuff here...
316 );
317 $build->add_build_element('dat');
318 $build->create_build_script;
319
320If your extra files don't go in F<lib/> but in some other place, see
321L<"Adding new elements to the install process"> for how to actually
322get them installed.
323
324Please note that these examples use some capabilities of Module::Build
7a827510 325that first appeared in version 0.26. Before that it could
bb4e9162
YST
326still be done, but the simple cases took a bit more work.
327
328
329=head2 Adding new elements to the install process
330
7a827510
RGS
331By default, Module::Build creates seven subdirectories of the F<blib>
332directory during the build process: F<lib>, F<arch>, F<bin>,
333F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
bb4e9162
YST
334missing or empty if there's nothing to go in them). Anything copied
335to these directories during the build will eventually be installed
336during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
337
7a827510 338If you need to create a new custom type of installable element, e.g. C<conf>,
bb4e9162
YST
339then you need to tell Module::Build where things in F<blib/conf/>
340should be installed. To do this, use the C<install_path> parameter to
341the C<new()> method:
342
343 my $build = Module::Build->new
344 (
345 ...other stuff here...
346 install_path => { conf => $installation_path }
347 );
348
349Or you can call the C<install_path()> method later:
350
7a827510 351 $build->install_path(conf => $installation_path);
bb4e9162
YST
352
353The user may also specify the path on the command line:
354
355 perl Build.PL --install_path conf=/foo/path/etc
356
357The important part, though, is that I<somehow> the install path needs
358to be set, or else nothing in the F<blib/conf/> directory will get
7a827510
RGS
359installed, and a runtime error during the C<install> action will
360result.
bb4e9162
YST
361
362See also L<"Adding new file types to the build process"> for how to
363create the stuff in F<blib/conf/> in the first place.
364
365
366=head1 EXAMPLES ON CPAN
367
368Several distributions on CPAN are making good use of various features
369of Module::Build. They can serve as real-world examples for others.
370
371
372=head2 SVN-Notify-Mirror
373
374L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
375
376John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
377
378=over 4
379
380=item 1. Using C<auto_features>, I check to see whether two optional
381modules are available - SVN::Notify::Config and Net::SSH;
382
383=item 2. If the S::N::Config module is loaded, I automatically
23837600 384generate test files for it during Build (using the C<PL_files>
bb4e9162
YST
385property).
386
387=item 3. If the C<ssh_feature> is available, I ask if the user wishes
388to perform the ssh tests (since it requires a little preliminary
389setup);
390
391=item 4. Only if the user has C<ssh_feature> and answers yes to the
392testing, do I generate a test file.
393
394I'm sure I could not have handled this complexity with EU::MM, but it
395was very easy to do with M::B.
396
15cb7b9d 397=back
bb4e9162
YST
398
399
47f13fd5
SP
400=head2 Modifying an action
401
402Sometimes you might need an to have an action, say C<./Build install>,
403do something unusual. For instance, you might need to change the
404ownership of a file or do something else peculiar to your application.
405
406You can subclass C<Module::Build> on the fly using the C<subclass()>
7a827510
RGS
407method and override the methods that perform the actions. You may
408need to read through C<Module::Build::Authoring> and
409C<Module::Build::API> to find the methods you want to override. All
410"action" methods are implemented by a method called "ACTION_" followed
411by the action's name, so here's an example of how it would work for
412the C<install> action:
47f13fd5
SP
413
414 # Build.PL
415 use Module::Build;
416 my $class = Module::Build->subclass(
417 class => "Module::Build::Custom",
418 code => <<'SUBCLASS' );
dc8021d3 419
47f13fd5
SP
420 sub ACTION_install {
421 my $self = shift;
422 # YOUR CODE HERE
423 $self->SUPER::ACTION_install;
424 }
425 SUBCLASS
dc8021d3 426
47f13fd5
SP
427 $class->new(
428 module_name => 'Your::Module',
429 # rest of the usual Module::Build parameters
430 )->create_build_script;
431
dc8021d3 432
15cb7b9d
SH
433=head2 Adding an action
434
435You can add a new C<./Build> action simply by writing the method for
436it in your subclass. Use C<depends_on> to declare that another action
437must have been run before your action.
438
439For example, let's say you wanted to be able to write C<./Build
440commit> to test your code and commit it to Subversion.
441
442 # Build.PL
443 use Module::Build;
444 my $class = Module::Build->subclass(
445 class => "Module::Build::Custom",
446 code => <<'SUBCLASS' );
447
448 sub ACTION_commit {
449 my $self = shift;
450
451 $self->depends_on("test");
452 $self->do_system(qw(svn commit));
453 }
454 SUBCLASS
455
456
457=head2 Bundling Module::Build
458
459Note: This section probably needs an update as the technology improves
23837600 460(see contrib/bundle.pl in the distribution).
15cb7b9d
SH
461
462Suppose you want to use some new-ish features of Module::Build,
463e.g. newer than the version of Module::Build your users are likely to
464already have installed on their systems. The first thing you should
465do is set C<configure_requires> to your minimum version of
466Module::Build. See L<Module::Build::Authoring>.
467
468But not every build system honors C<configure_requires> yet. Here's
469how you can ship a copy of Module::Build, but still use a newer
470installed version to take advantage of any bug fixes and upgrades.
471
472First, install Module::Build into F<Your-Project/inc/Module-Build>.
473CPAN will not index anything in the F<inc> directory so this copy will
474not show up in CPAN searches.
475
476 cd Module-Build
477 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
478 ./Build test
479 ./Build install
480
481You should now have all the Module::Build .pm files in
482F<Your-Project/inc/Module-Build/lib/perl5>.
483
484Next, add this to the top of your F<Build.PL>.
485
486 my $Bundled_MB = 0.30; # or whatever version it was.
487
488 # Find out what version of Module::Build is installed or fail quietly.
489 # This should be cross-platform.
53fc1c7e 490 my $Installed_MB =
15cb7b9d
SH
491 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1";
492
493 # some operating systems put a newline at the end of every print.
494 chomp $Installed_MB;
495
496 $Installed_MB = 0 if $?;
497
498 # Use our bundled copy of Module::Build if it's newer than the installed.
499 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
500
501 require Module::Build;
502
503And write the rest of your F<Build.PL> normally. Module::Build will
504remember your change to C<@INC> and use it when you run F<./Build>.
505
506In the future, we hope to provide a more automated solution for this
507scenario; see C<inc/latest.pm> in the Module::Build distribution for
508one indication of the direction we're moving.
509
510
bb4e9162
YST
511=head1 AUTHOR
512
77e96e88 513Ken Williams <kwilliams@cpan.org>
bb4e9162
YST
514
515
516=head1 COPYRIGHT
517
15cb7b9d 518Copyright (c) 2001-2008 Ken Williams. All rights reserved.
bb4e9162
YST
519
520This library is free software; you can redistribute it and/or
521modify it under the same terms as Perl itself.
522
523
524=head1 SEE ALSO
525
dc8021d3
SP
526perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
527L<Module::Build::API>(3)
bb4e9162
YST
528
529=cut