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