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