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