|
|
Module::Build::Authoring - Authoring Module::Build modules
When creating a Build.PL script for a module, something like the
following 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
whatever.
For information on providing compatibility with
ExtUtils::MakeMaker, see the Module::Build::Compat manpage and
http://www.makemaker.org/wiki/index.cgi.
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.)
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 Module::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
create_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
creating 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 the Module::Build::API manpage method.
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 modules 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.
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 separated by commas,
and all criteria must be satisfied.
A special perl entry lets you specify the versions of the Perl
interpreter 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.
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 provides a command line interface
to this same functionality. See also the generated
Foo::Bar::ConfigData documentation, and the config_data
script's documentation, for more information.
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-creators 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
ExtUtils::ModuleMaker, Module::Starter, and Module::Maker.
They have varying degrees of support for Module::Build.
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 exception.
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.
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.
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 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
perl(1), the Module::Build manpage(3), the Module::Build::API manpage(3), the Module::Build::Cookbook manpage(3), the ExtUtils::MakeMaker manpage(3), the YAML manpage(3)
META.yml Specification: http://module-build.sourceforge.net/META-spec-current.html