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