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