1098 lines
35 KiB
Perl
1098 lines
35 KiB
Perl
|
package Module::Build;
|
||
|
|
||
|
# This module doesn't do much of anything itself, it inherits from the
|
||
|
# modules that do the real work. The only real thing it has to do is
|
||
|
# figure out which OS-specific module to pull in. Many of the
|
||
|
# OS-specific modules don't do anything either - most of the work is
|
||
|
# done in Module::Build::Base.
|
||
|
|
||
|
use 5.006;
|
||
|
use strict;
|
||
|
use warnings;
|
||
|
use File::Spec ();
|
||
|
use File::Path ();
|
||
|
use File::Basename ();
|
||
|
use Perl::OSType ();
|
||
|
|
||
|
use Module::Build::Base;
|
||
|
|
||
|
our @ISA = qw(Module::Build::Base);
|
||
|
our $VERSION = '0.4231';
|
||
|
$VERSION = eval $VERSION;
|
||
|
|
||
|
# Inserts the given module into the @ISA hierarchy between
|
||
|
# Module::Build and its immediate parent
|
||
|
sub _interpose_module {
|
||
|
my ($self, $mod) = @_;
|
||
|
eval "use $mod";
|
||
|
die $@ if $@;
|
||
|
|
||
|
no strict 'refs';
|
||
|
my $top_class = $mod;
|
||
|
while (@{"${top_class}::ISA"}) {
|
||
|
last if ${"${top_class}::ISA"}[0] eq $ISA[0];
|
||
|
$top_class = ${"${top_class}::ISA"}[0];
|
||
|
}
|
||
|
|
||
|
@{"${top_class}::ISA"} = @ISA;
|
||
|
@ISA = ($mod);
|
||
|
}
|
||
|
|
||
|
if (grep {-e File::Spec->catfile($_, qw(Module Build Platform), $^O) . '.pm'} @INC) {
|
||
|
__PACKAGE__->_interpose_module("Module::Build::Platform::$^O");
|
||
|
|
||
|
} elsif ( my $ostype = os_type() ) {
|
||
|
__PACKAGE__->_interpose_module("Module::Build::Platform::$ostype");
|
||
|
|
||
|
} else {
|
||
|
warn "Unknown OS type '$^O' - using default settings\n";
|
||
|
}
|
||
|
|
||
|
sub os_type { return Perl::OSType::os_type() }
|
||
|
|
||
|
sub is_vmsish { return Perl::OSType::is_os_type('VMS') }
|
||
|
sub is_windowsish { return Perl::OSType::is_os_type('Windows') }
|
||
|
sub is_unixish { return Perl::OSType::is_os_type('Unix') }
|
||
|
|
||
|
1;
|
||
|
|
||
|
__END__
|
||
|
|
||
|
=for :stopwords
|
||
|
bindoc binhtml destdir distcheck distclean distdir distmeta distsign disttest
|
||
|
fakeinstall html installdirs installsitebin installsitescript installvendorbin
|
||
|
installvendorscript libdoc libhtml pardist ppd ppmdist realclean skipcheck
|
||
|
testall testcover testdb testpod testpodcoverage versioninstall
|
||
|
|
||
|
=head1 NAME
|
||
|
|
||
|
Module::Build - Build and install Perl modules
|
||
|
|
||
|
=head1 SYNOPSIS
|
||
|
|
||
|
Standard process for building & installing modules:
|
||
|
|
||
|
perl Build.PL
|
||
|
./Build
|
||
|
./Build test
|
||
|
./Build install
|
||
|
|
||
|
Or, if you're on a platform (like DOS or Windows) that doesn't require
|
||
|
the "./" notation, you can do this:
|
||
|
|
||
|
perl Build.PL
|
||
|
Build
|
||
|
Build test
|
||
|
Build install
|
||
|
|
||
|
|
||
|
=head1 DESCRIPTION
|
||
|
|
||
|
C<Module::Build> is a system for building, testing, and installing
|
||
|
Perl modules. It is meant to be an alternative to
|
||
|
C<ExtUtils::MakeMaker>. Developers may alter the behavior of the
|
||
|
module through subclassing. It also does not require a C<make> on your
|
||
|
system - most of the C<Module::Build> code is pure-perl and written in a
|
||
|
very cross-platform way.
|
||
|
|
||
|
See L</"COMPARISON"> for more comparisons between C<Module::Build> and
|
||
|
other installer tools.
|
||
|
|
||
|
To install C<Module::Build>, and any other module that uses
|
||
|
C<Module::Build> for its installation process, do the following:
|
||
|
|
||
|
perl Build.PL # 'Build.PL' script creates the '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 install
|
||
|
|
||
|
This illustrates initial configuration and the running of three
|
||
|
'actions'. In this case the actions run are 'build' (the default
|
||
|
action), 'test', and 'install'. Other actions defined so far include:
|
||
|
|
||
|
build manifest
|
||
|
clean manifest_skip
|
||
|
code manpages
|
||
|
config_data pardist
|
||
|
diff ppd
|
||
|
dist ppmdist
|
||
|
distcheck prereq_data
|
||
|
distclean prereq_report
|
||
|
distdir pure_install
|
||
|
distinstall realclean
|
||
|
distmeta retest
|
||
|
distsign skipcheck
|
||
|
disttest test
|
||
|
docs testall
|
||
|
fakeinstall testcover
|
||
|
help testdb
|
||
|
html testpod
|
||
|
install testpodcoverage
|
||
|
installdeps versioninstall
|
||
|
|
||
|
You can run the 'help' action for a complete list of actions.
|
||
|
|
||
|
|
||
|
=head1 GUIDE TO DOCUMENTATION
|
||
|
|
||
|
The documentation for C<Module::Build> is broken up into sections:
|
||
|
|
||
|
=over
|
||
|
|
||
|
=item General Usage (L<Module::Build>)
|
||
|
|
||
|
This is the document you are currently reading. It describes basic
|
||
|
usage and background information. Its main purpose is to assist the
|
||
|
user who wants to learn how to invoke and control C<Module::Build>
|
||
|
scripts at the command line.
|
||
|
|
||
|
=item Authoring Reference (L<Module::Build::Authoring>)
|
||
|
|
||
|
This document describes the structure and organization of
|
||
|
C<Module::Build>, and the relevant concepts needed by authors who are
|
||
|
writing F<Build.PL> scripts for a distribution or controlling
|
||
|
C<Module::Build> processes programmatically.
|
||
|
|
||
|
=item API Reference (L<Module::Build::API>)
|
||
|
|
||
|
This is a reference to the C<Module::Build> API.
|
||
|
|
||
|
=item Cookbook (L<Module::Build::Cookbook>)
|
||
|
|
||
|
This document demonstrates how to accomplish many common tasks. It
|
||
|
covers general command line usage and authoring of F<Build.PL>
|
||
|
scripts. Includes working examples.
|
||
|
|
||
|
=back
|
||
|
|
||
|
|
||
|
=head1 ACTIONS
|
||
|
|
||
|
There are some general principles at work here. First, each task when
|
||
|
building a module is called an "action". These actions are listed
|
||
|
above; they correspond to the building, testing, installing,
|
||
|
packaging, etc., tasks.
|
||
|
|
||
|
Second, arguments are processed in a very systematic way. Arguments
|
||
|
are always key=value pairs. They may be specified at C<perl Build.PL>
|
||
|
time (i.e. C<perl Build.PL destdir=/my/secret/place>), in which case
|
||
|
their values last for the lifetime of the C<Build> script. They may
|
||
|
also be specified when executing a particular action (i.e.
|
||
|
C<Build test verbose=1>), in which case their values last only for the
|
||
|
lifetime of that command. Per-action command line parameters take
|
||
|
precedence over parameters specified at C<perl Build.PL> time.
|
||
|
|
||
|
The build process also relies heavily on the C<Config.pm> module.
|
||
|
If the user wishes to override any of the
|
||
|
values in C<Config.pm>, she may specify them like so:
|
||
|
|
||
|
perl Build.PL --config cc=gcc --config ld=gcc
|
||
|
|
||
|
The following build actions are provided by default.
|
||
|
|
||
|
=over 4
|
||
|
|
||
|
=item build
|
||
|
|
||
|
[version 0.01]
|
||
|
|
||
|
If you run the C<Build> script without any arguments, it runs the
|
||
|
C<build> action, which in turn runs the C<code> and C<docs> actions.
|
||
|
|
||
|
This is analogous to the C<MakeMaker> I<make all> target.
|
||
|
|
||
|
=item clean
|
||
|
|
||
|
[version 0.01]
|
||
|
|
||
|
This action will clean up any files that the build process may have
|
||
|
created, including the C<blib/> directory (but not including the
|
||
|
C<_build/> directory and the C<Build> script itself).
|
||
|
|
||
|
=item code
|
||
|
|
||
|
[version 0.20]
|
||
|
|
||
|
This action builds your code base.
|
||
|
|
||
|
By default it just creates a C<blib/> directory and copies any C<.pm>
|
||
|
and C<.pod> files from your C<lib/> directory into the C<blib/>
|
||
|
directory. It also compiles any C<.xs> files from C<lib/> and places
|
||
|
them in C<blib/>. Of course, you need a working C compiler (probably
|
||
|
the same one that built perl itself) for the compilation to work
|
||
|
properly.
|
||
|
|
||
|
The C<code> action also runs any C<.PL> files in your F<lib/>
|
||
|
directory. Typically these create other files, named the same but
|
||
|
without the C<.PL> ending. For example, a file F<lib/Foo/Bar.pm.PL>
|
||
|
could create the file F<lib/Foo/Bar.pm>. The C<.PL> files are
|
||
|
processed first, so any C<.pm> files (or other kinds that we deal
|
||
|
with) will get copied correctly.
|
||
|
|
||
|
=item config_data
|
||
|
|
||
|
[version 0.26]
|
||
|
|
||
|
...
|
||
|
|
||
|
=item diff
|
||
|
|
||
|
[version 0.14]
|
||
|
|
||
|
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 C<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 C<-u>:
|
||
|
|
||
|
./Build diff flags=-u
|
||
|
|
||
|
=item dist
|
||
|
|
||
|
[version 0.02]
|
||
|
|
||
|
This action is helpful for module authors who want to package up their
|
||
|
module for source distribution through a medium like CPAN. It will create a
|
||
|
tarball of the files listed in F<MANIFEST> and compress the tarball using
|
||
|
GZIP compression.
|
||
|
|
||
|
By default, this action will use the C<Archive::Tar> module. However, you can
|
||
|
force it to use binary "tar" and "gzip" executables by supplying an explicit
|
||
|
C<tar> (and optional C<gzip>) parameter:
|
||
|
|
||
|
./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
|
||
|
|
||
|
=item distcheck
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
Reports which files are in the build directory but not in the
|
||
|
F<MANIFEST> file, and vice versa. (See L</manifest> for details.)
|
||
|
|
||
|
=item distclean
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
Performs the 'realclean' action and then the 'distcheck' action.
|
||
|
|
||
|
=item distdir
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
Creates a "distribution directory" named C<$dist_name-$dist_version>
|
||
|
(if that directory already exists, it will be removed first), then
|
||
|
copies all the files listed in the F<MANIFEST> file to that directory.
|
||
|
This directory is what the distribution tarball is created from.
|
||
|
|
||
|
=item distinstall
|
||
|
|
||
|
[version 0.37]
|
||
|
|
||
|
Performs the 'distdir' action, then switches into that directory and runs a
|
||
|
C<perl Build.PL>, followed by the 'build' and 'install' actions in that
|
||
|
directory. Use PERL_MB_OPT or F<.modulebuildrc> to set options that should be
|
||
|
applied during subprocesses
|
||
|
|
||
|
=item distmeta
|
||
|
|
||
|
[version 0.21]
|
||
|
|
||
|
Creates the F<META.yml> file that describes the distribution.
|
||
|
|
||
|
F<META.yml> is a file containing various bits of I<metadata> about the
|
||
|
distribution. The metadata includes the distribution name, version,
|
||
|
abstract, prerequisites, license, and various other data about the
|
||
|
distribution. This file is created as F<META.yml> in a simplified YAML format.
|
||
|
|
||
|
F<META.yml> file must also be listed in F<MANIFEST> - if it's not, a
|
||
|
warning will be issued.
|
||
|
|
||
|
The current version of the F<META.yml> specification can be found
|
||
|
on CPAN as L<CPAN::Meta::Spec>.
|
||
|
|
||
|
=item distsign
|
||
|
|
||
|
[version 0.16]
|
||
|
|
||
|
Uses C<Module::Signature> to create a SIGNATURE file for your
|
||
|
distribution, and adds the SIGNATURE file to the distribution's
|
||
|
MANIFEST.
|
||
|
|
||
|
=item disttest
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
Performs the 'distdir' action, then switches into that directory and runs a
|
||
|
C<perl Build.PL>, followed by the 'build' and 'test' actions in that directory.
|
||
|
Use PERL_MB_OPT or F<.modulebuildrc> to set options that should be applied
|
||
|
during subprocesses
|
||
|
|
||
|
|
||
|
=item docs
|
||
|
|
||
|
[version 0.20]
|
||
|
|
||
|
This will generate documentation (e.g. Unix man pages and HTML
|
||
|
documents) for any installable items under B<blib/> that
|
||
|
contain POD. If there are no C<bindoc> or C<libdoc> installation
|
||
|
targets defined (as will be the case on systems that don't support
|
||
|
Unix manpages) no action is taken for manpages. If there are no
|
||
|
C<binhtml> or C<libhtml> installation targets defined no action is
|
||
|
taken for HTML documents.
|
||
|
|
||
|
=item fakeinstall
|
||
|
|
||
|
[version 0.02]
|
||
|
|
||
|
This is just like the C<install> action, but it won't actually do
|
||
|
anything, it will just report what it I<would> have done if you had
|
||
|
actually run the C<install> action.
|
||
|
|
||
|
=item help
|
||
|
|
||
|
[version 0.03]
|
||
|
|
||
|
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
|
||
|
actions too.
|
||
|
|
||
|
With an optional argument specifying an action name (e.g. C<Build help
|
||
|
test>), the 'help' action will show you any POD documentation it can
|
||
|
find for that action.
|
||
|
|
||
|
=item html
|
||
|
|
||
|
[version 0.26]
|
||
|
|
||
|
This will generate HTML documentation for any binary or library files
|
||
|
under B<blib/> that contain POD. The HTML documentation will only be
|
||
|
installed if the install paths can be determined from values in
|
||
|
C<Config.pm>. You can also supply or override install paths on the
|
||
|
command line by specifying C<install_path> values for the C<binhtml>
|
||
|
and/or C<libhtml> installation targets.
|
||
|
|
||
|
With an optional C<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:
|
||
|
|
||
|
./Build html --html_links 0
|
||
|
|
||
|
=item install
|
||
|
|
||
|
[version 0.01]
|
||
|
|
||
|
This action will use C<ExtUtils::Install> to install the files from
|
||
|
C<blib/> into the system. See L</"INSTALL PATHS">
|
||
|
for details about how Module::Build determines where to install
|
||
|
things, and how to influence this process.
|
||
|
|
||
|
If you want the installation process to look around in C<@INC> for
|
||
|
other versions of the stuff you're installing and try to delete it,
|
||
|
you can use the C<uninst> parameter, which tells C<ExtUtils::Install> to
|
||
|
do so:
|
||
|
|
||
|
./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
|
||
|
situation indeed.
|
||
|
|
||
|
=item installdeps
|
||
|
|
||
|
[version 0.36]
|
||
|
|
||
|
This action will use the C<cpan_client> parameter as a command to install
|
||
|
missing prerequisites. You will be prompted whether to install
|
||
|
optional dependencies.
|
||
|
|
||
|
The C<cpan_client> option defaults to 'cpan' but can be set as an option or in
|
||
|
F<.modulebuildrc>. It must be a shell command that takes a list of modules to
|
||
|
install as arguments (e.g. 'cpanp -i' for CPANPLUS). If 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'
|
||
|
# installs to 5.8.9
|
||
|
|
||
|
=item manifest
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
This is an action intended for use by module authors, not people
|
||
|
installing modules. It will bring the F<MANIFEST> up to date with the
|
||
|
files currently present in the distribution. You may use a
|
||
|
F<MANIFEST.SKIP> file to exclude certain files or directories from
|
||
|
inclusion in the F<MANIFEST>. F<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 F<MANIFEST>.
|
||
|
|
||
|
The following is a reasonable F<MANIFEST.SKIP> starting point, you can
|
||
|
add your own stuff to it:
|
||
|
|
||
|
^_build
|
||
|
^Build$
|
||
|
^blib
|
||
|
~$
|
||
|
\.bak$
|
||
|
^MANIFEST\.SKIP$
|
||
|
CVS
|
||
|
|
||
|
See the L</distcheck> and L</skipcheck> actions if you want to find out
|
||
|
what the C<manifest> action would do, without actually doing anything.
|
||
|
|
||
|
=item manifest_skip
|
||
|
|
||
|
[version 0.3608]
|
||
|
|
||
|
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.
|
||
|
|
||
|
=item manpages
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
This will generate man pages for any binary or library files under
|
||
|
B<blib/> that contain POD. The man pages will only be installed if the
|
||
|
install paths can be determined from values in C<Config.pm>. You can
|
||
|
also supply or override install paths by specifying there values on
|
||
|
the command line with the C<bindoc> and C<libdoc> installation
|
||
|
targets.
|
||
|
|
||
|
=item pardist
|
||
|
|
||
|
[version 0.2806]
|
||
|
|
||
|
Generates a PAR binary distribution for use with L<PAR> or L<PAR::Dist>.
|
||
|
|
||
|
It requires that the PAR::Dist module (version 0.17 and up) is
|
||
|
installed on your system.
|
||
|
|
||
|
=item ppd
|
||
|
|
||
|
[version 0.20]
|
||
|
|
||
|
Build a PPD file for your distribution.
|
||
|
|
||
|
This action takes an optional argument C<codebase> which is used in
|
||
|
the generated PPD file to specify the (usually relative) URL of the
|
||
|
distribution. By default, this value is the distribution name without
|
||
|
any path information.
|
||
|
|
||
|
Example:
|
||
|
|
||
|
./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
|
||
|
|
||
|
=item ppmdist
|
||
|
|
||
|
[version 0.23]
|
||
|
|
||
|
Generates a PPM binary distribution and a PPD description file. This
|
||
|
action also invokes the C<ppd> action, so it can accept the same
|
||
|
C<codebase> argument described under that action.
|
||
|
|
||
|
This uses the same mechanism as the C<dist> action to tar & zip its
|
||
|
output, so you can supply C<tar> and/or C<gzip> parameters to affect
|
||
|
the result.
|
||
|
|
||
|
=item prereq_data
|
||
|
|
||
|
[version 0.32]
|
||
|
|
||
|
This action prints out a Perl data structure of all prerequisites and the versions
|
||
|
required. The output can be loaded again using C<eval()>. This can be useful for
|
||
|
external tools that wish to query a Build script for prerequisites.
|
||
|
|
||
|
=item prereq_report
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
This action prints out a list of all prerequisites, the versions 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.
|
||
|
|
||
|
=item pure_install
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
This action is identical to the C<install> action. In the future,
|
||
|
though, when C<install> starts writing to the file
|
||
|
F<$(INSTALLARCHLIB)/perllocal.pod>, C<pure_install> won't, and that
|
||
|
will be the only difference between them.
|
||
|
|
||
|
=item realclean
|
||
|
|
||
|
[version 0.01]
|
||
|
|
||
|
This action is just like the C<clean> action, but also removes the
|
||
|
C<_build> directory and the C<Build> script. If you run the
|
||
|
C<realclean> action, you are essentially starting over, so you will
|
||
|
have to re-create the C<Build> script again.
|
||
|
|
||
|
=item retest
|
||
|
|
||
|
[version 0.2806]
|
||
|
|
||
|
This is just like the C<test> action, but doesn't actually build the
|
||
|
distribution first, and doesn't add F<blib/> to the load path, and
|
||
|
therefore will test against a I<previously> installed version of the
|
||
|
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.
|
||
|
|
||
|
=item skipcheck
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
Reports which files are skipped due to the entries in the
|
||
|
F<MANIFEST.SKIP> file (See L</manifest> for details)
|
||
|
|
||
|
=item test
|
||
|
|
||
|
[version 0.01]
|
||
|
|
||
|
This will use C<Test::Harness> or C<TAP::Harness> to run any regression
|
||
|
tests and report their results. Tests can be defined in the standard
|
||
|
places: a file called C<test.pl> in the top-level directory, or several
|
||
|
files ending with C<.t> in a C<t/> directory.
|
||
|
|
||
|
If you want tests to be 'verbose', i.e. show details of test execution
|
||
|
rather than just summary information, pass the argument C<verbose=1>.
|
||
|
|
||
|
If you want to run tests under the perl debugger, pass the argument
|
||
|
C<debugger=1>.
|
||
|
|
||
|
If you want to have Module::Build find test files with different file
|
||
|
name extensions, pass the C<test_file_exts> argument with an array
|
||
|
of extensions, such as C<[qw( .t .s .z )]>.
|
||
|
|
||
|
If you want test to be run by C<TAP::Harness>, rather than C<Test::Harness>,
|
||
|
pass the argument C<tap_harness_args> as an array reference of arguments to
|
||
|
pass to the TAP::Harness constructor.
|
||
|
|
||
|
In addition, if a file called C<visual.pl> exists in the top-level
|
||
|
directory, this file will be executed as a Perl script and its output
|
||
|
will be shown to the user. This is a good place to put speed tests or
|
||
|
other tests that don't use the C<Test::Harness> format for output.
|
||
|
|
||
|
To override the choice of tests to run, you may pass a C<test_files>
|
||
|
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 a single test to see whether you've squashed a certain bug yet:
|
||
|
|
||
|
./Build test --test_files t/something_failing.t
|
||
|
|
||
|
You may also pass several C<test_files> arguments separately:
|
||
|
|
||
|
./Build test --test_files t/one.t --test_files t/two.t
|
||
|
|
||
|
or use a C<glob()>-style pattern:
|
||
|
|
||
|
./Build test --test_files 't/01-*.t'
|
||
|
|
||
|
=item testall
|
||
|
|
||
|
[version 0.2807]
|
||
|
|
||
|
[Note: the 'testall' action and the code snippets below are currently
|
||
|
in alpha stage, see
|
||
|
L<http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html> ]
|
||
|
|
||
|
Runs the C<test> action plus each of the C<test$type> actions defined by
|
||
|
the keys of the C<test_types> parameter.
|
||
|
|
||
|
Currently, you need to define the ACTION_test$type method yourself and
|
||
|
enumerate them in the test_types parameter.
|
||
|
|
||
|
my $mb = Module::Build->subclass(
|
||
|
code => q(
|
||
|
sub ACTION_testspecial { shift->generic_test(type => 'special'); }
|
||
|
sub ACTION_testauthor { shift->generic_test(type => 'author'); }
|
||
|
)
|
||
|
)->new(
|
||
|
...
|
||
|
test_types => {
|
||
|
special => '.st',
|
||
|
author => ['.at', '.pt' ],
|
||
|
},
|
||
|
...
|
||
|
|
||
|
=item testcover
|
||
|
|
||
|
[version 0.26]
|
||
|
|
||
|
Runs the C<test> action using C<Devel::Cover>, generating a
|
||
|
code-coverage report showing which parts of the code were actually
|
||
|
exercised during the tests.
|
||
|
|
||
|
To pass options to C<Devel::Cover>, set the C<$DEVEL_COVER_OPTIONS>
|
||
|
environment variable:
|
||
|
|
||
|
DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
|
||
|
|
||
|
=item testdb
|
||
|
|
||
|
[version 0.05]
|
||
|
|
||
|
This is a synonym for the 'test' action with the C<debugger=1>
|
||
|
argument.
|
||
|
|
||
|
=item testpod
|
||
|
|
||
|
[version 0.25]
|
||
|
|
||
|
This checks all the files described in the C<docs> action and
|
||
|
produces C<Test::Harness>-style output. If you are a module author,
|
||
|
this is useful to run before creating a new release.
|
||
|
|
||
|
=item testpodcoverage
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
This checks the pod coverage of the distribution and
|
||
|
produces C<Test::Harness>-style output. If you are a module author,
|
||
|
this is useful to run before creating a new release.
|
||
|
|
||
|
=item versioninstall
|
||
|
|
||
|
[version 0.16]
|
||
|
|
||
|
** Note: since C<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 C<only.pm> module installed on your system, you can
|
||
|
use this action to install a module into the version-specific library
|
||
|
trees. This means that you can have several versions of the same
|
||
|
module installed and C<use> a specific one like this:
|
||
|
|
||
|
use only MyModule => 0.55;
|
||
|
|
||
|
To override the default installation libraries in C<only::config>,
|
||
|
specify the C<versionlib> parameter when you run the C<Build.PL> script:
|
||
|
|
||
|
perl Build.PL --versionlib /my/version/place/
|
||
|
|
||
|
To override which version the module is installed as, specify the
|
||
|
C<version> parameter when you run the C<Build.PL> script:
|
||
|
|
||
|
perl Build.PL --version 0.50
|
||
|
|
||
|
See the C<only.pm> documentation for more information on
|
||
|
version-specific installs.
|
||
|
|
||
|
=back
|
||
|
|
||
|
|
||
|
=head1 OPTIONS
|
||
|
|
||
|
=head2 Command Line Options
|
||
|
|
||
|
The following options can be used during any invocation of C<Build.PL>
|
||
|
or the Build script, during any action. For information on other
|
||
|
options specific to an action, see the documentation for the
|
||
|
respective action.
|
||
|
|
||
|
NOTE: There is some preliminary support for options to use the more
|
||
|
familiar long option style. Most options can be preceded with the
|
||
|
C<--> long option prefix, and the underscores changed to dashes
|
||
|
(e.g. C<--use-rcfile>). Additionally, the argument to boolean options is
|
||
|
optional, and boolean options can be negated by prefixing them with
|
||
|
C<no> or C<no-> (e.g. C<--noverbose> or C<--no-verbose>).
|
||
|
|
||
|
=over 4
|
||
|
|
||
|
=item quiet
|
||
|
|
||
|
Suppress informative messages on output.
|
||
|
|
||
|
=item verbose
|
||
|
|
||
|
Display extra information about the Build on output. C<verbose> will
|
||
|
turn off C<quiet>
|
||
|
|
||
|
=item cpan_client
|
||
|
|
||
|
Sets the C<cpan_client> command for use with the C<installdeps> action.
|
||
|
See C<installdeps> for more details.
|
||
|
|
||
|
=item use_rcfile
|
||
|
|
||
|
Load the F<~/.modulebuildrc> option file. This option can be set to
|
||
|
false to prevent the custom resource file from being loaded.
|
||
|
|
||
|
=item 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 invoked
|
||
|
when building the distribution (i.e. when the C<Build.PL> script was
|
||
|
first run). As of 0.3601, a mismatch results in a warning instead of
|
||
|
a fatal error, so this option effectively just suppresses the warning.
|
||
|
|
||
|
=item debug
|
||
|
|
||
|
Prints Module::Build debugging information to STDOUT, such as a trace of
|
||
|
executed build actions.
|
||
|
|
||
|
=back
|
||
|
|
||
|
=head2 Default Options File (F<.modulebuildrc>)
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
When Module::Build starts up, it will look first for a file,
|
||
|
F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look
|
||
|
in the F<.modulebuildrc> file in the directories referred to by
|
||
|
the environment variables C<HOMEDRIVE> + C<HOMEDIR>, C<USERPROFILE>,
|
||
|
C<APPDATA>, C<WINDIR>, C<SYS$LOGIN>. If the file exists, the options
|
||
|
specified there will be used as defaults, as if they were typed on the
|
||
|
command line. The defaults can be overridden by specifying new values
|
||
|
on the command line.
|
||
|
|
||
|
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 they would be on the command line. They can be separated by any
|
||
|
amount of whitespace, including newlines, as long there is whitespace at
|
||
|
the beginning of each continued line. Anything following a hash mark (C<#>)
|
||
|
is considered a comment, and is stripped before parsing. If more than
|
||
|
one line begins with the same action name, those lines are merged into
|
||
|
one set of options.
|
||
|
|
||
|
Besides the regular actions, there are two special pseudo-actions: the
|
||
|
key C<*> (asterisk) denotes any global options that should be applied
|
||
|
to all actions, and the key 'Build_PL' specifies options to be applied
|
||
|
when you invoke C<perl Build.PL>.
|
||
|
|
||
|
* verbose=1 # global options
|
||
|
diff flags=-u
|
||
|
install --install_base /home/ken
|
||
|
--install_path html=/home/ken/docs/html
|
||
|
installdeps --cpan_client 'cpanp -i'
|
||
|
|
||
|
If you wish to locate your resource file in a different location, you
|
||
|
can set the environment variable C<MODULEBUILDRC> to the complete
|
||
|
absolute path of the file containing your options.
|
||
|
|
||
|
=head2 Environment variables
|
||
|
|
||
|
=over
|
||
|
|
||
|
=item MODULEBUILDRC
|
||
|
|
||
|
[version 0.28]
|
||
|
|
||
|
Specifies an alternate location for a default options file as described above.
|
||
|
|
||
|
=item PERL_MB_OPT
|
||
|
|
||
|
[version 0.36]
|
||
|
|
||
|
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.
|
||
|
|
||
|
=back
|
||
|
|
||
|
=head1 INSTALL PATHS
|
||
|
|
||
|
[version 0.19]
|
||
|
|
||
|
When you invoke Module::Build's C<build> action, it needs to figure
|
||
|
out where to install things. The nutshell version of how this works
|
||
|
is that default installation locations are determined from
|
||
|
F<Config.pm>, and they may be overridden by using the C<install_path>
|
||
|
parameter. An C<install_base> parameter lets you specify an
|
||
|
alternative installation root like F</home/foo>, and a C<destdir> lets
|
||
|
you specify a temporary installation directory like F</tmp/install> in
|
||
|
case you want to create bundled-up installable packages.
|
||
|
|
||
|
Natively, Module::Build provides default installation locations for
|
||
|
the following types of installable items:
|
||
|
|
||
|
=over 4
|
||
|
|
||
|
=item lib
|
||
|
|
||
|
Usually pure-Perl module files ending in F<.pm>.
|
||
|
|
||
|
=item arch
|
||
|
|
||
|
"Architecture-dependent" module files, usually produced by compiling
|
||
|
XS, L<Inline>, or similar code.
|
||
|
|
||
|
=item 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
|
||
|
possible.
|
||
|
|
||
|
=item bin
|
||
|
|
||
|
"Architecture-dependent" executable programs, i.e. compiled C code or
|
||
|
something. Pretty rare to see this in a perl distribution, but it
|
||
|
happens.
|
||
|
|
||
|
=item bindoc
|
||
|
|
||
|
Documentation for the stuff in C<script> and C<bin>. Usually
|
||
|
generated from the POD in those files. Under Unix, these are manual
|
||
|
pages belonging to the 'man1' category.
|
||
|
|
||
|
=item libdoc
|
||
|
|
||
|
Documentation for the stuff in C<lib> and C<arch>. This is usually
|
||
|
generated from the POD in F<.pm> files. Under Unix, these are manual
|
||
|
pages belonging to the 'man3' category.
|
||
|
|
||
|
=item binhtml
|
||
|
|
||
|
This is the same as C<bindoc> above, but applies to HTML documents.
|
||
|
|
||
|
=item libhtml
|
||
|
|
||
|
This is the same as C<libdoc> above, but applies to HTML documents.
|
||
|
|
||
|
=back
|
||
|
|
||
|
Four other parameters let you control various aspects of how
|
||
|
installation paths are determined:
|
||
|
|
||
|
=over 4
|
||
|
|
||
|
=item installdirs
|
||
|
|
||
|
The default destinations for these installable things come from
|
||
|
entries in your system's C<Config.pm>. You can select from three
|
||
|
different sets of default locations by setting the C<installdirs>
|
||
|
parameter as follows:
|
||
|
|
||
|
'installdirs' set to:
|
||
|
core site vendor
|
||
|
|
||
|
uses the following defaults from Config.pm:
|
||
|
|
||
|
lib => installprivlib installsitelib installvendorlib
|
||
|
arch => installarchlib installsitearch installvendorarch
|
||
|
script => installscript installsitescript installvendorscript
|
||
|
bin => installbin installsitebin installvendorbin
|
||
|
bindoc => installman1dir installsiteman1dir installvendorman1dir
|
||
|
libdoc => installman3dir installsiteman3dir installvendorman3dir
|
||
|
binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
|
||
|
libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
|
||
|
|
||
|
* Under some OS (eg. MSWin32) the destination for HTML documents is
|
||
|
determined by the C<Config.pm> entry C<installhtmldir>.
|
||
|
|
||
|
The default value of C<installdirs> is "site". If you're creating
|
||
|
vendor distributions of module packages, you may want to do something
|
||
|
like this:
|
||
|
|
||
|
perl Build.PL --installdirs vendor
|
||
|
|
||
|
or
|
||
|
|
||
|
./Build install --installdirs vendor
|
||
|
|
||
|
If you're installing an updated version of a module that was included
|
||
|
with perl itself (i.e. a "core module"), then you may set
|
||
|
C<installdirs> to "core" to overwrite the module in its present
|
||
|
location.
|
||
|
|
||
|
(Note that the 'script' line is different from C<MakeMaker> -
|
||
|
unfortunately there's no such thing as "installsitescript" or
|
||
|
"installvendorscript" entry in C<Config.pm>, so we use the
|
||
|
"installsitebin" and "installvendorbin" entries to at least get the
|
||
|
general location right. In the future, if C<Config.pm> adds some more
|
||
|
appropriate entries, we'll start using those.)
|
||
|
|
||
|
=item install_path
|
||
|
|
||
|
Once the defaults have been set, you can override them.
|
||
|
|
||
|
On the command line, that would look like this:
|
||
|
|
||
|
perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
|
||
|
|
||
|
or this:
|
||
|
|
||
|
./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
|
||
|
|
||
|
=item install_base
|
||
|
|
||
|
You can also set the whole bunch of installation paths by supplying the
|
||
|
C<install_base> parameter to point to a directory on your system. For
|
||
|
instance, if you set C<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 I<different> from how C<MakeMaker>'s C<PREFIX>
|
||
|
parameter works. C<install_base> just gives you a default layout under the
|
||
|
directory you specify, which may have little to do with the
|
||
|
C<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.
|
||
|
|
||
|
=item destdir
|
||
|
|
||
|
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 C<rpm> or C<dpkg> could create a package from), you can
|
||
|
use the C<destdir> parameter:
|
||
|
|
||
|
perl Build.PL --destdir /tmp/foo
|
||
|
|
||
|
or
|
||
|
|
||
|
./Build install --destdir /tmp/foo
|
||
|
|
||
|
This will effectively install to "/tmp/foo/$sitelib",
|
||
|
"/tmp/foo/$sitearch", and the like, except that it will use
|
||
|
C<File::Spec> to make the pathnames work correctly on whatever
|
||
|
platform you're installing on.
|
||
|
|
||
|
=item prefix
|
||
|
|
||
|
Provided for compatibility with C<ExtUtils::MakeMaker>'s PREFIX argument.
|
||
|
C<prefix> should be used when you want Module::Build to install your
|
||
|
modules, documentation, and scripts in the same place as
|
||
|
C<ExtUtils::MakeMaker>'s PREFIX mechanism.
|
||
|
|
||
|
The following are equivalent.
|
||
|
|
||
|
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 C<MakeMaker> has changed subtly over time.
|
||
|
Module::Build's --prefix logic is equivalent to the PREFIX logic found
|
||
|
in C<ExtUtils::MakeMaker> 6.30.
|
||
|
|
||
|
The maintainers of C<MakeMaker> do understand the troubles with the
|
||
|
PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of
|
||
|
C<MakeMaker>, which was released in 2006.
|
||
|
|
||
|
If you don't need to retain compatibility with old versions (pre-6.31) of C<ExtUtils::MakeMaker> or
|
||
|
are starting a fresh Perl installation we recommend you use
|
||
|
C<install_base> instead (and C<INSTALL_BASE> in C<ExtUtils::MakeMaker>).
|
||
|
See L<Module::Build::Cookbook/Installing in the same location as
|
||
|
ExtUtils::MakeMaker> for further information.
|
||
|
|
||
|
|
||
|
=back
|
||
|
|
||
|
|
||
|
=head1 COMPARISON
|
||
|
|
||
|
A comparison between C<Module::Build> and other CPAN distribution installers.
|
||
|
|
||
|
=over
|
||
|
|
||
|
=item *
|
||
|
|
||
|
L<ExtUtils::MakeMaker> requires C<make> and use of a F<Makefile>.
|
||
|
C<Module::Build> does not, nor do other pure-perl installers following the
|
||
|
F<Build.PL> spec such as L<Module::Build::Tiny>. In practice, this is usually
|
||
|
not an issue for the end user, as C<make> is already required to install most
|
||
|
CPAN modules, even on Windows.
|
||
|
|
||
|
=item *
|
||
|
|
||
|
L<ExtUtils::MakeMaker> has been a core module in every version of Perl 5, and
|
||
|
must maintain compatibility to install the majority of CPAN modules.
|
||
|
C<Module::Build> was added to core in Perl 5.10 and removed from core in Perl
|
||
|
5.20, and (like L<ExtUtils::MakeMaker>) is only updated to fix critical issues
|
||
|
and maintain compatibility. C<Module::Build> and other non-core installers like
|
||
|
L<Module::Build::Tiny> are installed from CPAN by declaring themselves as a
|
||
|
C<configure> phase prerequisite, and in this way any installer can be used in
|
||
|
place of L<ExtUtils::MakeMaker>.
|
||
|
|
||
|
=item *
|
||
|
|
||
|
Customizing the build process with L<ExtUtils::MakeMaker> involves overriding
|
||
|
certain methods that form the F<Makefile> by defining the subs in the C<MY::>
|
||
|
namespace, requiring in-depth knowledge of F<Makefile>, but allowing targeted
|
||
|
customization of the entire build. Customizing C<Module::Build> involves
|
||
|
subclassing C<Module::Build> itself, adding or overriding pure-perl methods
|
||
|
that represent build actions, which are invoked as arguments passed to the
|
||
|
generated C<./Build> script. This is a simpler concept but requires redefining
|
||
|
the standard build actions to invoke your customizations.
|
||
|
L<Module::Build::Tiny> does not allow for customization.
|
||
|
|
||
|
=item *
|
||
|
|
||
|
C<Module::Build> provides more features and a better experience for distribution
|
||
|
authors than L<ExtUtils::MakeMaker>. However, tools designed specifically for
|
||
|
authoring, such as L<Dist::Zilla> and its spinoffs L<Dist::Milla> and
|
||
|
L<Minilla>, provide these features and more, and generate a configure script
|
||
|
(F<Makefile.PL>/F<Build.PL>) that will use any of the various installers
|
||
|
separately on the end user side. L<App::ModuleBuildTiny> is an alternative
|
||
|
standalone authoring tool for distributions using L<Module::Build::Tiny>, which
|
||
|
requires only a simple two-line F<Build.PL>.
|
||
|
|
||
|
=back
|
||
|
|
||
|
|
||
|
=head1 TO DO
|
||
|
|
||
|
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
|
||
|
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
|
||
|
signature or the like, if available. See C<cons> for an example.
|
||
|
|
||
|
- append to perllocal.pod
|
||
|
- add a 'plugin' functionality
|
||
|
|
||
|
|
||
|
=head1 AUTHOR
|
||
|
|
||
|
Ken Williams <kwilliams@cpan.org>
|
||
|
|
||
|
Development questions, bug reports, and patches should be sent to the
|
||
|
Module-Build mailing list at <module-build@perl.org>.
|
||
|
|
||
|
Bug reports are also welcome at
|
||
|
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
|
||
|
|
||
|
The latest development version is available from the Git
|
||
|
repository at <https://github.com/Perl-Toolchain-Gang/Module-Build>
|
||
|
|
||
|
|
||
|
=head1 COPYRIGHT
|
||
|
|
||
|
Copyright (c) 2001-2006 Ken Williams. All rights reserved.
|
||
|
|
||
|
This library is free software; you can redistribute it and/or
|
||
|
modify it under the same terms as Perl itself.
|
||
|
|
||
|
|
||
|
=head1 SEE ALSO
|
||
|
|
||
|
perl(1), L<Module::Build::Cookbook>, L<Module::Build::Authoring>,
|
||
|
L<Module::Build::API>, L<ExtUtils::MakeMaker>
|
||
|
|
||
|
F<META.yml> Specification:
|
||
|
L<CPAN::Meta::Spec>
|
||
|
|
||
|
L<http://www.dsmit.com/cons/>
|
||
|
|
||
|
L<http://search.cpan.org/dist/PerlBuildSystem/>
|
||
|
|
||
|
=cut
|