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