This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Math-Complex now dual-lived with Jarkko Hietaniemi as the maintainer.
[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
134C<install_base> or C<prefix> parameters:
135
136 ./Build install --install_base /foo/bar
137 or
138 ./Build install --prefix /foo/bar
139
140Note that these have somewhat different effects - C<prefix> is an
141emulation of C<ExtUtils::MakeMaker>'s old C<PREFIX> setting, and
142inherits all its nasty gotchas. C<install_base> is more predictable,
143and newer versions of C<ExtUtils::MakeMaker> also support it, so it's
144often your best choice.
145
146See L<Module::Build/"INSTALL PATHS"> for a much more complete
147discussion of how installation paths are determined.
148
dc8021d3 149
bb4e9162
YST
150=head2 Running a single test file
151
dc8021d3 152C<Module::Build> supports running a single test, which enables you to
bb4e9162
YST
153track down errors more quickly. Use the following format:
154
155 ./Build test --test_files t/mytest.t
156
157In addition, you may want to run the test in verbose mode to get more
158informative output:
159
160 ./Build test --test_files t/mytest.t --verbose 1
161
162I run this so frequently that I actually define the following shell alias:
163
164 alias t './Build test --verbose 1 --test_files'
165
166So then I can just execute C<t t/mytest.t> to run a single test.
167
168
169=head1 ADVANCED RECIPES
170
171
172=head2 Changing the order of the build process
173
174The C<build_elements> property specifies the steps C<Module::Build>
175will take when building a distribution. To change the build order,
176change the order of the entries in that property:
177
178 # Process pod files first
179 my @e = @{$build->build_elements};
180 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
181 unshift @e, splice @e, $i, 1;
182
183Currently, C<build_elements> has the following default value:
184
185 [qw( PL support pm xs pod script )]
186
187Do take care when altering this property, since there may be
188non-obvious (and non-documented!) ordering dependencies in the
189C<Module::Build> code.
190
191
192=head2 Adding new file types to the build process
193
194Sometimes you might have extra types of files that you want to install
195alongside the standard types like F<.pm> and F<.pod> files. For
196instance, you might have a F<Bar.dat> file containing some data
197related to the C<Foo::Bar> module. Assuming the data doesn't need to
198be created on the fly, the best place for it to end up is probably as
199F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
200access it easily at runtime. The following code from a sample
201C<Build.PL> file demonstrates how to accomplish this:
202
203 use Module::Build;
204 my $build = Module::Build->new
205 (
206 module_name => 'Foo::Bar',
207 ...other stuff here...
208 );
209 $build->add_build_element('dat');
210 $build->create_build_script;
211
212This will find all F<.dat> files in the F<lib/> directory, copy them
213to the F<blib/lib/> directory during the C<build> action, and install
214them during the C<install> action.
215
216If your extra files aren't in the C<lib/> directory, you can
217explicitly say where they are, just as you'd do with F<.pm> or F<.pod>
218files:
219
220 use Module::Build;
221 my $build = new Module::Build
222 (
223 module_name => 'Foo::Bar',
224 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
225 ...other stuff here...
226 );
227 $build->add_build_element('dat');
228 $build->create_build_script;
229
230If your extra files actually need to be created on the user's machine,
231or if they need some other kind of special processing, you'll probably
232want to create a special method to do so, named
233C<process_${kind}_files()>:
234
235 use Module::Build;
236 my $class = Module::Build->subclass(code => <<'EOF');
237 sub process_dat_files {
238 my $self = shift;
239 ... locate and process *.dat files,
240 ... and create something in blib/lib/
241 }
242 EOF
243 my $build = $class->new
244 (
245 module_name => 'Foo::Bar',
246 ...other stuff here...
247 );
248 $build->add_build_element('dat');
249 $build->create_build_script;
250
251If your extra files don't go in F<lib/> but in some other place, see
252L<"Adding new elements to the install process"> for how to actually
253get them installed.
254
255Please note that these examples use some capabilities of Module::Build
256that first appeared in version 0.26. Before that it could certainly
257still be done, but the simple cases took a bit more work.
258
259
260=head2 Adding new elements to the install process
261
262By default, Module::Build creates seven subdirectories of the F<blib/>
263directory during the build process: F<lib/>, F<arch/>, F<bin/>,
264F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be
265missing or empty if there's nothing to go in them). Anything copied
266to these directories during the build will eventually be installed
267during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
268
269If you need to create a new type of installable element, e.g. C<conf>,
270then you need to tell Module::Build where things in F<blib/conf/>
271should be installed. To do this, use the C<install_path> parameter to
272the C<new()> method:
273
274 my $build = Module::Build->new
275 (
276 ...other stuff here...
277 install_path => { conf => $installation_path }
278 );
279
280Or you can call the C<install_path()> method later:
281
282 $build->install_path->{conf} || $installation_path;
283
284(Sneakily, or perhaps uglily, C<install_path()> returns a reference to
285a hash of install paths, and you can modify that hash to your heart's
286content.)
287
288The user may also specify the path on the command line:
289
290 perl Build.PL --install_path conf=/foo/path/etc
291
292The important part, though, is that I<somehow> the install path needs
293to be set, or else nothing in the F<blib/conf/> directory will get
294installed.
295
296See also L<"Adding new file types to the build process"> for how to
297create the stuff in F<blib/conf/> in the first place.
298
299
300=head1 EXAMPLES ON CPAN
301
302Several distributions on CPAN are making good use of various features
303of Module::Build. They can serve as real-world examples for others.
304
305
306=head2 SVN-Notify-Mirror
307
308L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
309
310John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
311
312=over 4
313
314=item 1. Using C<auto_features>, I check to see whether two optional
315modules are available - SVN::Notify::Config and Net::SSH;
316
317=item 2. If the S::N::Config module is loaded, I automatically
318generate testfiles for it during Build (using the C<PL_files>
319property).
320
321=item 3. If the C<ssh_feature> is available, I ask if the user wishes
322to perform the ssh tests (since it requires a little preliminary
323setup);
324
325=item 4. Only if the user has C<ssh_feature> and answers yes to the
326testing, do I generate a test file.
327
328I'm sure I could not have handled this complexity with EU::MM, but it
329was very easy to do with M::B.
330
331=back 4
332
333
47f13fd5
SP
334=head2 Modifying an action
335
336Sometimes you might need an to have an action, say C<./Build install>,
337do something unusual. For instance, you might need to change the
338ownership of a file or do something else peculiar to your application.
339
340You can subclass C<Module::Build> on the fly using the C<subclass()>
341method and override the methods that perform the actions. You may need
342to read through C<Module::Build::Authoring> to find the methods you
343want to override, but the general pattern is C<ACTION_> followed by
344the name of the action you want to modify. Here's an example of how
345it would work for C<install>:
346
347 # Build.PL
348 use Module::Build;
349 my $class = Module::Build->subclass(
350 class => "Module::Build::Custom",
351 code => <<'SUBCLASS' );
dc8021d3 352
47f13fd5
SP
353 sub ACTION_install {
354 my $self = shift;
355 # YOUR CODE HERE
356 $self->SUPER::ACTION_install;
357 }
358 SUBCLASS
dc8021d3 359
47f13fd5
SP
360 $class->new(
361 module_name => 'Your::Module',
362 # rest of the usual Module::Build parameters
363 )->create_build_script;
364
dc8021d3 365See the L<Module::Build::Authoring> pod in 0.27 or above for more
47f13fd5
SP
366complete documentation on this.
367
dc8021d3 368
bb4e9162
YST
369=head1 AUTHOR
370
371Ken Williams <ken@cpan.org>
372
373
374=head1 COPYRIGHT
375
376Copyright (c) 2001-2005 Ken Williams. All rights reserved.
377
378This library is free software; you can redistribute it and/or
379modify it under the same terms as Perl itself.
380
381
382=head1 SEE ALSO
383
dc8021d3
SP
384perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
385L<Module::Build::API>(3)
bb4e9162
YST
386
387=cut