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