Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "Module::Build::Cookbook 3" |
132 | .TH Module::Build::Cookbook 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Module::Build::Cookbook \- Examples of Module::Build Usage |
135 | .SH "DESCRIPTION" |
136 | .IX Header "DESCRIPTION" |
137 | \&\f(CW\*(C`Module::Build\*(C'\fR isn't conceptually very complicated, but examples are |
138 | always helpful. The following recipes should help developers and/or |
139 | installers put together the pieces from the other parts of the |
140 | documentation. |
141 | .SH "BASIC RECIPES" |
142 | .IX Header "BASIC RECIPES" |
143 | .Sh "Installing modules that use Module::Build" |
144 | .IX Subsection "Installing modules that use Module::Build" |
145 | In most cases, you can just issue the following commands: |
146 | .PP |
147 | .Vb 4 |
148 | \& perl Build.PL |
149 | \& ./Build |
150 | \& ./Build test |
151 | \& ./Build install |
152 | .Ve |
153 | .PP |
154 | There's nothing complicated here \- first you're running a script |
155 | called \fIBuild.PL\fR, then you're running a (newly\-generated) script |
156 | called \fIBuild\fR and passing it various arguments. |
157 | .PP |
158 | The exact commands may vary a bit depending on how you invoke perl |
159 | scripts on your system. For instance, if you have multiple versions |
160 | of perl installed, you can install to one particular perl's library |
161 | directories like so: |
162 | .PP |
163 | .Vb 4 |
164 | \& /usr/bin/perl5.8.1 Build.PL |
165 | \& ./Build |
166 | \& ./Build test |
167 | \& ./Build install |
168 | .Ve |
169 | .PP |
170 | If you're on Windows where the current directory is always searched |
171 | first for scripts, you'll probably do something like this: |
172 | .PP |
173 | .Vb 4 |
174 | \& perl Build.PL |
175 | \& Build |
176 | \& Build test |
177 | \& Build install |
178 | .Ve |
179 | .PP |
180 | On the old Mac \s-1OS\s0 (version 9 or lower) using MacPerl, you can |
181 | double-click on the \fIBuild.PL\fR script to create the \fIBuild\fR script, |
182 | then double-click on the \fIBuild\fR script to run its \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`test\*(C'\fR, |
183 | and \f(CW\*(C`install\*(C'\fR actions. |
184 | .PP |
185 | The \fIBuild\fR script knows what perl was used to run \fIBuild.PL\fR, so |
186 | you don't need to re-invoke the \fIBuild\fR script with the complete perl |
187 | path each time. If you invoke it with the \fIwrong\fR perl path, you'll |
188 | get a warning or a fatal error. |
189 | .Sh "Modifying Config.pm values" |
190 | .IX Subsection "Modifying Config.pm values" |
191 | \&\f(CW\*(C`Module::Build\*(C'\fR relies heavily on various values from perl's |
192 | \&\f(CW\*(C`Config.pm\*(C'\fR to do its work. For example, default installation paths |
193 | are given by \f(CW\*(C`installsitelib\*(C'\fR and \f(CW\*(C`installvendorman3dir\*(C'\fR and |
194 | friends, C linker & compiler settings are given by \f(CW\*(C`ld\*(C'\fR, |
195 | \&\f(CW\*(C`lddlflags\*(C'\fR, \f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR, and so on. \fIIf you're pretty sure |
196 | you know what you're doing\fR, you can tell \f(CW\*(C`Module::Build\*(C'\fR to pretend |
197 | there are different values in \fIConfig.pm\fR than what's really there, |
198 | by passing arguments for the \f(CW\*(C`\-\-config\*(C'\fR parameter on the command |
199 | line: |
200 | .PP |
201 | .Vb 1 |
202 | \& perl Build.PL \-\-config cc=gcc \-\-config ld=gcc |
203 | .Ve |
204 | .PP |
205 | Inside the \f(CW\*(C`Build.PL\*(C'\fR script the same thing can be accomplished by |
206 | passing values for the \f(CW\*(C`config\*(C'\fR parameter to \f(CW\*(C`new()\*(C'\fR: |
207 | .PP |
208 | .Vb 6 |
209 | \& my $build = Module::Build\->new |
210 | \& ( |
211 | \& ... |
212 | \& config => { cc => 'gcc', ld => 'gcc' }, |
213 | \& ... |
214 | \& ); |
215 | .Ve |
216 | .PP |
217 | In custom build code, the same thing can be accomplished by calling |
218 | the \*(L"config\*(R" in Module::Build method: |
219 | .PP |
220 | .Vb 4 |
221 | \& $build\->config( cc => 'gcc' ); # Set |
222 | \& $build\->config( ld => 'gcc' ); # Set |
223 | \& ... |
224 | \& my $linker = $build\->config('ld'); # Get |
225 | .Ve |
226 | .Sh "Installing modules using the programmatic interface" |
227 | .IX Subsection "Installing modules using the programmatic interface" |
228 | If you need to build, test, and/or install modules from within some |
229 | other perl code (as opposed to having the user type installation |
230 | commands at the shell), you can use the programmatic interface. |
231 | Create a Module::Build object (or an object of a custom Module::Build |
232 | subclass) and then invoke its \f(CW\*(C`dispatch()\*(C'\fR method to run various |
233 | actions. |
234 | .PP |
235 | .Vb 9 |
236 | \& my $build = Module::Build\->new |
237 | \& ( |
238 | \& module_name => 'Foo::Bar', |
239 | \& license => 'perl', |
240 | \& requires => { 'Some::Module' => '1.23' }, |
241 | \& ); |
242 | \& $build\->dispatch('build'); |
243 | \& $build\->dispatch('test', verbose => 1); |
244 | \& $build\->dispatch('install'); |
245 | .Ve |
246 | .PP |
247 | The first argument to \f(CW\*(C`dispatch()\*(C'\fR is the name of the action, and any |
248 | following arguments are named parameters. |
249 | .PP |
250 | This is the interface we use to test Module::Build itself in the |
251 | regression tests. |
252 | .Sh "Installing to a temporary directory" |
253 | .IX Subsection "Installing to a temporary directory" |
254 | To create packages for package managers like RedHat's \f(CW\*(C`rpm\*(C'\fR or |
255 | Debian's \f(CW\*(C`deb\*(C'\fR, you may need to install to a temporary directory |
256 | first and then create the package from that temporary installation. |
257 | To do this, specify the \f(CW\*(C`destdir\*(C'\fR parameter to the \f(CW\*(C`install\*(C'\fR action: |
258 | .PP |
259 | .Vb 1 |
260 | \& ./Build install \-\-destdir /tmp/my\-package\-1.003 |
261 | .Ve |
262 | .PP |
263 | This essentially just prepends all the installation paths with the |
264 | \&\fI/tmp/my\-package\-1.003\fR directory. |
265 | .Sh "Installing to a non-standard directory" |
266 | .IX Subsection "Installing to a non-standard directory" |
267 | To install to a non-standard directory (for example, if you don't have |
268 | permission to install in the system-wide directories), you can use the |
269 | \&\f(CW\*(C`install_base\*(C'\fR or \f(CW\*(C`prefix\*(C'\fR parameters: |
270 | .PP |
271 | .Vb 1 |
272 | \& ./Build install \-\-install_base /foo/bar |
273 | .Ve |
274 | .PP |
275 | See \*(L"\s-1INSTALL\s0 \s-1PATHS\s0\*(R" in Module::Build for a much more complete |
276 | discussion of how installation paths are determined. |
277 | .Sh "Installing in the same location as ExtUtils::MakeMaker" |
278 | .IX Subsection "Installing in the same location as ExtUtils::MakeMaker" |
279 | With the introduction of \f(CW\*(C`\-\-prefix\*(C'\fR in Module::Build 0.28 and |
280 | \&\f(CW\*(C`INSTALL_BASE\*(C'\fR in \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR 6.31 its easy to get them both |
281 | to install to the same locations. |
282 | .PP |
283 | First, ensure you have at least version 0.28 of Module::Build |
284 | installed and 6.31 of \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. Prior versions have |
285 | differing (and in some cases quite strange) installation behaviors. |
286 | .PP |
287 | The following installation flags are equivalent between |
288 | \&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR and \f(CW\*(C`Module::Build\*(C'\fR. |
289 | .PP |
290 | .Vb 10 |
291 | \& MakeMaker Module::Build |
292 | \& PREFIX=... \-\-prefix ... |
293 | \& INSTALL_BASE=... \-\-install_base ... |
294 | \& DESTDIR=... \-\-destdir ... |
295 | \& LIB=... \-\-install_path lib=... |
296 | \& INSTALLDIRS=... \-\-installdirs ... |
297 | \& INSTALLDIRS=perl \-\-installdirs core |
298 | \& UNINST=... \-\-uninst ... |
299 | \& INC=... \-\-extra_compiler_flags ... |
300 | \& POLLUTE=1 \-\-extra_compiler_flags \-DPERL_POLLUTE |
301 | .Ve |
302 | .PP |
303 | For example, if you are currently installing \f(CW\*(C`MakeMaker\*(C'\fR modules with |
304 | this command: |
305 | .PP |
306 | .Vb 3 |
307 | \& perl Makefile.PL PREFIX=~ |
308 | \& make test |
309 | \& make install UNINST=1 |
310 | .Ve |
311 | .PP |
312 | You can install into the same location with Module::Build using this: |
313 | .PP |
314 | .Vb 3 |
315 | \& perl Build.PL \-\-prefix ~ |
316 | \& ./Build test |
317 | \& ./Build install \-\-uninst 1 |
318 | .Ve |
319 | .PP |
320 | \fI\f(CI\*(C`prefix\*(C'\fI vs \f(CI\*(C`install_base\*(C'\fI\fR |
321 | .IX Subsection "prefix vs install_base" |
322 | .PP |
323 | The behavior of \f(CW\*(C`prefix\*(C'\fR is complicated and depends on |
324 | how your Perl is configured. The resulting installation locations |
325 | will vary from machine to machine and even different installations of |
326 | Perl on the same machine. Because of this, it's difficult to document |
327 | where \f(CW\*(C`prefix\*(C'\fR will place your modules. |
328 | .PP |
329 | In contrast, \f(CW\*(C`install_base\*(C'\fR has predictable, easy to explain |
330 | installation locations. Now that \f(CW\*(C`Module::Build\*(C'\fR and \f(CW\*(C`MakeMaker\*(C'\fR both |
331 | have \f(CW\*(C`install_base\*(C'\fR there is little reason to use \f(CW\*(C`prefix\*(C'\fR other |
332 | than to preserve your existing installation locations. If you are |
333 | starting a fresh Perl installation we encourage you to use |
334 | \&\f(CW\*(C`install_base\*(C'\fR. If you have an existing installation installed via |
335 | \&\f(CW\*(C`prefix\*(C'\fR, consider moving it to an installation structure matching |
336 | \&\f(CW\*(C`install_base\*(C'\fR and using that instead. |
337 | .Sh "Running a single test file" |
338 | .IX Subsection "Running a single test file" |
339 | \&\f(CW\*(C`Module::Build\*(C'\fR supports running a single test, which enables you to |
340 | track down errors more quickly. Use the following format: |
341 | .PP |
342 | .Vb 1 |
343 | \& ./Build test \-\-test_files t/mytest.t |
344 | .Ve |
345 | .PP |
346 | In addition, you may want to run the test in verbose mode to get more |
347 | informative output: |
348 | .PP |
349 | .Vb 1 |
350 | \& ./Build test \-\-test_files t/mytest.t \-\-verbose 1 |
351 | .Ve |
352 | .PP |
353 | I run this so frequently that I define the following shell alias: |
354 | .PP |
355 | .Vb 1 |
356 | \& alias t './Build test \-\-verbose 1 \-\-test_files' |
357 | .Ve |
358 | .PP |
359 | So then I can just execute \f(CW\*(C`t t/mytest.t\*(C'\fR to run a single test. |
360 | .SH "ADVANCED RECIPES" |
361 | .IX Header "ADVANCED RECIPES" |
362 | .Sh "Making a \s-1CPAN\s0.pm\-compatible distribution" |
363 | .IX Subsection "Making a CPAN.pm-compatible distribution" |
364 | New versions of \s-1CPAN\s0.pm understand how to use a \fIBuild.PL\fR script, |
365 | but old versions don't. If authors want to help users who have old |
366 | versions, some form of \fIMakefile.PL\fR should be supplied. The easiest |
367 | way to accomplish this is to use the \f(CW\*(C`create_makefile_pl\*(C'\fR parameter to |
368 | \&\f(CW\*(C`Module::Build\->new()\*(C'\fR in the \f(CW\*(C`Build.PL\*(C'\fR script, which can |
369 | create various flavors of \fIMakefile.PL\fR during the \f(CW\*(C`dist\*(C'\fR action. |
370 | .PP |
371 | As a best practice, we recommend using the \*(L"traditional\*(R" style of |
372 | \&\fIMakefile.PL\fR unless your distribution has needs that can't be |
373 | accomplished that way. |
374 | .PP |
375 | The \f(CW\*(C`Module::Build::Compat\*(C'\fR module, which is part of |
376 | \&\f(CW\*(C`Module::Build\*(C'\fR's distribution, is responsible for creating these |
377 | \&\fIMakefile.PL\fRs. Please see Module::Build::Compat for the details. |
378 | .Sh "Changing the order of the build process" |
379 | .IX Subsection "Changing the order of the build process" |
380 | The \f(CW\*(C`build_elements\*(C'\fR property specifies the steps \f(CW\*(C`Module::Build\*(C'\fR |
381 | will take when building a distribution. To change the build order, |
382 | change the order of the entries in that property: |
383 | .PP |
384 | .Vb 4 |
385 | \& # Process pod files first |
386 | \& my @e = @{$build\->build_elements}; |
387 | \& my ($i) = grep {$e[$_] eq 'pod'} 0..$#e; |
388 | \& unshift @e, splice @e, $i, 1; |
389 | .Ve |
390 | .PP |
391 | Currently, \f(CW\*(C`build_elements\*(C'\fR has the following default value: |
392 | .PP |
393 | .Vb 1 |
394 | \& [qw( PL support pm xs pod script )] |
395 | .Ve |
396 | .PP |
397 | Do take care when altering this property, since there may be |
398 | non-obvious (and non\-documented!) ordering dependencies in the |
399 | \&\f(CW\*(C`Module::Build\*(C'\fR code. |
400 | .Sh "Adding new file types to the build process" |
401 | .IX Subsection "Adding new file types to the build process" |
402 | Sometimes you might have extra types of files that you want to install |
403 | alongside the standard types like \fI.pm\fR and \fI.pod\fR files. For |
404 | instance, you might have a \fIBar.dat\fR file containing some data |
405 | related to the \f(CW\*(C`Foo::Bar\*(C'\fR module and you'd like for it to end up as |
406 | \&\fIFoo/Bar.dat\fR somewhere in perl's \f(CW@INC\fR path so \f(CW\*(C`Foo::Bar\*(C'\fR can |
407 | access it easily at runtime. The following code from a sample |
408 | \&\f(CW\*(C`Build.PL\*(C'\fR file demonstrates how to accomplish this: |
409 | .PP |
410 | .Vb 8 |
411 | \& use Module::Build; |
412 | \& my $build = Module::Build\->new |
413 | \& ( |
414 | \& module_name => 'Foo::Bar', |
415 | \& ...other stuff here... |
416 | \& ); |
417 | \& $build\->add_build_element('dat'); |
418 | \& $build\->create_build_script; |
419 | .Ve |
420 | .PP |
421 | This will find all \fI.dat\fR files in the \fIlib/\fR directory, copy them |
422 | to the \fIblib/lib/\fR directory during the \f(CW\*(C`build\*(C'\fR action, and install |
423 | them during the \f(CW\*(C`install\*(C'\fR action. |
424 | .PP |
425 | If your extra files aren't located in the \f(CW\*(C`lib/\*(C'\fR directory in your |
426 | distribution, you can explicitly say where they are, just as you'd do |
427 | with \fI.pm\fR or \fI.pod\fR files: |
428 | .PP |
429 | .Vb 9 |
430 | \& use Module::Build; |
431 | \& my $build = new Module::Build |
432 | \& ( |
433 | \& module_name => 'Foo::Bar', |
434 | \& dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'}, |
435 | \& ...other stuff here... |
436 | \& ); |
437 | \& $build\->add_build_element('dat'); |
438 | \& $build\->create_build_script; |
439 | .Ve |
440 | .PP |
441 | If your extra files actually need to be created on the user's machine, |
442 | or if they need some other kind of special processing, you'll probably |
443 | want to subclass \f(CW\*(C`Module::Build\*(C'\fR and create a special method to |
444 | process them, named \f(CW\*(C`process_${kind}_files()\*(C'\fR: |
445 | .PP |
446 | .Vb 15 |
447 | \& use Module::Build; |
448 | \& my $class = Module::Build\->subclass(code => <<'EOF'); |
449 | \& sub process_dat_files { |
450 | \& my $self = shift; |
451 | \& ... locate and process *.dat files, |
452 | \& ... and create something in blib/lib/ |
453 | \& } |
454 | \& EOF |
455 | \& my $build = $class\->new |
456 | \& ( |
457 | \& module_name => 'Foo::Bar', |
458 | \& ...other stuff here... |
459 | \& ); |
460 | \& $build\->add_build_element('dat'); |
461 | \& $build\->create_build_script; |
462 | .Ve |
463 | .PP |
464 | If your extra files don't go in \fIlib/\fR but in some other place, see |
465 | \&\*(L"Adding new elements to the install process\*(R" for how to actually |
466 | get them installed. |
467 | .PP |
468 | Please note that these examples use some capabilities of Module::Build |
469 | that first appeared in version 0.26. Before that it could |
470 | still be done, but the simple cases took a bit more work. |
471 | .Sh "Adding new elements to the install process" |
472 | .IX Subsection "Adding new elements to the install process" |
473 | By default, Module::Build creates seven subdirectories of the \fIblib\fR |
474 | directory during the build process: \fIlib\fR, \fIarch\fR, \fIbin\fR, |
475 | \&\fIscript\fR, \fIbindoc\fR, \fIlibdoc\fR, and \fIhtml\fR (some of these may be |
476 | missing or empty if there's nothing to go in them). Anything copied |
477 | to these directories during the build will eventually be installed |
478 | during the \f(CW\*(C`install\*(C'\fR action (see \*(L"\s-1INSTALL\s0 \s-1PATHS\s0\*(R" in Module::Build. |
479 | .PP |
480 | If you need to create a new custom type of installable element, e.g. \f(CW\*(C`conf\*(C'\fR, |
481 | then you need to tell Module::Build where things in \fIblib/conf/\fR |
482 | should be installed. To do this, use the \f(CW\*(C`install_path\*(C'\fR parameter to |
483 | the \f(CW\*(C`new()\*(C'\fR method: |
484 | .PP |
485 | .Vb 5 |
486 | \& my $build = Module::Build\->new |
487 | \& ( |
488 | \& ...other stuff here... |
489 | \& install_path => { conf => $installation_path } |
490 | \& ); |
491 | .Ve |
492 | .PP |
493 | Or you can call the \f(CW\*(C`install_path()\*(C'\fR method later: |
494 | .PP |
495 | .Vb 1 |
496 | \& $build\->install_path(conf => $installation_path); |
497 | .Ve |
498 | .PP |
499 | The user may also specify the path on the command line: |
500 | .PP |
501 | .Vb 1 |
502 | \& perl Build.PL \-\-install_path conf=/foo/path/etc |
503 | .Ve |
504 | .PP |
505 | The important part, though, is that \fIsomehow\fR the install path needs |
506 | to be set, or else nothing in the \fIblib/conf/\fR directory will get |
507 | installed, and a runtime error during the \f(CW\*(C`install\*(C'\fR action will |
508 | result. |
509 | .PP |
510 | See also \*(L"Adding new file types to the build process\*(R" for how to |
511 | create the stuff in \fIblib/conf/\fR in the first place. |
512 | .SH "EXAMPLES ON CPAN" |
513 | .IX Header "EXAMPLES ON CPAN" |
514 | Several distributions on \s-1CPAN\s0 are making good use of various features |
515 | of Module::Build. They can serve as real-world examples for others. |
516 | .Sh "SVN-Notify-Mirror" |
517 | .IX Subsection "SVN-Notify-Mirror" |
518 | <http://search.cpan.org/~jpeacock/SVN\-Notify\-Mirror/> |
519 | .PP |
520 | John Peacock, author of the \f(CW\*(C`SVN\-Notify\-Mirror\*(C'\fR distribution, says: |
521 | .ie n .IP "1. Using ""auto_features"", I check to see whether two optional modules are available \- SVN::Notify::Config and Net::SSH;" 4 |
522 | .el .IP "1. Using \f(CWauto_features\fR, I check to see whether two optional modules are available \- SVN::Notify::Config and Net::SSH;" 4 |
523 | .IX Item "1. Using auto_features, I check to see whether two optional modules are available - SVN::Notify::Config and Net::SSH;" |
524 | .PD 0 |
525 | .ie n .IP "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the ""PL_files"" property)." 4 |
526 | .el .IP "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the \f(CWPL_files\fR property)." 4 |
527 | .IX Item "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the PL_files property)." |
528 | .ie n .IP "3. If the ""ssh_feature"" is available, I ask if the user wishes to perform the ssh tests (since it requires a little preliminary setup);" 4 |
529 | .el .IP "3. If the \f(CWssh_feature\fR is available, I ask if the user wishes to perform the ssh tests (since it requires a little preliminary setup);" 4 |
530 | .IX Item "3. If the ssh_feature is available, I ask if the user wishes to perform the ssh tests (since it requires a little preliminary setup);" |
531 | .ie n .IP "4. Only if the user has ""ssh_feature"" and answers yes to the testing, do I generate a test file." 4 |
532 | .el .IP "4. Only if the user has \f(CWssh_feature\fR and answers yes to the testing, do I generate a test file." 4 |
533 | .IX Item "4. Only if the user has ssh_feature and answers yes to the testing, do I generate a test file." |
534 | .PD |
535 | I'm sure I could not have handled this complexity with \s-1EU::MM\s0, but it |
536 | was very easy to do with M::B. |
537 | .Sh "Modifying an action" |
538 | .IX Subsection "Modifying an action" |
539 | Sometimes you might need an to have an action, say \f(CW\*(C`./Build install\*(C'\fR, |
540 | do something unusual. For instance, you might need to change the |
541 | ownership of a file or do something else peculiar to your application. |
542 | .PP |
543 | You can subclass \f(CW\*(C`Module::Build\*(C'\fR on the fly using the \f(CW\*(C`subclass()\*(C'\fR |
544 | method and override the methods that perform the actions. You may |
545 | need to read through \f(CW\*(C`Module::Build::Authoring\*(C'\fR and |
546 | \&\f(CW\*(C`Module::Build::API\*(C'\fR to find the methods you want to override. All |
547 | \&\*(L"action\*(R" methods are implemented by a method called \*(L"\s-1ACTION_\s0\*(R" followed |
548 | by the action's name, so here's an example of how it would work for |
549 | the \f(CW\*(C`install\*(C'\fR action: |
550 | .PP |
551 | .Vb 5 |
552 | \& # Build.PL |
553 | \& use Module::Build; |
554 | \& my $class = Module::Build\->subclass( |
555 | \& class => "Module::Build::Custom", |
556 | \& code => <<'SUBCLASS' ); |
557 | .Ve |
558 | .PP |
559 | .Vb 6 |
560 | \& sub ACTION_install { |
561 | \& my $self = shift; |
562 | \& # YOUR CODE HERE |
563 | \& $self\->SUPER::ACTION_install; |
564 | \& } |
565 | \& SUBCLASS |
566 | .Ve |
567 | .PP |
568 | .Vb 4 |
569 | \& $class\->new( |
570 | \& module_name => 'Your::Module', |
571 | \& # rest of the usual Module::Build parameters |
572 | \& )\->create_build_script; |
573 | .Ve |
574 | .Sh "Adding an action" |
575 | .IX Subsection "Adding an action" |
576 | You can add a new \f(CW\*(C`./Build\*(C'\fR action simply by writing the method for |
577 | it in your subclass. Use \f(CW\*(C`depends_on\*(C'\fR to declare that another action |
578 | must have been run before your action. |
579 | .PP |
580 | For example, let's say you wanted to be able to write \f(CW\*(C`./Build |
581 | commit\*(C'\fR to test your code and commit it to Subversion. |
582 | .PP |
583 | .Vb 5 |
584 | \& # Build.PL |
585 | \& use Module::Build; |
586 | \& my $class = Module::Build\->subclass( |
587 | \& class => "Module::Build::Custom", |
588 | \& code => <<'SUBCLASS' ); |
589 | .Ve |
590 | .PP |
591 | .Vb 2 |
592 | \& sub ACTION_commit { |
593 | \& my $self = shift; |
594 | .Ve |
595 | .PP |
596 | .Vb 4 |
597 | \& $self\->depends_on("test"); |
598 | \& $self\->do_system(qw(svn commit)); |
599 | \& } |
600 | \& SUBCLASS |
601 | .Ve |
602 | .Sh "Bundling Module::Build" |
603 | .IX Subsection "Bundling Module::Build" |
604 | Note: This section probably needs an update as the technology improves |
605 | (see contrib/bundle.pl in the distribution). |
606 | .PP |
607 | Suppose you want to use some new-ish features of Module::Build, |
608 | e.g. newer than the version of Module::Build your users are likely to |
609 | already have installed on their systems. The first thing you should |
610 | do is set \f(CW\*(C`configure_requires\*(C'\fR to your minimum version of |
611 | Module::Build. See Module::Build::Authoring. |
612 | .PP |
613 | But not every build system honors \f(CW\*(C`configure_requires\*(C'\fR yet. Here's |
614 | how you can ship a copy of Module::Build, but still use a newer |
615 | installed version to take advantage of any bug fixes and upgrades. |
616 | .PP |
617 | First, install Module::Build into \fIYour\-Project/inc/Module\-Build\fR. |
618 | \&\s-1CPAN\s0 will not index anything in the \fIinc\fR directory so this copy will |
619 | not show up in \s-1CPAN\s0 searches. |
620 | .PP |
621 | .Vb 4 |
622 | \& cd Module\-Build |
623 | \& perl Build.PL \-\-install_base /path/to/Your\-Project/inc/Module\-Build |
624 | \& ./Build test |
625 | \& ./Build install |
626 | .Ve |
627 | .PP |
628 | You should now have all the Module::Build .pm files in |
629 | \&\fIYour\-Project/inc/Module\-Build/lib/perl5\fR. |
630 | .PP |
631 | Next, add this to the top of your \fIBuild.PL\fR. |
632 | .PP |
633 | .Vb 1 |
634 | \& my $Bundled_MB = 0.30; # or whatever version it was. |
635 | .Ve |
636 | .PP |
637 | .Vb 4 |
638 | \& # Find out what version of Module::Build is installed or fail quietly. |
639 | \& # This should be cross\-platform. |
640 | \& my $Installed_MB = |
641 | \& `$^X \-e "eval q{require Module::Build; print Module::Build\->VERSION} or exit 1"; |
642 | .Ve |
643 | .PP |
644 | .Vb 2 |
645 | \& # some operating systems put a newline at the end of every print. |
646 | \& chomp $Installed_MB; |
647 | .Ve |
648 | .PP |
649 | .Vb 1 |
650 | \& $Installed_MB = 0 if $?; |
651 | .Ve |
652 | .PP |
653 | .Vb 2 |
654 | \& # Use our bundled copy of Module::Build if it's newer than the installed. |
655 | \& unshift @INC, "inc/Module\-Build/lib/perl5" if $Bundled_MB > $Installed_MB; |
656 | .Ve |
657 | .PP |
658 | .Vb 1 |
659 | \& require Module::Build; |
660 | .Ve |
661 | .PP |
662 | And write the rest of your \fIBuild.PL\fR normally. Module::Build will |
663 | remember your change to \f(CW@INC\fR and use it when you run \fI./Build\fR. |
664 | .PP |
665 | In the future, we hope to provide a more automated solution for this |
666 | scenario; see \f(CW\*(C`inc/latest.pm\*(C'\fR in the Module::Build distribution for |
667 | one indication of the direction we're moving. |
668 | .SH "AUTHOR" |
669 | .IX Header "AUTHOR" |
670 | Ken Williams <kwilliams@cpan.org> |
671 | .SH "COPYRIGHT" |
672 | .IX Header "COPYRIGHT" |
673 | Copyright (c) 2001\-2008 Ken Williams. All rights reserved. |
674 | .PP |
675 | This library is free software; you can redistribute it and/or |
676 | modify it under the same terms as Perl itself. |
677 | .SH "SEE ALSO" |
678 | .IX Header "SEE ALSO" |
679 | \&\fIperl\fR\|(1), Module::Build(3), Module::Build::Authoring(3), |
680 | Module::Build::API(3) |