Module::Build::Cookbook - Examples of Module::Build Usage
Module::Build isn't conceptually very complicated, but examples are always helpful. I got the idea for writing this cookbook when attending Brian Ingerson's "Extreme Programming Tools for Module Authors" presentation at YAPC 2003, when he said, straightforwardly, "Write A Cookbook."
Module::Build
The definitional of how stuff works is in the main Module::Build documentation. It's best to get familiar with that too.
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 directories 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.
build
test
install
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.
Build.PL
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 following 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 Module::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::Compat module has some very helpful tools for keeping a Makefile.PL in sync with a Build.PL. See its documentation, and also the create_makefile_pl parameter to the Module::Build->new() method.
Module::Build::Compat
create_makefile_pl
Module::Build->new()
If you need to build, test, and/or install modules from within some other perl code (as opposed to having the user type installation commands 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.
dispatch()
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.
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, specify the destdir parameter to the install action:
rpm
deb
destdir
./Build install --destdir /tmp/my-package-1.003
This essentially just prepends all the installation paths with the /tmp/my-package-1.003 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 or prefix parameters:
install_base
prefix
./Build install --install_base /foo/bar or ./Build install --prefix /foo/bar
Note that these have somewhat different effects - prefix is an emulation of ExtUtils::MakeMaker's old PREFIX setting, and inherits all its nasty gotchas. install_base is more predictable, and newer versions of ExtUtils::MakeMaker also support it, so it's often your best choice.
ExtUtils::MakeMaker
PREFIX
See "INSTALL PATHS" in Module::Build for a much more complete discussion of how installation paths are determined.
Module::Builde supports running a single test, which enables you to track down errors more quickly. Use the following format:
Module::Builde
./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.
t t/mytest.t
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:
build_elements
# 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-obvious (and non-documented!) ordering dependencies in the Module::Build code.
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 somewhere in perl's @INC path so Foo::Bar can access it easily at runtime. The following code from a sample Build.PL file demonstrates how to accomplish this:
Foo::Bar
@INC
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:
lib/
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():
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.
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:
conf
install_path
new()
my $build = Module::Build->new ( ...other stuff here... install_path => { conf => $installation_path } );
Or you can call the install_path() method later:
install_path()
$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.
Several distributions on CPAN are making good use of various features of Module::Build. They can serve as real-world examples for others.
http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/
John Peacock, author of the SVN-Notify-Mirror distribution, says:
SVN-Notify-Mirror
auto_features
PL_files
ssh_feature
I'm sure I could not have handled this complexity with EU::MM, but it was very easy to do with M::B.
Sometimes you might need an to have an action, say ./Build install, do something unusual. For instance, you might need to change the ownership of a file or do something else peculiar to your application.
./Build install
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:
subclass()
Module::Build::Authoring
ACTION_
# 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.
Ken Williams <ken@cpan.org>
Copyright (c) 2001-2005 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.
perl(1), Module::Build(3)
1 POD Error
The following errors were encountered while parsing the POD:
=back doesn't take any parameters, but you said =back 4
To install Module::Build, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Build
CPAN shell
perl -MCPAN -e shell install Module::Build
For more information on module installation, please visit the detailed CPAN module installation guide.