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