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