Commit | Line | Data |
---|---|---|
bb4e9162 YST |
1 | package Module::Build; |
2 | ||
3 | # This module doesn't do much of anything itself, it inherits from the | |
4 | # modules that do the real work. The only real thing it has to do is | |
5 | # figure out which OS-specific module to pull in. Many of the | |
6 | # OS-specific modules don't do anything either - most of the work is | |
7 | # done in Module::Build::Base. | |
8 | ||
9 | use strict; | |
10 | use File::Spec (); | |
11 | use File::Path (); | |
12 | use File::Basename (); | |
13 | ||
14 | use Module::Build::Base; | |
15 | ||
16 | use vars qw($VERSION @ISA); | |
17 | @ISA = qw(Module::Build::Base); | |
15cb7b9d | 18 | $VERSION = '0.31012'; |
bb4e9162 YST |
19 | $VERSION = eval $VERSION; |
20 | ||
21 | # Okay, this is the brute-force method of finding out what kind of | |
22 | # platform we're on. I don't know of a systematic way. These values | |
23 | # came from the latest (bleadperl) perlport.pod. | |
24 | ||
25 | my %OSTYPES = qw( | |
26 | aix Unix | |
27 | bsdos Unix | |
28 | dgux Unix | |
6e3f52c9 | 29 | dragonfly Unix |
bb4e9162 YST |
30 | dynixptx Unix |
31 | freebsd Unix | |
32 | linux Unix | |
df00ff3b | 33 | haiku Unix |
bb4e9162 YST |
34 | hpux Unix |
35 | irix Unix | |
36 | darwin Unix | |
37 | machten Unix | |
ad1ae84a | 38 | midnightbsd Unix |
15cb7b9d | 39 | mirbsd Unix |
bb4e9162 YST |
40 | next Unix |
41 | openbsd Unix | |
42 | netbsd Unix | |
43 | dec_osf Unix | |
738349a8 | 44 | nto Unix |
bb4e9162 YST |
45 | svr4 Unix |
46 | svr5 Unix | |
47 | sco_sv Unix | |
48 | unicos Unix | |
49 | unicosmk Unix | |
50 | solaris Unix | |
51 | sunos Unix | |
52 | cygwin Unix | |
53 | os2 Unix | |
77e96e88 | 54 | interix Unix |
738349a8 SH |
55 | gnu Unix |
56 | gnukfreebsd Unix | |
57 | ||
bb4e9162 YST |
58 | dos Windows |
59 | MSWin32 Windows | |
60 | ||
61 | os390 EBCDIC | |
62 | os400 EBCDIC | |
63 | posix-bc EBCDIC | |
64 | vmesa EBCDIC | |
65 | ||
66 | MacOS MacOS | |
67 | VMS VMS | |
68 | VOS VOS | |
69 | riscos RiscOS | |
70 | amigaos Amiga | |
71 | mpeix MPEiX | |
72 | ); | |
73 | ||
74 | # Inserts the given module into the @ISA hierarchy between | |
75 | # Module::Build and its immediate parent | |
76 | sub _interpose_module { | |
77 | my ($self, $mod) = @_; | |
78 | eval "use $mod"; | |
79 | die $@ if $@; | |
80 | ||
81 | no strict 'refs'; | |
82 | my $top_class = $mod; | |
83 | while (@{"${top_class}::ISA"}) { | |
84 | last if ${"${top_class}::ISA"}[0] eq $ISA[0]; | |
85 | $top_class = ${"${top_class}::ISA"}[0]; | |
86 | } | |
87 | ||
88 | @{"${top_class}::ISA"} = @ISA; | |
89 | @ISA = ($mod); | |
90 | } | |
91 | ||
92 | if (grep {-e File::Spec->catfile($_, qw(Module Build Platform), $^O) . '.pm'} @INC) { | |
93 | __PACKAGE__->_interpose_module("Module::Build::Platform::$^O"); | |
94 | ||
95 | } elsif (exists $OSTYPES{$^O}) { | |
96 | __PACKAGE__->_interpose_module("Module::Build::Platform::$OSTYPES{$^O}"); | |
97 | ||
98 | } else { | |
99 | warn "Unknown OS type '$^O' - using default settings\n"; | |
100 | } | |
101 | ||
102 | sub os_type { $OSTYPES{$^O} } | |
103 | ||
c1d8f74e SP |
104 | sub is_vmsish { return ((os_type() || '') eq 'VMS') } |
105 | sub is_windowsish { return ((os_type() || '') eq 'Windows') } | |
106 | sub is_unixish { return ((os_type() || '') eq 'Unix') } | |
107 | ||
bb4e9162 YST |
108 | 1; |
109 | ||
110 | __END__ | |
111 | ||
112 | ||
113 | =head1 NAME | |
114 | ||
115 | Module::Build - Build and install Perl modules | |
116 | ||
117 | ||
118 | =head1 SYNOPSIS | |
119 | ||
120 | Standard process for building & installing modules: | |
121 | ||
122 | perl Build.PL | |
123 | ./Build | |
124 | ./Build test | |
125 | ./Build install | |
126 | ||
127 | Or, if you're on a platform (like DOS or Windows) that doesn't require | |
128 | the "./" notation, you can do this: | |
129 | ||
130 | perl Build.PL | |
131 | Build | |
132 | Build test | |
133 | Build install | |
134 | ||
135 | ||
136 | =head1 DESCRIPTION | |
137 | ||
138 | C<Module::Build> is a system for building, testing, and installing | |
139 | Perl modules. It is meant to be an alternative to | |
140 | C<ExtUtils::MakeMaker>. Developers may alter the behavior of the | |
141 | module through subclassing in a much more straightforward way than | |
142 | with C<MakeMaker>. It also does not require a C<make> on your system | |
143 | - most of the C<Module::Build> code is pure-perl and written in a very | |
144 | cross-platform way. In fact, you don't even need a shell, so even | |
145 | platforms like MacOS (traditional) can use it fairly easily. Its only | |
146 | prerequisites are modules that are included with perl 5.6.0, and it | |
147 | works fine on perl 5.005 if you can install a few additional modules. | |
148 | ||
149 | See L<"MOTIVATIONS"> for more comparisons between C<ExtUtils::MakeMaker> | |
150 | and C<Module::Build>. | |
151 | ||
152 | To install C<Module::Build>, and any other module that uses | |
153 | C<Module::Build> for its installation process, do the following: | |
154 | ||
155 | perl Build.PL # 'Build.PL' script creates the 'Build' script | |
156 | ./Build # Need ./ to ensure we're using this "Build" script | |
157 | ./Build test # and not another one that happens to be in the PATH | |
158 | ./Build install | |
159 | ||
160 | This illustrates initial configuration and the running of three | |
161 | 'actions'. In this case the actions run are 'build' (the default | |
162 | action), 'test', and 'install'. Other actions defined so far include: | |
163 | ||
77e96e88 RGS |
164 | build manifest |
165 | clean manpages | |
166 | code pardist | |
47f13fd5 SP |
167 | config_data ppd |
168 | diff ppmdist | |
169 | dist prereq_report | |
170 | distcheck pure_install | |
171 | distclean realclean | |
77e96e88 RGS |
172 | distdir retest |
173 | distmeta skipcheck | |
174 | distsign test | |
7253302f SP |
175 | disttest testall |
176 | docs testcover | |
177 | fakeinstall testdb | |
178 | help testpod | |
179 | html testpodcoverage | |
180 | install versioninstall | |
bb4e9162 YST |
181 | |
182 | ||
183 | You can run the 'help' action for a complete list of actions. | |
184 | ||
185 | ||
186 | =head1 GUIDE TO DOCUMENTATION | |
187 | ||
188 | The documentation for C<Module::Build> is broken up into three sections: | |
189 | ||
190 | =over | |
191 | ||
192 | =item General Usage (L<Module::Build>) | |
193 | ||
194 | This is the document you are currently reading. It describes basic | |
195 | usage and background information. Its main purpose is to assist the | |
196 | user who wants to learn how to invoke and control C<Module::Build> | |
197 | scripts at the command line. | |
198 | ||
199 | =item Authoring Reference (L<Module::Build::Authoring>) | |
200 | ||
dc8021d3 SP |
201 | This document describes the structure and organization of |
202 | C<Module::Build>, and the relevant concepts needed by authors who are | |
bb4e9162 | 203 | writing F<Build.PL> scripts for a distribution or controlling |
dc8021d3 SP |
204 | C<Module::Build> processes programmatically. |
205 | ||
206 | =item API Reference (L<Module::Build::API>) | |
207 | ||
208 | This is a reference to the C<Module::Build> API. | |
bb4e9162 YST |
209 | |
210 | =item Cookbook (L<Module::Build::Cookbook>) | |
211 | ||
212 | This document demonstrates how to accomplish many common tasks. It | |
213 | covers general command line usage and authoring of F<Build.PL> | |
214 | scripts. Includes working examples. | |
215 | ||
216 | =back | |
217 | ||
218 | ||
219 | =head1 ACTIONS | |
220 | ||
221 | There are some general principles at work here. First, each task when | |
222 | building a module is called an "action". These actions are listed | |
223 | above; they correspond to the building, testing, installing, | |
224 | packaging, etc., tasks. | |
225 | ||
226 | Second, arguments are processed in a very systematic way. Arguments | |
227 | are always key=value pairs. They may be specified at C<perl Build.PL> | |
228 | time (i.e. C<perl Build.PL destdir=/my/secret/place>), in which case | |
229 | their values last for the lifetime of the C<Build> script. They may | |
230 | also be specified when executing a particular action (i.e. | |
231 | C<Build test verbose=1>), in which case their values last only for the | |
232 | lifetime of that command. Per-action command line parameters take | |
233 | precedence over parameters specified at C<perl Build.PL> time. | |
234 | ||
7a827510 RGS |
235 | The build process also relies heavily on the C<Config.pm> module. |
236 | If the user wishes to override any of the | |
bb4e9162 YST |
237 | values in C<Config.pm>, she may specify them like so: |
238 | ||
239 | perl Build.PL --config cc=gcc --config ld=gcc | |
240 | ||
241 | The following build actions are provided by default. | |
242 | ||
243 | =over 4 | |
244 | ||
245 | =item build | |
246 | ||
a314697d RS |
247 | [version 0.01] |
248 | ||
bb4e9162 YST |
249 | If you run the C<Build> script without any arguments, it runs the |
250 | C<build> action, which in turn runs the C<code> and C<docs> actions. | |
251 | ||
252 | This is analogous to the MakeMaker 'make all' target. | |
253 | ||
254 | =item clean | |
255 | ||
a314697d RS |
256 | [version 0.01] |
257 | ||
bb4e9162 YST |
258 | This action will clean up any files that the build process may have |
259 | created, including the C<blib/> directory (but not including the | |
260 | C<_build/> directory and the C<Build> script itself). | |
261 | ||
262 | =item code | |
263 | ||
a314697d RS |
264 | [version 0.20] |
265 | ||
bb4e9162 YST |
266 | This action builds your codebase. |
267 | ||
268 | By default it just creates a C<blib/> directory and copies any C<.pm> | |
269 | and C<.pod> files from your C<lib/> directory into the C<blib/> | |
270 | directory. It also compiles any C<.xs> files from C<lib/> and places | |
271 | them in C<blib/>. Of course, you need a working C compiler (probably | |
272 | the same one that built perl itself) for the compilation to work | |
273 | properly. | |
274 | ||
275 | The C<code> action also runs any C<.PL> files in your F<lib/> | |
276 | directory. Typically these create other files, named the same but | |
277 | without the C<.PL> ending. For example, a file F<lib/Foo/Bar.pm.PL> | |
278 | could create the file F<lib/Foo/Bar.pm>. The C<.PL> files are | |
279 | processed first, so any C<.pm> files (or other kinds that we deal | |
280 | with) will get copied correctly. | |
281 | ||
282 | =item config_data | |
283 | ||
a314697d RS |
284 | [version 0.26] |
285 | ||
bb4e9162 YST |
286 | ... |
287 | ||
288 | =item diff | |
289 | ||
a314697d RS |
290 | [version 0.14] |
291 | ||
bb4e9162 YST |
292 | This action will compare the files about to be installed with their |
293 | installed counterparts. For .pm and .pod files, a diff will be shown | |
294 | (this currently requires a 'diff' program to be in your PATH). For | |
295 | other files like compiled binary files, we simply report whether they | |
296 | differ. | |
297 | ||
298 | A C<flags> parameter may be passed to the action, which will be passed | |
299 | to the 'diff' program. Consult your 'diff' documentation for the | |
300 | parameters it will accept - a good one is C<-u>: | |
301 | ||
302 | ./Build diff flags=-u | |
303 | ||
304 | =item dist | |
305 | ||
a314697d RS |
306 | [version 0.02] |
307 | ||
bb4e9162 YST |
308 | This action is helpful for module authors who want to package up their |
309 | module for source distribution through a medium like CPAN. It will create a | |
310 | tarball of the files listed in F<MANIFEST> and compress the tarball using | |
311 | GZIP compression. | |
312 | ||
313 | By default, this action will use the external C<tar> and C<gzip> | |
314 | executables on Unix-like platforms, and the C<Archive::Tar> module | |
315 | elsewhere. However, you can force it to use whatever executable you | |
316 | want by supplying an explicit C<tar> (and optional C<gzip>) parameter: | |
317 | ||
318 | ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe | |
319 | ||
320 | =item distcheck | |
321 | ||
a314697d RS |
322 | [version 0.05] |
323 | ||
bb4e9162 YST |
324 | Reports which files are in the build directory but not in the |
325 | F<MANIFEST> file, and vice versa. (See L<manifest> for details.) | |
326 | ||
327 | =item distclean | |
328 | ||
a314697d RS |
329 | [version 0.05] |
330 | ||
bb4e9162 YST |
331 | Performs the 'realclean' action and then the 'distcheck' action. |
332 | ||
333 | =item distdir | |
334 | ||
a314697d RS |
335 | [version 0.05] |
336 | ||
bb4e9162 YST |
337 | Creates a "distribution directory" named C<$dist_name-$dist_version> |
338 | (if that directory already exists, it will be removed first), then | |
339 | copies all the files listed in the F<MANIFEST> file to that directory. | |
340 | This directory is what the distribution tarball is created from. | |
341 | ||
342 | =item distmeta | |
343 | ||
a314697d RS |
344 | [version 0.21] |
345 | ||
bb4e9162 YST |
346 | Creates the F<META.yml> file that describes the distribution. |
347 | ||
348 | F<META.yml> is a file containing various bits of "metadata" about the | |
349 | distribution. The metadata includes the distribution name, version, | |
350 | abstract, prerequisites, license, and various other data about the | |
a314697d RS |
351 | distribution. This file is created as F<META.yml> in YAML format. |
352 | It is recommended that the C<YAML> module be installed to create it. | |
353 | If the C<YAML> module is not installed, an internal module supplied | |
354 | with Module::Build will be used to write the META.yml file, and this | |
355 | will most likely be fine. | |
356 | ||
bb4e9162 YST |
357 | F<META.yml> file must also be listed in F<MANIFEST> - if it's not, a |
358 | warning will be issued. | |
359 | ||
360 | The current version of the F<META.yml> specification can be found at | |
77e96e88 | 361 | L<http://module-build.sourceforge.net/META-spec-current.html> |
bb4e9162 YST |
362 | |
363 | =item distsign | |
364 | ||
a314697d RS |
365 | [version 0.16] |
366 | ||
bb4e9162 YST |
367 | Uses C<Module::Signature> to create a SIGNATURE file for your |
368 | distribution, and adds the SIGNATURE file to the distribution's | |
369 | MANIFEST. | |
370 | ||
371 | =item disttest | |
372 | ||
a314697d RS |
373 | [version 0.05] |
374 | ||
bb4e9162 YST |
375 | Performs the 'distdir' action, then switches into that directory and |
376 | runs a C<perl Build.PL>, followed by the 'build' and 'test' actions in | |
377 | that directory. | |
378 | ||
379 | =item docs | |
380 | ||
a314697d RS |
381 | [version 0.20] |
382 | ||
bb4e9162 YST |
383 | This will generate documentation (e.g. Unix man pages and html |
384 | documents) for any installable items under B<blib/> that | |
385 | contain POD. If there are no C<bindoc> or C<libdoc> installation | |
386 | targets defined (as will be the case on systems that don't support | |
387 | Unix manpages) no action is taken for manpages. If there are no | |
388 | C<binhtml> or C<libhtml> installation targets defined no action is | |
389 | taken for html documents. | |
390 | ||
391 | =item fakeinstall | |
392 | ||
a314697d RS |
393 | [version 0.02] |
394 | ||
bb4e9162 YST |
395 | This is just like the C<install> action, but it won't actually do |
396 | anything, it will just report what it I<would> have done if you had | |
397 | actually run the C<install> action. | |
398 | ||
399 | =item help | |
400 | ||
a314697d RS |
401 | [version 0.03] |
402 | ||
bb4e9162 YST |
403 | This action will simply print out a message that is meant to help you |
404 | use the build process. It will show you a list of available build | |
405 | actions too. | |
406 | ||
407 | With an optional argument specifying an action name (e.g. C<Build help | |
408 | test>), the 'help' action will show you any POD documentation it can | |
409 | find for that action. | |
410 | ||
411 | =item html | |
412 | ||
a314697d RS |
413 | [version 0.26] |
414 | ||
bb4e9162 YST |
415 | This will generate HTML documentation for any binary or library files |
416 | under B<blib/> that contain POD. The HTML documentation will only be | |
417 | installed if the install paths can be determined from values in | |
418 | C<Config.pm>. You can also supply or override install paths on the | |
419 | command line by specifying C<install_path> values for the C<binhtml> | |
420 | and/or C<libhtml> installation targets. | |
421 | ||
422 | =item install | |
423 | ||
a314697d RS |
424 | [version 0.01] |
425 | ||
bb4e9162 | 426 | This action will use C<ExtUtils::Install> to install the files from |
dc8021d3 | 427 | C<blib/> into the system. See L<"INSTALL PATHS"> |
bb4e9162 YST |
428 | for details about how Module::Build determines where to install |
429 | things, and how to influence this process. | |
430 | ||
431 | If you want the installation process to look around in C<@INC> for | |
432 | other versions of the stuff you're installing and try to delete it, | |
433 | you can use the C<uninst> parameter, which tells C<ExtUtils::Install> to | |
434 | do so: | |
435 | ||
436 | ./Build install uninst=1 | |
437 | ||
438 | This can be a good idea, as it helps prevent multiple versions of a | |
439 | module from being present on your system, which can be a confusing | |
440 | situation indeed. | |
441 | ||
442 | =item manifest | |
443 | ||
a314697d RS |
444 | [version 0.05] |
445 | ||
bb4e9162 YST |
446 | This is an action intended for use by module authors, not people |
447 | installing modules. It will bring the F<MANIFEST> up to date with the | |
448 | files currently present in the distribution. You may use a | |
449 | F<MANIFEST.SKIP> file to exclude certain files or directories from | |
450 | inclusion in the F<MANIFEST>. F<MANIFEST.SKIP> should contain a bunch | |
451 | of regular expressions, one per line. If a file in the distribution | |
452 | directory matches any of the regular expressions, it won't be included | |
453 | in the F<MANIFEST>. | |
454 | ||
455 | The following is a reasonable F<MANIFEST.SKIP> starting point, you can | |
456 | add your own stuff to it: | |
457 | ||
458 | ^_build | |
459 | ^Build$ | |
460 | ^blib | |
461 | ~$ | |
462 | \.bak$ | |
463 | ^MANIFEST\.SKIP$ | |
464 | CVS | |
465 | ||
466 | See the L<distcheck> and L<skipcheck> actions if you want to find out | |
467 | what the C<manifest> action would do, without actually doing anything. | |
468 | ||
469 | =item manpages | |
470 | ||
a314697d RS |
471 | [version 0.28] |
472 | ||
bb4e9162 YST |
473 | This will generate man pages for any binary or library files under |
474 | B<blib/> that contain POD. The man pages will only be installed if the | |
475 | install paths can be determined from values in C<Config.pm>. You can | |
476 | also supply or override install paths by specifying there values on | |
477 | the command line with the C<bindoc> and C<libdoc> installation | |
478 | targets. | |
479 | ||
77e96e88 RGS |
480 | =item pardist |
481 | ||
482 | [version 0.2806] | |
483 | ||
484 | Generates a PAR binary distribution for use with L<PAR> or L<PAR::Dist>. | |
485 | ||
486 | It requires that the PAR::Dist module (version 0.17 and up) is | |
487 | installed on your system. | |
488 | ||
bb4e9162 YST |
489 | =item ppd |
490 | ||
a314697d RS |
491 | [version 0.20] |
492 | ||
bb4e9162 YST |
493 | Build a PPD file for your distribution. |
494 | ||
495 | This action takes an optional argument C<codebase> which is used in | |
496 | the generated ppd file to specify the (usually relative) URL of the | |
497 | distribution. By default, this value is the distribution name without | |
498 | any path information. | |
499 | ||
500 | Example: | |
501 | ||
502 | ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz" | |
503 | ||
504 | =item ppmdist | |
505 | ||
a314697d RS |
506 | [version 0.23] |
507 | ||
bb4e9162 YST |
508 | Generates a PPM binary distribution and a PPD description file. This |
509 | action also invokes the 'ppd' action, so it can accept the same | |
510 | C<codebase> argument described under that action. | |
511 | ||
512 | This uses the same mechanism as the C<dist> action to tar & zip its | |
513 | output, so you can supply C<tar> and/or C<gzip> parameters to affect | |
514 | the result. | |
515 | ||
516 | =item prereq_report | |
517 | ||
a314697d RS |
518 | [version 0.28] |
519 | ||
bb4e9162 YST |
520 | This action prints out a list of all prerequisites, the versions required, and |
521 | the versions actually installed. This can be useful for reviewing the | |
522 | configuration of your system prior to a build, or when compiling data to send | |
523 | for a bug report. | |
524 | ||
525 | =item pure_install | |
526 | ||
a314697d RS |
527 | [version 0.28] |
528 | ||
bb4e9162 | 529 | This action is identical to the C<install> action. In the future, |
7a827510 | 530 | though, when C<install> starts writing to the file |
bb4e9162 YST |
531 | F<$(INSTALLARCHLIB)/perllocal.pod>, C<pure_install> won't, and that |
532 | will be the only difference between them. | |
533 | ||
534 | =item realclean | |
535 | ||
a314697d RS |
536 | [version 0.01] |
537 | ||
bb4e9162 YST |
538 | This action is just like the C<clean> action, but also removes the |
539 | C<_build> directory and the C<Build> script. If you run the | |
540 | C<realclean> action, you are essentially starting over, so you will | |
541 | have to re-create the C<Build> script again. | |
542 | ||
77e96e88 RGS |
543 | =item retest |
544 | ||
545 | [version 0.2806] | |
546 | ||
547 | This is just like the C<test> action, but doesn't actually build the | |
548 | distribution first, and doesn't add F<blib/> to the load path, and | |
549 | therefore will test against a I<previously> installed version of the | |
550 | distribution. This can be used to verify that a certain installed | |
551 | distribution still works, or to see whether newer versions of a | |
552 | distribution still pass the old regression tests, and so on. | |
553 | ||
bb4e9162 YST |
554 | =item skipcheck |
555 | ||
a314697d RS |
556 | [version 0.05] |
557 | ||
bb4e9162 YST |
558 | Reports which files are skipped due to the entries in the |
559 | F<MANIFEST.SKIP> file (See L<manifest> for details) | |
560 | ||
561 | =item test | |
562 | ||
a314697d RS |
563 | [version 0.01] |
564 | ||
738349a8 SH |
565 | This will use C<Test::Harness> or C<TAP::Harness> to run any regression |
566 | tests and report their results. Tests can be defined in the standard | |
567 | places: a file called C<test.pl> in the top-level directory, or several | |
568 | files ending with C<.t> in a C<t/> directory. | |
bb4e9162 YST |
569 | |
570 | If you want tests to be 'verbose', i.e. show details of test execution | |
571 | rather than just summary information, pass the argument C<verbose=1>. | |
572 | ||
573 | If you want to run tests under the perl debugger, pass the argument | |
574 | C<debugger=1>. | |
575 | ||
738349a8 SH |
576 | If you want to have Module::Build find test files with different file |
577 | name extensions, pass the C<test_file_exts> argument with an array | |
578 | of extensions, such as C<[qw( .t .s .z )]>. | |
579 | ||
580 | If you want test to be run by C<TAP::Harness>, rather than C<Test::Harness>, | |
581 | pass the argument C<tap_harness_args> as an array reference of arguments to | |
582 | pass to the TAP::Harness constructor. | |
583 | ||
bb4e9162 YST |
584 | In addition, if a file called C<visual.pl> exists in the top-level |
585 | directory, this file will be executed as a Perl script and its output | |
586 | will be shown to the user. This is a good place to put speed tests or | |
587 | other tests that don't use the C<Test::Harness> format for output. | |
588 | ||
589 | To override the choice of tests to run, you may pass a C<test_files> | |
590 | argument whose value is a whitespace-separated list of test scripts to | |
591 | run. This is especially useful in development, when you only want to | |
592 | run a single test to see whether you've squashed a certain bug yet: | |
593 | ||
594 | ./Build test --test_files t/something_failing.t | |
595 | ||
596 | You may also pass several C<test_files> arguments separately: | |
597 | ||
598 | ./Build test --test_files t/one.t --test_files t/two.t | |
599 | ||
600 | or use a C<glob()>-style pattern: | |
601 | ||
602 | ./Build test --test_files 't/01-*.t' | |
603 | ||
7253302f SP |
604 | =item testall |
605 | ||
606 | [verion 0.2807] | |
607 | ||
608 | [Note: the 'testall' action and the code snippets below are currently | |
609 | in alpha stage, see | |
610 | L<"http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"> ] | |
611 | ||
612 | Runs the C<test> action plus each of the C<test$type> actions defined by | |
613 | the keys of the C<test_types> parameter. | |
614 | ||
615 | Currently, you need to define the ACTION_test$type method yourself and | |
616 | enumerate them in the test_types parameter. | |
617 | ||
618 | my $mb = Module::Build->subclass( | |
619 | code => q( | |
620 | sub ACTION_testspecial { shift->generic_test(type => 'special'); } | |
621 | sub ACTION_testauthor { shift->generic_test(type => 'author'); } | |
622 | ) | |
623 | )->new( | |
624 | ... | |
625 | test_types => { | |
626 | special => '.st', | |
738349a8 | 627 | author => ['.at', '.pt' ], |
7253302f SP |
628 | }, |
629 | ... | |
630 | ||
bb4e9162 YST |
631 | =item testcover |
632 | ||
a314697d RS |
633 | [version 0.26] |
634 | ||
bb4e9162 YST |
635 | Runs the C<test> action using C<Devel::Cover>, generating a |
636 | code-coverage report showing which parts of the code were actually | |
637 | exercised during the tests. | |
638 | ||
639 | To pass options to C<Devel::Cover>, set the C<$DEVEL_COVER_OPTIONS> | |
640 | environment variable: | |
641 | ||
642 | DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover | |
643 | ||
644 | =item testdb | |
645 | ||
a314697d RS |
646 | [version 0.05] |
647 | ||
bb4e9162 YST |
648 | This is a synonym for the 'test' action with the C<debugger=1> |
649 | argument. | |
650 | ||
651 | =item testpod | |
652 | ||
a314697d RS |
653 | [version 0.25] |
654 | ||
bb4e9162 YST |
655 | This checks all the files described in the C<docs> action and |
656 | produces C<Test::Harness>-style output. If you are a module author, | |
657 | this is useful to run before creating a new release. | |
658 | ||
a314697d RS |
659 | =item testpodcoverage |
660 | ||
661 | [version 0.28] | |
662 | ||
663 | This checks the pod coverage of the distribution and | |
664 | produces C<Test::Harness>-style output. If you are a module author, | |
665 | this is useful to run before creating a new release. | |
666 | ||
bb4e9162 YST |
667 | =item versioninstall |
668 | ||
a314697d RS |
669 | [version 0.16] |
670 | ||
bb4e9162 YST |
671 | ** Note: since C<only.pm> is so new, and since we just recently added |
672 | support for it here too, this feature is to be considered | |
673 | experimental. ** | |
674 | ||
675 | If you have the C<only.pm> module installed on your system, you can | |
676 | use this action to install a module into the version-specific library | |
677 | trees. This means that you can have several versions of the same | |
678 | module installed and C<use> a specific one like this: | |
679 | ||
680 | use only MyModule => 0.55; | |
681 | ||
682 | To override the default installation libraries in C<only::config>, | |
683 | specify the C<versionlib> parameter when you run the C<Build.PL> script: | |
684 | ||
685 | perl Build.PL --versionlib /my/version/place/ | |
686 | ||
687 | To override which version the module is installed as, specify the | |
688 | C<versionlib> parameter when you run the C<Build.PL> script: | |
689 | ||
690 | perl Build.PL --version 0.50 | |
691 | ||
692 | See the C<only.pm> documentation for more information on | |
693 | version-specific installs. | |
694 | ||
695 | =back | |
696 | ||
697 | ||
698 | =head1 OPTIONS | |
699 | ||
700 | =head2 Command Line Options | |
701 | ||
702 | The following options can be used during any invocation of C<Build.PL> | |
703 | or the Build script, during any action. For information on other | |
704 | options specific to an action, see the documentation for the | |
705 | respective action. | |
706 | ||
707 | NOTE: There is some preliminary support for options to use the more | |
708 | familiar long option style. Most options can be preceded with the | |
709 | C<--> long option prefix, and the underscores changed to dashes | |
710 | (e.g. --use-rcfile). Additionally, the argument to boolean options is | |
711 | optional, and boolean options can be negated by prefixing them with | |
712 | 'no' or 'no-' (e.g. --noverbose or --no-verbose). | |
713 | ||
714 | =over 4 | |
715 | ||
716 | =item quiet | |
717 | ||
718 | Suppress informative messages on output. | |
719 | ||
720 | =item use_rcfile | |
721 | ||
722 | Load the F<~/.modulebuildrc> option file. This option can be set to | |
723 | false to prevent the custom resource file from being loaded. | |
724 | ||
725 | =item verbose | |
726 | ||
727 | Display extra information about the Build on output. | |
728 | ||
0ec9ad96 SP |
729 | =item allow_mb_mismatch |
730 | ||
731 | Suppresses the check upon startup that the version of Module::Build | |
732 | we're now running under is the same version that was initially invoked | |
733 | when building the distribution (i.e. when the C<Build.PL> script was | |
734 | first run). Use with caution. | |
735 | ||
bb4e9162 YST |
736 | =back |
737 | ||
738 | ||
739 | =head2 Default Options File (F<.modulebuildrc>) | |
740 | ||
a314697d RS |
741 | [version 0.28] |
742 | ||
dc8021d3 SP |
743 | When Module::Build starts up, it will look first for a file, |
744 | F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look | |
745 | in the the F<.modulebuildrc> file in the directories referred to by | |
746 | the environment variables C<HOMEDRIVE> + C<HOMEDIR>, C<USERPROFILE>, | |
747 | C<APPDATA>, C<WINDIR>, C<SYS$LOGIN>. If the file exists, the options | |
bb4e9162 YST |
748 | specified there will be used as defaults, as if they were typed on the |
749 | command line. The defaults can be overridden by specifying new values | |
750 | on the command line. | |
751 | ||
752 | The action name must come at the beginning of the line, followed by any | |
753 | amount of whitespace and then the options. Options are given the same | |
754 | as they would be on the command line. They can be separated by any | |
755 | amount of whitespace, including newlines, as long there is whitespace at | |
756 | the beginning of each continued line. Anything following a hash mark (C<#>) | |
757 | is considered a comment, and is stripped before parsing. If more than | |
758 | one line begins with the same action name, those lines are merged into | |
759 | one set of options. | |
760 | ||
761 | Besides the regular actions, there are two special pseudo-actions: the | |
762 | key C<*> (asterisk) denotes any global options that should be applied | |
763 | to all actions, and the key 'Build_PL' specifies options to be applied | |
764 | when you invoke C<perl Build.PL>. | |
765 | ||
766 | * verbose=1 # global options | |
767 | diff flags=-u | |
768 | install --install_base /home/ken | |
769 | --install_path html=/home/ken/docs/html | |
770 | ||
771 | If you wish to locate your resource file in a different location, you | |
772 | can set the environment variable 'MODULEBUILDRC' to the complete | |
773 | absolute path of the file containing your options. | |
774 | ||
775 | ||
776 | =head1 INSTALL PATHS | |
777 | ||
a314697d RS |
778 | [version 0.19] |
779 | ||
bb4e9162 YST |
780 | When you invoke Module::Build's C<build> action, it needs to figure |
781 | out where to install things. The nutshell version of how this works | |
782 | is that default installation locations are determined from | |
783 | F<Config.pm>, and they may be overridden by using the C<install_path> | |
784 | parameter. An C<install_base> parameter lets you specify an | |
785 | alternative installation root like F</home/foo>, and a C<destdir> lets | |
786 | you specify a temporary installation directory like F</tmp/install> in | |
787 | case you want to create bundled-up installable packages. | |
788 | ||
789 | Natively, Module::Build provides default installation locations for | |
790 | the following types of installable items: | |
791 | ||
792 | =over 4 | |
793 | ||
794 | =item lib | |
795 | ||
796 | Usually pure-Perl module files ending in F<.pm>. | |
797 | ||
798 | =item arch | |
799 | ||
800 | "Architecture-dependent" module files, usually produced by compiling | |
801 | XS, Inline, or similar code. | |
802 | ||
803 | =item script | |
804 | ||
805 | Programs written in pure Perl. In order to improve reuse, try to make | |
806 | these as small as possible - put the code into modules whenever | |
807 | possible. | |
808 | ||
809 | =item bin | |
810 | ||
811 | "Architecture-dependent" executable programs, i.e. compiled C code or | |
812 | something. Pretty rare to see this in a perl distribution, but it | |
813 | happens. | |
814 | ||
815 | =item bindoc | |
816 | ||
817 | Documentation for the stuff in C<script> and C<bin>. Usually | |
818 | generated from the POD in those files. Under Unix, these are manual | |
819 | pages belonging to the 'man1' category. | |
820 | ||
821 | =item libdoc | |
822 | ||
823 | Documentation for the stuff in C<lib> and C<arch>. This is usually | |
824 | generated from the POD in F<.pm> files. Under Unix, these are manual | |
825 | pages belonging to the 'man3' category. | |
826 | ||
827 | =item binhtml | |
828 | ||
829 | This is the same as C<bindoc> above, but applies to html documents. | |
830 | ||
831 | =item libhtml | |
832 | ||
833 | This is the same as C<bindoc> above, but applies to html documents. | |
834 | ||
835 | =back | |
836 | ||
837 | Four other parameters let you control various aspects of how | |
838 | installation paths are determined: | |
839 | ||
840 | =over 4 | |
841 | ||
842 | =item installdirs | |
843 | ||
844 | The default destinations for these installable things come from | |
845 | entries in your system's C<Config.pm>. You can select from three | |
846 | different sets of default locations by setting the C<installdirs> | |
847 | parameter as follows: | |
848 | ||
849 | 'installdirs' set to: | |
850 | core site vendor | |
851 | ||
852 | uses the following defaults from Config.pm: | |
853 | ||
854 | lib => installprivlib installsitelib installvendorlib | |
855 | arch => installarchlib installsitearch installvendorarch | |
856 | script => installscript installsitebin installvendorbin | |
857 | bin => installbin installsitebin installvendorbin | |
858 | bindoc => installman1dir installsiteman1dir installvendorman1dir | |
859 | libdoc => installman3dir installsiteman3dir installvendorman3dir | |
860 | binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*] | |
861 | libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*] | |
862 | ||
863 | * Under some OS (eg. MSWin32) the destination for html documents is | |
864 | determined by the C<Config.pm> entry C<installhtmldir>. | |
865 | ||
866 | The default value of C<installdirs> is "site". If you're creating | |
867 | vendor distributions of module packages, you may want to do something | |
868 | like this: | |
869 | ||
870 | perl Build.PL --installdirs vendor | |
871 | ||
872 | or | |
873 | ||
874 | ./Build install --installdirs vendor | |
875 | ||
876 | If you're installing an updated version of a module that was included | |
877 | with perl itself (i.e. a "core module"), then you may set | |
878 | C<installdirs> to "core" to overwrite the module in its present | |
879 | location. | |
880 | ||
881 | (Note that the 'script' line is different from MakeMaker - | |
882 | unfortunately there's no such thing as "installsitescript" or | |
883 | "installvendorscript" entry in C<Config.pm>, so we use the | |
884 | "installsitebin" and "installvendorbin" entries to at least get the | |
885 | general location right. In the future, if C<Config.pm> adds some more | |
886 | appropriate entries, we'll start using those.) | |
887 | ||
888 | =item install_path | |
889 | ||
890 | Once the defaults have been set, you can override them. | |
891 | ||
892 | On the command line, that would look like this: | |
893 | ||
894 | perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch | |
895 | ||
896 | or this: | |
897 | ||
898 | ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch | |
899 | ||
900 | =item install_base | |
901 | ||
902 | You can also set the whole bunch of installation paths by supplying the | |
903 | C<install_base> parameter to point to a directory on your system. For | |
904 | instance, if you set C<install_base> to "/home/ken" on a Linux | |
905 | system, you'll install as follows: | |
906 | ||
907 | lib => /home/ken/lib/perl5 | |
908 | arch => /home/ken/lib/perl5/i386-linux | |
909 | script => /home/ken/bin | |
910 | bin => /home/ken/bin | |
911 | bindoc => /home/ken/man/man1 | |
912 | libdoc => /home/ken/man/man3 | |
913 | binhtml => /home/ken/html | |
914 | libhtml => /home/ken/html | |
915 | ||
916 | Note that this is I<different> from how MakeMaker's C<PREFIX> | |
77e96e88 | 917 | parameter works. C<install_base> just gives you a default layout under the |
bb4e9162 YST |
918 | directory you specify, which may have little to do with the |
919 | C<installdirs=site> layout. | |
920 | ||
921 | The exact layout under the directory you specify may vary by system - | |
922 | we try to do the "sensible" thing on each platform. | |
923 | ||
924 | =item destdir | |
925 | ||
926 | If you want to install everything into a temporary directory first | |
927 | (for instance, if you want to create a directory tree that a package | |
928 | manager like C<rpm> or C<dpkg> could create a package from), you can | |
929 | use the C<destdir> parameter: | |
930 | ||
931 | perl Build.PL --destdir /tmp/foo | |
932 | ||
933 | or | |
934 | ||
935 | ./Build install --destdir /tmp/foo | |
936 | ||
937 | This will effectively install to "/tmp/foo/$sitelib", | |
938 | "/tmp/foo/$sitearch", and the like, except that it will use | |
939 | C<File::Spec> to make the pathnames work correctly on whatever | |
940 | platform you're installing on. | |
941 | ||
f943a5bf | 942 | =item prefix |
bb4e9162 | 943 | |
f943a5bf SP |
944 | Provided for compatibility with ExtUtils::MakeMaker's PREFIX argument. |
945 | C<prefix> should be used when you wish Module::Build to install your | |
946 | modules, documentation and scripts in the same place | |
947 | ExtUtils::MakeMaker does. | |
bb4e9162 | 948 | |
f943a5bf | 949 | The following are equivalent. |
bb4e9162 | 950 | |
f943a5bf SP |
951 | perl Build.PL --prefix /tmp/foo |
952 | perl Makefile.PL PREFIX=/tmp/foo | |
bb4e9162 | 953 | |
f943a5bf SP |
954 | Because of the very complex nature of the prefixification logic, the |
955 | behavior of PREFIX in MakeMaker has changed subtly over time. | |
956 | Module::Build's --prefix logic is equivalent to the PREFIX logic found | |
957 | in ExtUtils::MakeMaker 6.30. | |
bb4e9162 | 958 | |
f943a5bf SP |
959 | If you do not need to retain compatibility with ExtUtils::MakeMaker or |
960 | are starting a fresh Perl installation we recommand you use | |
961 | C<install_base> instead (and C<INSTALL_BASE> in ExtUtils::MakeMaker). | |
962 | See L<Module::Build::Cookbook/Instaling in the same location as | |
963 | ExtUtils::MakeMaker> for further information. | |
bb4e9162 | 964 | |
bb4e9162 YST |
965 | |
966 | =back | |
967 | ||
968 | ||
969 | =head1 MOTIVATIONS | |
970 | ||
971 | There are several reasons I wanted to start over, and not just fix | |
972 | what I didn't like about MakeMaker: | |
973 | ||
974 | =over 4 | |
975 | ||
976 | =item * | |
977 | ||
978 | I don't like the core idea of MakeMaker, namely that C<make> should be | |
979 | involved in the build process. Here are my reasons: | |
980 | ||
981 | =over 4 | |
982 | ||
983 | =item + | |
984 | ||
985 | When a person is installing a Perl module, what can you assume about | |
986 | their environment? Can you assume they have C<make>? No, but you can | |
987 | assume they have some version of Perl. | |
988 | ||
989 | =item + | |
990 | ||
991 | When a person is writing a Perl module for intended distribution, can | |
992 | you assume that they know how to build a Makefile, so they can | |
993 | customize their build process? No, but you can assume they know Perl, | |
994 | and could customize that way. | |
995 | ||
996 | =back | |
997 | ||
998 | For years, these things have been a barrier to people getting the | |
999 | build/install process to do what they want. | |
1000 | ||
1001 | =item * | |
1002 | ||
1003 | There are several architectural decisions in MakeMaker that make it | |
1004 | very difficult to customize its behavior. For instance, when using | |
1005 | MakeMaker you do C<use ExtUtils::MakeMaker>, but the object created in | |
1006 | C<WriteMakefile()> is actually blessed into a package name that's | |
1007 | created on the fly, so you can't simply subclass | |
1008 | C<ExtUtils::MakeMaker>. There is a workaround C<MY> package that lets | |
1009 | you override certain MakeMaker methods, but only certain explicitly | |
1010 | preselected (by MakeMaker) methods can be overridden. Also, the method | |
1011 | of customization is very crude: you have to modify a string containing | |
1012 | the Makefile text for the particular target. Since these strings | |
1013 | aren't documented, and I<can't> be documented (they take on different | |
1014 | values depending on the platform, version of perl, version of | |
1015 | MakeMaker, etc.), you have no guarantee that your modifications will | |
1016 | work on someone else's machine or after an upgrade of MakeMaker or | |
1017 | perl. | |
1018 | ||
1019 | =item * | |
1020 | ||
1021 | It is risky to make major changes to MakeMaker, since it does so many | |
1022 | things, is so important, and generally works. C<Module::Build> is an | |
1023 | entirely separate package so that I can work on it all I want, without | |
1024 | worrying about backward compatibility. | |
1025 | ||
1026 | =item * | |
1027 | ||
1028 | Finally, Perl is said to be a language for system administration. | |
1029 | Could it really be the case that Perl isn't up to the task of building | |
1030 | and installing software? Even if that software is a bunch of stupid | |
1031 | little C<.pm> files that just need to be copied from one place to | |
1032 | another? My sense was that we could design a system to accomplish | |
1033 | this in a flexible, extensible, and friendly manner. Or die trying. | |
1034 | ||
1035 | =back | |
1036 | ||
1037 | ||
1038 | =head1 TO DO | |
1039 | ||
1040 | The current method of relying on time stamps to determine whether a | |
1041 | derived file is out of date isn't likely to scale well, since it | |
1042 | requires tracing all dependencies backward, it runs into problems on | |
1043 | NFS, and it's just generally flimsy. It would be better to use an MD5 | |
1044 | signature or the like, if available. See C<cons> for an example. | |
1045 | ||
1046 | - append to perllocal.pod | |
1047 | - add a 'plugin' functionality | |
1048 | ||
1049 | ||
1050 | =head1 AUTHOR | |
1051 | ||
1052 | Ken Williams <kwilliams@cpan.org> | |
1053 | ||
1054 | Development questions, bug reports, and patches should be sent to the | |
0ec9ad96 | 1055 | Module-Build mailing list at <module-build@perl.org>. |
bb4e9162 YST |
1056 | |
1057 | Bug reports are also welcome at | |
1058 | <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. | |
1059 | ||
dc8021d3 SP |
1060 | The latest development version is available from the Subversion |
1061 | repository at <https://svn.perl.org/modules/Module-Build/trunk/> | |
bb4e9162 YST |
1062 | |
1063 | ||
1064 | =head1 COPYRIGHT | |
1065 | ||
77e96e88 | 1066 | Copyright (c) 2001-2006 Ken Williams. All rights reserved. |
bb4e9162 YST |
1067 | |
1068 | This library is free software; you can redistribute it and/or | |
1069 | modify it under the same terms as Perl itself. | |
1070 | ||
1071 | ||
1072 | =head1 SEE ALSO | |
1073 | ||
77e96e88 RGS |
1074 | perl(1), L<Module::Build::Cookbook>, L<Module::Build::Authoring>, |
1075 | L<Module::Build::API>, L<ExtUtils::MakeMaker>, L<YAML> | |
bb4e9162 YST |
1076 | |
1077 | F<META.yml> Specification: | |
77e96e88 | 1078 | L<http://module-build.sourceforge.net/META-spec-current.html> |
bb4e9162 YST |
1079 | |
1080 | L<http://www.dsmit.com/cons/> | |
1081 | ||
dc8021d3 SP |
1082 | L<http://search.cpan.org/dist/PerlBuildSystem/> |
1083 | ||
bb4e9162 | 1084 | =cut |