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