Commit | Line | Data |
---|---|---|
bb4e9162 | 1 | package Module::Build::Cookbook; |
738349a8 SH |
2 | use strict; |
3 | use vars qw($VERSION); | |
6e4bdc3f | 4 | $VERSION = '0.4008'; |
bb4e9162 YST |
5 | |
6 | ||
7 | =head1 NAME | |
8 | ||
9 | Module::Build::Cookbook - Examples of Module::Build Usage | |
10 | ||
bb4e9162 YST |
11 | =head1 DESCRIPTION |
12 | ||
13 | C<Module::Build> isn't conceptually very complicated, but examples are | |
7a827510 RGS |
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. | |
bb4e9162 YST |
17 | |
18 | ||
19 | =head1 BASIC RECIPES | |
20 | ||
21 | ||
7a827510 | 22 | =head2 Installing modules that use Module::Build |
bb4e9162 YST |
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 | ||
7a827510 | 58 | The F<Build> script knows what perl was used to run F<Build.PL>, so |
bb4e9162 YST |
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 | ||
7a827510 | 63 | =head2 Modifying Config.pm values |
bb4e9162 | 64 | |
7a827510 RGS |
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: | |
bb4e9162 | 74 | |
7a827510 | 75 | perl Build.PL --config cc=gcc --config ld=gcc |
bb4e9162 | 76 | |
7a827510 RGS |
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()>: | |
bb4e9162 | 79 | |
7a827510 RGS |
80 | my $build = Module::Build->new |
81 | ( | |
82 | ... | |
83 | config => { cc => 'gcc', ld => 'gcc' }, | |
84 | ... | |
85 | ); | |
bb4e9162 | 86 | |
7a827510 RGS |
87 | In custom build code, the same thing can be accomplished by calling |
88 | the L<Module::Build/config> method: | |
bb4e9162 | 89 | |
7a827510 RGS |
90 | $build->config( cc => 'gcc' ); # Set |
91 | $build->config( ld => 'gcc' ); # Set | |
92 | ... | |
93 | my $linker = $build->config('ld'); # Get | |
bb4e9162 YST |
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 | ||
dc8021d3 | 134 | |
bb4e9162 YST |
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 | |
7a827510 | 139 | C<install_base> or C<prefix> parameters: |
bb4e9162 YST |
140 | |
141 | ./Build install --install_base /foo/bar | |
bb4e9162 YST |
142 | |
143 | See L<Module::Build/"INSTALL PATHS"> for a much more complete | |
144 | discussion of how installation paths are determined. | |
145 | ||
dc8021d3 | 146 | |
f943a5bf SP |
147 | =head2 Installing in the same location as ExtUtils::MakeMaker |
148 | ||
149 | With the introduction of C<--prefix> in Module::Build 0.28 and | |
23837600 | 150 | C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both |
f943a5bf SP |
151 | to install to the same locations. |
152 | ||
153 | First, ensure you have at least version 0.28 of Module::Build | |
23837600 | 154 | installed and 6.31 of C<ExtUtils::MakeMaker>. Prior versions have |
7a827510 | 155 | differing (and in some cases quite strange) installation behaviors. |
f943a5bf SP |
156 | |
157 | The following installation flags are equivalent between | |
23837600 | 158 | C<ExtUtils::MakeMaker> and C<Module::Build>. |
f943a5bf SP |
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 | ||
23837600 | 171 | For example, if you are currently installing C<MakeMaker> modules with |
f943a5bf SP |
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 | ||
7a827510 | 186 | The behavior of C<prefix> is complicated and depends on |
f943a5bf SP |
187 | how your Perl is configured. The resulting installation locations |
188 | will vary from machine to machine and even different installations of | |
7a827510 | 189 | Perl on the same machine. Because of this, it's difficult to document |
f943a5bf SP |
190 | where C<prefix> will place your modules. |
191 | ||
192 | In contrast, C<install_base> has predictable, easy to explain | |
23837600 | 193 | installation locations. Now that C<Module::Build> and C<MakeMaker> both |
f943a5bf SP |
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 | ||
bb4e9162 YST |
202 | =head2 Running a single test file |
203 | ||
dc8021d3 | 204 | C<Module::Build> supports running a single test, which enables you to |
bb4e9162 YST |
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 | ||
7a827510 | 214 | I run this so frequently that I define the following shell alias: |
bb4e9162 YST |
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 | ||
7a827510 RGS |
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 | ||
bb4e9162 YST |
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}; | |
738349a8 | 250 | my ($i) = grep {$e[$_] eq 'pod'} 0..$#e; |
bb4e9162 YST |
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 | |
7a827510 | 267 | related to the C<Foo::Bar> module and you'd like for it to end up as |
bb4e9162 YST |
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 | ||
7a827510 RGS |
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: | |
bb4e9162 YST |
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 | |
7a827510 RGS |
301 | want to subclass C<Module::Build> and create a special method to |
302 | process them, named C<process_${kind}_files()>: | |
bb4e9162 YST |
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 | |
7a827510 | 325 | that first appeared in version 0.26. Before that it could |
bb4e9162 YST |
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 | ||
7a827510 RGS |
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 | |
bb4e9162 YST |
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 | ||
7a827510 | 338 | If you need to create a new custom type of installable element, e.g. C<conf>, |
bb4e9162 YST |
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 | ||
7a827510 | 351 | $build->install_path(conf => $installation_path); |
bb4e9162 YST |
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 | |
7a827510 RGS |
359 | installed, and a runtime error during the C<install> action will |
360 | result. | |
bb4e9162 YST |
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 | |
23837600 | 384 | generate test files for it during Build (using the C<PL_files> |
bb4e9162 YST |
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 | ||
15cb7b9d | 397 | =back |
bb4e9162 YST |
398 | |
399 | ||
47f13fd5 SP |
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()> | |
7a827510 RGS |
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: | |
47f13fd5 SP |
413 | |
414 | # Build.PL | |
415 | use Module::Build; | |
416 | my $class = Module::Build->subclass( | |
417 | class => "Module::Build::Custom", | |
418 | code => <<'SUBCLASS' ); | |
dc8021d3 | 419 | |
47f13fd5 SP |
420 | sub ACTION_install { |
421 | my $self = shift; | |
422 | # YOUR CODE HERE | |
423 | $self->SUPER::ACTION_install; | |
424 | } | |
425 | SUBCLASS | |
dc8021d3 | 426 | |
47f13fd5 SP |
427 | $class->new( |
428 | module_name => 'Your::Module', | |
429 | # rest of the usual Module::Build parameters | |
430 | )->create_build_script; | |
431 | ||
dc8021d3 | 432 | |
15cb7b9d SH |
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 | |
23837600 | 460 | (see contrib/bundle.pl in the distribution). |
15cb7b9d SH |
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. | |
53fc1c7e | 490 | my $Installed_MB = |
15cb7b9d SH |
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 | ||
bb4e9162 YST |
511 | =head1 AUTHOR |
512 | ||
77e96e88 | 513 | Ken Williams <kwilliams@cpan.org> |
bb4e9162 YST |
514 | |
515 | ||
516 | =head1 COPYRIGHT | |
517 | ||
15cb7b9d | 518 | Copyright (c) 2001-2008 Ken Williams. All rights reserved. |
bb4e9162 YST |
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 | ||
dc8021d3 SP |
526 | perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3), |
527 | L<Module::Build::API>(3) | |
bb4e9162 YST |
528 | |
529 | =cut |