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