view release on metacpan or  search on metacpan

local/lib/perl5/Module/Build/Cookbook.pm  view on Meta::CPAN

=head2 Modifying an action

Sometimes you might need an to have an action, say C<./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.

You can subclass C<Module::Build> on the fly using the C<subclass()>
method and override the methods that perform the actions.  You may
need to read through C<Module::Build::Authoring> and
C<Module::Build::API> to find the methods you want to override.  All
"action" methods are implemented by a method called "ACTION_" followed
by the action's name, so here's an example of how it would work for
the C<install> 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;


=head2 Adding an action

You can add a new C<./Build> action simply by writing the method for
it in your subclass.  Use C<depends_on> to declare that another action
must have been run before your action.

For example, let's say you wanted to be able to write C<./Build
commit> to test your code and commit it to Subversion.

  # Build.PL
  use Module::Build;
  my $class = Module::Build->subclass(
      class => "Module::Build::Custom",
      code => <<'SUBCLASS' );

  sub ACTION_commit {
      my $self = shift;

      $self->depends_on("test");
      $self->do_system(qw(svn commit));
  }
  SUBCLASS


=head2 Bundling Module::Build

Note: This section probably needs an update as the technology improves
(see contrib/bundle.pl in the distribution).

Suppose you want to use some new-ish features of Module::Build,
e.g. newer than the version of Module::Build your users are likely to
already have installed on their systems.  The first thing you should
do is set C<configure_requires> to your minimum version of
Module::Build.  See L<Module::Build::Authoring>.

But not every build system honors C<configure_requires> yet.  Here's
how you can ship a copy of Module::Build, but still use a newer
installed version to take advantage of any bug fixes and upgrades.

First, install Module::Build into F<Your-Project/inc/Module-Build>.
CPAN will not index anything in the F<inc> directory so this copy will
not show up in CPAN searches.

    cd Module-Build
    perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
    ./Build test
    ./Build install

You should now have all the Module::Build .pm files in
F<Your-Project/inc/Module-Build/lib/perl5>.

Next, add this to the top of your F<Build.PL>.

    my $Bundled_MB = 0.30;  # or whatever version it was.

    # Find out what version of Module::Build is installed or fail quietly.
    # This should be cross-platform.
    my $Installed_MB =
        `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1"`;

    # some operating systems put a newline at the end of every print.
    chomp $Installed_MB;

    $Installed_MB = 0 if $?;

    # Use our bundled copy of Module::Build if it's newer than the installed.
    unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;

    require Module::Build;

And write the rest of your F<Build.PL> normally.  Module::Build will
remember your change to C<@INC> and use it when you run F<./Build>.

In the future, we hope to provide a more automated solution for this
scenario; see C<inc/latest.pm> in the Module::Build distribution for
one indication of the direction we're moving.


=head1 AUTHOR

Ken Williams <kwilliams@cpan.org>


=head1 COPYRIGHT

Copyright (c) 2001-2008 Ken Williams.  All rights reserved.