Commit | Line | Data |
3fea05b9 |
1 | package Module::Build::Cookbook; |
2 | use strict; |
3 | use vars qw($VERSION); |
4 | $VERSION = '0.35'; |
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 |