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