Module::Build::CookbooUser Contributed Perl DocumentModule::Build::Cookbook(3)NAMEModule::Build::Cookbook - Examples of Module::Build Usage
DESCRIPTION
"Module::Build" isn't conceptually very complicated, but examples are
always helpful. I got the idea for writing this cookbook when attend-
ing Brian Ingerson's "Extreme Programming Tools for Module Authors"
presentation at YAPC 2003, when he said, straightforwardly, "Write A
Cookbook."
The definitional of how stuff works is in the main "Module::Build" doc-
umentation. It's best to get familiar with that too.
BASIC RECIPES
The basic installation recipe for modules that use Module::Build
In most cases, you can just issue the following commands:
perl Build.PL
./Build
./Build test
./Build install
There's nothing complicated here - first you're running a script called
Build.PL, then you're running a (newly-generated) script called Build
and passing it various arguments.
The exact commands may vary a bit depending on how you invoke perl
scripts on your system. For instance, if you have multiple versions of
perl installed, you can install to one particular perl's library direc-
tories like so:
/usr/bin/perl5.8.1 Build.PL
./Build
./Build test
./Build install
If you're on Windows where the current directory is always searched
first for scripts, you'll probably do something like this:
perl Build.PL
Build
Build test
Build install
On the old Mac OS (version 9 or lower) using MacPerl, you can double-
click on the Build.PL script to create the Build script, then double-
click on the Build script to run its "build", "test", and "install"
actions.
The Build script knows what perl was used to run "Build.PL", so you
don't need to re-invoke the Build script with the complete perl path
each time. If you invoke it with the wrong perl path, you'll get a
warning or a fatal error.
Making a CPAN.pm-compatible distribution
New versions of CPAN.pm understand how to use a Build.PL script, but
old versions don't. If you want to help users who have old versions,
do the following:
Create a file in your distribution named Makefile.PL, with the follow-
ing contents:
use Module::Build::Compat;
Module::Build::Compat->run_build_pl(args => \@ARGV);
Module::Build::Compat->write_makefile();
Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make
test`, and `make install`, provided the end-user already has "Mod-
ule::Build" installed.
If the end-user might not have "Module::Build" installed, it's probably
best to supply a "traditional" Makefile.PL. The "Module::Build::Com-
pat" module has some very helpful tools for keeping a Makefile.PL in
sync with a Build.PL. See its documentation, and also the "cre-
ate_makefile_pl" parameter to the "Module::Build->new()" method.
Installing modules using the programmatic interface
If you need to build, test, and/or install modules from within some
other perl code (as opposed to having the user type installation com-
mands at the shell), you can use the programmatic interface. Create a
Module::Build object (or an object of a custom Module::Build subclass)
and then invoke its "dispatch()" method to run various actions.
my $build = Module::Build->new
(
module_name => 'Foo::Bar',
license => 'perl',
requires => { 'Some::Module' => '1.23' },
);
$build->dispatch('build');
$build->dispatch('test', verbose => 1);
$build->dispatch('install');
The first argument to "dispatch()" is the name of the action, and any
following arguments are named parameters.
This is the interface we use to test Module::Build itself in the
regression tests.
Installing to a temporary directory
To create packages for package managers like RedHat's "rpm" or Debian's
"deb", you may need to install to a temporary directory first and then
create the package from that temporary installation. To do this, spec-
ify the "destdir" parameter to the "install" action:
./Build install --destdir /tmp/my-package-1.003
This essentially just prepends all the installation paths with the
/tmp/my-package-1.003 directory.
Installing to a non-standard directory
To install to a non-standard directory (for example, if you don't have
permission to install in the system-wide directories), you can use the
"install_base":
./Build install --install_base /foo/bar
See "INSTALL PATHS" in Module::Build for a much more complete discus-
sion of how installation paths are determined.
Installing in the same location as ExtUtils::MakeMaker
With the introduction of "--prefix" in Module::Build 0.28 and
"INSTALL_BASE" in ExtUtils::MakeMaker 6.31 its easy to get them both to
install to the same locations.
First, ensure you have at least version 0.28 of Module::Build installed
and 6.31 of ExtUtils::MakeMaker. Prior versions have differing instal-
lation behaviors.
The following installation flags are equivalent between ExtUtils::Make-
Maker and Module::Build.
MakeMaker Module::Build
PREFIX=... --prefix ...
INSTALL_BASE=... --install_base ...
DESTDIR=... --destdir ...
LIB=... --install_path lib=...
INSTALLDIRS=... --installdirs ...
INSTALLDIRS=perl --installdirs core
UNINST=... --uninst ...
INC=... --extra_compiler_flags ...
POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
For example, if you are currently installing MakeMaker modules with
this command:
perl Makefile.PL PREFIX=~
make test
make install UNINST=1
You can install into the same location with Module::Build using this:
perl Build.PL --prefix ~
./Build test
./Build install --uninst 1
"prefix" vs "install_base"
The behavior of "prefix" is complicated and depends closely on how your
Perl is configured. The resulting installation locations will vary
from machine to machine and even different installations of Perl on the
same machine. Because of this, its difficult to document where "pre-
fix" will place your modules.
In contrast, "install_base" has predictable, easy to explain installa-
tion locations. Now that Module::Build and MakeMaker both have
"install_base" there is little reason to use "prefix" other than to
preserve your existing installation locations. If you are starting a
fresh Perl installation we encourage you to use "install_base". If you
have an existing installation installed via "prefix", consider moving
it to an installation structure matching "install_base" and using that
instead.
Running a single test file
"Module::Build" supports running a single test, which enables you to
track down errors more quickly. Use the following format:
./Build test --test_files t/mytest.t
In addition, you may want to run the test in verbose mode to get more
informative output:
./Build test --test_files t/mytest.t --verbose 1
I run this so frequently that I actually define the following shell
alias:
alias t './Build test --verbose 1 --test_files'
So then I can just execute "t t/mytest.t" to run a single test.
ADVANCED RECIPES
Changing the order of the build process
The "build_elements" property specifies the steps "Module::Build" will
take when building a distribution. To change the build order, change
the order of the entries in that property:
# Process pod files first
my @e = @{$build->build_elements};
my $i = grep {$e[$_] eq 'pod'} 0..$#e;
unshift @e, splice @e, $i, 1;
Currently, "build_elements" has the following default value:
[qw( PL support pm xs pod script )]
Do take care when altering this property, since there may be non-obvi-
ous (and non-documented!) ordering dependencies in the "Module::Build"
code.
Adding new file types to the build process
Sometimes you might have extra types of files that you want to install
alongside the standard types like .pm and .pod files. For instance,
you might have a Bar.dat file containing some data related to the
"Foo::Bar" module. Assuming the data doesn't need to be created on the
fly, the best place for it to end up is probably as Foo/Bar.dat some-
where in perl's @INC path so "Foo::Bar" can access it easily at run-
time. The following code from a sample "Build.PL" file demonstrates
how to accomplish this:
use Module::Build;
my $build = Module::Build->new
(
module_name => 'Foo::Bar',
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
This will find all .dat files in the lib/ directory, copy them to the
blib/lib/ directory during the "build" action, and install them during
the "install" action.
If your extra files aren't in the "lib/" directory, you can explicitly
say where they are, just as you'd do with .pm or .pod files:
use Module::Build;
my $build = new Module::Build
(
module_name => 'Foo::Bar',
dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
If your extra files actually need to be created on the user's machine,
or if they need some other kind of special processing, you'll probably
want to create a special method to do so, named
"process_${kind}_files()":
use Module::Build;
my $class = Module::Build->subclass(code => <<'EOF');
sub process_dat_files {
my $self = shift;
... locate and process *.dat files,
... and create something in blib/lib/
}
EOF
my $build = $class->new
(
module_name => 'Foo::Bar',
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
If your extra files don't go in lib/ but in some other place, see
"Adding new elements to the install process" for how to actually get
them installed.
Please note that these examples use some capabilities of Module::Build
that first appeared in version 0.26. Before that it could certainly
still be done, but the simple cases took a bit more work.
Adding new elements to the install process
By default, Module::Build creates seven subdirectories of the blib/
directory during the build process: lib/, arch/, bin/, script/,
bindoc/, libdoc/, and html/ (some of these may be missing or empty if
there's nothing to go in them). Anything copied to these directories
during the build will eventually be installed during the "install"
action (see "INSTALL PATHS" in Module::Build.
If you need to create a new type of installable element, e.g. "conf",
then you need to tell Module::Build where things in blib/conf/ should
be installed. To do this, use the "install_path" parameter to the
"new()" method:
my $build = Module::Build->new
(
...other stuff here...
install_path => { conf => $installation_path }
);
Or you can call the "install_path()" method later:
$build->install_path->{conf} || $installation_path;
(Sneakily, or perhaps uglily, "install_path()" returns a reference to a
hash of install paths, and you can modify that hash to your heart's
content.)
The user may also specify the path on the command line:
perl Build.PL --install_path conf=/foo/path/etc
The important part, though, is that somehow the install path needs to
be set, or else nothing in the blib/conf/ directory will get installed.
See also "Adding new file types to the build process" for how to create
the stuff in blib/conf/ in the first place.
EXAMPLES ON CPAN
Several distributions on CPAN are making good use of various features
of Module::Build. They can serve as real-world examples for others.
SVN-Notify-Mirror
<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
1. Using "auto_features", I check to see whether two optional modules
are available - SVN::Notify::Config and Net::SSH;
2. If the S::N::Config module is loaded, I automatically generate test-
files for it during Build (using the "PL_files" property).
3. If the "ssh_feature" is available, I ask if the user wishes to per-
form the ssh tests (since it requires a little preliminary setup);
4. Only if the user has "ssh_feature" and answers yes to the testing,
do I generate a test file.
I'm sure I could not have handled this complexity with EU::MM, but
it was very easy to do with M::B.
Modifying an action
Sometimes you might need an to have an action, say "./Build install",
do something unusual. For instance, you might need to change the own-
ership of a file or do something else peculiar to your application.
You can subclass "Module::Build" on the fly using the "subclass()"
method and override the methods that perform the actions. You may need
to read through "Module::Build::Authoring" to find the methods you want
to override, but the general pattern is "ACTION_" followed by the name
of the action you want to modify. Here's an example of how it would
work for "install":
# Build.PL
use Module::Build;
my $class = Module::Build->subclass(
class => "Module::Build::Custom",
code => <<'SUBCLASS' );
sub ACTION_install {
my $self = shift;
# YOUR CODE HERE
$self->SUPER::ACTION_install;
}
SUBCLASS
$class->new(
module_name => 'Your::Module',
# rest of the usual Module::Build parameters
)->create_build_script;
See the Module::Build::Authoring pod in 0.27 or above for more complete
documentation on this.
AUTHOR
Ken Williams <kwilliams@cpan.org>
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.
SEE ALSOperl(1), Module::Build(3), Module::Build::Authoring(3), Mod-
ule::Build::API(3)perl v5.8.8 2007-10-29 Module::Build::Cookbook(3)