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