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