1Module::Build(3)      User Contributed Perl Documentation     Module::Build(3)
2
3
4

NAME

6       Module::Build - Build and install Perl modules
7

SYNOPSIS

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

DESCRIPTION

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

GUIDE TO DOCUMENTATION

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

ACTIONS

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 a
408           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

OPTIONS

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

INSTALL PATHS

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

COMPARISON

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

TO DO

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

AUTHOR

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

SEE ALSO

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.36.0                      2023-01-20                  Module::Build(3)
Impressum