view release on metacpan or  search on metacpan

inc/inc_Module-Build/Module/Build/Authoring.pod  view on Meta::CPAN

=head1 NAME

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

=head1 DESCRIPTION

When creating a C<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
C<Build.PL> script:

  use Module::Build;
  Module::Build->new(
    module_name => 'Foo::Bar',
    license     => 'perl',
  )->create_build_script;

The model used by C<Module::Build> is a lot like the C<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 C<Module::Build>
and adding a method called (for example) C<ACTION_test>, overriding
the default 'test' action.  You could also add a method called
C<ACTION_whatever>, and then you could perform the action C<Build
whatever>.

For information on providing compatibility with
C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.


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


=head1 SUBCLASSING

Right now, there are two ways to subclass Module::Build.  The first
way is to create a regular module (in a C<.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
C<create_build_script()> method will ensure that the current value of
C<@INC> (including the C</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 C<chdir> into a different directories
in your subclass methods or actions, be sure to always return to the original
directory (available via the C<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 C<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 C<.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 L<Module::Build::API/"subclass()">
method.


=head1 PREREQUISITES

=head2 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:

=over 3

=item configure_requires

Items that must be installed I<before> configuring this distribution
(i.e. before running the F<Build.PL> script).  This might be a
specific minimum version of C<Module::Build> or any other module the
F<Build.PL> needs in order to do its stuff.  Clients like C<CPAN.pm>
or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
F<META.yml> file and install these items before running the
C<Build.PL>.

If no configure_requires is specified, the current version of Module::Build
is automatically added to configure_requires.

=item build_requires