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