This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update generated Module::Build::ConfigData
[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);
08fc25ad 18$VERSION = '0.35_09';
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
08fc25ad
DG
170 build manifest
171 clean manpages
172 code pardist
173 config_data ppd
174 diff ppmdist
175 dist prereq_data
613f422f
DG
176 distcheck prereq_report
177 distclean pure_install
08fc25ad
DG
178 distdir realclean
179 distmeta retest
180 distsign skipcheck
181 disttest test
182 docs testall
183 fakeinstall testcover
184 help testdb
185 html testpod
613f422f
DG
186 install testpodcoverage
187 installdeps versioninstall
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 320By default, this action will use the C<Archive::Tar> module. However, you can
08fc25ad 321force it to use binary "tar" and "gzip" executables by supplying an explicit
94410036 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 357distribution. This file is created as F<META.yml> in YAML format.
613f422f
DG
358It is recommended that the C<YAML::Tiny> module be installed to create it.
359If the C<YAML::Tiny> module is not installed, an internal module supplied
a314697d
RS
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
613f422f
DG
448=item installdeps
449
450[version 0.36]
451
452This action will use the C<cpan_client> parameter as a command to install
453missing prerequisites. You will be prompted whether to install
454optional dependencies.
455
456The C<cpan_client> option defaults to 'cpan' but can be set as an option or in
457F<.modulebuildrc>. It must be a shell command that takes a list of modules to
458install as arguments (e.g. 'cpanp -i' for CPANPLUS). If the program part is a
459relative path (e.g. 'cpan' or 'cpanp'), it will be located relative to the perl
460program that executed Build.PL.
461
462 /opt/perl/5.8.9/bin/perl Build.PL
463 ./Build installdeps --cpan_client 'cpanp -i'
464 # installs to 5.8.9
465
bb4e9162
YST
466=item manifest
467
a314697d
RS
468[version 0.05]
469
bb4e9162
YST
470This is an action intended for use by module authors, not people
471installing modules. It will bring the F<MANIFEST> up to date with the
472files currently present in the distribution. You may use a
473F<MANIFEST.SKIP> file to exclude certain files or directories from
474inclusion in the F<MANIFEST>. F<MANIFEST.SKIP> should contain a bunch
475of regular expressions, one per line. If a file in the distribution
476directory matches any of the regular expressions, it won't be included
477in the F<MANIFEST>.
478
479The following is a reasonable F<MANIFEST.SKIP> starting point, you can
480add your own stuff to it:
481
482 ^_build
483 ^Build$
484 ^blib
485 ~$
486 \.bak$
487 ^MANIFEST\.SKIP$
488 CVS
489
490See the L<distcheck> and L<skipcheck> actions if you want to find out
491what the C<manifest> action would do, without actually doing anything.
492
493=item manpages
494
a314697d
RS
495[version 0.28]
496
bb4e9162
YST
497This will generate man pages for any binary or library files under
498B<blib/> that contain POD. The man pages will only be installed if the
499install paths can be determined from values in C<Config.pm>. You can
500also supply or override install paths by specifying there values on
501the command line with the C<bindoc> and C<libdoc> installation
502targets.
503
77e96e88
RGS
504=item pardist
505
506[version 0.2806]
507
508Generates a PAR binary distribution for use with L<PAR> or L<PAR::Dist>.
509
510It requires that the PAR::Dist module (version 0.17 and up) is
511installed on your system.
512
bb4e9162
YST
513=item ppd
514
a314697d
RS
515[version 0.20]
516
bb4e9162
YST
517Build a PPD file for your distribution.
518
519This action takes an optional argument C<codebase> which is used in
23837600 520the generated PPD file to specify the (usually relative) URL of the
bb4e9162
YST
521distribution. By default, this value is the distribution name without
522any path information.
523
524Example:
525
526 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
527
528=item ppmdist
529
a314697d
RS
530[version 0.23]
531
bb4e9162 532Generates a PPM binary distribution and a PPD description file. This
23837600 533action also invokes the C<ppd> action, so it can accept the same
bb4e9162
YST
534C<codebase> argument described under that action.
535
536This uses the same mechanism as the C<dist> action to tar & zip its
537output, so you can supply C<tar> and/or C<gzip> parameters to affect
538the result.
539
66e531b6
NC
540=item prereq_data
541
542[version 0.32]
543
23837600 544This action prints out a Perl data structure of all prerequisites and the versions
66e531b6
NC
545required. The output can be loaded again using C<eval()>. This can be useful for
546external tools that wish to query a Build script for prerequisites.
547
bb4e9162
YST
548=item prereq_report
549
a314697d
RS
550[version 0.28]
551
bb4e9162
YST
552This action prints out a list of all prerequisites, the versions required, and
553the versions actually installed. This can be useful for reviewing the
554configuration of your system prior to a build, or when compiling data to send
555for a bug report.
556
557=item pure_install
558
a314697d
RS
559[version 0.28]
560
bb4e9162 561This action is identical to the C<install> action. In the future,
08fc25ad 562though, when C<install> starts writing to the file
bb4e9162
YST
563F<$(INSTALLARCHLIB)/perllocal.pod>, C<pure_install> won't, and that
564will be the only difference between them.
565
566=item realclean
567
a314697d
RS
568[version 0.01]
569
bb4e9162
YST
570This action is just like the C<clean> action, but also removes the
571C<_build> directory and the C<Build> script. If you run the
572C<realclean> action, you are essentially starting over, so you will
573have to re-create the C<Build> script again.
574
77e96e88
RGS
575=item retest
576
577[version 0.2806]
578
579This is just like the C<test> action, but doesn't actually build the
580distribution first, and doesn't add F<blib/> to the load path, and
581therefore will test against a I<previously> installed version of the
582distribution. This can be used to verify that a certain installed
583distribution still works, or to see whether newer versions of a
584distribution still pass the old regression tests, and so on.
585
bb4e9162
YST
586=item skipcheck
587
a314697d
RS
588[version 0.05]
589
bb4e9162
YST
590Reports which files are skipped due to the entries in the
591F<MANIFEST.SKIP> file (See L<manifest> for details)
592
593=item test
594
a314697d
RS
595[version 0.01]
596
738349a8
SH
597This will use C<Test::Harness> or C<TAP::Harness> to run any regression
598tests and report their results. Tests can be defined in the standard
599places: a file called C<test.pl> in the top-level directory, or several
600files ending with C<.t> in a C<t/> directory.
bb4e9162
YST
601
602If you want tests to be 'verbose', i.e. show details of test execution
603rather than just summary information, pass the argument C<verbose=1>.
604
605If you want to run tests under the perl debugger, pass the argument
606C<debugger=1>.
607
738349a8
SH
608If you want to have Module::Build find test files with different file
609name extensions, pass the C<test_file_exts> argument with an array
610of extensions, such as C<[qw( .t .s .z )]>.
611
612If you want test to be run by C<TAP::Harness>, rather than C<Test::Harness>,
613pass the argument C<tap_harness_args> as an array reference of arguments to
614pass to the TAP::Harness constructor.
615
bb4e9162
YST
616In addition, if a file called C<visual.pl> exists in the top-level
617directory, this file will be executed as a Perl script and its output
618will be shown to the user. This is a good place to put speed tests or
619other tests that don't use the C<Test::Harness> format for output.
620
621To override the choice of tests to run, you may pass a C<test_files>
622argument whose value is a whitespace-separated list of test scripts to
623run. This is especially useful in development, when you only want to
624run a single test to see whether you've squashed a certain bug yet:
625
626 ./Build test --test_files t/something_failing.t
627
628You may also pass several C<test_files> arguments separately:
629
630 ./Build test --test_files t/one.t --test_files t/two.t
631
632or use a C<glob()>-style pattern:
633
634 ./Build test --test_files 't/01-*.t'
635
7253302f
SP
636=item testall
637
23837600 638[version 0.2807]
7253302f
SP
639
640[Note: the 'testall' action and the code snippets below are currently
641in alpha stage, see
642L<"http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"> ]
643
644Runs the C<test> action plus each of the C<test$type> actions defined by
645the keys of the C<test_types> parameter.
646
647Currently, you need to define the ACTION_test$type method yourself and
648enumerate them in the test_types parameter.
649
650 my $mb = Module::Build->subclass(
651 code => q(
652 sub ACTION_testspecial { shift->generic_test(type => 'special'); }
653 sub ACTION_testauthor { shift->generic_test(type => 'author'); }
654 )
655 )->new(
656 ...
657 test_types => {
658 special => '.st',
738349a8 659 author => ['.at', '.pt' ],
7253302f
SP
660 },
661 ...
662
bb4e9162
YST
663=item testcover
664
a314697d
RS
665[version 0.26]
666
bb4e9162
YST
667Runs the C<test> action using C<Devel::Cover>, generating a
668code-coverage report showing which parts of the code were actually
669exercised during the tests.
670
671To pass options to C<Devel::Cover>, set the C<$DEVEL_COVER_OPTIONS>
672environment variable:
673
674 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
675
676=item testdb
677
a314697d
RS
678[version 0.05]
679
bb4e9162
YST
680This is a synonym for the 'test' action with the C<debugger=1>
681argument.
682
683=item testpod
684
a314697d
RS
685[version 0.25]
686
08fc25ad 687This checks all the files described in the C<docs> action and
bb4e9162
YST
688produces C<Test::Harness>-style output. If you are a module author,
689this is useful to run before creating a new release.
690
a314697d
RS
691=item testpodcoverage
692
693[version 0.28]
694
08fc25ad 695This checks the pod coverage of the distribution and
a314697d
RS
696produces C<Test::Harness>-style output. If you are a module author,
697this is useful to run before creating a new release.
698
bb4e9162
YST
699=item versioninstall
700
a314697d
RS
701[version 0.16]
702
bb4e9162
YST
703** Note: since C<only.pm> is so new, and since we just recently added
704support for it here too, this feature is to be considered
705experimental. **
706
707If you have the C<only.pm> module installed on your system, you can
708use this action to install a module into the version-specific library
709trees. This means that you can have several versions of the same
710module installed and C<use> a specific one like this:
711
712 use only MyModule => 0.55;
713
714To override the default installation libraries in C<only::config>,
715specify the C<versionlib> parameter when you run the C<Build.PL> script:
716
717 perl Build.PL --versionlib /my/version/place/
718
719To override which version the module is installed as, specify the
720C<versionlib> parameter when you run the C<Build.PL> script:
721
722 perl Build.PL --version 0.50
723
724See the C<only.pm> documentation for more information on
725version-specific installs.
726
727=back
728
729
730=head1 OPTIONS
731
732=head2 Command Line Options
733
734The following options can be used during any invocation of C<Build.PL>
735or the Build script, during any action. For information on other
736options specific to an action, see the documentation for the
737respective action.
738
739NOTE: There is some preliminary support for options to use the more
740familiar long option style. Most options can be preceded with the
741C<--> long option prefix, and the underscores changed to dashes
23837600 742(e.g. C<--use-rcfile>). Additionally, the argument to boolean options is
bb4e9162 743optional, and boolean options can be negated by prefixing them with
23837600 744C<no> or C<no-> (e.g. C<--noverbose> or C<--no-verbose>).
bb4e9162
YST
745
746=over 4
747
748=item quiet
749
750Suppress informative messages on output.
751
613f422f
DG
752=item verbose
753
754Display extra information about the Build on output.
755
756=item cpan_client
757
758Sets the C<cpan_client> command for use with the C<installdeps> action.
759See C<installdeps> for more details.
760
bb4e9162
YST
761=item use_rcfile
762
763Load the F<~/.modulebuildrc> option file. This option can be set to
764false to prevent the custom resource file from being loaded.
765
0ec9ad96
SP
766=item allow_mb_mismatch
767
768Suppresses the check upon startup that the version of Module::Build
769we're now running under is the same version that was initially invoked
770when building the distribution (i.e. when the C<Build.PL> script was
771first run). Use with caution.
772
4085a377
DG
773=item debug
774
775Prints Module::Build debugging information to STDOUT, such as a trace of
776executed build actions.
777
bb4e9162
YST
778=back
779
bb4e9162
YST
780=head2 Default Options File (F<.modulebuildrc>)
781
a314697d
RS
782[version 0.28]
783
dc8021d3
SP
784When Module::Build starts up, it will look first for a file,
785F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look
786in the the F<.modulebuildrc> file in the directories referred to by
787the environment variables C<HOMEDRIVE> + C<HOMEDIR>, C<USERPROFILE>,
788C<APPDATA>, C<WINDIR>, C<SYS$LOGIN>. If the file exists, the options
bb4e9162
YST
789specified there will be used as defaults, as if they were typed on the
790command line. The defaults can be overridden by specifying new values
791on the command line.
792
793The action name must come at the beginning of the line, followed by any
794amount of whitespace and then the options. Options are given the same
795as they would be on the command line. They can be separated by any
796amount of whitespace, including newlines, as long there is whitespace at
797the beginning of each continued line. Anything following a hash mark (C<#>)
798is considered a comment, and is stripped before parsing. If more than
799one line begins with the same action name, those lines are merged into
800one set of options.
801
802Besides the regular actions, there are two special pseudo-actions: the
803key C<*> (asterisk) denotes any global options that should be applied
804to all actions, and the key 'Build_PL' specifies options to be applied
805when you invoke C<perl Build.PL>.
806
613f422f
DG
807 * verbose=1 # global options
808 diff flags=-u
809 install --install_base /home/ken
810 --install_path html=/home/ken/docs/html
811 installdeps --cpan_client 'cpanp -i'
bb4e9162
YST
812
813If you wish to locate your resource file in a different location, you
23837600 814can set the environment variable C<MODULEBUILDRC> to the complete
bb4e9162
YST
815absolute path of the file containing your options.
816
613f422f
DG
817=head2 Environment variables
818
819=over
820
821=item MODULEBUILDRC
822
823[version 0.28]
824
825Specifies an alternate location for a default options file as described above.
826
827=item PERL_MB_OPT
828
829[version 0.36]
830
831Command line options that are applied to Build.PL or any Build action. The
832string is split as the shell would (e.g. whitespace) and the result is
833prepended to any actual command-line arguments.
834
835=back
bb4e9162
YST
836
837=head1 INSTALL PATHS
838
a314697d
RS
839[version 0.19]
840
bb4e9162
YST
841When you invoke Module::Build's C<build> action, it needs to figure
842out where to install things. The nutshell version of how this works
843is that default installation locations are determined from
844F<Config.pm>, and they may be overridden by using the C<install_path>
845parameter. An C<install_base> parameter lets you specify an
846alternative installation root like F</home/foo>, and a C<destdir> lets
847you specify a temporary installation directory like F</tmp/install> in
848case you want to create bundled-up installable packages.
849
850Natively, Module::Build provides default installation locations for
851the following types of installable items:
852
853=over 4
854
855=item lib
856
857Usually pure-Perl module files ending in F<.pm>.
858
859=item arch
860
861"Architecture-dependent" module files, usually produced by compiling
23837600 862XS, L<Inline>, or similar code.
bb4e9162
YST
863
864=item script
865
866Programs written in pure Perl. In order to improve reuse, try to make
867these as small as possible - put the code into modules whenever
868possible.
869
870=item bin
871
872"Architecture-dependent" executable programs, i.e. compiled C code or
873something. Pretty rare to see this in a perl distribution, but it
874happens.
875
876=item bindoc
877
878Documentation for the stuff in C<script> and C<bin>. Usually
879generated from the POD in those files. Under Unix, these are manual
880pages belonging to the 'man1' category.
881
882=item libdoc
883
884Documentation for the stuff in C<lib> and C<arch>. This is usually
885generated from the POD in F<.pm> files. Under Unix, these are manual
886pages belonging to the 'man3' category.
887
888=item binhtml
889
23837600 890This is the same as C<bindoc> above, but applies to HTML documents.
bb4e9162
YST
891
892=item libhtml
893
23837600 894This is the same as C<bindoc> above, but applies to HTML documents.
bb4e9162
YST
895
896=back
897
898Four other parameters let you control various aspects of how
899installation paths are determined:
900
901=over 4
902
903=item installdirs
904
905The default destinations for these installable things come from
906entries in your system's C<Config.pm>. You can select from three
907different sets of default locations by setting the C<installdirs>
908parameter as follows:
909
910 'installdirs' set to:
911 core site vendor
912
913 uses the following defaults from Config.pm:
914
915 lib => installprivlib installsitelib installvendorlib
916 arch => installarchlib installsitearch installvendorarch
917 script => installscript installsitebin installvendorbin
918 bin => installbin installsitebin installvendorbin
919 bindoc => installman1dir installsiteman1dir installvendorman1dir
920 libdoc => installman3dir installsiteman3dir installvendorman3dir
921 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
922 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
923
23837600 924 * Under some OS (eg. MSWin32) the destination for HTML documents is
bb4e9162
YST
925 determined by the C<Config.pm> entry C<installhtmldir>.
926
927The default value of C<installdirs> is "site". If you're creating
928vendor distributions of module packages, you may want to do something
929like this:
930
931 perl Build.PL --installdirs vendor
932
933or
934
935 ./Build install --installdirs vendor
936
937If you're installing an updated version of a module that was included
938with perl itself (i.e. a "core module"), then you may set
939C<installdirs> to "core" to overwrite the module in its present
940location.
941
23837600 942(Note that the 'script' line is different from C<MakeMaker> -
bb4e9162
YST
943unfortunately there's no such thing as "installsitescript" or
944"installvendorscript" entry in C<Config.pm>, so we use the
945"installsitebin" and "installvendorbin" entries to at least get the
946general location right. In the future, if C<Config.pm> adds some more
947appropriate entries, we'll start using those.)
948
949=item install_path
950
951Once the defaults have been set, you can override them.
952
953On the command line, that would look like this:
954
955 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
956
957or this:
958
959 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
960
961=item install_base
962
963You can also set the whole bunch of installation paths by supplying the
964C<install_base> parameter to point to a directory on your system. For
965instance, if you set C<install_base> to "/home/ken" on a Linux
966system, you'll install as follows:
967
968 lib => /home/ken/lib/perl5
969 arch => /home/ken/lib/perl5/i386-linux
970 script => /home/ken/bin
971 bin => /home/ken/bin
972 bindoc => /home/ken/man/man1
973 libdoc => /home/ken/man/man3
974 binhtml => /home/ken/html
975 libhtml => /home/ken/html
976
23837600 977Note that this is I<different> from how C<MakeMaker>'s C<PREFIX>
77e96e88 978parameter works. C<install_base> just gives you a default layout under the
bb4e9162
YST
979directory you specify, which may have little to do with the
980C<installdirs=site> layout.
981
982The exact layout under the directory you specify may vary by system -
983we try to do the "sensible" thing on each platform.
984
985=item destdir
986
987If you want to install everything into a temporary directory first
988(for instance, if you want to create a directory tree that a package
989manager like C<rpm> or C<dpkg> could create a package from), you can
990use the C<destdir> parameter:
991
992 perl Build.PL --destdir /tmp/foo
993
994or
995
996 ./Build install --destdir /tmp/foo
997
998This will effectively install to "/tmp/foo/$sitelib",
999"/tmp/foo/$sitearch", and the like, except that it will use
1000C<File::Spec> to make the pathnames work correctly on whatever
1001platform you're installing on.
1002
f943a5bf 1003=item prefix
bb4e9162 1004
23837600 1005Provided for compatibility with C<ExtUtils::MakeMaker>'s PREFIX argument.
f943a5bf
SP
1006C<prefix> should be used when you wish Module::Build to install your
1007modules, documentation and scripts in the same place
23837600 1008C<ExtUtils::MakeMaker> does.
bb4e9162 1009
f943a5bf 1010The following are equivalent.
bb4e9162 1011
f943a5bf
SP
1012 perl Build.PL --prefix /tmp/foo
1013 perl Makefile.PL PREFIX=/tmp/foo
bb4e9162 1014
f943a5bf 1015Because of the very complex nature of the prefixification logic, the
23837600 1016behavior of PREFIX in C<MakeMaker> has changed subtly over time.
f943a5bf 1017Module::Build's --prefix logic is equivalent to the PREFIX logic found
23837600 1018in C<ExtUtils::MakeMaker> 6.30.
bb4e9162 1019
23837600
DG
1020If you do not need to retain compatibility with C<ExtUtils::MakeMaker> or
1021are starting a fresh Perl installation we recommend you use
1022C<install_base> instead (and C<INSTALL_BASE> in C<ExtUtils::MakeMaker>).
f943a5bf
SP
1023See L<Module::Build::Cookbook/Instaling in the same location as
1024ExtUtils::MakeMaker> for further information.
bb4e9162 1025
bb4e9162
YST
1026
1027=back
1028
1029
1030=head1 MOTIVATIONS
1031
1032There are several reasons I wanted to start over, and not just fix
23837600 1033what I didn't like about C<MakeMaker>:
bb4e9162
YST
1034
1035=over 4
1036
1037=item *
1038
23837600 1039I don't like the core idea of C<MakeMaker>, namely that C<make> should be
bb4e9162
YST
1040involved in the build process. Here are my reasons:
1041
1042=over 4
1043
1044=item +
1045
1046When a person is installing a Perl module, what can you assume about
1047their environment? Can you assume they have C<make>? No, but you can
1048assume they have some version of Perl.
1049
1050=item +
1051
1052When a person is writing a Perl module for intended distribution, can
1053you assume that they know how to build a Makefile, so they can
1054customize their build process? No, but you can assume they know Perl,
1055and could customize that way.
1056
1057=back
1058
1059For years, these things have been a barrier to people getting the
1060build/install process to do what they want.
1061
1062=item *
1063
23837600 1064There are several architectural decisions in C<MakeMaker> that make it
bb4e9162 1065very difficult to customize its behavior. For instance, when using
23837600 1066C<MakeMaker> you do C<use ExtUtils::MakeMaker>, but the object created in
bb4e9162
YST
1067C<WriteMakefile()> is actually blessed into a package name that's
1068created on the fly, so you can't simply subclass
1069C<ExtUtils::MakeMaker>. There is a workaround C<MY> package that lets
23837600
DG
1070you override certain C<MakeMaker> methods, but only certain explicitly
1071preselected (by C<MakeMaker>) methods can be overridden. Also, the method
bb4e9162
YST
1072of customization is very crude: you have to modify a string containing
1073the Makefile text for the particular target. Since these strings
1074aren't documented, and I<can't> be documented (they take on different
1075values depending on the platform, version of perl, version of
23837600
DG
1076C<MakeMaker>, etc.), you have no guarantee that your modifications will
1077work on someone else's machine or after an upgrade of C<MakeMaker> or
bb4e9162
YST
1078perl.
1079
1080=item *
1081
23837600 1082It is risky to make major changes to C<MakeMaker>, since it does so many
bb4e9162
YST
1083things, is so important, and generally works. C<Module::Build> is an
1084entirely separate package so that I can work on it all I want, without
1085worrying about backward compatibility.
1086
1087=item *
1088
1089Finally, Perl is said to be a language for system administration.
1090Could it really be the case that Perl isn't up to the task of building
1091and installing software? Even if that software is a bunch of stupid
1092little C<.pm> files that just need to be copied from one place to
1093another? My sense was that we could design a system to accomplish
1094this in a flexible, extensible, and friendly manner. Or die trying.
1095
1096=back
1097
1098
1099=head1 TO DO
1100
1101The current method of relying on time stamps to determine whether a
1102derived file is out of date isn't likely to scale well, since it
1103requires tracing all dependencies backward, it runs into problems on
1104NFS, and it's just generally flimsy. It would be better to use an MD5
1105signature or the like, if available. See C<cons> for an example.
1106
1107 - append to perllocal.pod
1108 - add a 'plugin' functionality
1109
1110
1111=head1 AUTHOR
1112
1113Ken Williams <kwilliams@cpan.org>
1114
1115Development questions, bug reports, and patches should be sent to the
0ec9ad96 1116Module-Build mailing list at <module-build@perl.org>.
bb4e9162
YST
1117
1118Bug reports are also welcome at
1119<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
1120
dc8021d3
SP
1121The latest development version is available from the Subversion
1122repository at <https://svn.perl.org/modules/Module-Build/trunk/>
bb4e9162
YST
1123
1124
1125=head1 COPYRIGHT
1126
77e96e88 1127Copyright (c) 2001-2006 Ken Williams. All rights reserved.
bb4e9162
YST
1128
1129This library is free software; you can redistribute it and/or
1130modify it under the same terms as Perl itself.
1131
1132
1133=head1 SEE ALSO
1134
77e96e88 1135perl(1), L<Module::Build::Cookbook>, L<Module::Build::Authoring>,
613f422f 1136L<Module::Build::API>, L<ExtUtils::MakeMaker>, L<YAML::Tiny>
bb4e9162
YST
1137
1138F<META.yml> Specification:
77e96e88 1139L<http://module-build.sourceforge.net/META-spec-current.html>
bb4e9162
YST
1140
1141L<http://www.dsmit.com/cons/>
1142
dc8021d3
SP
1143L<http://search.cpan.org/dist/PerlBuildSystem/>
1144
bb4e9162 1145=cut