2 Module::Build - Build and install Perl modules
5 Standard process for building & installing modules:
12 Or, if you're on a platform (like DOS or Windows) that doesn't require
13 the "./" notation, you can do this:
21 `Module::Build' is a system for building, testing, and installing Perl
22 modules. It is meant to be an alternative to `ExtUtils::MakeMaker'.
23 Developers may alter the behavior of the module through subclassing in a
24 much more straightforward way than with `MakeMaker'. It also does not
25 require a `make' on your system - most of the `Module::Build' code is
26 pure-perl and written in a very cross-platform way. In fact, you don't
27 even need a shell, so even platforms like MacOS (traditional) can use it
28 fairly easily. Its only prerequisites are modules that are included with
29 perl 5.6.0, and it works fine on perl 5.005 if you can install a few
32 See "MOTIVATIONS" for more comparisons between `ExtUtils::MakeMaker' and
35 To install `Module::Build', and any other module that uses
36 `Module::Build' for its installation process, do the following:
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
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:
49 You can run the 'help' action for a complete list of actions.
51 GUIDE TO DOCUMENTATION
52 The documentation for `Module::Build' is broken up into three sections:
54 General Usage (Module::Build)
55 This is the document you are currently reading. It describes basic
56 usage and background information. Its main purpose is to assist the
57 user who wants to learn how to invoke and control `Module::Build'
58 scripts at the command line.
60 Authoring Reference (Module::Build::Authoring)
61 This document describes the structure and organization of
62 `Module::Build', and the relevant concepts needed by authors who are
63 writing Build.PL scripts for a distribution or controlling
64 `Module::Build' processes programmatically.
66 API Reference (Module::Build::API)
67 This is a reference to the `Module::Build' API.
69 Cookbook (Module::Build::Cookbook)
70 This document demonstrates how to accomplish many common tasks. It
71 covers general command line usage and authoring of Build.PL scripts.
72 Includes working examples.
75 There are some general principles at work here. First, each task when
76 building a module is called an "action". These actions are listed above;
77 they correspond to the building, testing, installing, packaging, etc.,
80 Second, arguments are processed in a very systematic way. Arguments are
81 always key=value pairs. They may be specified at `perl Build.PL' time
82 (i.e. `perl Build.PL destdir=/my/secret/place'), in which case their
83 values last for the lifetime of the `Build' script. They may also be
84 specified when executing a particular action (i.e. `Build test
85 verbose=1'), in which case their values last only for the lifetime of
86 that command. Per-action command line parameters take precedence over
87 parameters specified at `perl Build.PL' time.
89 The build process also relies heavily on the `Config.pm' module. If the
90 user wishes to override any of the values in `Config.pm', she may
93 perl Build.PL --config cc=gcc --config ld=gcc
95 The following build actions are provided by default.
100 If you run the `Build' script without any arguments, it runs the
101 `build' action, which in turn runs the `code' and `docs' actions.
103 This is analogous to the MakeMaker 'make all' target.
108 This action will clean up any files that the build process may have
109 created, including the `blib/' directory (but not including the
110 `_build/' directory and the `Build' script itself).
115 This action builds your codebase.
117 By default it just creates a `blib/' directory and copies any `.pm'
118 and `.pod' files from your `lib/' directory into the `blib/'
119 directory. It also compiles any `.xs' files from `lib/' and places
120 them in `blib/'. Of course, you need a working C compiler (probably
121 the same one that built perl itself) for the compilation to work
124 The `code' action also runs any `.PL' files in your lib/ directory.
125 Typically these create other files, named the same but without the
126 `.PL' ending. For example, a file lib/Foo/Bar.pm.PL could create the
127 file lib/Foo/Bar.pm. The `.PL' files are processed first, so any
128 `.pm' files (or other kinds that we deal with) will get copied
139 This action will compare the files about to be installed with their
140 installed counterparts. For .pm and .pod files, a diff will be shown
141 (this currently requires a 'diff' program to be in your PATH). For
142 other files like compiled binary files, we simply report whether
145 A `flags' parameter may be passed to the action, which will be
146 passed to the 'diff' program. Consult your 'diff' documentation for
147 the parameters it will accept - a good one is `-u':
149 ./Build diff flags=-u
154 This action is helpful for module authors who want to package up
155 their module for source distribution through a medium like CPAN. It
156 will create a tarball of the files listed in MANIFEST and compress
157 the tarball using GZIP compression.
159 By default, this action will use the external `tar' and `gzip'
160 executables on Unix-like platforms, and the `Archive::Tar' module
161 elsewhere. However, you can force it to use whatever executable you
162 want by supplying an explicit `tar' (and optional `gzip') parameter:
164 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
169 Reports which files are in the build directory but not in the
170 MANIFEST file, and vice versa. (See manifest for details.)
175 Performs the 'realclean' action and then the 'distcheck' action.
180 Creates a "distribution directory" named `$dist_name-$dist_version'
181 (if that directory already exists, it will be removed first), then
182 copies all the files listed in the MANIFEST file to that directory.
183 This directory is what the distribution tarball is created from.
188 Creates the META.yml file that describes the distribution.
190 META.yml is a file containing various bits of "metadata" about the
191 distribution. The metadata includes the distribution name, version,
192 abstract, prerequisites, license, and various other data about the
193 distribution. This file is created as META.yml in YAML format. It is
194 recommended that the `YAML' module be installed to create it. If the
195 `YAML' module is not installed, an internal module supplied with
196 Module::Build will be used to write the META.yml file, and this will
199 META.yml file must also be listed in MANIFEST - if it's not, a
200 warning will be issued.
202 The current version of the META.yml specification can be found at
203 http://module-build.sourceforge.net/META-spec-current.html
208 Uses `Module::Signature' to create a SIGNATURE file for your
209 distribution, and adds the SIGNATURE file to the distribution's
215 Performs the 'distdir' action, then switches into that directory and
216 runs a `perl Build.PL', followed by the 'build' and 'test' actions
222 This will generate documentation (e.g. Unix man pages and html
223 documents) for any installable items under blib/ that contain POD.
224 If there are no `bindoc' or `libdoc' installation targets defined
225 (as will be the case on systems that don't support Unix manpages) no
226 action is taken for manpages. If there are no `binhtml' or `libhtml'
227 installation targets defined no action is taken for html documents.
232 This is just like the `install' action, but it won't actually do
233 anything, it will just report what it *would* have done if you had
234 actually run the `install' action.
239 This action will simply print out a message that is meant to help
240 you use the build process. It will show you a list of available
243 With an optional argument specifying an action name (e.g. `Build
244 help test'), the 'help' action will show you any POD documentation
245 it can find for that action.
250 This will generate HTML documentation for any binary or library
251 files under blib/ that contain POD. The HTML documentation will only
252 be installed if the install paths can be determined from values in
253 `Config.pm'. You can also supply or override install paths on the
254 command line by specifying `install_path' values for the `binhtml'
255 and/or `libhtml' installation targets.
260 This action will use `ExtUtils::Install' to install the files from
261 `blib/' into the system. See "INSTALL PATHS" for details about how
262 Module::Build determines where to install things, and how to
263 influence this process.
265 If you want the installation process to look around in `@INC' for
266 other versions of the stuff you're installing and try to delete it,
267 you can use the `uninst' parameter, which tells `ExtUtils::Install'
270 ./Build install uninst=1
272 This can be a good idea, as it helps prevent multiple versions of a
273 module from being present on your system, which can be a confusing
279 This is an action intended for use by module authors, not people
280 installing modules. It will bring the MANIFEST up to date with the
281 files currently present in the distribution. You may use a
282 MANIFEST.SKIP file to exclude certain files or directories from
283 inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of
284 regular expressions, one per line. If a file in the distribution
285 directory matches any of the regular expressions, it won't be
286 included in the MANIFEST.
288 The following is a reasonable MANIFEST.SKIP starting point, you can
289 add your own stuff to it:
299 See the distcheck and skipcheck actions if you want to find out what
300 the `manifest' action would do, without actually doing anything.
305 This will generate man pages for any binary or library files under
306 blib/ that contain POD. The man pages will only be installed if the
307 install paths can be determined from values in `Config.pm'. You can
308 also supply or override install paths by specifying there values on
309 the command line with the `bindoc' and `libdoc' installation
315 Generates a PAR binary distribution for use with PAR or PAR::Dist.
317 It requires that the PAR::Dist module (version 0.17 and up) is
318 installed on your system.
322 Build a PPD file for your distribution.
324 This action takes an optional argument `codebase' which is used in
325 the generated ppd file to specify the (usually relative) URL of the
326 distribution. By default, this value is the distribution name
327 without any path information.
331 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
336 Generates a PPM binary distribution and a PPD description file. This
337 action also invokes the 'ppd' action, so it can accept the same
338 `codebase' argument described under that action.
340 This uses the same mechanism as the `dist' action to tar & zip its
341 output, so you can supply `tar' and/or `gzip' parameters to affect
347 This action prints out a list of all prerequisites, the versions
348 required, and the versions actually installed. This can be useful
349 for reviewing the configuration of your system prior to a build, or
350 when compiling data to send for a bug report.
355 This action is identical to the `install' action. In the future,
356 though, when `install' starts writing to the file
357 $(INSTALLARCHLIB)/perllocal.pod, `pure_install' won't, and that will
358 be the only difference between them.
363 This action is just like the `clean' action, but also removes the
364 `_build' directory and the `Build' script. If you run the
365 `realclean' action, you are essentially starting over, so you will
366 have to re-create the `Build' script again.
371 This is just like the `test' action, but doesn't actually build the
372 distribution first, and doesn't add blib/ to the load path, and
373 therefore will test against a *previously* installed version of the
374 distribution. This can be used to verify that a certain installed
375 distribution still works, or to see whether newer versions of a
376 distribution still pass the old regression tests, and so on.
381 Reports which files are skipped due to the entries in the
382 MANIFEST.SKIP file (See manifest for details)
387 This will use `Test::Harness' to run any regression tests and report
388 their results. Tests can be defined in the standard places: a file
389 called `test.pl' in the top-level directory, or several files ending
390 with `.t' in a `t/' directory.
392 If you want tests to be 'verbose', i.e. show details of test
393 execution rather than just summary information, pass the argument
396 If you want to run tests under the perl debugger, pass the argument
399 In addition, if a file called `visual.pl' exists in the top-level
400 directory, this file will be executed as a Perl script and its
401 output will be shown to the user. This is a good place to put speed
402 tests or other tests that don't use the `Test::Harness' format for
405 To override the choice of tests to run, you may pass a `test_files'
406 argument whose value is a whitespace-separated list of test scripts
407 to run. This is especially useful in development, when you only want
408 to run a single test to see whether you've squashed a certain bug
411 ./Build test --test_files t/something_failing.t
413 You may also pass several `test_files' arguments separately:
415 ./Build test --test_files t/one.t --test_files t/two.t
417 or use a `glob()'-style pattern:
419 ./Build test --test_files 't/01-*.t'
424 [Note: the 'testall' action and the code snippets below are
425 currently in alpha stage, see
426 "http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.htm
429 Runs the `test' action plus each of the `test$type' actions defined
430 by the keys of the `test_types' parameter.
432 Currently, you need to define the ACTION_test$type method yourself
433 and enumerate them in the test_types parameter.
435 my $mb = Module::Build->subclass(
437 sub ACTION_testspecial { shift->generic_test(type => 'special'); }
438 sub ACTION_testauthor { shift->generic_test(type => 'author'); }
451 Runs the `test' action using `Devel::Cover', generating a
452 code-coverage report showing which parts of the code were actually
453 exercised during the tests.
455 To pass options to `Devel::Cover', set the `$DEVEL_COVER_OPTIONS'
456 environment variable:
458 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
463 This is a synonym for the 'test' action with the `debugger=1'
469 This checks all the files described in the `docs' action and
470 produces `Test::Harness'-style output. If you are a module author,
471 this is useful to run before creating a new release.
476 This checks the pod coverage of the distribution and produces
477 `Test::Harness'-style output. If you are a module author, this is
478 useful to run before creating a new release.
483 ** Note: since `only.pm' is so new, and since we just recently added
484 support for it here too, this feature is to be considered
487 If you have the `only.pm' module installed on your system, you can
488 use this action to install a module into the version-specific
489 library trees. This means that you can have several versions of the
490 same module installed and `use' a specific one like this:
492 use only MyModule => 0.55;
494 To override the default installation libraries in `only::config',
495 specify the `versionlib' parameter when you run the `Build.PL'
498 perl Build.PL --versionlib /my/version/place/
500 To override which version the module is installed as, specify the
501 `versionlib' parameter when you run the `Build.PL' script:
503 perl Build.PL --version 0.50
505 See the `only.pm' documentation for more information on
506 version-specific installs.
511 The following options can be used during any invocation of `Build.PL' or
512 the Build script, during any action. For information on other options
513 specific to an action, see the documentation for the respective action.
515 NOTE: There is some preliminary support for options to use the more
516 familiar long option style. Most options can be preceded with the `--'
517 long option prefix, and the underscores changed to dashes (e.g.
518 --use-rcfile). Additionally, the argument to boolean options is
519 optional, and boolean options can be negated by prefixing them with 'no'
520 or 'no-' (e.g. --noverbose or --no-verbose).
523 Suppress informative messages on output.
526 Load the ~/.modulebuildrc option file. This option can be set to
527 false to prevent the custom resource file from being loaded.
530 Display extra information about the Build on output.
533 Suppresses the check upon startup that the version of Module::Build
534 we're now running under is the same version that was initially
535 invoked when building the distribution (i.e. when the `Build.PL'
536 script was first run). Use with caution.
538 Default Options File (.modulebuildrc)
542 When Module::Build starts up, it will look first for a file,
543 $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the
544 the .modulebuildrc file in the directories referred to by the
545 environment variables `HOMEDRIVE' + `HOMEDIR', `USERPROFILE', `APPDATA',
546 `WINDIR', `SYS$LOGIN'. If the file exists, the options specified there
547 will be used as defaults, as if they were typed on the command line. The
548 defaults can be overridden by specifying new values on the command line.
550 The action name must come at the beginning of the line, followed by any
551 amount of whitespace and then the options. Options are given the same as
552 they would be on the command line. They can be separated by any amount
553 of whitespace, including newlines, as long there is whitespace at the
554 beginning of each continued line. Anything following a hash mark (`#')
555 is considered a comment, and is stripped before parsing. If more than
556 one line begins with the same action name, those lines are merged into
559 Besides the regular actions, there are two special pseudo-actions: the
560 key `*' (asterisk) denotes any global options that should be applied to
561 all actions, and the key 'Build_PL' specifies options to be applied when
562 you invoke `perl Build.PL'.
564 * verbose=1 # global options
566 install --install_base /home/ken
567 --install_path html=/home/ken/docs/html
569 If you wish to locate your resource file in a different location, you
570 can set the environment variable 'MODULEBUILDRC' to the complete
571 absolute path of the file containing your options.
576 When you invoke Module::Build's `build' action, it needs to figure out
577 where to install things. The nutshell version of how this works is that
578 default installation locations are determined from Config.pm, and they
579 may be overridden by using the `install_path' parameter. An
580 `install_base' parameter lets you specify an alternative installation
581 root like /home/foo, and a `destdir' lets you specify a temporary
582 installation directory like /tmp/install in case you want to create
583 bundled-up installable packages.
585 Natively, Module::Build provides default installation locations for the
586 following types of installable items:
588 lib Usually pure-Perl module files ending in .pm.
591 "Architecture-dependent" module files, usually produced by compiling
592 XS, Inline, or similar code.
595 Programs written in pure Perl. In order to improve reuse, try to
596 make these as small as possible - put the code into modules whenever
599 bin "Architecture-dependent" executable programs, i.e. compiled C code
600 or something. Pretty rare to see this in a perl distribution, but it
604 Documentation for the stuff in `script' and `bin'. Usually generated
605 from the POD in those files. Under Unix, these are manual pages
606 belonging to the 'man1' category.
609 Documentation for the stuff in `lib' and `arch'. This is usually
610 generated from the POD in .pm files. Under Unix, these are manual
611 pages belonging to the 'man3' category.
614 This is the same as `bindoc' above, but applies to html documents.
617 This is the same as `bindoc' above, but applies to html documents.
619 Four other parameters let you control various aspects of how
620 installation paths are determined:
623 The default destinations for these installable things come from
624 entries in your system's `Config.pm'. You can select from three
625 different sets of default locations by setting the `installdirs'
626 parameter as follows:
628 'installdirs' set to:
631 uses the following defaults from Config.pm:
633 lib => installprivlib installsitelib installvendorlib
634 arch => installarchlib installsitearch installvendorarch
635 script => installscript installsitebin installvendorbin
636 bin => installbin installsitebin installvendorbin
637 bindoc => installman1dir installsiteman1dir installvendorman1dir
638 libdoc => installman3dir installsiteman3dir installvendorman3dir
639 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
640 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
642 * Under some OS (eg. MSWin32) the destination for html documents is
643 determined by the C<Config.pm> entry C<installhtmldir>.
645 The default value of `installdirs' is "site". If you're creating
646 vendor distributions of module packages, you may want to do
649 perl Build.PL --installdirs vendor
653 ./Build install --installdirs vendor
655 If you're installing an updated version of a module that was
656 included with perl itself (i.e. a "core module"), then you may set
657 `installdirs' to "core" to overwrite the module in its present
660 (Note that the 'script' line is different from MakeMaker -
661 unfortunately there's no such thing as "installsitescript" or
662 "installvendorscript" entry in `Config.pm', so we use the
663 "installsitebin" and "installvendorbin" entries to at least get the
664 general location right. In the future, if `Config.pm' adds some more
665 appropriate entries, we'll start using those.)
668 Once the defaults have been set, you can override them.
670 On the command line, that would look like this:
672 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
676 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
679 You can also set the whole bunch of installation paths by supplying
680 the `install_base' parameter to point to a directory on your system.
681 For instance, if you set `install_base' to "/home/ken" on a Linux
682 system, you'll install as follows:
684 lib => /home/ken/lib/perl5
685 arch => /home/ken/lib/perl5/i386-linux
686 script => /home/ken/bin
688 bindoc => /home/ken/man/man1
689 libdoc => /home/ken/man/man3
690 binhtml => /home/ken/html
691 libhtml => /home/ken/html
693 Note that this is *different* from how MakeMaker's `PREFIX'
694 parameter works. `install_base' just gives you a default layout
695 under the directory you specify, which may have little to do with
696 the `installdirs=site' layout.
698 The exact layout under the directory you specify may vary by system
699 - we try to do the "sensible" thing on each platform.
702 If you want to install everything into a temporary directory first
703 (for instance, if you want to create a directory tree that a package
704 manager like `rpm' or `dpkg' could create a package from), you can
705 use the `destdir' parameter:
707 perl Build.PL --destdir /tmp/foo
711 ./Build install --destdir /tmp/foo
713 This will effectively install to "/tmp/foo/$sitelib",
714 "/tmp/foo/$sitearch", and the like, except that it will use
715 `File::Spec' to make the pathnames work correctly on whatever
716 platform you're installing on.
719 Provided for compatibility with ExtUtils::MakeMaker's PREFIX
720 argument. `prefix' should be used when you wish Module::Build to
721 install your modules, documentation and scripts in the same place
722 ExtUtils::MakeMaker does.
724 The following are equivalent.
726 perl Build.PL --prefix /tmp/foo
727 perl Makefile.PL PREFIX=/tmp/foo
729 Because of the very complex nature of the prefixification logic, the
730 behavior of PREFIX in MakeMaker has changed subtly over time.
731 Module::Build's --prefix logic is equivalent to the PREFIX logic
732 found in ExtUtils::MakeMaker 6.30.
734 If you do not need to retain compatibility with ExtUtils::MakeMaker
735 or are starting a fresh Perl installation we recommand you use
736 `install_base' instead (and `INSTALL_BASE' in ExtUtils::MakeMaker).
737 See Module::Build::Cookbook for further information.
740 There are several reasons I wanted to start over, and not just fix what
741 I didn't like about MakeMaker:
743 * I don't like the core idea of MakeMaker, namely that `make' should
744 be involved in the build process. Here are my reasons:
746 + When a person is installing a Perl module, what can you assume
747 about their environment? Can you assume they have `make'? No,
748 but you can assume they have some version of Perl.
750 + When a person is writing a Perl module for intended
751 distribution, can you assume that they know how to build a
752 Makefile, so they can customize their build process? No, but you
753 can assume they know Perl, and could customize that way.
755 For years, these things have been a barrier to people getting the
756 build/install process to do what they want.
758 * There are several architectural decisions in MakeMaker that make it
759 very difficult to customize its behavior. For instance, when using
760 MakeMaker you do `use ExtUtils::MakeMaker', but the object created
761 in `WriteMakefile()' is actually blessed into a package name that's
762 created on the fly, so you can't simply subclass
763 `ExtUtils::MakeMaker'. There is a workaround `MY' package that lets
764 you override certain MakeMaker methods, but only certain explicitly
765 preselected (by MakeMaker) methods can be overridden. Also, the
766 method of customization is very crude: you have to modify a string
767 containing the Makefile text for the particular target. Since these
768 strings aren't documented, and *can't* be documented (they take on
769 different values depending on the platform, version of perl, version
770 of MakeMaker, etc.), you have no guarantee that your modifications
771 will work on someone else's machine or after an upgrade of MakeMaker
774 * It is risky to make major changes to MakeMaker, since it does so
775 many things, is so important, and generally works. `Module::Build'
776 is an entirely separate package so that I can work on it all I want,
777 without worrying about backward compatibility.
779 * Finally, Perl is said to be a language for system administration.
780 Could it really be the case that Perl isn't up to the task of
781 building and installing software? Even if that software is a bunch
782 of stupid little `.pm' files that just need to be copied from one
783 place to another? My sense was that we could design a system to
784 accomplish this in a flexible, extensible, and friendly manner. Or
788 The current method of relying on time stamps to determine whether a
789 derived file is out of date isn't likely to scale well, since it
790 requires tracing all dependencies backward, it runs into problems on
791 NFS, and it's just generally flimsy. It would be better to use an MD5
792 signature or the like, if available. See `cons' for an example.
794 - append to perllocal.pod
795 - add a 'plugin' functionality
798 Ken Williams <kwilliams@cpan.org>
800 Development questions, bug reports, and patches should be sent to the
801 Module-Build mailing list at <module-build@perl.org>.
803 Bug reports are also welcome at
804 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
806 The latest development version is available from the Subversion
807 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
810 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
812 This library is free software; you can redistribute it and/or modify it
813 under the same terms as Perl itself.
816 perl(1), Module::Build::Cookbook, Module::Build::Authoring,
817 Module::Build::API, ExtUtils::MakeMaker, YAML
819 META.yml Specification:
820 http://module-build.sourceforge.net/META-spec-current.html
822 http://www.dsmit.com/cons/
824 http://search.cpan.org/dist/PerlBuildSystem/