Module::Build::AuthoriUser)Contributed Perl DocumenModule::Build::Authoring(3)NAMEModule::Build::Authoring - Authoring Module::Build modules
DESCRIPTION
When creating a "Build.PL" script for a module, something like the fol-
lowing code will typically be used:
use Module::Build;
my $build = Module::Build->new
(
module_name => 'Foo::Bar',
license => 'perl',
requires => {
'perl' => '5.6.1',
'Some::Module' => '1.23',
'Other::Module' => '>= 1.2, != 1.5, < 2.0',
},
);
$build->create_build_script;
A simple module could get away with something as short as this for its
"Build.PL" script:
use Module::Build;
Module::Build->new(
module_name => 'Foo::Bar',
license => 'perl',
)->create_build_script;
The model used by "Module::Build" is a lot like the "MakeMaker"
metaphor, with the following correspondences:
In Module::Build In ExtUtils::MakeMaker
---------------------------------------------------
Build.PL (initial script) Makefile.PL (initial script)
Build (a short perl script) Makefile (a long Makefile)
_build/ (saved state info) various config text in the Makefile
Any customization can be done simply by subclassing "Module::Build" and
adding a method called (for example) "ACTION_test", overriding the
default 'test' action. You could also add a method called
"ACTION_whatever", and then you could perform the action "Build what-
ever".
For information on providing compatibility with "ExtUtils::MakeMaker",
see Module::Build::Compat and <http://www.make-
maker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
STRUCTURE
Module::Build creates a class hierarchy conducive to customization.
Here is the parent-child class hierarchy in classy ASCII art:
/--------------------\
| Your::Parent | (If you subclass Module::Build)
\--------------------/
|
|
/--------------------\ (Doesn't define any functionality
| Module::Build | of its own - just figures out what
\--------------------/ other modules to load.)
|
|
/-----------------------------------\ (Some values of $^O may
| Module::Build::Platform::$^O | define specialized functionality.
\-----------------------------------/ Otherwise it's ...::Default, a
| pass-through class.)
|
/--------------------------\
| Module::Build::Base | (Most of the functionality of
\--------------------------/ Module::Build is defined here.)
SUBCLASSING
Right now, there are two ways to subclass Module::Build. The first way
is to create a regular module (in a ".pm" file) that inherits from Mod-
ule::Build, and use that module's class instead of using Module::Build
directly:
------ in Build.PL: ----------
#!/usr/bin/perl
use lib q(/nonstandard/library/path);
use My::Builder; # Or whatever you want to call it
my $build = My::Builder->new
(
module_name => 'Foo::Bar', # All the regular args...
license => 'perl',
dist_author => 'A N Other <me@here.net.au>',
requires => { Carp => 0 }
);
$build->create_build_script;
This is relatively straightforward, and is the best way to do things if
your My::Builder class contains lots of code. The "cre-
ate_build_script()" method will ensure that the current value of @INC
(including the "/nonstandard/library/path") is propogated to the Build
script, so that My::Builder can be found when running build actions.
For very small additions, Module::Build provides a "subclass()" method
that lets you subclass Module::Build more conveniently, without creat-
ing a separate file for your module:
------ in Build.PL: ----------
#!/usr/bin/perl
use Module::Build;
my $class = Module::Build->subclass
(
class => 'My::Builder',
code => q{
sub ACTION_foo {
print "I'm fooing to death!\n";
}
},
);
my $build = $class->new
(
module_name => 'Foo::Bar', # All the regular args...
license => 'perl',
dist_author => 'A N Other <me@here.net.au>',
requires => { Carp => 0 }
);
$build->create_build_script;
Behind the scenes, this actually does create a ".pm" file, since the
code you provide must persist after Build.PL is run if it is to be very
useful.
See also the documentation for the "subclass()" in Module::Build::API
method.
PREREQUISITES
There are three basic types of prerequisites that can be defined: 1)
"requires" - are versions of modules that are required for certain
functionality to be available; 2) "recommends" - are versions of mod-
ules that are recommended to provide enhanced functionality; and 3)
"conflicts" - are versions of modules that conflict with, and that can
cause problems with the distribution.
Each of the three types of prerequisites listed above can be applied to
different aspects of the Build process. For the module distribution
itself you simply define "requires", "recommends", or "conflicts". The
types can also apply to other aspects of the Build process. Currently,
only "build_requires" is defined which is used for modules which are
required during the Build process.
Format of prerequisites
The prerequisites are given in a hash reference, where the keys are the
module names and the values are version specifiers:
requires => {
Foo::Module => '2.4',
Bar::Module => 0,
Ken::Module => '>= 1.2, != 1.5, < 2.0',
perl => '5.6.0'
},
These four version specifiers have different effects. The value '2.4'
means that at least version 2.4 of "Foo::Module" must be installed.
The value 0 means that any version of "Bar::Module" is acceptable, even
if "Bar::Module" doesn't define a version. The more verbose value '>=
1.2, != 1.5, < 2.0' means that "Ken::Module"'s version must be at least
1.2, less than 2.0, and not equal to 1.5. The list of criteria is sep-
arated by commas, and all criteria must be satisfied.
A special "perl" entry lets you specify the versions of the Perl inter-
preter that are supported by your module. The same version dependency-
checking semantics are available, except that we also understand perl's
new double-dotted version numbers.
SAVING CONFIGURATION INFORMATION
Module::Build provides a very convenient way to save configuration
information that your installed modules (or your regression tests) can
access. If your Build process calls the "feature()" or "config_data()"
methods, then a "Foo::Bar::ConfigData" module will automatically be
created for you, where "Foo::Bar" is the "module_name" parameter as
passed to "new()". This module provides access to the data saved by
these methods, and a way to update the values. There is also a utility
script called "config_data" distributed with Module::Build that pro-
vides a command line interface to this same functionality. See also
the generated "Foo::Bar::ConfigData" documentation, and the "con-
fig_data" script's documentation, for more information.
STARTING MODULE DEVELOPMENT
When starting development on a new module, it's rarely worth your time
to create a tree of all the files by hand. Some automatic module-cre-
ators are available: the oldest is "h2xs", which has shipped with perl
itself for a long time. Its name reflects the fact that modules were
originally conceived of as a way to wrap up a C library (thus the "h"
part) into perl extensions (thus the "xs" part).
These days, "h2xs" has largely been superseded by modules like "ExtU-
tils::ModuleMaker", "Module::Starter", and "Module::Maker". They have
varying degrees of support for "Module::Build".
AUTOMATION
One advantage of Module::Build is that since it's implemented as Perl
methods, you can invoke these methods directly if you want to install a
module non-interactively. For instance, the following Perl script will
invoke the entire build/install procedure:
my $build = Module::Build->new(module_name => 'MyModule');
$build->dispatch('build');
$build->dispatch('test');
$build->dispatch('install');
If any of these steps encounters an error, it will throw a fatal excep-
tion.
You can also pass arguments as part of the build process:
my $build = Module::Build->new(module_name => 'MyModule');
$build->dispatch('build');
$build->dispatch('test', verbose => 1);
$build->dispatch('install', sitelib => '/my/secret/place/');
Building and installing modules in this way skips creating the "Build"
script.
MIGRATION
Note that if you want to provide both a Makefile.PL and a Build.PL for
your distribution, you probably want to add the following to
"WriteMakefile" in your Makefile.PL so that MakeMaker doesn't try to
run your Build.PL as a normal .PL file:
PL_FILES => {},
You may also be interested in looking at the "Module::Build::Compat"
module, which can automatically create various kinds of Makefile.PL
compatibility layers.
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 Subversion reposi-
tory at <https://svn.perl.org/modules/Module-Build/trunk/>
SEE ALSOperl(1), Module::Build(3), Module::Build::API(3), Module::Build::Cook-
book(3), ExtUtils::MakeMaker(3), YAML(3)
META.yml Specification: <http://module-build.source-
forge.net/META-spec-current.html>
<http://www.dsmit.com/cons/>
<http://search.cpan.org/dist/PerlBuildSystem/>
perl v5.8.8 2007-10-29 Module::Build::Authoring(3)
