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