1Module::Build(3) User Contributed Perl Documentation Module::Build(3)
2
6 Module::Build - Build and install Perl modules
7
9 Standard process for building & installing modules:
10 perl Build.PL
12 ./Build
13 ./Build test
14 ./Build install
15 Or, if you're on a platform (like DOS or Windows) that doesn't require
17 the "./" notation, you can do this:
18 perl Build.PL
20 Build
21 Build test
22 Build install
23
25 "Module::Build" is a system for building, testing, and installing Perl
26 modules. It is meant to be an alternative to "ExtUtils::MakeMaker".
27 Developers may alter the behavior of the module through subclassing in
28 a much more straightforward way than with "MakeMaker". It also does
29 not require a "make" on your system - most of the "Module::Build" code
30 is pure-perl and written in a very cross-platform way.
31 See "MOTIVATIONS" for more comparisons between "ExtUtils::MakeMaker"
33 and "Module::Build".
34 To install "Module::Build", and any other module that uses
36 "Module::Build" for its installation process, do the following:
37 perl Build.PL # 'Build.PL' script creates the 'Build' script
39 ./Build # Need ./ to ensure we're using this "Build" script
40 ./Build test # and not another one that happens to be in the PATH
41 ./Build install
42 This illustrates initial configuration and the running of three
44 'actions'. In this case the actions run are 'build' (the default
45 action), 'test', and 'install'. Other actions defined so far include:
46 build manifest
48 clean manifest_skip
49 code manpages
50 config_data pardist
51 diff ppd
52 dist ppmdist
53 distcheck prereq_data
54 distclean prereq_report
55 distdir pure_install
56 distinstall realclean
57 distmeta retest
58 distsign skipcheck
59 disttest test
60 docs testall
61 fakeinstall testcover
62 help testdb
63 html testpod
64 install testpodcoverage
65 installdeps versioninstall
66 You can run the 'help' action for a complete list of actions.
68
70 The documentation for "Module::Build" is broken up into sections:
71 General Usage (Module::Build)
73 This is the document you are currently reading. It describes basic
74 usage and background information. Its main purpose is to assist
75 the user who wants to learn how to invoke and control
76 "Module::Build" scripts at the command line.
77 Authoring Reference (Module::Build::Authoring)
79 This document describes the structure and organization of
80 "Module::Build", and the relevant concepts needed by authors who
81 are writing Build.PL scripts for a distribution or controlling
82 "Module::Build" processes programmatically.
83 API Reference (Module::Build::API)
85 This is a reference to the "Module::Build" API.
86 Cookbook (Module::Build::Cookbook)
88 This document demonstrates how to accomplish many common tasks. It
89 covers general command line usage and authoring of Build.PL
90 scripts. Includes working examples.
91
93 There are some general principles at work here. First, each task when
94 building a module is called an "action". These actions are listed
95 above; they correspond to the building, testing, installing, packaging,
96 etc., tasks.
97 Second, arguments are processed in a very systematic way. Arguments
99 are always key=value pairs. They may be specified at "perl Build.PL"
100 time (i.e. "perl Build.PL destdir=/my/secret/place"), in which case
101 their values last for the lifetime of the "Build" script. They may
102 also be specified when executing a particular action (i.e. "Build test
103 verbose=1"), in which case their values last only for the lifetime of
104 that command. Per-action command line parameters take precedence over
105 parameters specified at "perl Build.PL" time.
106 The build process also relies heavily on the "Config.pm" module. If
108 the user wishes to override any of the values in "Config.pm", she may
109 specify them like so:
110 perl Build.PL --config cc=gcc --config ld=gcc
112 The following build actions are provided by default.
114 build
116 [version 0.01]
117 If you run the "Build" script without any arguments, it runs the
119 "build" action, which in turn runs the "code" and "docs" actions.
120 This is analogous to the "MakeMaker" make all target.
122 clean
124 [version 0.01]
125 This action will clean up any files that the build process may have
127 created, including the "blib/" directory (but not including the
128 "_build/" directory and the "Build" script itself).
129 code
131 [version 0.20]
132 This action builds your code base.
134 By default it just creates a "blib/" directory and copies any ".pm"
136 and ".pod" files from your "lib/" directory into the "blib/"
137 directory. It also compiles any ".xs" files from "lib/" and places
138 them in "blib/". Of course, you need a working C compiler
139 (probably the same one that built perl itself) for the compilation
140 to work properly.
141 The "code" action also runs any ".PL" files in your lib/ directory.
143 Typically these create other files, named the same but without the
144 ".PL" ending. For example, a file lib/Foo/Bar.pm.PL could create
145 the file lib/Foo/Bar.pm. The ".PL" files are processed first, so
146 any ".pm" files (or other kinds that we deal with) will get copied
147 correctly.
148 config_data
150 [version 0.26]
151 ...
153 diff
155 [version 0.14]
156 This action will compare the files about to be installed with their
158 installed counterparts. For .pm and .pod files, a diff will be
159 shown (this currently requires a 'diff' program to be in your
160 PATH). For other files like compiled binary files, we simply
161 report whether they differ.
162 A "flags" parameter may be passed to the action, which will be
164 passed to the 'diff' program. Consult your 'diff' documentation
165 for the parameters it will accept - a good one is "-u":
166 ./Build diff flags=-u
168 dist
170 [version 0.02]
171 This action is helpful for module authors who want to package up
173 their module for source distribution through a medium like CPAN.
174 It will create a tarball of the files listed in MANIFEST and
175 compress the tarball using GZIP compression.
176 By default, this action will use the "Archive::Tar" module.
178 However, you can force it to use binary "tar" and "gzip"
179 executables by supplying an explicit "tar" (and optional "gzip")
180 parameter:
181 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
183 distcheck
185 [version 0.05]
186 Reports which files are in the build directory but not in the
188 MANIFEST file, and vice versa. (See manifest for details.)
189 distclean
191 [version 0.05]
192 Performs the 'realclean' action and then the 'distcheck' action.
194 distdir
196 [version 0.05]
197 Creates a "distribution directory" named "$dist_name-$dist_version"
199 (if that directory already exists, it will be removed first), then
200 copies all the files listed in the MANIFEST file to that directory.
201 This directory is what the distribution tarball is created from.
202 distinstall
204 [version 0.37]
205 Performs the 'distdir' action, then switches into that directory
207 and runs a "perl Build.PL", followed by the 'build' and 'install'
208 actions in that directory. Use PERL_MB_OPT or .modulebuildrc to
209 set options that should be applied during subprocesses
210 distmeta
212 [version 0.21]
213 Creates the META.yml file that describes the distribution.
215 META.yml is a file containing various bits of metadata about the
217 distribution. The metadata includes the distribution name,
218 version, abstract, prerequisites, license, and various other data
219 about the distribution. This file is created as META.yml in a
220 simplified YAML format.
221 META.yml file must also be listed in MANIFEST - if it's not, a
223 warning will be issued.
224 The current version of the META.yml specification can be found on
226 CPAN as CPAN::Meta::Spec.
227 distsign
229 [version 0.16]
230 Uses "Module::Signature" to create a SIGNATURE file for your
232 distribution, and adds the SIGNATURE file to the distribution's
233 MANIFEST.
234 disttest
236 [version 0.05]
237 Performs the 'distdir' action, then switches into that directory
239 and runs a "perl Build.PL", followed by the 'build' and 'test'
240 actions in that directory. Use PERL_MB_OPT or .modulebuildrc to
241 set options that should be applied during subprocesses
242 docs
244 [version 0.20]
245 This will generate documentation (e.g. Unix man pages and HTML
247 documents) for any installable items under blib/ that contain POD.
248 If there are no "bindoc" or "libdoc" installation targets defined
249 (as will be the case on systems that don't support Unix manpages)
250 no action is taken for manpages. If there are no "binhtml" or
251 "libhtml" installation targets defined no action is taken for HTML
252 documents.
253 fakeinstall
255 [version 0.02]
256 This is just like the "install" action, but it won't actually do
258 anything, it will just report what it would have done if you had
259 actually run the "install" action.
260 help
262 [version 0.03]
263 This action will simply print out a message that is meant to help
265 you use the build process. It will show you a list of available
266 build actions too.
267 With an optional argument specifying an action name (e.g. "Build
269 help test"), the 'help' action will show you any POD documentation
270 it can find for that action.
271 html
273 [version 0.26]
274 This will generate HTML documentation for any binary or library
276 files under blib/ that contain POD. The HTML documentation will
277 only be installed if the install paths can be determined from
278 values in "Config.pm". You can also supply or override install
279 paths on the command line by specifying "install_path" values for
280 the "binhtml" and/or "libhtml" installation targets.
281 With an optional "html_links" argument set to a false value, you
283 can skip the search for other documentation to link to, because
284 that can waste a lot of time if there aren't any links to generate
285 anyway:
286 ./Build html --html_links 0
288 install
290 [version 0.01]
291 This action will use "ExtUtils::Install" to install the files from
293 "blib/" into the system. See "INSTALL PATHS" for details about how
294 Module::Build determines where to install things, and how to
295 influence this process.
296 If you want the installation process to look around in @INC for
298 other versions of the stuff you're installing and try to delete it,
299 you can use the "uninst" parameter, which tells "ExtUtils::Install"
300 to do so:
301 ./Build install uninst=1
303 This can be a good idea, as it helps prevent multiple versions of a
305 module from being present on your system, which can be a confusing
306 situation indeed.
307 installdeps
309 [version 0.36]
310 This action will use the "cpan_client" parameter as a command to
312 install missing prerequisites. You will be prompted whether to
313 install optional dependencies.
314 The "cpan_client" option defaults to 'cpan' but can be set as an
316 option or in .modulebuildrc. It must be a shell command that takes
317 a list of modules to install as arguments (e.g. 'cpanp -i' for
318 CPANPLUS). If the program part is a relative path (e.g. 'cpan' or
319 'cpanp'), it will be located relative to the perl program that
320 executed Build.PL.
321 /opt/perl/5.8.9/bin/perl Build.PL
323 ./Build installdeps --cpan_client 'cpanp -i'
324 # installs to 5.8.9
325 manifest
327 [version 0.05]
328 This is an action intended for use by module authors, not people
330 installing modules. It will bring the MANIFEST up to date with the
331 files currently present in the distribution. You may use a
332 MANIFEST.SKIP file to exclude certain files or directories from
333 inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of
334 regular expressions, one per line. If a file in the distribution
335 directory matches any of the regular expressions, it won't be
336 included in the MANIFEST.
337 The following is a reasonable MANIFEST.SKIP starting point, you can
339 add your own stuff to it:
340 ^_build
342 ^Build$
343 ^blib
344 ~$
345 \.bak$
346 ^MANIFEST\.SKIP$
347 CVS
348 See the distcheck and skipcheck actions if you want to find out
350 what the "manifest" action would do, without actually doing
351 anything.
352 manifest_skip
354 [version 0.3608]
355 This is an action intended for use by module authors, not people
357 installing modules. It will generate a boilerplate MANIFEST.SKIP
358 file if one does not already exist.
359 manpages
361 [version 0.28]
362 This will generate man pages for any binary or library files under
364 blib/ that contain POD. The man pages will only be installed if
365 the install paths can be determined from values in "Config.pm".
366 You can also supply or override install paths by specifying there
367 values on the command line with the "bindoc" and "libdoc"
368 installation targets.
369 pardist
371 [version 0.2806]
372 Generates a PAR binary distribution for use with PAR or PAR::Dist.
374 It requires that the PAR::Dist module (version 0.17 and up) is
376 installed on your system.
377 ppd [version 0.20]
379 Build a PPD file for your distribution.
381 This action takes an optional argument "codebase" which is used in
383 the generated PPD file to specify the (usually relative) URL of the
384 distribution. By default, this value is the distribution name
385 without any path information.
386 Example:
388 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
390 ppmdist
392 [version 0.23]
393 Generates a PPM binary distribution and a PPD description file.
395 This action also invokes the "ppd" action, so it can accept the
396 same "codebase" argument described under that action.
397 This uses the same mechanism as the "dist" action to tar & zip its
399 output, so you can supply "tar" and/or "gzip" parameters to affect
400 the result.
401 prereq_data
403 [version 0.32]
404 This action prints out a Perl data structure of all prerequisites
406 and the versions required. The output can be loaded again using
407 "eval()". This can be useful for external tools that wish to query
408 a Build script for prerequisites.
409 prereq_report
411 [version 0.28]
412 This action prints out a list of all prerequisites, the versions
414 required, and the versions actually installed. This can be useful
415 for reviewing the configuration of your system prior to a build, or
416 when compiling data to send for a bug report.
417 pure_install
419 [version 0.28]
420 This action is identical to the "install" action. In the future,
422 though, when "install" starts writing to the file
423 $(INSTALLARCHLIB)/perllocal.pod, "pure_install" won't, and that
424 will be the only difference between them.
425 realclean
427 [version 0.01]
428 This action is just like the "clean" action, but also removes the
430 "_build" directory and the "Build" script. If you run the
431 "realclean" action, you are essentially starting over, so you will
432 have to re-create the "Build" script again.
433 retest
435 [version 0.2806]
436 This is just like the "test" action, but doesn't actually build the
438 distribution first, and doesn't add blib/ to the load path, and
439 therefore will test against a previously installed version of the
440 distribution. This can be used to verify that a certain installed
441 distribution still works, or to see whether newer versions of a
442 distribution still pass the old regression tests, and so on.
443 skipcheck
445 [version 0.05]
446 Reports which files are skipped due to the entries in the
448 MANIFEST.SKIP file (See manifest for details)
449 test
451 [version 0.01]
452 This will use "Test::Harness" or "TAP::Harness" to run any
454 regression tests and report their results. Tests can be defined in
455 the standard places: a file called "test.pl" in the top-level
456 directory, or several files ending with ".t" in a "t/" directory.
457 If you want tests to be 'verbose', i.e. show details of test
459 execution rather than just summary information, pass the argument
460 "verbose=1".
461 If you want to run tests under the perl debugger, pass the argument
463 "debugger=1".
464 If you want to have Module::Build find test files with different
466 file name extensions, pass the "test_file_exts" argument with an
467 array of extensions, such as "[qw( .t .s .z )]".
468 If you want test to be run by "TAP::Harness", rather than
470 "Test::Harness", pass the argument "tap_harness_args" as an array
471 reference of arguments to pass to the TAP::Harness constructor.
472 In addition, if a file called "visual.pl" exists in the top-level
474 directory, this file will be executed as a Perl script and its
475 output will be shown to the user. This is a good place to put
476 speed tests or other tests that don't use the "Test::Harness"
477 format for output.
478 To override the choice of tests to run, you may pass a "test_files"
480 argument whose value is a whitespace-separated list of test scripts
481 to run. This is especially useful in development, when you only
482 want to run a single test to see whether you've squashed a certain
483 bug yet:
484 ./Build test --test_files t/something_failing.t
486 You may also pass several "test_files" arguments separately:
488 ./Build test --test_files t/one.t --test_files t/two.t
490 or use a "glob()"-style pattern:
492 ./Build test --test_files 't/01-*.t'
494 testall
496 [version 0.2807]
497 [Note: the 'testall' action and the code snippets below are
499 currently in alpha stage, see
500 "/www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html""
501 in "http: ]
502 Runs the "test" action plus each of the "test$type" actions defined
504 by the keys of the "test_types" parameter.
505 Currently, you need to define the ACTION_test$type method yourself
507 and enumerate them in the test_types parameter.
508 my $mb = Module::Build->subclass(
510 code => q(
511 sub ACTION_testspecial { shift->generic_test(type => 'special'); }
512 sub ACTION_testauthor { shift->generic_test(type => 'author'); }
513 )
514 )->new(
515 ...
516 test_types => {
517 special => '.st',
518 author => ['.at', '.pt' ],
519 },
520 ...
521 testcover
523 [version 0.26]
524 Runs the "test" action using "Devel::Cover", generating a code-
526 coverage report showing which parts of the code were actually
527 exercised during the tests.
528 To pass options to "Devel::Cover", set the $DEVEL_COVER_OPTIONS
530 environment variable:
531 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
533 testdb
535 [version 0.05]
536 This is a synonym for the 'test' action with the "debugger=1"
538 argument.
539 testpod
541 [version 0.25]
542 This checks all the files described in the "docs" action and
544 produces "Test::Harness"-style output. If you are a module author,
545 this is useful to run before creating a new release.
546 testpodcoverage
548 [version 0.28]
549 This checks the pod coverage of the distribution and produces
551 "Test::Harness"-style output. If you are a module author, this is
552 useful to run before creating a new release.
553 versioninstall
555 [version 0.16]
556 ** Note: since "only.pm" is so new, and since we just recently
558 added support for it here too, this feature is to be considered
559 experimental. **
560 If you have the "only.pm" module installed on your system, you can
562 use this action to install a module into the version-specific
563 library trees. This means that you can have several versions of
564 the same module installed and "use" a specific one like this:
565 use only MyModule => 0.55;
567 To override the default installation libraries in "only::config",
569 specify the "versionlib" parameter when you run the "Build.PL"
570 script:
571 perl Build.PL --versionlib /my/version/place/
573 To override which version the module is installed as, specify the
575 "version" parameter when you run the "Build.PL" script:
576 perl Build.PL --version 0.50
578 See the "only.pm" documentation for more information on version-
580 specific installs.
581
583 Command Line Options
584 The following options can be used during any invocation of "Build.PL"
585 or the Build script, during any action. For information on other
586 options specific to an action, see the documentation for the respective
587 action.
588 NOTE: There is some preliminary support for options to use the more
590 familiar long option style. Most options can be preceded with the "--"
591 long option prefix, and the underscores changed to dashes (e.g.
592 "--use-rcfile"). Additionally, the argument to boolean options is
593 optional, and boolean options can be negated by prefixing them with
594 "no" or "no-" (e.g. "--noverbose" or "--no-verbose").
595 quiet
597 Suppress informative messages on output.
598 verbose
600 Display extra information about the Build on output. "verbose"
601 will turn off "quiet"
602 cpan_client
604 Sets the "cpan_client" command for use with the "installdeps"
605 action. See "installdeps" for more details.
606 use_rcfile
608 Load the ~/.modulebuildrc option file. This option can be set to
609 false to prevent the custom resource file from being loaded.
610 allow_mb_mismatch
612 Suppresses the check upon startup that the version of Module::Build
613 we're now running under is the same version that was initially
614 invoked when building the distribution (i.e. when the "Build.PL"
615 script was first run). As of 0.3601, a mismatch results in a
616 warning instead of a fatal error, so this option effectively just
617 suppresses the warning.
618 debug
620 Prints Module::Build debugging information to STDOUT, such as a
621 trace of executed build actions.
622 Default Options File (.modulebuildrc)
624 [version 0.28]
625 When Module::Build starts up, it will look first for a file,
627 $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in
628 the .modulebuildrc file in the directories referred to by the
629 environment variables "HOMEDRIVE" + "HOMEDIR", "USERPROFILE",
630 "APPDATA", "WINDIR", "SYS$LOGIN". If the file exists, the options
631 specified there will be used as defaults, as if they were typed on the
632 command line. The defaults can be overridden by specifying new values
633 on the command line.
634 The action name must come at the beginning of the line, followed by any
636 amount of whitespace and then the options. Options are given the same
637 as they would be on the command line. They can be separated by any
638 amount of whitespace, including newlines, as long there is whitespace
639 at the beginning of each continued line. Anything following a hash
640 mark ("#") is considered a comment, and is stripped before parsing. If
641 more than one line begins with the same action name, those lines are
642 merged into one set of options.
643 Besides the regular actions, there are two special pseudo-actions: the
645 key "*" (asterisk) denotes any global options that should be applied to
646 all actions, and the key 'Build_PL' specifies options to be applied
647 when you invoke "perl Build.PL".
648 * verbose=1 # global options
650 diff flags=-u
651 install --install_base /home/ken
652 --install_path html=/home/ken/docs/html
653 installdeps --cpan_client 'cpanp -i'
654 If you wish to locate your resource file in a different location, you
656 can set the environment variable "MODULEBUILDRC" to the complete
657 absolute path of the file containing your options.
658 Environment variables
660 MODULEBUILDRC
661 [version 0.28]
662 Specifies an alternate location for a default options file as
664 described above.
665 PERL_MB_OPT
667 [version 0.36]
668 Command line options that are applied to Build.PL or any Build
670 action. The string is split as the shell would (e.g. whitespace)
671 and the result is prepended to any actual command-line arguments.
672
674 [version 0.19]
675 When you invoke Module::Build's "build" action, it needs to figure out
677 where to install things. The nutshell version of how this works is
678 that default installation locations are determined from Config.pm, and
679 they may be overridden by using the "install_path" parameter. An
680 "install_base" parameter lets you specify an alternative installation
681 root like /home/foo, and a "destdir" lets you specify a temporary
682 installation directory like /tmp/install in case you want to create
683 bundled-up installable packages.
684 Natively, Module::Build provides default installation locations for the
686 following types of installable items:
687 lib Usually pure-Perl module files ending in .pm.
689 arch
691 "Architecture-dependent" module files, usually produced by
692 compiling XS, Inline, or similar code.
693 script
695 Programs written in pure Perl. In order to improve reuse, try to
696 make these as small as possible - put the code into modules
697 whenever possible.
698 bin "Architecture-dependent" executable programs, i.e. compiled C code
700 or something. Pretty rare to see this in a perl distribution, but
701 it happens.
702 bindoc
704 Documentation for the stuff in "script" and "bin". Usually
705 generated from the POD in those files. Under Unix, these are
706 manual pages belonging to the 'man1' category.
707 libdoc
709 Documentation for the stuff in "lib" and "arch". This is usually
710 generated from the POD in .pm files. Under Unix, these are manual
711 pages belonging to the 'man3' category.
712 binhtml
714 This is the same as "bindoc" above, but applies to HTML documents.
715 libhtml
717 This is the same as "libdoc" above, but applies to HTML documents.
718 Four other parameters let you control various aspects of how
720 installation paths are determined:
721 installdirs
723 The default destinations for these installable things come from
724 entries in your system's "Config.pm". You can select from three
725 different sets of default locations by setting the "installdirs"
726 parameter as follows:
727 'installdirs' set to:
729 core site vendor
730 uses the following defaults from Config.pm:
732 lib => installprivlib installsitelib installvendorlib
734 arch => installarchlib installsitearch installvendorarch
735 script => installscript installsitescript installvendorscript
736 bin => installbin installsitebin installvendorbin
737 bindoc => installman1dir installsiteman1dir installvendorman1dir
738 libdoc => installman3dir installsiteman3dir installvendorman3dir
739 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
740 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
741 * Under some OS (eg. MSWin32) the destination for HTML documents is
743 determined by the C<Config.pm> entry C<installhtmldir>.
744 The default value of "installdirs" is "site". If you're creating
746 vendor distributions of module packages, you may want to do
747 something like this:
748 perl Build.PL --installdirs vendor
750 or
752 ./Build install --installdirs vendor
754 If you're installing an updated version of a module that was
756 included with perl itself (i.e. a "core module"), then you may set
757 "installdirs" to "core" to overwrite the module in its present
758 location.
759 (Note that the 'script' line is different from "MakeMaker" -
761 unfortunately there's no such thing as "installsitescript" or
762 "installvendorscript" entry in "Config.pm", so we use the
763 "installsitebin" and "installvendorbin" entries to at least get the
764 general location right. In the future, if "Config.pm" adds some
765 more appropriate entries, we'll start using those.)
766 install_path
768 Once the defaults have been set, you can override them.
769 On the command line, that would look like this:
771 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
773 or this:
775 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
777 install_base
779 You can also set the whole bunch of installation paths by supplying
780 the "install_base" parameter to point to a directory on your
781 system. For instance, if you set "install_base" to "/home/ken" on
782 a Linux system, you'll install as follows:
783 lib => /home/ken/lib/perl5
785 arch => /home/ken/lib/perl5/i386-linux
786 script => /home/ken/bin
787 bin => /home/ken/bin
788 bindoc => /home/ken/man/man1
789 libdoc => /home/ken/man/man3
790 binhtml => /home/ken/html
791 libhtml => /home/ken/html
792 Note that this is different from how "MakeMaker"'s "PREFIX"
794 parameter works. "install_base" just gives you a default layout
795 under the directory you specify, which may have little to do with
796 the "installdirs=site" layout.
797 The exact layout under the directory you specify may vary by system
799 - we try to do the "sensible" thing on each platform.
800 destdir
802 If you want to install everything into a temporary directory first
803 (for instance, if you want to create a directory tree that a
804 package manager like "rpm" or "dpkg" could create a package from),
805 you can use the "destdir" parameter:
806 perl Build.PL --destdir /tmp/foo
808 or
810 ./Build install --destdir /tmp/foo
812 This will effectively install to "/tmp/foo/$sitelib",
814 "/tmp/foo/$sitearch", and the like, except that it will use
815 "File::Spec" to make the pathnames work correctly on whatever
816 platform you're installing on.
817 prefix
819 Provided for compatibility with "ExtUtils::MakeMaker"'s PREFIX
820 argument. "prefix" should be used when you want Module::Build to
821 install your modules, documentation, and scripts in the same place
822 as "ExtUtils::MakeMaker"'s PREFIX mechanism.
823 The following are equivalent.
825 perl Build.PL --prefix /tmp/foo
827 perl Makefile.PL PREFIX=/tmp/foo
828 Because of the complex nature of the prefixification logic, the
830 behavior of PREFIX in "MakeMaker" has changed subtly over time.
831 Module::Build's --prefix logic is equivalent to the PREFIX logic
832 found in "ExtUtils::MakeMaker" 6.30.
833 The maintainers of "MakeMaker" do understand the troubles with the
835 PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of
836 "MakeMaker", which was released in 2006.
837 If you don't need to retain compatibility with old versions
839 (pre-6.31) of "ExtUtils::MakeMaker" or are starting a fresh Perl
840 installation we recommend you use "install_base" instead (and
841 "INSTALL_BASE" in "ExtUtils::MakeMaker"). See "Installing in the
842 same location as ExtUtils::MakeMaker" in Module::Build::Cookbook
843 for further information.
844
846 There are several reasons I wanted to start over, and not just fix what
847 I didn't like about "MakeMaker":
848 · I don't like the core idea of "MakeMaker", namely that "make"
850 should be involved in the build process. Here are my reasons:
851 + When a person is installing a Perl module, what can you assume
853 about their environment? Can you assume they have "make"? No,
854 but you can assume they have some version of Perl.
855 + When a person is writing a Perl module for intended
857 distribution, can you assume that they know how to build a
858 Makefile, so they can customize their build process? No, but
859 you can assume they know Perl, and could customize that way.
860 For years, these things have been a barrier to people getting the
862 build/install process to do what they want.
863 · There are several architectural decisions in "MakeMaker" that make
865 it very difficult to customize its behavior. For instance, when
866 using "MakeMaker" you do "use ExtUtils::MakeMaker", but the object
867 created in "WriteMakefile()" is actually blessed into a package
868 name that's created on the fly, so you can't simply subclass
869 "ExtUtils::MakeMaker". There is a workaround "MY" package that
870 lets you override certain "MakeMaker" methods, but only certain
871 explicitly preselected (by "MakeMaker") methods can be overridden.
872 Also, the method of customization is very crude: you have to modify
873 a string containing the Makefile text for the particular target.
874 Since these strings aren't documented, and can't be documented
875 (they take on different values depending on the platform, version
876 of perl, version of "MakeMaker", etc.), you have no guarantee that
877 your modifications will work on someone else's machine or after an
878 upgrade of "MakeMaker" or perl.
879 · It is risky to make major changes to "MakeMaker", since it does so
881 many things, is so important, and generally works. "Module::Build"
882 is an entirely separate package so that I can work on it all I
883 want, without worrying about backward compatibility with
884 "MakeMaker".
885 · Finally, Perl is said to be a language for system administration.
887 Could it really be the case that Perl isn't up to the task of
888 building and installing software? Even if that software is a bunch
889 of ".pm" files that just need to be copied from one place to
890 another? My sense was that we could design a system to accomplish
891 this in a flexible, extensible, and friendly manner. Or die
892 trying.
893
895 The current method of relying on time stamps to determine whether a
896 derived file is out of date isn't likely to scale well, since it
897 requires tracing all dependencies backward, it runs into problems on
898 NFS, and it's just generally flimsy. It would be better to use an MD5
899 signature or the like, if available. See "cons" for an example.
900 - append to perllocal.pod
902 - add a 'plugin' functionality
903
905 Ken Williams <kwilliams@cpan.org>
906 Development questions, bug reports, and patches should be sent to the
908 Module-Build mailing list at <module-build@perl.org>.
909 Bug reports are also welcome at
911 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
912 The latest development version is available from the Git repository at
914 <https://github.com/Perl-Toolchain-Gang/Module-Build>
915
917 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
918 This library is free software; you can redistribute it and/or modify it
920 under the same terms as Perl itself.
921
923 perl(1), Module::Build::Cookbook, Module::Build::Authoring,
924 Module::Build::API, ExtUtils::MakeMaker
925 META.yml Specification: CPAN::Meta::Spec
927 <http://www.dsmit.com/cons/>
929 <http://search.cpan.org/dist/PerlBuildSystem/>
931perl v5.26.3 2019-05-14 Module::Build(3)