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