Commit | Line | Data |
bb4e9162 |
1 | package Module::Build::Cookbook; |
2 | |
3 | |
4 | =head1 NAME |
5 | |
6 | Module::Build::Cookbook - Examples of Module::Build Usage |
7 | |
8 | |
9 | =head1 DESCRIPTION |
10 | |
11 | C<Module::Build> isn't conceptually very complicated, but examples are |
12 | always helpful. I got the idea for writing this cookbook when |
13 | attending Brian Ingerson's "Extreme Programming Tools for Module |
14 | Authors" presentation at YAPC 2003, when he said, straightforwardly, |
15 | "Write A Cookbook." |
16 | |
17 | The definitional of how stuff works is in the main C<Module::Build> |
18 | documentation. 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 | |
26 | In most cases, you can just issue the following commands: |
27 | |
28 | perl Build.PL |
29 | ./Build |
30 | ./Build test |
31 | ./Build install |
32 | |
33 | There's nothing complicated here - first you're running a script |
34 | called F<Build.PL>, then you're running a (newly-generated) script |
35 | called F<Build> and passing it various arguments. |
36 | |
37 | The exact commands may vary a bit depending on how you invoke perl |
38 | scripts on your system. For instance, if you have multiple versions |
39 | of perl installed, you can install to one particular perl's library |
40 | directories like so: |
41 | |
42 | /usr/bin/perl5.8.1 Build.PL |
43 | ./Build |
44 | ./Build test |
45 | ./Build install |
46 | |
47 | If you're on Windows where the current directory is always searched |
48 | first for scripts, you'll probably do something like this: |
49 | |
50 | perl Build.PL |
51 | Build |
52 | Build test |
53 | Build install |
54 | |
55 | On the old Mac OS (version 9 or lower) using MacPerl, you can |
56 | double-click on the F<Build.PL> script to create the F<Build> script, |
57 | then double-click on the F<Build> script to run its C<build>, C<test>, |
58 | and C<install> actions. |
59 | |
60 | The F<Build> script knows what perl was used to run C<Build.PL>, so |
61 | you don't need to re-invoke the F<Build> script with the complete perl |
62 | path each time. If you invoke it with the I<wrong> perl path, you'll |
63 | get a warning or a fatal error. |
64 | |
65 | |
66 | =head2 Making a CPAN.pm-compatible distribution |
67 | |
68 | New versions of CPAN.pm understand how to use a F<Build.PL> script, |
69 | but old versions don't. If you want to help users who have old |
70 | versions, do the following: |
71 | |
72 | Create a file in your distribution named F<Makefile.PL>, with the |
73 | following contents: |
74 | |
75 | use Module::Build::Compat; |
76 | Module::Build::Compat->run_build_pl(args => \@ARGV); |
77 | Module::Build::Compat->write_makefile(); |
78 | |
79 | Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make |
80 | test`, and `make install`, provided the end-user already has |
81 | C<Module::Build> installed. |
82 | |
83 | If the end-user might not have C<Module::Build> installed, it's |
84 | probably best to supply a "traditional" F<Makefile.PL>. The |
85 | C<Module::Build::Compat> module has some very helpful tools for |
86 | keeping a F<Makefile.PL> in sync with a F<Build.PL>. See its |
87 | documentation, and also the C<create_makefile_pl> parameter to the |
88 | C<< Module::Build->new() >> method. |
89 | |
90 | |
91 | =head2 Installing modules using the programmatic interface |
92 | |
93 | If you need to build, test, and/or install modules from within some |
94 | other perl code (as opposed to having the user type installation |
95 | commands at the shell), you can use the programmatic interface. |
96 | Create a Module::Build object (or an object of a custom Module::Build |
97 | subclass) and then invoke its C<dispatch()> method to run various |
98 | actions. |
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 | |
110 | The first argument to C<dispatch()> is the name of the action, and any |
111 | following arguments are named parameters. |
112 | |
113 | This is the interface we use to test Module::Build itself in the |
114 | regression tests. |
115 | |
116 | |
117 | =head2 Installing to a temporary directory |
118 | |
119 | To create packages for package managers like RedHat's C<rpm> or |
120 | Debian's C<deb>, you may need to install to a temporary directory |
121 | first and then create the package from that temporary installation. |
122 | To do this, specify the C<destdir> parameter to the C<install> action: |
123 | |
124 | ./Build install --destdir /tmp/my-package-1.003 |
125 | |
126 | This essentially just prepends all the installation paths with the |
127 | F</tmp/my-package-1.003> directory. |
128 | |
dc8021d3 |
129 | |
bb4e9162 |
130 | =head2 Installing to a non-standard directory |
131 | |
132 | To install to a non-standard directory (for example, if you don't have |
133 | permission to install in the system-wide directories), you can use the |
f943a5bf |
134 | C<install_base>: |
bb4e9162 |
135 | |
136 | ./Build install --install_base /foo/bar |
bb4e9162 |
137 | |
138 | See L<Module::Build/"INSTALL PATHS"> for a much more complete |
139 | discussion of how installation paths are determined. |
140 | |
dc8021d3 |
141 | |
f943a5bf |
142 | =head2 Installing in the same location as ExtUtils::MakeMaker |
143 | |
144 | With the introduction of C<--prefix> in Module::Build 0.28 and |
145 | C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both |
146 | to install to the same locations. |
147 | |
148 | First, ensure you have at least version 0.28 of Module::Build |
149 | installed and 6.31 of ExtUtils::MakeMaker. Prior versions have |
150 | differing installation behaviors. |
151 | |
152 | The following installation flags are equivalent between |
153 | ExtUtils::MakeMaker and Module::Build. |
154 | |
155 | MakeMaker Module::Build |
156 | PREFIX=... --prefix ... |
157 | INSTALL_BASE=... --install_base ... |
158 | DESTDIR=... --destdir ... |
159 | LIB=... --install_path lib=... |
160 | INSTALLDIRS=... --installdirs ... |
161 | INSTALLDIRS=perl --installdirs core |
162 | UNINST=... --uninst ... |
163 | INC=... --extra_compiler_flags ... |
164 | POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE |
165 | |
166 | For example, if you are currently installing MakeMaker modules with |
167 | this command: |
168 | |
169 | perl Makefile.PL PREFIX=~ |
170 | make test |
171 | make install UNINST=1 |
172 | |
173 | You can install into the same location with Module::Build using this: |
174 | |
175 | perl Build.PL --prefix ~ |
176 | ./Build test |
177 | ./Build install --uninst 1 |
178 | |
179 | =head3 C<prefix> vs C<install_base> |
180 | |
181 | The behavior of C<prefix> is complicated and depends closely on |
182 | how your Perl is configured. The resulting installation locations |
183 | will vary from machine to machine and even different installations of |
184 | Perl on the same machine. Because of this, its difficult to document |
185 | where C<prefix> will place your modules. |
186 | |
187 | In contrast, C<install_base> has predictable, easy to explain |
188 | installation locations. Now that Module::Build and MakeMaker both |
189 | have C<install_base> there is little reason to use C<prefix> other |
190 | than to preserve your existing installation locations. If you are |
191 | starting a fresh Perl installation we encourage you to use |
192 | C<install_base>. If you have an existing installation installed via |
193 | C<prefix>, consider moving it to an installation structure matching |
194 | C<install_base> and using that instead. |
195 | |
196 | |
bb4e9162 |
197 | =head2 Running a single test file |
198 | |
dc8021d3 |
199 | C<Module::Build> supports running a single test, which enables you to |
bb4e9162 |
200 | track down errors more quickly. Use the following format: |
201 | |
202 | ./Build test --test_files t/mytest.t |
203 | |
204 | In addition, you may want to run the test in verbose mode to get more |
205 | informative output: |
206 | |
207 | ./Build test --test_files t/mytest.t --verbose 1 |
208 | |
209 | I run this so frequently that I actually define the following shell alias: |
210 | |
211 | alias t './Build test --verbose 1 --test_files' |
212 | |
213 | So then I can just execute C<t t/mytest.t> to run a single test. |
214 | |
215 | |
216 | =head1 ADVANCED RECIPES |
217 | |
218 | |
219 | =head2 Changing the order of the build process |
220 | |
221 | The C<build_elements> property specifies the steps C<Module::Build> |
222 | will take when building a distribution. To change the build order, |
223 | change the order of the entries in that property: |
224 | |
225 | # Process pod files first |
226 | my @e = @{$build->build_elements}; |
227 | my $i = grep {$e[$_] eq 'pod'} 0..$#e; |
228 | unshift @e, splice @e, $i, 1; |
229 | |
230 | Currently, C<build_elements> has the following default value: |
231 | |
232 | [qw( PL support pm xs pod script )] |
233 | |
234 | Do take care when altering this property, since there may be |
235 | non-obvious (and non-documented!) ordering dependencies in the |
236 | C<Module::Build> code. |
237 | |
238 | |
239 | =head2 Adding new file types to the build process |
240 | |
241 | Sometimes you might have extra types of files that you want to install |
242 | alongside the standard types like F<.pm> and F<.pod> files. For |
243 | instance, you might have a F<Bar.dat> file containing some data |
244 | related to the C<Foo::Bar> module. Assuming the data doesn't need to |
245 | be created on the fly, the best place for it to end up is probably as |
246 | F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can |
247 | access it easily at runtime. The following code from a sample |
248 | C<Build.PL> file demonstrates how to accomplish this: |
249 | |
250 | use Module::Build; |
251 | my $build = Module::Build->new |
252 | ( |
253 | module_name => 'Foo::Bar', |
254 | ...other stuff here... |
255 | ); |
256 | $build->add_build_element('dat'); |
257 | $build->create_build_script; |
258 | |
259 | This will find all F<.dat> files in the F<lib/> directory, copy them |
260 | to the F<blib/lib/> directory during the C<build> action, and install |
261 | them during the C<install> action. |
262 | |
263 | If your extra files aren't in the C<lib/> directory, you can |
264 | explicitly say where they are, just as you'd do with F<.pm> or F<.pod> |
265 | files: |
266 | |
267 | use Module::Build; |
268 | my $build = new Module::Build |
269 | ( |
270 | module_name => 'Foo::Bar', |
271 | dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'}, |
272 | ...other stuff here... |
273 | ); |
274 | $build->add_build_element('dat'); |
275 | $build->create_build_script; |
276 | |
277 | If your extra files actually need to be created on the user's machine, |
278 | or if they need some other kind of special processing, you'll probably |
279 | want to create a special method to do so, named |
280 | C<process_${kind}_files()>: |
281 | |
282 | use Module::Build; |
283 | my $class = Module::Build->subclass(code => <<'EOF'); |
284 | sub process_dat_files { |
285 | my $self = shift; |
286 | ... locate and process *.dat files, |
287 | ... and create something in blib/lib/ |
288 | } |
289 | EOF |
290 | my $build = $class->new |
291 | ( |
292 | module_name => 'Foo::Bar', |
293 | ...other stuff here... |
294 | ); |
295 | $build->add_build_element('dat'); |
296 | $build->create_build_script; |
297 | |
298 | If your extra files don't go in F<lib/> but in some other place, see |
299 | L<"Adding new elements to the install process"> for how to actually |
300 | get them installed. |
301 | |
302 | Please note that these examples use some capabilities of Module::Build |
303 | that first appeared in version 0.26. Before that it could certainly |
304 | still be done, but the simple cases took a bit more work. |
305 | |
306 | |
307 | =head2 Adding new elements to the install process |
308 | |
309 | By default, Module::Build creates seven subdirectories of the F<blib/> |
310 | directory during the build process: F<lib/>, F<arch/>, F<bin/>, |
311 | F<script/>, F<bindoc/>, F<libdoc/>, and F<html/> (some of these may be |
312 | missing or empty if there's nothing to go in them). Anything copied |
313 | to these directories during the build will eventually be installed |
314 | during the C<install> action (see L<Module::Build/"INSTALL PATHS">. |
315 | |
316 | If you need to create a new type of installable element, e.g. C<conf>, |
317 | then you need to tell Module::Build where things in F<blib/conf/> |
318 | should be installed. To do this, use the C<install_path> parameter to |
319 | the C<new()> method: |
320 | |
321 | my $build = Module::Build->new |
322 | ( |
323 | ...other stuff here... |
324 | install_path => { conf => $installation_path } |
325 | ); |
326 | |
327 | Or you can call the C<install_path()> method later: |
328 | |
329 | $build->install_path->{conf} || $installation_path; |
330 | |
331 | (Sneakily, or perhaps uglily, C<install_path()> returns a reference to |
332 | a hash of install paths, and you can modify that hash to your heart's |
333 | content.) |
334 | |
335 | The user may also specify the path on the command line: |
336 | |
337 | perl Build.PL --install_path conf=/foo/path/etc |
338 | |
339 | The important part, though, is that I<somehow> the install path needs |
340 | to be set, or else nothing in the F<blib/conf/> directory will get |
341 | installed. |
342 | |
343 | See also L<"Adding new file types to the build process"> for how to |
344 | create the stuff in F<blib/conf/> in the first place. |
345 | |
346 | |
347 | =head1 EXAMPLES ON CPAN |
348 | |
349 | Several distributions on CPAN are making good use of various features |
350 | of Module::Build. They can serve as real-world examples for others. |
351 | |
352 | |
353 | =head2 SVN-Notify-Mirror |
354 | |
355 | L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/> |
356 | |
357 | John Peacock, author of the C<SVN-Notify-Mirror> distribution, says: |
358 | |
359 | =over 4 |
360 | |
361 | =item 1. Using C<auto_features>, I check to see whether two optional |
362 | modules are available - SVN::Notify::Config and Net::SSH; |
363 | |
364 | =item 2. If the S::N::Config module is loaded, I automatically |
365 | generate testfiles for it during Build (using the C<PL_files> |
366 | property). |
367 | |
368 | =item 3. If the C<ssh_feature> is available, I ask if the user wishes |
369 | to perform the ssh tests (since it requires a little preliminary |
370 | setup); |
371 | |
372 | =item 4. Only if the user has C<ssh_feature> and answers yes to the |
373 | testing, do I generate a test file. |
374 | |
375 | I'm sure I could not have handled this complexity with EU::MM, but it |
376 | was very easy to do with M::B. |
377 | |
378 | =back 4 |
379 | |
380 | |
47f13fd5 |
381 | =head2 Modifying an action |
382 | |
383 | Sometimes you might need an to have an action, say C<./Build install>, |
384 | do something unusual. For instance, you might need to change the |
385 | ownership of a file or do something else peculiar to your application. |
386 | |
387 | You can subclass C<Module::Build> on the fly using the C<subclass()> |
388 | method and override the methods that perform the actions. You may need |
389 | to read through C<Module::Build::Authoring> to find the methods you |
390 | want to override, but the general pattern is C<ACTION_> followed by |
391 | the name of the action you want to modify. Here's an example of how |
392 | it would work for C<install>: |
393 | |
394 | # Build.PL |
395 | use Module::Build; |
396 | my $class = Module::Build->subclass( |
397 | class => "Module::Build::Custom", |
398 | code => <<'SUBCLASS' ); |
dc8021d3 |
399 | |
47f13fd5 |
400 | sub ACTION_install { |
401 | my $self = shift; |
402 | # YOUR CODE HERE |
403 | $self->SUPER::ACTION_install; |
404 | } |
405 | SUBCLASS |
dc8021d3 |
406 | |
47f13fd5 |
407 | $class->new( |
408 | module_name => 'Your::Module', |
409 | # rest of the usual Module::Build parameters |
410 | )->create_build_script; |
411 | |
dc8021d3 |
412 | See the L<Module::Build::Authoring> pod in 0.27 or above for more |
47f13fd5 |
413 | complete documentation on this. |
414 | |
dc8021d3 |
415 | |
bb4e9162 |
416 | =head1 AUTHOR |
417 | |
77e96e88 |
418 | Ken Williams <kwilliams@cpan.org> |
bb4e9162 |
419 | |
420 | |
421 | =head1 COPYRIGHT |
422 | |
77e96e88 |
423 | Copyright (c) 2001-2006 Ken Williams. All rights reserved. |
bb4e9162 |
424 | |
425 | This library is free software; you can redistribute it and/or |
426 | modify it under the same terms as Perl itself. |
427 | |
428 | |
429 | =head1 SEE ALSO |
430 | |
dc8021d3 |
431 | perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3), |
432 | L<Module::Build::API>(3) |
bb4e9162 |
433 | |
434 | =cut |