This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clean up regexec.c, and remove two functions
[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);
47f13fd5 18$VERSION = '0.27_09';
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
188This document describes the C<Module::Build> API for authors who are
189writing F<Build.PL> scripts for a distribution or controlling
190C<Module::Build> processes programmatically. It describes the
191methods available as well as providing general information on
192subclassing C<Module::Build> to alter and extend its behavior. Also,
193there is a section on controlling the Build process from other
194scripts, including how to construct an object and how to invoke
195actions through it from an external script.
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
236If you run the C<Build> script without any arguments, it runs the
237C<build> action, which in turn runs the C<code> and C<docs> actions.
238
239This is analogous to the MakeMaker 'make all' target.
240
47f13fd5
SP
241=item testpodcoverage
242
243This checks the pod coverage of the distribution and
244produces C<Test::Harness>-style output. If you are a module author,
245this is useful to run before creating a new release.
246
bb4e9162
YST
247=item clean
248
249This action will clean up any files that the build process may have
250created, including the C<blib/> directory (but not including the
251C<_build/> directory and the C<Build> script itself).
252
253=item code
254
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
273...
274
275=item diff
276
277This action will compare the files about to be installed with their
278installed counterparts. For .pm and .pod files, a diff will be shown
279(this currently requires a 'diff' program to be in your PATH). For
280other files like compiled binary files, we simply report whether they
281differ.
282
283A C<flags> parameter may be passed to the action, which will be passed
284to the 'diff' program. Consult your 'diff' documentation for the
285parameters it will accept - a good one is C<-u>:
286
287 ./Build diff flags=-u
288
289=item dist
290
291This action is helpful for module authors who want to package up their
292module for source distribution through a medium like CPAN. It will create a
293tarball of the files listed in F<MANIFEST> and compress the tarball using
294GZIP compression.
295
296By default, this action will use the external C<tar> and C<gzip>
297executables on Unix-like platforms, and the C<Archive::Tar> module
298elsewhere. However, you can force it to use whatever executable you
299want by supplying an explicit C<tar> (and optional C<gzip>) parameter:
300
301 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
302
303=item distcheck
304
305Reports which files are in the build directory but not in the
306F<MANIFEST> file, and vice versa. (See L<manifest> for details.)
307
308=item distclean
309
310Performs the 'realclean' action and then the 'distcheck' action.
311
312=item distdir
313
314Creates a "distribution directory" named C<$dist_name-$dist_version>
315(if that directory already exists, it will be removed first), then
316copies all the files listed in the F<MANIFEST> file to that directory.
317This directory is what the distribution tarball is created from.
318
319=item distmeta
320
321Creates the F<META.yml> file that describes the distribution.
322
323F<META.yml> is a file containing various bits of "metadata" about the
324distribution. The metadata includes the distribution name, version,
325abstract, prerequisites, license, and various other data about the
326distribution. This file is created as F<META.yml> in YAML format, so
327the C<YAML> module must be installed in order to create it. The
328F<META.yml> file must also be listed in F<MANIFEST> - if it's not, a
329warning will be issued.
330
331The current version of the F<META.yml> specification can be found at
332L<http://module-build.sourceforge.net/META-spec-v1.2.html>
333
334=item distsign
335
336Uses C<Module::Signature> to create a SIGNATURE file for your
337distribution, and adds the SIGNATURE file to the distribution's
338MANIFEST.
339
340=item disttest
341
342Performs the 'distdir' action, then switches into that directory and
343runs a C<perl Build.PL>, followed by the 'build' and 'test' actions in
344that directory.
345
346=item docs
347
348This will generate documentation (e.g. Unix man pages and html
349documents) for any installable items under B<blib/> that
350contain POD. If there are no C<bindoc> or C<libdoc> installation
351targets defined (as will be the case on systems that don't support
352Unix manpages) no action is taken for manpages. If there are no
353C<binhtml> or C<libhtml> installation targets defined no action is
354taken for html documents.
355
356=item fakeinstall
357
358This is just like the C<install> action, but it won't actually do
359anything, it will just report what it I<would> have done if you had
360actually run the C<install> action.
361
362=item help
363
364This action will simply print out a message that is meant to help you
365use the build process. It will show you a list of available build
366actions too.
367
368With an optional argument specifying an action name (e.g. C<Build help
369test>), the 'help' action will show you any POD documentation it can
370find for that action.
371
372=item html
373
374This will generate HTML documentation for any binary or library files
375under B<blib/> that contain POD. The HTML documentation will only be
376installed if the install paths can be determined from values in
377C<Config.pm>. You can also supply or override install paths on the
378command line by specifying C<install_path> values for the C<binhtml>
379and/or C<libhtml> installation targets.
380
381=item install
382
383This action will use C<ExtUtils::Install> to install the files from
384C<blib/> into the system. See L<INSTALL PATHS>
385for details about how Module::Build determines where to install
386things, and how to influence this process.
387
388If you want the installation process to look around in C<@INC> for
389other versions of the stuff you're installing and try to delete it,
390you can use the C<uninst> parameter, which tells C<ExtUtils::Install> to
391do so:
392
393 ./Build install uninst=1
394
395This can be a good idea, as it helps prevent multiple versions of a
396module from being present on your system, which can be a confusing
397situation indeed.
398
399=item manifest
400
401This is an action intended for use by module authors, not people
402installing modules. It will bring the F<MANIFEST> up to date with the
403files currently present in the distribution. You may use a
404F<MANIFEST.SKIP> file to exclude certain files or directories from
405inclusion in the F<MANIFEST>. F<MANIFEST.SKIP> should contain a bunch
406of regular expressions, one per line. If a file in the distribution
407directory matches any of the regular expressions, it won't be included
408in the F<MANIFEST>.
409
410The following is a reasonable F<MANIFEST.SKIP> starting point, you can
411add your own stuff to it:
412
413 ^_build
414 ^Build$
415 ^blib
416 ~$
417 \.bak$
418 ^MANIFEST\.SKIP$
419 CVS
420
421See the L<distcheck> and L<skipcheck> actions if you want to find out
422what the C<manifest> action would do, without actually doing anything.
423
424=item manpages
425
426This will generate man pages for any binary or library files under
427B<blib/> that contain POD. The man pages will only be installed if the
428install paths can be determined from values in C<Config.pm>. You can
429also supply or override install paths by specifying there values on
430the command line with the C<bindoc> and C<libdoc> installation
431targets.
432
433=item ppd
434
435Build a PPD file for your distribution.
436
437This action takes an optional argument C<codebase> which is used in
438the generated ppd file to specify the (usually relative) URL of the
439distribution. By default, this value is the distribution name without
440any path information.
441
442Example:
443
444 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
445
446=item ppmdist
447
448Generates a PPM binary distribution and a PPD description file. This
449action also invokes the 'ppd' action, so it can accept the same
450C<codebase> argument described under that action.
451
452This uses the same mechanism as the C<dist> action to tar & zip its
453output, so you can supply C<tar> and/or C<gzip> parameters to affect
454the result.
455
456=item prereq_report
457
458This action prints out a list of all prerequisites, the versions required, and
459the versions actually installed. This can be useful for reviewing the
460configuration of your system prior to a build, or when compiling data to send
461for a bug report.
462
463=item pure_install
464
465This action is identical to the C<install> action. In the future,
466though, if C<install> starts writing to the file file
467F<$(INSTALLARCHLIB)/perllocal.pod>, C<pure_install> won't, and that
468will be the only difference between them.
469
470=item realclean
471
472This action is just like the C<clean> action, but also removes the
473C<_build> directory and the C<Build> script. If you run the
474C<realclean> action, you are essentially starting over, so you will
475have to re-create the C<Build> script again.
476
477=item skipcheck
478
479Reports which files are skipped due to the entries in the
480F<MANIFEST.SKIP> file (See L<manifest> for details)
481
482=item test
483
484This will use C<Test::Harness> to run any regression tests and report
485their results. Tests can be defined in the standard places: a file
486called C<test.pl> in the top-level directory, or several files ending
487with C<.t> in a C<t/> directory.
488
489If you want tests to be 'verbose', i.e. show details of test execution
490rather than just summary information, pass the argument C<verbose=1>.
491
492If you want to run tests under the perl debugger, pass the argument
493C<debugger=1>.
494
495In addition, if a file called C<visual.pl> exists in the top-level
496directory, this file will be executed as a Perl script and its output
497will be shown to the user. This is a good place to put speed tests or
498other tests that don't use the C<Test::Harness> format for output.
499
500To override the choice of tests to run, you may pass a C<test_files>
501argument whose value is a whitespace-separated list of test scripts to
502run. This is especially useful in development, when you only want to
503run a single test to see whether you've squashed a certain bug yet:
504
505 ./Build test --test_files t/something_failing.t
506
507You may also pass several C<test_files> arguments separately:
508
509 ./Build test --test_files t/one.t --test_files t/two.t
510
511or use a C<glob()>-style pattern:
512
513 ./Build test --test_files 't/01-*.t'
514
515=item testcover
516
517Runs the C<test> action using C<Devel::Cover>, generating a
518code-coverage report showing which parts of the code were actually
519exercised during the tests.
520
521To pass options to C<Devel::Cover>, set the C<$DEVEL_COVER_OPTIONS>
522environment variable:
523
524 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
525
526=item testdb
527
528This is a synonym for the 'test' action with the C<debugger=1>
529argument.
530
531=item testpod
532
533This checks all the files described in the C<docs> action and
534produces C<Test::Harness>-style output. If you are a module author,
535this is useful to run before creating a new release.
536
537=item versioninstall
538
539** Note: since C<only.pm> is so new, and since we just recently added
540support for it here too, this feature is to be considered
541experimental. **
542
543If you have the C<only.pm> module installed on your system, you can
544use this action to install a module into the version-specific library
545trees. This means that you can have several versions of the same
546module installed and C<use> a specific one like this:
547
548 use only MyModule => 0.55;
549
550To override the default installation libraries in C<only::config>,
551specify the C<versionlib> parameter when you run the C<Build.PL> script:
552
553 perl Build.PL --versionlib /my/version/place/
554
555To override which version the module is installed as, specify the
556C<versionlib> parameter when you run the C<Build.PL> script:
557
558 perl Build.PL --version 0.50
559
560See the C<only.pm> documentation for more information on
561version-specific installs.
562
563=back
564
565
566=head1 OPTIONS
567
568=head2 Command Line Options
569
570The following options can be used during any invocation of C<Build.PL>
571or the Build script, during any action. For information on other
572options specific to an action, see the documentation for the
573respective action.
574
575NOTE: There is some preliminary support for options to use the more
576familiar long option style. Most options can be preceded with the
577C<--> long option prefix, and the underscores changed to dashes
578(e.g. --use-rcfile). Additionally, the argument to boolean options is
579optional, and boolean options can be negated by prefixing them with
580'no' or 'no-' (e.g. --noverbose or --no-verbose).
581
582=over 4
583
584=item quiet
585
586Suppress informative messages on output.
587
588=item use_rcfile
589
590Load the F<~/.modulebuildrc> option file. This option can be set to
591false to prevent the custom resource file from being loaded.
592
593=item verbose
594
595Display extra information about the Build on output.
596
597=back
598
599
600=head2 Default Options File (F<.modulebuildrc>)
601
602When Module::Build starts up, it will look for a file,
603F<$ENV{HOME}/.modulebuildrc>. If the file exists, the options
604specified there will be used as defaults, as if they were typed on the
605command line. The defaults can be overridden by specifying new values
606on the command line.
607
608The action name must come at the beginning of the line, followed by any
609amount of whitespace and then the options. Options are given the same
610as they would be on the command line. They can be separated by any
611amount of whitespace, including newlines, as long there is whitespace at
612the beginning of each continued line. Anything following a hash mark (C<#>)
613is considered a comment, and is stripped before parsing. If more than
614one line begins with the same action name, those lines are merged into
615one set of options.
616
617Besides the regular actions, there are two special pseudo-actions: the
618key C<*> (asterisk) denotes any global options that should be applied
619to all actions, and the key 'Build_PL' specifies options to be applied
620when you invoke C<perl Build.PL>.
621
622 * verbose=1 # global options
623 diff flags=-u
624 install --install_base /home/ken
625 --install_path html=/home/ken/docs/html
626
627If you wish to locate your resource file in a different location, you
628can set the environment variable 'MODULEBUILDRC' to the complete
629absolute path of the file containing your options.
630
631
632=head1 INSTALL PATHS
633
634When you invoke Module::Build's C<build> action, it needs to figure
635out where to install things. The nutshell version of how this works
636is that default installation locations are determined from
637F<Config.pm>, and they may be overridden by using the C<install_path>
638parameter. An C<install_base> parameter lets you specify an
639alternative installation root like F</home/foo>, and a C<destdir> lets
640you specify a temporary installation directory like F</tmp/install> in
641case you want to create bundled-up installable packages.
642
643Natively, Module::Build provides default installation locations for
644the following types of installable items:
645
646=over 4
647
648=item lib
649
650Usually pure-Perl module files ending in F<.pm>.
651
652=item arch
653
654"Architecture-dependent" module files, usually produced by compiling
655XS, Inline, or similar code.
656
657=item script
658
659Programs written in pure Perl. In order to improve reuse, try to make
660these as small as possible - put the code into modules whenever
661possible.
662
663=item bin
664
665"Architecture-dependent" executable programs, i.e. compiled C code or
666something. Pretty rare to see this in a perl distribution, but it
667happens.
668
669=item bindoc
670
671Documentation for the stuff in C<script> and C<bin>. Usually
672generated from the POD in those files. Under Unix, these are manual
673pages belonging to the 'man1' category.
674
675=item libdoc
676
677Documentation for the stuff in C<lib> and C<arch>. This is usually
678generated from the POD in F<.pm> files. Under Unix, these are manual
679pages belonging to the 'man3' category.
680
681=item binhtml
682
683This is the same as C<bindoc> above, but applies to html documents.
684
685=item libhtml
686
687This is the same as C<bindoc> above, but applies to html documents.
688
689=back
690
691Four other parameters let you control various aspects of how
692installation paths are determined:
693
694=over 4
695
696=item installdirs
697
698The default destinations for these installable things come from
699entries in your system's C<Config.pm>. You can select from three
700different sets of default locations by setting the C<installdirs>
701parameter as follows:
702
703 'installdirs' set to:
704 core site vendor
705
706 uses the following defaults from Config.pm:
707
708 lib => installprivlib installsitelib installvendorlib
709 arch => installarchlib installsitearch installvendorarch
710 script => installscript installsitebin installvendorbin
711 bin => installbin installsitebin installvendorbin
712 bindoc => installman1dir installsiteman1dir installvendorman1dir
713 libdoc => installman3dir installsiteman3dir installvendorman3dir
714 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
715 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
716
717 * Under some OS (eg. MSWin32) the destination for html documents is
718 determined by the C<Config.pm> entry C<installhtmldir>.
719
720The default value of C<installdirs> is "site". If you're creating
721vendor distributions of module packages, you may want to do something
722like this:
723
724 perl Build.PL --installdirs vendor
725
726or
727
728 ./Build install --installdirs vendor
729
730If you're installing an updated version of a module that was included
731with perl itself (i.e. a "core module"), then you may set
732C<installdirs> to "core" to overwrite the module in its present
733location.
734
735(Note that the 'script' line is different from MakeMaker -
736unfortunately there's no such thing as "installsitescript" or
737"installvendorscript" entry in C<Config.pm>, so we use the
738"installsitebin" and "installvendorbin" entries to at least get the
739general location right. In the future, if C<Config.pm> adds some more
740appropriate entries, we'll start using those.)
741
742=item install_path
743
744Once the defaults have been set, you can override them.
745
746On the command line, that would look like this:
747
748 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
749
750or this:
751
752 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
753
754=item install_base
755
756You can also set the whole bunch of installation paths by supplying the
757C<install_base> parameter to point to a directory on your system. For
758instance, if you set C<install_base> to "/home/ken" on a Linux
759system, you'll install as follows:
760
761 lib => /home/ken/lib/perl5
762 arch => /home/ken/lib/perl5/i386-linux
763 script => /home/ken/bin
764 bin => /home/ken/bin
765 bindoc => /home/ken/man/man1
766 libdoc => /home/ken/man/man3
767 binhtml => /home/ken/html
768 libhtml => /home/ken/html
769
770Note that this is I<different> from how MakeMaker's C<PREFIX>
771parameter works. See L</"Why PREFIX is not recommended"> for more
772details. C<install_base> just gives you a default layout under the
773directory you specify, which may have little to do with the
774C<installdirs=site> layout.
775
776The exact layout under the directory you specify may vary by system -
777we try to do the "sensible" thing on each platform.
778
779=item destdir
780
781If you want to install everything into a temporary directory first
782(for instance, if you want to create a directory tree that a package
783manager like C<rpm> or C<dpkg> could create a package from), you can
784use the C<destdir> parameter:
785
786 perl Build.PL --destdir /tmp/foo
787
788or
789
790 ./Build install --destdir /tmp/foo
791
792This will effectively install to "/tmp/foo/$sitelib",
793"/tmp/foo/$sitearch", and the like, except that it will use
794C<File::Spec> to make the pathnames work correctly on whatever
795platform you're installing on.
796
797=back
798
799=head2 About PREFIX Support
800
801First, it is necessary to understand the original idea behind
802C<PREFIX>. If, for example, the default installation locations for
803your machine are F</usr/local/lib/perl5/5.8.5> for modules,
804F</usr/local/bin> for executables, F</usr/local/man/man1> and
805F</usr/local/man/man3> for manual pages, etc., then they all share the
806same "prefix" F</usr/local>. MakeMaker's C<PREFIX> mechanism was
807intended as a way to change an existing prefix that happened to occur
808in all those paths - essentially a C<< s{/usr/local}{/foo/bar} >> for
809each path.
810
811However, the real world is more complicated than that. The C<PREFIX>
812idea is fundamentally broken when your machine doesn't jibe with
813C<PREFIX>'s worldview.
814
815
816=over 4
817
818=item Why PREFIX is not recommended
819
820=over 4
821
822=item *
823
824Many systems have Perl configs that make little sense with PREFIX.
825For example, OS X, where core modules go in
826F</System/Library/Perl/...>, user-installed modules go in
827F</Library/Perl/...>, and man pages go in F</usr/share/man/...>. The
828PREFIX is thus set to F</>. Install L<Foo::Bar> on OS X with
829C<PREFIX=/home/spurkis> and you get things like
830F</home/spurkis/Library/Perl/5.8.1/Foo/Bar.pm> and
831F</home/spurkis/usr/share/man/man3/Foo::Bar.3pm>. Not too pretty.
832
833The problem is not limited to Unix-like platforms, either - on Windows
834builds (e.g. ActiveState perl 5.8.0), we have user-installed modules
835going in F<C:\Perl\site\lib>, user-installed executables going in
836F<C:\Perl\bin>, and PREFIX=F<C:\Perl\site>. The prefix just doesn't
837apply neatly to the executables.
838
839=item *
840
841The PREFIX logic is too complicated and hard to predict for the user.
842It's hard to document what exactly is going to happen. You can't give
843a user simple instructions like "run perl Makefile.PL PREFIX=~ and
844then set PERL5LIB=~/lib/perl5".
845
846=item *
847
848The results from PREFIX will change if your configuration of Perl
849changes (for example, if you upgrade Perl). This means your modules
850will end up in different places.
851
852=item *
853
854The results from PREFIX can change with different releases of
855MakeMaker. The logic of PREFIX is subtle and it has been altered in
856the past (mostly to limit damage in the many "edge cases" when its
857behavior was undesirable).
858
859=item *
860
861PREFIX imposes decisions made by the person who configured Perl onto
862the person installing a module. The person who configured Perl could
863have been you or it could have been some guy at Redhat.
864
865=back
866
867
868=item Alternatives to PREFIX
869
870Module::Build offers L</install_base> as a simple, predictable, and
871user-configurable alternative to ExtUtils::MakeMaker's C<PREFIX>.
872What's more, MakeMaker will soon accept C<INSTALL_BASE> -- we strongly
873urge you to make the switch.
874
875Here's a quick comparison of the two when installing modules to your
876home directory on a unix box:
877
878MakeMaker [*]:
879
880 % perl Makefile.PL PREFIX=/home/spurkis
881 PERL5LIB=/home/spurkis/lib/perl5/5.8.5:/home/spurkis/lib/perl5/site_perl/5.8.5
882 PATH=/home/spurkis/bin
883 MANPATH=/home/spurkis/man
884
885Module::Build:
886
887 % perl Build.PL install_base=/home/spurkis
888 PERL5LIB=/home/spurkis/lib/perl5
889 PATH=/home/spurkis/bin
890 MANPATH=/home/spurkis/man
891
892[*] Note that MakeMaker's behaviour cannot be guaranteed in even this
893common scenario, and differs among different versions of MakeMaker.
894
895In short, using C<install_base> is similar to the following MakeMaker usage:
896
897 perl Makefile.PL PREFIX=/home/spurkis LIB=/home/spurkis/lib/perl5
898
899See L</INSTALL PATHS> for details on other
900installation options available and how to configure them.
901
902=back
903
904
905=head1 MOTIVATIONS
906
907There are several reasons I wanted to start over, and not just fix
908what I didn't like about MakeMaker:
909
910=over 4
911
912=item *
913
914I don't like the core idea of MakeMaker, namely that C<make> should be
915involved in the build process. Here are my reasons:
916
917=over 4
918
919=item +
920
921When a person is installing a Perl module, what can you assume about
922their environment? Can you assume they have C<make>? No, but you can
923assume they have some version of Perl.
924
925=item +
926
927When a person is writing a Perl module for intended distribution, can
928you assume that they know how to build a Makefile, so they can
929customize their build process? No, but you can assume they know Perl,
930and could customize that way.
931
932=back
933
934For years, these things have been a barrier to people getting the
935build/install process to do what they want.
936
937=item *
938
939There are several architectural decisions in MakeMaker that make it
940very difficult to customize its behavior. For instance, when using
941MakeMaker you do C<use ExtUtils::MakeMaker>, but the object created in
942C<WriteMakefile()> is actually blessed into a package name that's
943created on the fly, so you can't simply subclass
944C<ExtUtils::MakeMaker>. There is a workaround C<MY> package that lets
945you override certain MakeMaker methods, but only certain explicitly
946preselected (by MakeMaker) methods can be overridden. Also, the method
947of customization is very crude: you have to modify a string containing
948the Makefile text for the particular target. Since these strings
949aren't documented, and I<can't> be documented (they take on different
950values depending on the platform, version of perl, version of
951MakeMaker, etc.), you have no guarantee that your modifications will
952work on someone else's machine or after an upgrade of MakeMaker or
953perl.
954
955=item *
956
957It is risky to make major changes to MakeMaker, since it does so many
958things, is so important, and generally works. C<Module::Build> is an
959entirely separate package so that I can work on it all I want, without
960worrying about backward compatibility.
961
962=item *
963
964Finally, Perl is said to be a language for system administration.
965Could it really be the case that Perl isn't up to the task of building
966and installing software? Even if that software is a bunch of stupid
967little C<.pm> files that just need to be copied from one place to
968another? My sense was that we could design a system to accomplish
969this in a flexible, extensible, and friendly manner. Or die trying.
970
971=back
972
973
974=head1 TO DO
975
976The current method of relying on time stamps to determine whether a
977derived file is out of date isn't likely to scale well, since it
978requires tracing all dependencies backward, it runs into problems on
979NFS, and it's just generally flimsy. It would be better to use an MD5
980signature or the like, if available. See C<cons> for an example.
981
982 - append to perllocal.pod
983 - add a 'plugin' functionality
984
985
986=head1 AUTHOR
987
988Ken Williams <kwilliams@cpan.org>
989
990Development questions, bug reports, and patches should be sent to the
991Module-Build mailing list at <module-build-general@lists.sourceforge.net>.
992
993Bug reports are also welcome at
994<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
995
996An anonymous CVS repository containing the latest development version
997is available; see <http://sourceforge.net/cvs/?group_id=45731> for the
998details of how to access it.
999
1000
1001=head1 COPYRIGHT
1002
1003Copyright (c) 2001-2005 Ken Williams. All rights reserved.
1004
1005This library is free software; you can redistribute it and/or
1006modify it under the same terms as Perl itself.
1007
1008
1009=head1 SEE ALSO
1010
1011perl(1), Module::Build::Cookbook(3), Module::Build::Authoring(3),
1012ExtUtils::MakeMaker(3), YAML(3)
1013
1014F<META.yml> Specification:
1015L<http://module-build.sourceforge.net/META-spec-v1.2.html>
1016
1017L<http://www.dsmit.com/cons/>
1018
1019=cut