1Module::Build(3) User Contributed Perl Documentation Module::Build(3)
2
3
4
6 Module::Build - Build and install Perl modules
7
9 Standard process for building & installing modules:
10
11 perl Build.PL
12 ./Build
13 ./Build test
14 ./Build install
15
16 Or, if you're on a platform (like DOS or Windows) that doesn't require
17 the "./" notation, you can do this:
18
19 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.
28 It also does not require a "make" on your system - most of the
29 "Module::Build" code is pure-perl and written in a very cross-platform
30 way.
31
32 See "COMPARISON" for more comparisons between "Module::Build" and other
33 installer tools.
34
35 To install "Module::Build", and any other module that uses
36 "Module::Build" for its installation process, do the following:
37
38 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
43 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
47 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
67 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
72 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
78 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
84 API Reference (Module::Build::API)
85 This is a reference to the "Module::Build" API.
86
87 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
98 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
107 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
111 perl Build.PL --config cc=gcc --config ld=gcc
112
113 The following build actions are provided by default.
114
115 build
116 [version 0.01]
117
118 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
121 This is analogous to the "MakeMaker" make all target.
122
123 clean
124 [version 0.01]
125
126 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
130 code
131 [version 0.20]
132
133 This action builds your code base.
134
135 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
142 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
149 config_data
150 [version 0.26]
151
152 ...
153
154 diff
155 [version 0.14]
156
157 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
163 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
167 ./Build diff flags=-u
168
169 dist
170 [version 0.02]
171
172 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
177 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
182 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
183
184 distcheck
185 [version 0.05]
186
187 Reports which files are in the build directory but not in the
188 MANIFEST file, and vice versa. (See "manifest" for details.)
189
190 distclean
191 [version 0.05]
192
193 Performs the 'realclean' action and then the 'distcheck' action.
194
195 distdir
196 [version 0.05]
197
198 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
203 distinstall
204 [version 0.37]
205
206 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
211 distmeta
212 [version 0.21]
213
214 Creates the META.yml file that describes the distribution.
215
216 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
222 META.yml file must also be listed in MANIFEST - if it's not, a
223 warning will be issued.
224
225 The current version of the META.yml specification can be found on
226 CPAN as CPAN::Meta::Spec.
227
228 distsign
229 [version 0.16]
230
231 Uses "Module::Signature" to create a SIGNATURE file for your
232 distribution, and adds the SIGNATURE file to the distribution's
233 MANIFEST.
234
235 disttest
236 [version 0.05]
237
238 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
243 docs
244 [version 0.20]
245
246 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
254 fakeinstall
255 [version 0.02]
256
257 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
261 help
262 [version 0.03]
263
264 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
268 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
272 html
273 [version 0.26]
274
275 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
282 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
287 ./Build html --html_links 0
288
289 install
290 [version 0.01]
291
292 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
297 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
302 ./Build install uninst=1
303
304 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
308 installdeps
309 [version 0.36]
310
311 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
315 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
322 /opt/perl/5.8.9/bin/perl Build.PL
323 ./Build installdeps --cpan_client 'cpanp -i'
324 # installs to 5.8.9
325
326 manifest
327 [version 0.05]
328
329 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
338 The following is a reasonable MANIFEST.SKIP starting point, you can
339 add your own stuff to it:
340
341 ^_build
342 ^Build$
343 ^blib
344 ~$
345 \.bak$
346 ^MANIFEST\.SKIP$
347 CVS
348
349 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
353 manifest_skip
354 [version 0.3608]
355
356 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
360 manpages
361 [version 0.28]
362
363 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
370 pardist
371 [version 0.2806]
372
373 Generates a PAR binary distribution for use with PAR or PAR::Dist.
374
375 It requires that the PAR::Dist module (version 0.17 and up) is
376 installed on your system.
377
378 ppd [version 0.20]
379
380 Build a PPD file for your distribution.
381
382 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
387 Example:
388
389 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
390
391 ppmdist
392 [version 0.23]
393
394 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
398 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
402 prereq_data
403 [version 0.32]
404
405 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
410 prereq_report
411 [version 0.28]
412
413 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
418 pure_install
419 [version 0.28]
420
421 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
426 realclean
427 [version 0.01]
428
429 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
434 retest
435 [version 0.2806]
436
437 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
444 skipcheck
445 [version 0.05]
446
447 Reports which files are skipped due to the entries in the
448 MANIFEST.SKIP file (See "manifest" for details)
449
450 test
451 [version 0.01]
452
453 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
458 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
462 If you want to run tests under the perl debugger, pass the argument
463 "debugger=1".
464
465 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
469 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
473 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
479 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
485 ./Build test --test_files t/something_failing.t
486
487 You may also pass several "test_files" arguments separately:
488
489 ./Build test --test_files t/one.t --test_files t/two.t
490
491 or use a "glob()"-style pattern:
492
493 ./Build test --test_files 't/01-*.t'
494
495 testall
496 [version 0.2807]
497
498 [Note: the 'testall' action and the code snippets below are
499 currently in alpha stage, see
500 <http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html>
501 ]
502
503 Runs the "test" action plus each of the "test$type" actions defined
504 by the keys of the "test_types" parameter.
505
506 Currently, you need to define the ACTION_test$type method yourself
507 and enumerate them in the test_types parameter.
508
509 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
522 testcover
523 [version 0.26]
524
525 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
529 To pass options to "Devel::Cover", set the $DEVEL_COVER_OPTIONS
530 environment variable:
531
532 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
533
534 testdb
535 [version 0.05]
536
537 This is a synonym for the 'test' action with the "debugger=1"
538 argument.
539
540 testpod
541 [version 0.25]
542
543 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
547 testpodcoverage
548 [version 0.28]
549
550 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
554 versioninstall
555 [version 0.16]
556
557 ** 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
561 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
566 use only MyModule => 0.55;
567
568 To override the default installation libraries in "only::config",
569 specify the "versionlib" parameter when you run the "Build.PL"
570 script:
571
572 perl Build.PL --versionlib /my/version/place/
573
574 To override which version the module is installed as, specify the
575 "version" parameter when you run the "Build.PL" script:
576
577 perl Build.PL --version 0.50
578
579 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
589 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
596 quiet
597 Suppress informative messages on output.
598
599 verbose
600 Display extra information about the Build on output. "verbose"
601 will turn off "quiet"
602
603 cpan_client
604 Sets the "cpan_client" command for use with the "installdeps"
605 action. See "installdeps" for more details.
606
607 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
611 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
619 debug
620 Prints Module::Build debugging information to STDOUT, such as a
621 trace of executed build actions.
622
623 Default Options File (.modulebuildrc)
624 [version 0.28]
625
626 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
635 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
644 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
649 * 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
655 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
659 Environment variables
660 MODULEBUILDRC
661 [version 0.28]
662
663 Specifies an alternate location for a default options file as
664 described above.
665
666 PERL_MB_OPT
667 [version 0.36]
668
669 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
676 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
685 Natively, Module::Build provides default installation locations for the
686 following types of installable items:
687
688 lib Usually pure-Perl module files ending in .pm.
689
690 arch
691 "Architecture-dependent" module files, usually produced by
692 compiling XS, Inline, or similar code.
693
694 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
699 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
703 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
708 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
713 binhtml
714 This is the same as "bindoc" above, but applies to HTML documents.
715
716 libhtml
717 This is the same as "libdoc" above, but applies to HTML documents.
718
719 Four other parameters let you control various aspects of how
720 installation paths are determined:
721
722 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
728 'installdirs' set to:
729 core site vendor
730
731 uses the following defaults from Config.pm:
732
733 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
742 * Under some OS (eg. MSWin32) the destination for HTML documents is
743 determined by the C<Config.pm> entry C<installhtmldir>.
744
745 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
749 perl Build.PL --installdirs vendor
750
751 or
752
753 ./Build install --installdirs vendor
754
755 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
760 (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
767 install_path
768 Once the defaults have been set, you can override them.
769
770 On the command line, that would look like this:
771
772 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
773
774 or this:
775
776 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
777
778 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
784 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
793 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
798 The exact layout under the directory you specify may vary by system
799 - we try to do the "sensible" thing on each platform.
800
801 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
807 perl Build.PL --destdir /tmp/foo
808
809 or
810
811 ./Build install --destdir /tmp/foo
812
813 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
818 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
824 The following are equivalent.
825
826 perl Build.PL --prefix /tmp/foo
827 perl Makefile.PL PREFIX=/tmp/foo
828
829 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
834 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
838 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 A comparison between "Module::Build" and other CPAN distribution
847 installers.
848
849 · ExtUtils::MakeMaker requires "make" and use of a Makefile.
850 "Module::Build" does not, nor do other pure-perl installers
851 following the Build.PL spec such as Module::Build::Tiny. In
852 practice, this is usually not an issue for the end user, as "make"
853 is already required to install most CPAN modules, even on Windows.
854
855 · ExtUtils::MakeMaker has been a core module in every version of Perl
856 5, and must maintain compatibility to install the majority of CPAN
857 modules. "Module::Build" was added to core in Perl 5.10 and
858 removed from core in Perl 5.20, and (like ExtUtils::MakeMaker) is
859 only updated to fix critical issues and maintain compatibility.
860 "Module::Build" and other non-core installers like
861 Module::Build::Tiny are installed from CPAN by declaring themselves
862 as a "configure" phase prerequisite, and in this way any installer
863 can be used in place of ExtUtils::MakeMaker.
864
865 · Customizing the build process with ExtUtils::MakeMaker involves
866 overriding certain methods that form the Makefile by defining the
867 subs in the "MY::" namespace, requiring in-depth knowledge of
868 Makefile, but allowing targeted customization of the entire build.
869 Customizing "Module::Build" involves subclassing "Module::Build"
870 itself, adding or overriding pure-perl methods that represent build
871 actions, which are invoked as arguments passed to the generated
872 "./Build" script. This is a simpler concept but requires redefining
873 the standard build actions to invoke your customizations.
874 Module::Build::Tiny does not allow for customization.
875
876 · "Module::Build" provides more features and a better experience for
877 distribution authors than ExtUtils::MakeMaker. However, tools
878 designed specifically for authoring, such as Dist::Zilla and its
879 spinoffs Dist::Milla and Minilla, provide these features and more,
880 and generate a configure script (Makefile.PL/Build.PL) that will
881 use any of the various installers separately on the end user side.
882 App::ModuleBuildTiny is an alternative standalone authoring tool
883 for distributions using Module::Build::Tiny, which requires only a
884 simple two-line Build.PL.
885
887 The current method of relying on time stamps to determine whether a
888 derived file is out of date isn't likely to scale well, since it
889 requires tracing all dependencies backward, it runs into problems on
890 NFS, and it's just generally flimsy. It would be better to use an MD5
891 signature or the like, if available. See "cons" for an example.
892
893 - append to perllocal.pod
894 - add a 'plugin' functionality
895
897 Ken Williams <kwilliams@cpan.org>
898
899 Development questions, bug reports, and patches should be sent to the
900 Module-Build mailing list at <module-build@perl.org>.
901
902 Bug reports are also welcome at
903 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
904
905 The latest development version is available from the Git repository at
906 <https://github.com/Perl-Toolchain-Gang/Module-Build>
907
909 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
910
911 This library is free software; you can redistribute it and/or modify it
912 under the same terms as Perl itself.
913
915 perl(1), Module::Build::Cookbook, Module::Build::Authoring,
916 Module::Build::API, ExtUtils::MakeMaker
917
918 META.yml Specification: CPAN::Meta::Spec
919
920 <http://www.dsmit.com/cons/>
921
922 <http://search.cpan.org/dist/PerlBuildSystem/>
923
924
925
926perl v5.30.0 2019-07-26 Module::Build(3)