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 "Mod‐
40 ule::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 manpages
53 code pardist
54 config_data ppd
55 diff ppmdist
56 dist prereq_report
57 distcheck pure_install
58 distclean realclean
59 distdir retest
60 distmeta skipcheck
61 distsign test
62 disttest testall
63 docs testcover
64 fakeinstall testdb
65 help testpod
66 html testpodcoverage
67 install versioninstall
68 You can run the 'help' action for a complete list of actions.
70
72 The documentation for "Module::Build" is broken up into three sections:
73 General Usage (Module::Build)
75 This is the document you are currently reading. It describes basic
76 usage and background information. Its main purpose is to assist
77 the user who wants to learn how to invoke and control "Mod‐
78 ule::Build" scripts at the command line.
79 Authoring Reference (Module::Build::Authoring)
81 This document describes the structure and organization of "Mod‐
82 ule::Build", and the relevant concepts needed by authors who are
83 writing Build.PL scripts for a distribution or controlling "Mod‐
84 ule::Build" processes programmatically.
85 API Reference (Module::Build::API)
87 This is a reference to the "Module::Build" API.
88 Cookbook (Module::Build::Cookbook)
90 This document demonstrates how to accomplish many common tasks. It
91 covers general command line usage and authoring of Build.PL
92 scripts. Includes working examples.
93
95 There are some general principles at work here. First, each task when
96 building a module is called an "action". These actions are listed
97 above; they correspond to the building, testing, installing, packaging,
98 etc., tasks.
99 Second, arguments are processed in a very systematic way. Arguments
101 are always key=value pairs. They may be specified at "perl Build.PL"
102 time (i.e. "perl Build.PL destdir=/my/secret/place"), in which case
103 their values last for the lifetime of the "Build" script. They may
104 also be specified when executing a particular action (i.e. "Build test
105 verbose=1"), in which case their values last only for the lifetime of
106 that command. Per-action command line parameters take precedence over
107 parameters specified at "perl Build.PL" time.
108 The build process also relies heavily on the "Config.pm" module, and
110 all the key=value pairs in "Config.pm" are available in
111 "$self->{config}". If the user wishes to override any of the values in
113 "Config.pm", she may 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 codebase.
138 By default it just creates a "blib/" directory and copies any ".pm"
140 and ".pod" files from your "lib/" directory into the "blib/" direc‐
141 tory. It also compiles any ".xs" files from "lib/" and places them
142 in "blib/". Of course, you need a working C compiler (probably the
143 same one that built perl itself) for the compilation to work prop‐
144 erly.
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 com‐
179 press the tarball using GZIP compression.
180 By default, this action will use the external "tar" and "gzip" exe‐
182 cutables on Unix-like platforms, and the "Archive::Tar" module
183 elsewhere. However, you can force it to use whatever executable
184 you want by supplying an explicit "tar" (and optional "gzip")
185 parameter:
186 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
188 distcheck
190 [version 0.05]
191 Reports which files are in the build directory but not in the MANI‐
193 FEST file, and vice versa. (See manifest for details.)
194 distclean
196 [version 0.05]
197 Performs the 'realclean' action and then the 'distcheck' action.
199 distdir
201 [version 0.05]
202 Creates a "distribution directory" named "$dist_name-$dist_version"
204 (if that directory already exists, it will be removed first), then
205 copies all the files listed in the MANIFEST file to that directory.
206 This directory is what the distribution tarball is created from.
207 distmeta
209 [version 0.21]
210 Creates the META.yml file that describes the distribution.
212 META.yml is a file containing various bits of "metadata" about the
214 distribution. The metadata includes the distribution name, ver‐
215 sion, abstract, prerequisites, license, and various other data
216 about the distribution. This file is created as META.yml in YAML
217 format. It is recommended that the "YAML" module be installed to
218 create it. If the "YAML" module is not installed, an internal mod‐
219 ule supplied with Module::Build will be used to write the META.yml
220 file, and this will most likely be fine.
221 META.yml file must also be listed in MANIFEST - if it's not, a
223 warning will be issued.
224 The current version of the META.yml specification can be found at
226 <http://module-build.sourceforge.net/META-spec-current.html>
227 distsign
229 [version 0.16]
230 Uses "Module::Signature" to create a SIGNATURE file for your dis‐
232 tribution, and adds the SIGNATURE file to the distribution's MANI‐
233 FEST.
234 disttest
236 [version 0.05]
237 Performs the 'distdir' action, then switches into that directory
239 and runs a "perl Build.PL", followed by the 'build' and 'test'
240 actions in that directory.
241 docs
243 [version 0.20]
244 This will generate documentation (e.g. Unix man pages and html doc‐
246 uments) for any installable items under blib/ that contain POD. If
247 there are no "bindoc" or "libdoc" installation targets defined (as
248 will be the case on systems that don't support Unix manpages) no
249 action is taken for manpages. If there are no "binhtml" or "lib‐
250 html" installation targets defined no action is taken for html doc‐
251 uments.
252 fakeinstall
254 [version 0.02]
255 This is just like the "install" action, but it won't actually do
257 anything, it will just report what it would have done if you had
258 actually run the "install" action.
259 help
261 [version 0.03]
262 This action will simply print out a message that is meant to help
264 you use the build process. It will show you a list of available
265 build actions too.
266 With an optional argument specifying an action name (e.g. "Build
268 help test"), the 'help' action will show you any POD documentation
269 it can find for that action.
270 html
272 [version 0.26]
273 This will generate HTML documentation for any binary or library
275 files under blib/ that contain POD. The HTML documentation will
276 only be installed if the install paths can be determined from val‐
277 ues in "Config.pm". You can also supply or override install paths
278 on the command line by specifying "install_path" values for the
279 "binhtml" and/or "libhtml" installation targets.
280 install
282 [version 0.01]
283 This action will use "ExtUtils::Install" to install the files from
285 "blib/" into the system. See "INSTALL PATHS" for details about how
286 Module::Build determines where to install things, and how to influ‐
287 ence this process.
288 If you want the installation process to look around in @INC for
290 other versions of the stuff you're installing and try to delete it,
291 you can use the "uninst" parameter, which tells "ExtUtils::Install"
292 to do so:
293 ./Build install uninst=1
295 This can be a good idea, as it helps prevent multiple versions of a
297 module from being present on your system, which can be a confusing
298 situation indeed.
299 manifest
301 [version 0.05]
302 This is an action intended for use by module authors, not people
304 installing modules. It will bring the MANIFEST up to date with the
305 files currently present in the distribution. You may use a MANI‐
306 FEST.SKIP file to exclude certain files or directories from inclu‐
307 sion in the MANIFEST. MANIFEST.SKIP should contain a bunch of reg‐
308 ular expressions, one per line. If a file in the distribution
309 directory matches any of the regular expressions, it won't be
310 included in the MANIFEST.
311 The following is a reasonable MANIFEST.SKIP starting point, you can
313 add your own stuff to it:
314 ^_build
316 ^Build$
317 ^blib
318 ~$
319 \.bak$
320 ^MANIFEST\.SKIP$
321 CVS
322 See the distcheck and skipcheck actions if you want to find out
324 what the "manifest" action would do, without actually doing any‐
325 thing.
326 manpages
328 [version 0.28]
329 This will generate man pages for any binary or library files under
331 blib/ that contain POD. The man pages will only be installed if
332 the install paths can be determined from values in "Config.pm".
333 You can also supply or override install paths by specifying there
334 values on the command line with the "bindoc" and "libdoc" installa‐
335 tion targets.
336 pardist
338 [version 0.2806]
339 Generates a PAR binary distribution for use with PAR or PAR::Dist.
341 It requires that the PAR::Dist module (version 0.17 and up) is
343 installed on your system.
344 ppd [version 0.20]
346 Build a PPD file for your distribution.
348 This action takes an optional argument "codebase" which is used in
350 the generated ppd file to specify the (usually relative) URL of the
351 distribution. By default, this value is the distribution name
352 without any path information.
353 Example:
355 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
357 ppmdist
359 [version 0.23]
360 Generates a PPM binary distribution and a PPD description file.
362 This action also invokes the 'ppd' action, so it can accept the
363 same "codebase" argument described under that action.
364 This uses the same mechanism as the "dist" action to tar & zip its
366 output, so you can supply "tar" and/or "gzip" parameters to affect
367 the result.
368 prereq_report
370 [version 0.28]
371 This action prints out a list of all prerequisites, the versions
373 required, and the versions actually installed. This can be useful
374 for reviewing the configuration of your system prior to a build, or
375 when compiling data to send for a bug report.
376 pure_install
378 [version 0.28]
379 This action is identical to the "install" action. In the future,
381 though, if "install" starts writing to the file file $(INSTALLARCH‐
382 LIB)/perllocal.pod, "pure_install" won't, and that will be the only
383 difference between them.
384 realclean
386 [version 0.01]
387 This action is just like the "clean" action, but also removes the
389 "_build" directory and the "Build" script. If you run the "real‐
390 clean" action, you are essentially starting over, so you will have
391 to re-create the "Build" script again.
392 retest
394 [version 0.2806]
395 This is just like the "test" action, but doesn't actually build the
397 distribution first, and doesn't add blib/ to the load path, and
398 therefore will test against a previously installed version of the
399 distribution. This can be used to verify that a certain installed
400 distribution still works, or to see whether newer versions of a
401 distribution still pass the old regression tests, and so on.
402 skipcheck
404 [version 0.05]
405 Reports which files are skipped due to the entries in the MANI‐
407 FEST.SKIP file (See manifest for details)
408 test
410 [version 0.01]
411 This will use "Test::Harness" to run any regression tests and
413 report their results. Tests can be defined in the standard places:
414 a file called "test.pl" in the top-level directory, or several
415 files ending with ".t" in a "t/" directory.
416 If you want tests to be 'verbose', i.e. show details of test execu‐
418 tion rather than just summary information, pass the argument "ver‐
419 bose=1".
420 If you want to run tests under the perl debugger, pass the argument
422 "debugger=1".
423 In addition, if a file called "visual.pl" exists in the top-level
425 directory, this file will be executed as a Perl script and its out‐
426 put will be shown to the user. This is a good place to put speed
427 tests or other tests that don't use the "Test::Harness" format for
428 output.
429 To override the choice of tests to run, you may pass a "test_files"
431 argument whose value is a whitespace-separated list of test scripts
432 to run. This is especially useful in development, when you only
433 want to run a single test to see whether you've squashed a certain
434 bug yet:
435 ./Build test --test_files t/something_failing.t
437 You may also pass several "test_files" arguments separately:
439 ./Build test --test_files t/one.t --test_files t/two.t
441 or use a "glob()"-style pattern:
443 ./Build test --test_files 't/01-*.t'
445 testall
447 [verion 0.2807]
448 [Note: the 'testall' action and the code snippets below are cur‐
450 rently in alpha stage, see
451 "http://www.nntp.perl.org/group/perl.mod‐
452 ule.build/2007/03/msg584.html" ]
453 Runs the "test" action plus each of the "test$type" actions defined
455 by the keys of the "test_types" parameter.
456 Currently, you need to define the ACTION_test$type method yourself
458 and enumerate them in the test_types parameter.
459 my $mb = Module::Build->subclass(
461 code => q(
462 sub ACTION_testspecial { shift->generic_test(type => 'special'); }
463 sub ACTION_testauthor { shift->generic_test(type => 'author'); }
464 )
465 )->new(
466 ...
467 test_types => {
468 special => '.st',
469 author => '.at',
470 },
471 ...
472 testcover
474 [version 0.26]
475 Runs the "test" action using "Devel::Cover", generating a code-cov‐
477 erage report showing which parts of the code were actually exer‐
478 cised during the tests.
479 To pass options to "Devel::Cover", set the $DEVEL_COVER_OPTIONS
481 environment variable:
482 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
484 testdb
486 [version 0.05]
487 This is a synonym for the 'test' action with the "debugger=1" argu‐
489 ment.
490 testpod
492 [version 0.25]
493 This checks all the files described in the "docs" action and pro‐
495 duces "Test::Harness"-style output. If you are a module author,
496 this is useful to run before creating a new release.
497 testpodcoverage
499 [version 0.28]
500 This checks the pod coverage of the distribution and produces
502 "Test::Harness"-style output. If you are a module author, this is
503 useful to run before creating a new release.
504 versioninstall
506 [version 0.16]
507 ** Note: since "only.pm" is so new, and since we just recently
509 added support for it here too, this feature is to be considered
510 experimental. **
511 If you have the "only.pm" module installed on your system, you can
513 use this action to install a module into the version-specific
514 library trees. This means that you can have several versions of
515 the same module installed and "use" a specific one like this:
516 use only MyModule => 0.55;
518 To override the default installation libraries in "only::config",
520 specify the "versionlib" parameter when you run the "Build.PL"
521 script:
522 perl Build.PL --versionlib /my/version/place/
524 To override which version the module is installed as, specify the
526 "versionlib" parameter when you run the "Build.PL" script:
527 perl Build.PL --version 0.50
529 See the "only.pm" documentation for more information on version-
531 specific installs.
532
534 Command Line Options
535 The following options can be used during any invocation of "Build.PL"
537 or the Build script, during any action. For information on other
538 options specific to an action, see the documentation for the respective
539 action.
540 NOTE: There is some preliminary support for options to use the more
542 familiar long option style. Most options can be preceded with the "--"
543 long option prefix, and the underscores changed to dashes (e.g.
544 --use-rcfile). Additionally, the argument to boolean options is
545 optional, and boolean options can be negated by prefixing them with
546 'no' or 'no-' (e.g. --noverbose or --no-verbose).
547 quiet
549 Suppress informative messages on output.
550 use_rcfile
552 Load the ~/.modulebuildrc option file. This option can be set to
553 false to prevent the custom resource file from being loaded.
554 verbose
556 Display extra information about the Build on output.
557 allow_mb_mismatch
559 Suppresses the check upon startup that the version of Module::Build
560 we're now running under is the same version that was initially
561 invoked when building the distribution (i.e. when the "Build.PL"
562 script was first run). Use with caution.
563 Default Options File (.modulebuildrc)
565 [version 0.28]
567 When Module::Build starts up, it will look first for a file,
569 $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in
570 the the .modulebuildrc file in the directories referred to by the envi‐
571 ronment variables "HOMEDRIVE" + "HOMEDIR", "USERPROFILE", "APPDATA",
572 "WINDIR", "SYS$LOGIN". If the file exists, the options specified there
573 will be used as defaults, as if they were typed on the command line.
574 The defaults can be overridden by specifying new values on the command
575 line.
576 The action name must come at the beginning of the line, followed by any
578 amount of whitespace and then the options. Options are given the same
579 as they would be on the command line. They can be separated by any
580 amount of whitespace, including newlines, as long there is whitespace
581 at the beginning of each continued line. Anything following a hash
582 mark ("#") is considered a comment, and is stripped before parsing. If
583 more than one line begins with the same action name, those lines are
584 merged into one set of options.
585 Besides the regular actions, there are two special pseudo-actions: the
587 key "*" (asterisk) denotes any global options that should be applied to
588 all actions, and the key 'Build_PL' specifies options to be applied
589 when you invoke "perl Build.PL".
590 * verbose=1 # global options
592 diff flags=-u
593 install --install_base /home/ken
594 --install_path html=/home/ken/docs/html
595 If you wish to locate your resource file in a different location, you
597 can set the environment variable 'MODULEBUILDRC' to the complete abso‐
598 lute path of the file containing your options.
599
601 [version 0.19]
602 When you invoke Module::Build's "build" action, it needs to figure out
604 where to install things. The nutshell version of how this works is
605 that default installation locations are determined from Config.pm, and
606 they may be overridden by using the "install_path" parameter. An
607 "install_base" parameter lets you specify an alternative installation
608 root like /home/foo, and a "destdir" lets you specify a temporary
609 installation directory like /tmp/install in case you want to create
610 bundled-up installable packages.
611 Natively, Module::Build provides default installation locations for the
613 following types of installable items:
614 lib Usually pure-Perl module files ending in .pm.
616 arch
618 "Architecture-dependent" module files, usually produced by compil‐
619 ing XS, Inline, or similar code.
620 script
622 Programs written in pure Perl. In order to improve reuse, try to
623 make these as small as possible - put the code into modules when‐
624 ever possible.
625 bin "Architecture-dependent" executable programs, i.e. compiled C code
627 or something. Pretty rare to see this in a perl distribution, but
628 it happens.
629 bindoc
631 Documentation for the stuff in "script" and "bin". Usually gener‐
632 ated from the POD in those files. Under Unix, these are manual
633 pages belonging to the 'man1' category.
634 libdoc
636 Documentation for the stuff in "lib" and "arch". This is usually
637 generated from the POD in .pm files. Under Unix, these are manual
638 pages belonging to the 'man3' category.
639 binhtml
641 This is the same as "bindoc" above, but applies to html documents.
642 libhtml
644 This is the same as "bindoc" above, but applies to html documents.
645 Four other parameters let you control various aspects of how installa‐
647 tion paths are determined:
648 installdirs
650 The default destinations for these installable things come from
651 entries in your system's "Config.pm". You can select from three
652 different sets of default locations by setting the "installdirs"
653 parameter as follows:
654 'installdirs' set to:
656 core site vendor
657 uses the following defaults from Config.pm:
659 lib => installprivlib installsitelib installvendorlib
661 arch => installarchlib installsitearch installvendorarch
662 script => installscript installsitebin installvendorbin
663 bin => installbin installsitebin installvendorbin
664 bindoc => installman1dir installsiteman1dir installvendorman1dir
665 libdoc => installman3dir installsiteman3dir installvendorman3dir
666 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
667 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
668 * Under some OS (eg. MSWin32) the destination for html documents is
670 determined by the C<Config.pm> entry C<installhtmldir>.
671 The default value of "installdirs" is "site". If you're creating
673 vendor distributions of module packages, you may want to do some‐
674 thing like this:
675 perl Build.PL --installdirs vendor
677 or
679 ./Build install --installdirs vendor
681 If you're installing an updated version of a module that was
683 included with perl itself (i.e. a "core module"), then you may set
684 "installdirs" to "core" to overwrite the module in its present
685 location.
686 (Note that the 'script' line is different from MakeMaker - unfortu‐
688 nately there's no such thing as "installsitescript" or "installven‐
689 dorscript" entry in "Config.pm", so we use the "installsitebin" and
690 "installvendorbin" entries to at least get the general location
691 right. In the future, if "Config.pm" adds some more appropriate
692 entries, we'll start using those.)
693 install_path
695 Once the defaults have been set, you can override them.
696 On the command line, that would look like this:
698 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
700 or this:
702 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
704 install_base
706 You can also set the whole bunch of installation paths by supplying
707 the "install_base" parameter to point to a directory on your sys‐
708 tem. For instance, if you set "install_base" to "/home/ken" on a
709 Linux system, you'll install as follows:
710 lib => /home/ken/lib/perl5
712 arch => /home/ken/lib/perl5/i386-linux
713 script => /home/ken/bin
714 bin => /home/ken/bin
715 bindoc => /home/ken/man/man1
716 libdoc => /home/ken/man/man3
717 binhtml => /home/ken/html
718 libhtml => /home/ken/html
719 Note that this is different from how MakeMaker's "PREFIX" parameter
721 works. "install_base" just gives you a default layout under the
722 directory you specify, which may have little to do with the
723 "installdirs=site" layout.
724 The exact layout under the directory you specify may vary by system
726 - we try to do the "sensible" thing on each platform.
727 destdir
729 If you want to install everything into a temporary directory first
730 (for instance, if you want to create a directory tree that a pack‐
731 age manager like "rpm" or "dpkg" could create a package from), you
732 can use the "destdir" parameter:
733 perl Build.PL --destdir /tmp/foo
735 or
737 ./Build install --destdir /tmp/foo
739 This will effectively install to "/tmp/foo/$sitelib",
741 "/tmp/foo/$sitearch", and the like, except that it will use
742 "File::Spec" to make the pathnames work correctly on whatever plat‐
743 form you're installing on.
744 prefix
746 Provided for compatibility with ExtUtils::MakeMaker's PREFIX argu‐
747 ment. "prefix" should be used when you wish Module::Build to
748 install your modules, documentation and scripts in the same place
749 ExtUtils::MakeMaker does.
750 The following are equivalent.
752 perl Build.PL --prefix /tmp/foo
754 perl Makefile.PL PREFIX=/tmp/foo
755 Because of the very complex nature of the prefixification logic,
757 the behavior of PREFIX in MakeMaker has changed subtly over time.
758 Module::Build's --prefix logic is equivalent to the PREFIX logic
759 found in ExtUtils::MakeMaker 6.30.
760 If you do not need to retain compatibility with ExtUtils::MakeMaker
762 or are starting a fresh Perl installation we recommand you use
763 "install_base" instead (and "INSTALL_BASE" in ExtUtils::MakeMaker).
764 See "Instaling in the same location as ExtUtils::MakeMaker" in Mod‐
765 ule::Build::Cookbook for further information.
766
768 There are several reasons I wanted to start over, and not just fix what
769 I didn't like about MakeMaker:
770 · I don't like the core idea of MakeMaker, namely that "make" should
772 be involved in the build process. Here are my reasons:
773 + When a person is installing a Perl module, what can you assume
775 about their environment? Can you assume they have "make"? No,
776 but you can assume they have some version of Perl.
777 + When a person is writing a Perl module for intended distribu‐
779 tion, can you assume that they know how to build a Makefile, so
780 they can customize their build process? No, but you can assume
781 they know Perl, and could customize that way.
782 For years, these things have been a barrier to people getting the
784 build/install process to do what they want.
785 · There are several architectural decisions in MakeMaker that make it
787 very difficult to customize its behavior. For instance, when using
788 MakeMaker you do "use ExtUtils::MakeMaker", but the object created
789 in "WriteMakefile()" is actually blessed into a package name that's
790 created on the fly, so you can't simply subclass "ExtUtils::Make‐
791 Maker". There is a workaround "MY" package that lets you override
792 certain MakeMaker methods, but only certain explicitly preselected
793 (by MakeMaker) methods can be overridden. Also, the method of cus‐
794 tomization is very crude: you have to modify a string containing
795 the Makefile text for the particular target. Since these strings
796 aren't documented, and can't be documented (they take on different
797 values depending on the platform, version of perl, version of Make‐
798 Maker, etc.), you have no guarantee that your modifications will
799 work on someone else's machine or after an upgrade of MakeMaker or
800 perl.
801 · It is risky to make major changes to MakeMaker, since it does so
803 many things, is so important, and generally works. "Module::Build"
804 is an entirely separate package so that I can work on it all I
805 want, without worrying about backward compatibility.
806 · Finally, Perl is said to be a language for system administration.
808 Could it really be the case that Perl isn't up to the task of
809 building and installing software? Even if that software is a bunch
810 of stupid little ".pm" files that just need to be copied from one
811 place to another? My sense was that we could design a system to
812 accomplish this in a flexible, extensible, and friendly manner. Or
813 die trying.
814
816 The current method of relying on time stamps to determine whether a
817 derived file is out of date isn't likely to scale well, since it
818 requires tracing all dependencies backward, it runs into problems on
819 NFS, and it's just generally flimsy. It would be better to use an MD5
820 signature or the like, if available. See "cons" for an example.
821 - append to perllocal.pod
823 - add a 'plugin' functionality
824
826 Ken Williams <kwilliams@cpan.org>
827 Development questions, bug reports, and patches should be sent to the
829 Module-Build mailing list at <module-build@perl.org>.
830 Bug reports are also welcome at
832 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
833 The latest development version is available from the Subversion reposi‐
835 tory at <https://svn.perl.org/modules/Module-Build/trunk/>
836
838 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
839 This library is free software; you can redistribute it and/or modify it
841 under the same terms as Perl itself.
842
844 perl(1), Module::Build::Cookbook, Module::Build::Authoring, Mod‐
845 ule::Build::API, ExtUtils::MakeMaker, YAML
846 META.yml Specification: <http://module-build.source‐
848 forge.net/META-spec-current.html>
849 <http://www.dsmit.com/cons/>
851 <http://search.cpan.org/dist/PerlBuildSystem/>
853perl v5.8.8 2007-04-02 Module::Build(3)