Module::Build::Authoring - Authoring Module::Build modules


NAME

Module::Build::Authoring - Authoring Module::Build modules

Back to Top


DESCRIPTION

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.

Back to Top


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.)

Back to Top


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 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 propagated to the Build script, so that My::Builder can be found when running build actions. If you find that you need to chdir into a different directories in your subclass methods or actions, be sure to always return to the original directory (available via the base_dir() method before returning control to the parent class. This is important to avoid data serialization problems.

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.

Back to Top


PREREQUISITES

Types of prerequisites

To specify what versions of other modules are used by this distribution, several types of prerequisites can be defined with the following parameters:

configure_requires

Items that must be installed before configuring this distribution (i.e. before running the Build.PL script). This might be a spe0