## "Fossies" - the Fresh Open Source Software Archive

### Source code changes of the file "README" betweenModule-Build-0.4222.tar.gz and Module-Build-0.4224.tar.gz

About: Module-Build - building & installing Perl modules.

NAME NAME
Module::Build - Build and install Perl modules Module::Build - Build and install Perl modules
SYNOPSIS SYNOPSIS
Standard process for building & installing modules: Standard process for building & installing modules:
perl Build.PL perl Build.PL
./Build ./Build
./Build test ./Build test
./Build install ./Build install
Or, if you're on a platform (like DOS or Windows) that doesn't require Or, if you're on a platform (like DOS or Windows) that doesn't require
the "./" notation, you can do this: the "./" notation, you can do this:
perl Build.PL perl Build.PL
Build Build
Build test Build test
Build install Build install
DESCRIPTION DESCRIPTION
is a system for building, testing, and installing Perl
modules. It is meant to be an alternative to Module::Build is a system for building, testing, and installing Perl
Developers may alter the behavior of the module through subclassing in a modules. It is meant to be an alternative to ExtUtils::MakeMaker.
much more straightforward way than with It also does not Developers may alter the behavior of the module through subclassing in
require a on your system - most of the code is a much more straightforward way than with MakeMaker. It also does not
require a make on your system - most of the Module::Build code is
pure-perl and written in a very cross-platform way. pure-perl and written in a very cross-platform way.
See "MOTIVATIONS" for more comparisons between and See "MOTIVATIONS" for more comparisons between ExtUtils::MakeMaker and
Module::Build.
To install and any other module that uses To install Module::Build, and any other module that uses Module::Build
for its installation process, do the following: for its installation process, do the following:
perl Build.PL # 'Build.PL' script creates the 'Build' script perl Build.PL # 'Build.PL' script creates the 'Build' script
./Build # Need ./ to ensure we're using this "Build" script ./Build # Need ./ to ensure we're using this "Build" script
./Build test # and not another one that happens to be in the PATH ./Build test # and not another one that happens to be in the PATH
./Build install ./Build install
This illustrates initial configuration and the running of three This illustrates initial configuration and the running of three
'actions'. In this case the actions run are 'build' (the default 'actions'. In this case the actions run are 'build' (the default
action), 'test', and 'install'. Other actions defined so far include: action), 'test', and 'install'. Other actions defined so far include:
<action_list> <action_list>
You can run the 'help' action for a complete list of actions. You can run the 'help' action for a complete list of actions.
GUIDE TO DOCUMENTATION GUIDE TO DOCUMENTATION
The documentation for is broken up into sections:
The documentation for Module::Build is broken up into sections:
General Usage (Module::Build) General Usage (Module::Build)
This is the document you are currently reading. It describes basic
usage and background information. Its main purpose is to assist the This is the document you are currently reading. It describes basic
user who wants to learn how to invoke and control usage and background information. Its main purpose is to assist the
scripts at the command line. user who wants to learn how to invoke and control Module::Build
scripts at the command line.
Authoring Reference (Module::Build::Authoring) Authoring Reference (Module::Build::Authoring)
This document describes the structure and organization of
and the relevant concepts needed by authors who are This document describes the structure and organization of
writing Build.PL scripts for a distribution or controlling Module::Build, and the relevant concepts needed by authors who are
processes programmatically. writing Build.PL scripts for a distribution or controlling
Module::Build processes programmatically.
API Reference (Module::Build::API) API Reference (Module::Build::API)
This is a reference to the API.
This is a reference to the Module::Build API.
Cookbook (Module::Build::Cookbook) Cookbook (Module::Build::Cookbook)
This document demonstrates how to accomplish many common tasks. It
covers general command line usage and authoring of Build.PL scripts. This document demonstrates how to accomplish many common tasks. It
Includes working examples. covers general command line usage and authoring of Build.PL scripts.
Includes working examples.
ACTIONS ACTIONS
There are some general principles at work here. First, each task when There are some general principles at work here. First, each task when
building a module is called an "action". These actions are listed above; building a module is called an "action". These actions are listed
they correspond to the building, testing, installing, packaging, etc., above; they correspond to the building, testing, installing, packaging,
Second, arguments are processed in a very systematic way. Arguments are Second, arguments are processed in a very systematic way. Arguments are
always key=value pairs. They may be specified at time always key=value pairs. They may be specified at perl Build.PL time
(i.e. Build.PL in which case their (i.e. perl Build.PL destdir=/my/secret/place), in which case their
values last for the lifetime of the script. They may also be values last for the lifetime of the Build script. They may also be
specified when executing a particular action (i.e. test specified when executing a particular action (i.e. Build test
in which case their values last only for the lifetime of verbose=1), in which case their values last only for the lifetime of
that command. Per-action command line parameters take precedence over that command. Per-action command line parameters take precedence over
parameters specified at time. parameters specified at perl Build.PL time.
The build process also relies heavily on the module. If the The build process also relies heavily on the Config.pm module. If the
user wishes to override any of the values in she may user wishes to override any of the values in Config.pm, she may specify
specify them like so: them like so:
perl Build.PL --config cc=gcc --config ld=gcc perl Build.PL --config cc=gcc --config ld=gcc
The following build actions are provided by default. The following build actions are provided by default.
build build
If you run the script without any arguments, it runs the [version 0.01]
action, which in turn runs the and actions.
If you run the Build script without any arguments, it runs the build
action, which in turn runs the code and docs actions.
target. This is analogous to the MakeMaker make all target.
clean clean
This action will clean up any files that the build process may have [version 0.01]
created, including the directory (but not including the
directory and the script itself). This action will clean up any files that the build process may have
created, including the blib/ directory (but not including the _build/
directory and the Build script itself).
code code
This action builds your code base. [version 0.20]
This action builds your code base.
By default it just creates a directory and copies any By default it just creates a blib/ directory and copies any .pm and
and files from your directory into the .pod files from your lib/ directory into the blib/ directory. It also
directory. It also compiles any files from and places compiles any .xs files from lib/ and places them in blib/. Of course,
them in Of course, you need a working C compiler (probably you need a working C compiler (probably the same one that built perl
the same one that built perl itself) for the compilation to work itself) for the compilation to work properly.
properly.
The code action also runs any .PL files in your lib/ directory.
The action also runs any files in your lib/ directory. Typically these create other files, named the same but without the
Typically these create other files, named the same but without the .PL ending. For example, a file lib/Foo/Bar.pm.PL could create the
ending. For example, a file lib/Foo/Bar.pm.PL could create the file lib/Foo/Bar.pm. The .PL files are processed first, so any .pm
file lib/Foo/Bar.pm. The files are processed first, so any files (or other kinds that we deal with) will get copied correctly.
files (or other kinds that we deal with) will get copied
correctly.
config_data config_data
... [version 0.26]
...
diff diff
[version 0.14]
./Build diff flags=-u This action will compare the files about to be installed with their
installed counterparts. For .pm and .pod files, a diff will be shown
(this currently requires a 'diff' program to be in your PATH). For
other files like compiled binary files, we simply report whether they
differ.
A flags parameter may be passed to the action, which will be passed
to the 'diff' program. Consult your 'diff' documentation for the
parameters it will accept - a good one is -u:
./Build diff flags=-u
dist dist
This action is helpful for module authors who want to package up [version 0.02]
their module for source distribution through a medium like CPAN. It
will create a tarball of the files listed in MANIFEST and compress This action is helpful for module authors who want to package up
the tarball using GZIP compression. their module for source distribution through a medium like CPAN. It
will create a tarball of the files listed in MANIFEST and compress
By default, this action will use the module. However, the tarball using GZIP compression.
you can force it to use binary "tar" and "gzip" executables by
supplying an explicit (and optional parameter: By default, this action will use the Archive::Tar module. However,
you can force it to use binary "tar" and "gzip" executables by
supplying an explicit tar (and optional gzip) parameter:
./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
distcheck distcheck
Reports which files are in the build directory but not in the [version 0.05]
MANIFEST file, and vice versa. (See manifest for details.)
Reports which files are in the build directory but not in the
MANIFEST file, and vice versa. (See manifest for details.)
distclean distclean
Performs the 'realclean' action and then the 'distcheck' action. [version 0.05]
Performs the 'realclean' action and then the 'distcheck' action.
distdir distdir
Creates a "distribution directory" named [version 0.05]
(if that directory already exists, it will be removed first), then
copies all the files listed in the MANIFEST file to that directory. Creates a "distribution directory" named $dist_name-$dist_version (if
This directory is what the distribution tarball is created from. that directory already exists, it will be removed first), then copies
all the files listed in the MANIFEST file to that directory. This
directory is what the distribution tarball is created from.
distinstall distinstall
Performs the 'distdir' action, then switches into that directory and [version 0.37]
runs a followed by the 'build' and 'install'
actions in that directory. Use PERL_MB_OPT or .modulebuildrc to set Performs the 'distdir' action, then switches into that directory and
options that should be applied during subprocesses runs a perl Build.PL, followed by the 'build' and 'install' actions
in that directory. Use PERL_MB_OPT or .modulebuildrc to set options
that should be applied during subprocesses
distmeta distmeta
Creates the META.yml file that describes the distribution. [version 0.21]
Creates the META.yml file that describes the distribution.
META.yml is a file containing various bits of about the META.yml is a file containing various bits of metadata about the
distribution. The metadata includes the distribution name, version, distribution. The metadata includes the distribution name, version,
distribution. This file is created as META.yml in a simplified YAML distribution. This file is created as META.yml in a simplified YAML
format. format.
META.yml file must also be listed in MANIFEST - if it's not, a META.yml file must also be listed in MANIFEST - if it's not, a
warning will be issued. warning will be issued.
The current version of the META.yml specification can be found on The current version of the META.yml specification can be found on
CPAN as CPAN::Meta::Spec. CPAN as CPAN::Meta::Spec.
distsign distsign
Uses to create a SIGNATURE file for your [version 0.16]
distribution, and adds the SIGNATURE file to the distribution's
MANIFEST. Uses Module::Signature to create a SIGNATURE file for your
distribution, and adds the SIGNATURE file to the distribution's
MANIFEST.
disttest disttest
Performs the 'distdir' action, then switches into that directory and [version 0.05]
runs a followed by the 'build' and 'test' actions
in that directory. Use PERL_MB_OPT or .modulebuildrc to set options Performs the 'distdir' action, then switches into that directory and
that should be applied during subprocesses runs a perl Build.PL, followed by the 'build' and 'test' actions in
that directory. Use PERL_MB_OPT or .modulebuildrc to set options that
should be applied during subprocesses
docs docs
This will generate documentation (e.g. Unix man pages and HTML [version 0.20]
documents) for any installable items under blib/ that contain POD.
If there are no or installation targets defined This will generate documentation (e.g. Unix man pages and HTML
(as will be the case on systems that don't support Unix manpages) no documents) for any installable items under blib/ that contain POD. If
action is taken for manpages. If there are no or there are no bindoc or libdoc installation targets defined (as will
installation targets defined no action is taken for HTML documents. be the case on systems that don't support Unix manpages) no action is
taken for manpages. If there are no binhtml or libhtml installation
targets defined no action is taken for HTML documents.
fakeinstall fakeinstall
This is just like the action, but it won't actually do [version 0.02]
anything, it will just report what it have done if you had
actually run the action. This is just like the install action, but it won't actually do
anything, it will just report what it would have done if you had
actually run the install action.
help help
This action will simply print out a message that is meant to help [version 0.03]
you use the build process. It will show you a list of available
build actions too. This action will simply print out a message that is meant to help you
use the build process. It will show you a list of available build
With an optional argument specifying an action name (e.g. actions too.
help the 'help' action will show you any POD documentation
it can find for that action. With an optional argument specifying an action name (e.g. Build help
test), the 'help' action will show you any POD documentation it can
find for that action.
html html
[version 0.26]
./Build html --html_links 0 This will generate HTML documentation for any binary or library files
under blib/ that contain POD. The HTML documentation will only be
installed if the install paths can be determined from values in
Config.pm. You can also supply or override install paths on the
command line by specifying install_path values for the binhtml and/or
libhtml installation targets.
With an optional html_links argument set to a false value, you can
skip the search for other documentation to link to, because that can
waste a lot of time if there aren't any links to generate anyway:
install install
This action will use to install the files from [version 0.01]
into the system. See "INSTALL PATHS" for details about how
Module::Build determines where to install things, and how to This action will use ExtUtils::Install to install the files from
influence this process. blib/ into the system. See "INSTALL PATHS" for details about how
Module::Build determines where to install things, and how to
If you want the installation process to look around in @INC for influence this process.
other versions of the stuff you're installing and try to delete it,
you can use the parameter, which tells If you want the installation process to look around in @INC for other
to do so: versions of the stuff you're installing and try to delete it, you can
use the uninst parameter, which tells ExtUtils::Install to do so:
./Build install uninst=1
./Build install uninst=1
This can be a good idea, as it helps prevent multiple versions of a
module from being present on your system, which can be a confusing This can be a good idea, as it helps prevent multiple versions of a
situation indeed. module from being present on your system, which can be a confusing
situation indeed.
installdeps installdeps
This action will use the parameter as a command to [version 0.36]
install missing prerequisites. You will be prompted whether to
install optional dependencies. This action will use the cpan_client parameter as a command to
install missing prerequisites. You will be prompted whether to
The option defaults to 'cpan' but can be set as an install optional dependencies.
option or in .modulebuildrc. It must be a shell command that takes a
list of modules to install as arguments (e.g. 'cpanp -i' for The cpan_client option defaults to 'cpan' but can be set as an option
CPANPLUS). If the program part is a relative path (e.g. 'cpan' or or in .modulebuildrc. It must be a shell command that takes a list of
'cpanp'), it will be located relative to the perl program that modules to install as arguments (e.g. 'cpanp -i' for CPANPLUS). If
executed Build.PL. the program part is a relative path (e.g. 'cpan' or 'cpanp'), it will
be located relative to the perl program that executed Build.PL.
/opt/perl/5.8.9/bin/perl Build.PL
./Build installdeps --cpan_client 'cpanp -i' /opt/perl/5.8.9/bin/perl Build.PL
# installs to 5.8.9 ./Build installdeps --cpan_client 'cpanp -i'
# installs to 5.8.9
manifest manifest
[version 0.05]
See the distcheck and skipcheck actions if you want to find out what This is an action intended for use by module authors, not people
the action would do, without actually doing anything. installing modules. It will bring the MANIFEST up to date with the
files currently present in the distribution. You may use a
MANIFEST.SKIP file to exclude certain files or directories from
inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of
regular expressions, one per line. If a file in the distribution
directory matches any of the regular expressions, it won't be
included in the MANIFEST.
The following is a reasonable MANIFEST.SKIP starting point, you can
^_build
^Build$^blib ~$
\.bak$^MANIFEST\.SKIP$
CVS
See the distcheck and skipcheck actions if you want to find out what
the manifest action would do, without actually doing anything.
manifest_skip manifest_skip
This is an action intended for use by module authors, not people [version 0.3608]
installing modules. It will generate a boilerplate MANIFEST.SKIP
file if one does not already exist. This is an action intended for use by module authors, not people
installing modules. It will generate a boilerplate MANIFEST.SKIP file
if one does not already exist.
manpages manpages
This will generate man pages for any binary or library files under [version 0.28]
blib/ that contain POD. The man pages will only be installed if the
install paths can be determined from values in You can This will generate man pages for any binary or library files under
also supply or override install paths by specifying there values on blib/ that contain POD. The man pages will only be installed if the
the command line with the and installation install paths can be determined from values in Config.pm. You can
targets. also supply or override install paths by specifying there values on
the command line with the bindoc and libdoc installation targets.
pardist pardist
Generates a PAR binary distribution for use with PAR or PAR::Dist. [version 0.2806]
Generates a PAR binary distribution for use with PAR or PAR::Dist.
It requires that the PAR::Dist module (version 0.17 and up) is
ppd
[version 0.20] [version 0.20]
Build a PPD file for your distribution. Build a PPD file for your distribution.
This action takes an optional argument which is used in This action takes an optional argument codebase which is used in the
the generated PPD file to specify the (usually relative) URL of the generated PPD file to specify the (usually relative) URL of the
distribution. By default, this value is the distribution name distribution. By default, this value is the distribution name without
without any path information. any path information.
Example: Example:
z" ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.g z"
ppmdist ppmdist
Generates a PPM binary distribution and a PPD description file. This [version 0.23]
action also invokes the action, so it can accept the same
argument described under that action. Generates a PPM binary distribution and a PPD description file. This
action also invokes the ppd action, so it can accept the same
This uses the same mechanism as the action to tar & zip its codebase argument described under that action.
output, so you can supply and/or parameters to affect
the result. This uses the same mechanism as the dist action to tar & zip its
output, so you can supply tar and/or gzip parameters to affect the
result.
prereq_data prereq_data
This action prints out a Perl data structure of all prerequisites [version 0.32]
and the versions required. The output can be loaded again using
This can be useful for external tools that wish to query a This action prints out a Perl data structure of all prerequisites and
Build script for prerequisites. the versions required. The output can be loaded again using eval().
This can be useful for external tools that wish to query a Build
script for prerequisites.
prereq_report prereq_report
This action prints out a list of all prerequisites, the versions [version 0.28]
required, and the versions actually installed. This can be useful
for reviewing the configuration of your system prior to a build, or This action prints out a list of all prerequisites, the versions
when compiling data to send for a bug report. required, and the versions actually installed. This can be useful for
reviewing the configuration of your system prior to a build, or when
compiling data to send for a bug report.
pure_install pure_install
This action is identical to the action. In the future, [version 0.28]
though, when starts writing to the file
$(INSTALLARCHLIB)/perllocal.pod, won't, and that will This action is identical to the install action. In the future, be the only difference between them. though, when install starts writing to the file$(INSTALLARCHLIB)/perllocal.pod, pure_install won't, and that will be
the only difference between them.
realclean realclean
This action is just like the action, but also removes the [version 0.01]
directory and the script. If you run the
action, you are essentially starting over, so you will This action is just like the clean action, but also removes the
have to re-create the script again. _build directory and the Build script. If you run the realclean
action, you are essentially starting over, so you will have to
re-create the Build script again.
retest retest
This is just like the action, but doesn't actually build the [version 0.2806]
therefore will test against a installed version of the This is just like the test action, but doesn't actually build the
distribution. This can be used to verify that a certain installed distribution first, and doesn't add blib/ to the load path, and
distribution still works, or to see whether newer versions of a therefore will test against a previously installed version of the
distribution still pass the old regression tests, and so on. distribution. This can be used to verify that a certain installed
distribution still works, or to see whether newer versions of a
distribution still pass the old regression tests, and so on.
skipcheck skipcheck
Reports which files are skipped due to the entries in the [version 0.05]
MANIFEST.SKIP file (See manifest for details)
Reports which files are skipped due to the entries in the
MANIFEST.SKIP file (See manifest for details)
test test
This will use or to run any [version 0.01]
regression tests and report their results. Tests can be defined in
the standard places: a file called in the top-level This will use Test::Harness or TAP::Harness to run any regression
directory, or several files ending with in a directory. tests and report their results. Tests can be defined in the standard
places: a file called test.pl in the top-level directory, or several
files ending with .t in a t/ directory.
If you want tests to be 'verbose', i.e. show details of test If you want tests to be 'verbose', i.e. show details of test
execution rather than just summary information, pass the argument execution rather than just summary information, pass the argument
verbose=1.
If you want to run tests under the perl debugger, pass the argument If you want to run tests under the perl debugger, pass the argument
debugger=1.
If you want to have Module::Build find test files with different If you want to have Module::Build find test files with different file
file name extensions, pass the argument with an name extensions, pass the test_file_exts argument with an array of
array of extensions, such as .t .s .z extensions, such as [qw( .t .s .z )].
If you want test to be run by rather than If you want test to be run by TAP::Harness, rather than
pass the argument as an array Test::Harness, pass the argument tap_harness_args as an array
reference of arguments to pass to the TAP::Harness constructor. reference of arguments to pass to the TAP::Harness constructor.
In addition, if a file called exists in the top-level In addition, if a file called visual.pl exists in the top-level
directory, this file will be executed as a Perl script and its directory, this file will be executed as a Perl script and its output
output will be shown to the user. This is a good place to put speed will be shown to the user. This is a good place to put speed tests or
tests or other tests that don't use the format for other tests that don't use the Test::Harness format for output.
output.
To override the choice of tests to run, you may pass a To override the choice of tests to run, you may pass a test_files
argument whose value is a whitespace-separated list of test scripts argument whose value is a whitespace-separated list of test scripts
to run. This is especially useful in development, when you only want to run. This is especially useful in development, when you only want
to run a single test to see whether you've squashed a certain bug to run a single test to see whether you've squashed a certain bug
yet: yet:
./Build test --test_files t/something_failing.t ./Build test --test_files t/something_failing.t
arguments separately: You may also pass several test_files arguments separately:
./Build test --test_files t/one.t --test_files t/two.t ./Build test --test_files t/one.t --test_files t/two.t
-style pattern: or use a glob()-style pattern:
./Build test --test_files 't/01-*.t' ./Build test --test_files 't/01-*.t'
testall testall
[Note: the 'testall' action and the code snippets below are [version 0.2807]
currently in alpha stage, see
"/www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"" in [Note: the 'testall' action and the code snippets below are currently
"http: ] in alpha stage, see
"/www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"" in
Runs the action plus each of the actions defined "http: ]
by the keys of the parameter.
Runs the test action plus each of the test$type actions defined by Currently, you need to define the ACTION_test$type method yourself the keys of the test_types parameter.
and enumerate them in the test_types parameter.
Currently, you need to define the ACTION_test$type method yourself my$mb = Module::Build->subclass( and enumerate them in the test_types parameter.
code => q(
sub ACTION_testspecial { shift->generic_test(type => 'special'); } my $mb = Module::Build->subclass( sub ACTION_testauthor { shift->generic_test(type => 'author'); } code => q( ) sub ACTION_testspecial { shift->generic_test(type => 'special'); } )->new( sub ACTION_testauthor { shift->generic_test(type => 'author'); } ... ) test_types => { )->new( special => '.st', ... author => ['.at', '.pt' ], test_types => { }, special => '.st', ... author => ['.at', '.pt' ], }, ... testcover testcover [version 0.26] the Runs the test action using Devel::Cover, generating a code-coverage report showing which parts of the code were actually exercised during the tests. DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover To pass options to Devel::Cover, set the$DEVEL_COVER_OPTIONS
environment variable:
DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
testdb testdb
This is a synonym for the 'test' action with the [version 0.05]
argument.
This is a synonym for the 'test' action with the debugger=1 argument.
testpod testpod
This checks all the files described in the action and [version 0.25]
produces output. If you are a module author,
this is useful to run before creating a new release. This checks all the files described in the docs action and produces
Test::Harness-style output. If you are a module author, this is
useful to run before creating a new release.
testpodcoverage testpodcoverage
This checks the pod coverage of the distribution and produces [version 0.28]
output. If you are a module author, this is
useful to run before creating a new release. This checks the pod coverage of the distribution and produces
Test::Harness-style output. If you are a module author, this is
useful to run before creating a new release.
versioninstall versioninstall
** Note: since is so new, and since we just recently added [version 0.16]
support for it here too, this feature is to be considered
experimental. ** ** Note: since only.pm is so new, and since we just recently added
support for it here too, this feature is to be considered
experimental. **
If you have the module installed on your system, you can If you have the only.pm module installed on your system, you can use
use this action to install a module into the version-specific this action to install a module into the version-specific library
library trees. This means that you can have several versions of the trees. This means that you can have several versions of the same
same module installed and a specific one like this: module installed and use a specific one like this:
use only MyModule => 0.55; use only MyModule => 0.55;
To override the default installation libraries in To override the default installation libraries in only::config,
specify the parameter when you run the specify the versionlib parameter when you run the Build.PL script:
script:
perl Build.PL --versionlib /my/version/place/ perl Build.PL --versionlib /my/version/place/
To override which version the module is installed as, specify the To override which version the module is installed as, specify the
parameter when you run the script: version parameter when you run the Build.PL script:
perl Build.PL --version 0.50 perl Build.PL --version 0.50
version-specific installs. version-specific installs.
OPTIONS OPTIONS
Command Line Options
The following options can be used during any invocation of or Command Line Options
The following options can be used during any invocation of Build.PL or
the Build script, during any action. For information on other options the Build script, during any action. For information on other options
specific to an action, see the documentation for the respective action. specific to an action, see the documentation for the respective action.
NOTE: There is some preliminary support for options to use the more NOTE: There is some preliminary support for options to use the more
familiar long option style. Most options can be preceded with the familiar long option style. Most options can be preceded with the --
long option prefix, and the underscores changed to dashes (e.g. long option prefix, and the underscores changed to dashes (e.g.
Additionally, the argument to boolean options is --use-rcfile). Additionally, the argument to boolean options is
optional, and boolean options can be negated by prefixing them with optional, and boolean options can be negated by prefixing them with no
or (e.g. or or no- (e.g. --noverbose or --no-verbose).
quiet quiet
Suppress informative messages on output.
Suppress informative messages on output.
verbose verbose
Display extra information about the Build on output. will
turn off Display extra information about the Build on output. verbose will
turn off quiet
cpan_client cpan_client
Sets the command for use with the
action. See for more details. Sets the cpan_client command for use with the installdeps action. See
installdeps for more details.
use_rcfile use_rcfile
Load the ~/.modulebuildrc option file. This option can be set to
false to prevent the custom resource file from being loaded. Load the ~/.modulebuildrc option file. This option can be set to
false to prevent the custom resource file from being loaded.
allow_mb_mismatch allow_mb_mismatch
Suppresses the check upon startup that the version of Module::Build
we're now running under is the same version that was initially Suppresses the check upon startup that the version of Module::Build
invoked when building the distribution (i.e. when the we're now running under is the same version that was initially
script was first run). As of 0.3601, a mismatch results in a warning invoked when building the distribution (i.e. when the Build.PL script
instead of a fatal error, so this option effectively just suppresses was first run). As of 0.3601, a mismatch results in a warning instead
the warning. of a fatal error, so this option effectively just suppresses the
warning.
debug debug
Default Options File (.modulebuildrc) Prints Module::Build debugging information to STDOUT, such as a trace
of executed build actions.
Default Options File (.modulebuildrc)
[version 0.28] [version 0.28]
When Module::Build starts up, it will look first for a file, When Module::Build starts up, it will look first for a file,
$ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the$ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the
.modulebuildrc file in the directories referred to by the environment .modulebuildrc file in the directories referred to by the environment
variables + variables HOMEDRIVE + HOMEDIR, USERPROFILE, APPDATA, WINDIR, SYS$LOGIN. If the file exists, the options specified there will be If the file exists, the options specified there will be used as used as defaults, as if they were typed on the command line. The defaults, as if they were typed on the command line. The defaults can defaults can be overridden by specifying new values on the command line. be overridden by specifying new values on the command line. The action name must come at the beginning of the line, followed by any The action name must come at the beginning of the line, followed by any amount of whitespace and then the options. Options are given the same as amount of whitespace and then the options. Options are given the same they would be on the command line. They can be separated by any amount as they would be on the command line. They can be separated by any of whitespace, including newlines, as long there is whitespace at the amount of whitespace, including newlines, as long there is whitespace beginning of each continued line. Anything following a hash mark at the beginning of each continued line. Anything following a hash mark is considered a comment, and is stripped before parsing. If more than (#) is considered a comment, and is stripped before parsing. If more one line begins with the same action name, those lines are merged into than one line begins with the same action name, those lines are merged one set of options. into one set of options. Besides the regular actions, there are two special pseudo-actions: the Besides the regular actions, there are two special pseudo-actions: the key (asterisk) denotes any global options that should be applied to key * (asterisk) denotes any global options that should be applied to all actions, and the key 'Build_PL' specifies options to be applied when all actions, and the key 'Build_PL' specifies options to be applied you invoke when you invoke perl Build.PL. * verbose=1 # global options * verbose=1 # global options diff flags=-u diff flags=-u install --install_base /home/ken install --install_base /home/ken --install_path html=/home/ken/docs/html --install_path html=/home/ken/docs/html installdeps --cpan_client 'cpanp -i' installdeps --cpan_client 'cpanp -i' If you wish to locate your resource file in a different location, you If you wish to locate your resource file in a different location, you can set the environment variable to the complete can set the environment variable MODULEBUILDRC to the complete absolute absolute path of the file containing your options. path of the file containing your options. Environment variables MODULEBUILDRC MODULEBUILDRC Specifies an alternate location for a default options file as [version 0.28] described above. Specifies an alternate location for a default options file as described above. PERL_MB_OPT PERL_MB_OPT Command line options that are applied to Build.PL or any Build [version 0.36] action. The string is split as the shell would (e.g. whitespace) and the result is prepended to any actual command-line arguments. Command line options that are applied to Build.PL or any Build action. The string is split as the shell would (e.g. whitespace) and the result is prepended to any actual command-line arguments. INSTALL PATHS INSTALL PATHS [version 0.19] [version 0.19] When you invoke Module::Build's action, it needs to figure out When you invoke Module::Build's build action, it needs to figure out where to install things. The nutshell version of how this works is that where to install things. The nutshell version of how this works is that default installation locations are determined from Config.pm, and they default installation locations are determined from Config.pm, and they may be overridden by using the parameter. An may be overridden by using the install_path parameter. An install_base parameter lets you specify an alternative installation parameter lets you specify an alternative installation root like root like /home/foo, and a lets you specify a temporary /home/foo, and a destdir lets you specify a temporary installation installation directory like /tmp/install in case you want to create directory like /tmp/install in case you want to create bundled-up bundled-up installable packages. installable packages. Natively, Module::Build provides default installation locations for the Natively, Module::Build provides default installation locations for the following types of installable items: following types of installable items: lib Usually pure-Perl module files ending in .pm. lib Usually pure-Perl module files ending in .pm. arch arch "Architecture-dependent" module files, usually produced by compiling XS, Inline, or similar code. "Architecture-dependent" module files, usually produced by compiling XS, Inline, or similar code. script script Programs written in pure Perl. In order to improve reuse, try to make these as small as possible - put the code into modules whenever Programs written in pure Perl. In order to improve reuse, try to make possible. these as small as possible - put the code into modules whenever possible. bin "Architecture-dependent" executable programs, i.e. compiled C code or something. Pretty rare to see this in a perl distribution, but it bin happens. "Architecture-dependent" executable programs, i.e. compiled C code or something. Pretty rare to see this in a perl distribution, but it happens. bindoc bindoc Documentation for the stuff in and Usually generated from the POD in those files. Under Unix, these are manual pages Documentation for the stuff in script and bin. Usually generated from belonging to the 'man1' category. the POD in those files. Under Unix, these are manual pages belonging to the 'man1' category. libdoc libdoc Documentation for the stuff in and This is usually generated from the POD in .pm files. Under Unix, these are manual Documentation for the stuff in lib and arch. This is usually pages belonging to the 'man3' category. generated from the POD in .pm files. Under Unix, these are manual pages belonging to the 'man3' category. binhtml binhtml This is the same as above, but applies to HTML documents. This is the same as bindoc above, but applies to HTML documents. libhtml libhtml This is the same as above, but applies to HTML documents. This is the same as libdoc above, but applies to HTML documents. Four other parameters let you control various aspects of how Four other parameters let you control various aspects of how installation paths are determined: installation paths are determined: installdirs installdirs The default destinations for these installable things come from entries in your system's You can select from three The default destinations for these installable things come from different sets of default locations by setting the entries in your system's Config.pm. You can select from three parameter as follows: different sets of default locations by setting the installdirs parameter as follows: 'installdirs' set to: core site vendor 'installdirs' set to: core site vendor uses the following defaults from Config.pm: uses the following defaults from Config.pm: lib => installprivlib installsitelib installvendorlib arch => installarchlib installsitearch installvendorarch lib => installprivlib installsitelib installvendorlib script => installscript installsitescript installvendorscript arch => installarchlib installsitearch installvendorarch bin => installbin installsitebin installvendorbin script => installscript installsitescript installvendorscript bindoc => installman1dir installsiteman1dir installvendorman1dir bin => installbin installsitebin installvendorbin libdoc => installman3dir installsiteman3dir installvendorman3dir bindoc => installman1dir installsiteman1dir installvendorman1dir binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir libdoc => installman3dir installsiteman3dir installvendorman3dir binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*] libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*] * Under some OS (eg. MSWin32) the destination for HTML documents is * Under some OS (eg. MSWin32) the destination for HTML documents is determined by the C<Config.pm> entry C<installhtmldir>. determined by the C<Config.pm> entry C<installhtmldir>. The default value of installdirs is "site". If you're creating vendor The default value of is "site". If you're creating distributions of module packages, you may want to do something like vendor distributions of module packages, you may want to do this: something like this: perl Build.PL --installdirs vendor perl Build.PL --installdirs vendor or or ./Build install --installdirs vendor ./Build install --installdirs vendor If you're installing an updated version of a module that was included If you're installing an updated version of a module that was with perl itself (i.e. a "core module"), then you may set installdirs included with perl itself (i.e. a "core module"), then you may set to "core" to overwrite the module in its present location. to "core" to overwrite the module in its present location. (Note that the 'script' line is different from MakeMaker - unfortunately there's no such thing as "installsitescript" or (Note that the 'script' line is different from - "installvendorscript" entry in Config.pm, so we use the unfortunately there's no such thing as "installsitescript" or "installsitebin" and "installvendorbin" entries to at least get the "installvendorscript" entry in so we use the general location right. In the future, if Config.pm adds some more "installsitebin" and "installvendorbin" entries to at least get the appropriate entries, we'll start using those.) general location right. In the future, if adds some more appropriate entries, we'll start using those.) install_path install_path On the command line, that would look like this: Once the defaults have been set, you can override them. On the command line, that would look like this: rch perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/a rch or this: or this: /arch ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib /arch install_base install_base The exact layout under the directory you specify may vary by system You can also set the whole bunch of installation paths by supplying - we try to do the "sensible" thing on each platform. the install_base parameter to point to a directory on your system. For instance, if you set install_base to "/home/ken" on a Linux system, you'll install as follows: lib => /home/ken/lib/perl5 arch => /home/ken/lib/perl5/i386-linux script => /home/ken/bin bin => /home/ken/bin bindoc => /home/ken/man/man1 libdoc => /home/ken/man/man3 binhtml => /home/ken/html libhtml => /home/ken/html Note that this is different from how MakeMaker's PREFIX parameter works. install_base just gives you a default layout under the directory you specify, which may have little to do with the installdirs=site layout. The exact layout under the directory you specify may vary by system - we try to do the "sensible" thing on each platform. destdir destdir perl Build.PL --destdir /tmp/foo If you want to install everything into a temporary directory first (for instance, if you want to create a directory tree that a package manager like rpm or dpkg could create a package from), you can use the destdir parameter: perl Build.PL --destdir /tmp/foo or or ./Build install --destdir /tmp/foo ./Build install --destdir /tmp/foo This will effectively install to "/tmp/foo/$sitelib", This will effectively install to "/tmp/foo/$sitelib", "/tmp/foo/$sitearch", and the like, except that it will use "/tmp/foo/\$sitearch", and the like, except that it will use
to make the pathnames work correctly on whatever File::Spec to make the pathnames work correctly on whatever platform
platform you're installing on. you're installing on.
prefix prefix
Provided for compatibility with PREFIX
argument. should be used when you want Module::Build to Provided for compatibility with ExtUtils::MakeMaker's PREFIX
install your modules, documentation, and scripts in the same place argument. prefix should be used when you want Module::Build to
as PREFIX mechanism. install your modules, documentation, and scripts in the same place as
ExtUtils::MakeMaker's PREFIX mechanism.
The following are equivalent.
The following are equivalent.
perl Build.PL --prefix /tmp/foo
perl Makefile.PL PREFIX=/tmp/foo perl Build.PL --prefix /tmp/foo
perl Makefile.PL PREFIX=/tmp/foo
Because of the complex nature of the prefixification logic, the
behavior of PREFIX in has changed subtly over time. Because of the complex nature of the prefixification logic, the
Module::Build's --prefix logic is equivalent to the PREFIX logic behavior of PREFIX in MakeMaker has changed subtly over time.
found in 6.30. Module::Build's --prefix logic is equivalent to the PREFIX logic
found in ExtUtils::MakeMaker 6.30.
The maintainers of do understand the troubles with the
PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of The maintainers of MakeMaker do understand the troubles with the
which was released in 2006. PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of
MakeMaker, which was released in 2006.
If you don't need to retain compatibility with old versions
(pre-6.31) of or are starting a fresh Perl If you don't need to retain compatibility with old versions
installation we recommend you use instead (and (pre-6.31) of ExtUtils::MakeMaker or are starting a fresh Perl
in See "Installing in the installation we recommend you use install_base instead (and
same location as ExtUtils::MakeMaker" in Module::Build::Cookbook for INSTALL_BASE in ExtUtils::MakeMaker). See "Installing in the same
further information. location as ExtUtils::MakeMaker" in Module::Build::Cookbook for
further information.
MOTIVATIONS MOTIVATIONS
There are several reasons I wanted to start over, and not just fix what There are several reasons I wanted to start over, and not just fix what
* I don't like the core idea of MakeMaker, namely that make should be
involved in the build process. Here are my reasons:
+
When a person is installing a Perl module, what can you assume When a person is installing a Perl module, what can you assume
about their environment? Can you assume they have No, about their environment? Can you assume they have make? No, but you
but you can assume they have some version of Perl. can assume they have some version of Perl.
+ When a person is writing a Perl module for intended +
distribution, can you assume that they know how to build a
Makefile, so they can customize their build process? No, but you When a person is writing a Perl module for intended distribution,
can assume they know Perl, and could customize that way. can you assume that they know how to build a Makefile, so they can
customize their build process? No, but you can assume they know
For years, these things have been a barrier to people getting the Perl, and could customize that way.
build/install process to do what they want.
For years, these things have been a barrier to people getting the
* There are several architectural decisions in that make build/install process to do what they want.
it very difficult to customize its behavior. For instance, when
using you do but the object * There are several architectural decisions in MakeMaker that make it
created in is actually blessed into a package name very difficult to customize its behavior. For instance, when using
that's created on the fly, so you can't simply subclass MakeMaker you do use ExtUtils::MakeMaker, but the object created in
There is a workaround package that lets WriteMakefile() is actually blessed into a package name that's
you override certain methods, but only certain created on the fly, so you can't simply subclass ExtUtils::MakeMaker.
explicitly preselected (by methods can be overridden. There is a workaround MY package that lets you override certain
Also, the method of customization is very crude: you have to modify MakeMaker methods, but only certain explicitly preselected (by
a string containing the Makefile text for the particular target. MakeMaker) methods can be overridden. Also, the method of
Since these strings aren't documented, and be documented customization is very crude: you have to modify a string containing
(they take on different values depending on the platform, version of the Makefile text for the particular target. Since these strings
perl, version of etc.), you have no guarantee that your aren't documented, and can't be documented (they take on different
modifications will work on someone else's machine or after an values depending on the platform, version of perl, version of
upgrade of or perl. MakeMaker, etc.), you have no guarantee that your modifications will
work on someone else's machine or after an upgrade of MakeMaker or
* It is risky to make major changes to since it does so perl.
many things, is so important, and generally works.
is an entirely separate package so that I can work on it all I want, * It is risky to make major changes to MakeMaker, since it does so
without worrying about backward compatibility with many things, is so important, and generally works. Module::Build is
an entirely separate package so that I can work on it all I want,
* Finally, Perl is said to be a language for system administration. without worrying about backward compatibility with MakeMaker.
Could it really be the case that Perl isn't up to the task of
building and installing software? Even if that software is a bunch * Finally, Perl is said to be a language for system administration.
of files that just need to be copied from one place to Could it really be the case that Perl isn't up to the task of
another? My sense was that we could design a system to accomplish building and installing software? Even if that software is a bunch of
this in a flexible, extensible, and friendly manner. Or die trying. .pm files that just need to be copied from one place to another? My
sense was that we could design a system to accomplish this in a
flexible, extensible, and friendly manner. Or die trying.
TO DO TO DO
The current method of relying on time stamps to determine whether a The current method of relying on time stamps to determine whether a
derived file is out of date isn't likely to scale well, since it derived file is out of date isn't likely to scale well, since it
requires tracing all dependencies backward, it runs into problems on requires tracing all dependencies backward, it runs into problems on
NFS, and it's just generally flimsy. It would be better to use an MD5 NFS, and it's just generally flimsy. It would be better to use an MD5
signature or the like, if available. See for an example. signature or the like, if available. See cons for an example.
- append to perllocal.pod - append to perllocal.pod
AUTHOR AUTHOR
Ken Williams <kwilliams@cpan.org> Ken Williams <kwilliams@cpan.org>
Development questions, bug reports, and patches should be sent to the Development questions, bug reports, and patches should be sent to the
Module-Build mailing list at <module-build@perl.org>. Module-Build mailing list at <module-build@perl.org>.
Bug reports are also welcome at Bug reports are also welcome at
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
The latest development version is available from the Git repository at The latest development version is available from the Git repository at
<https://github.com/Perl-Toolchain-Gang/Module-Build> <https://github.com/Perl-Toolchain-Gang/Module-Build>