view release on metacpan or  search on metacpan

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

create the stuff in F<blib/conf/> in the first place.


=head1 EXAMPLES ON CPAN

Several distributions on CPAN are making good use of various features
of Module::Build.  They can serve as real-world examples for others.


=head2 SVN-Notify-Mirror

L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>

John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:

=over 4

=item 1. Using C<auto_features>, I check to see whether two optional
modules are available - SVN::Notify::Config and Net::SSH;

=item 2. If the S::N::Config module is loaded, I automatically
generate test files for it during Build (using the C<PL_files>
property).

=item 3. If the C<ssh_feature> is available, I ask if the user wishes
to perform the ssh tests (since it requires a little preliminary
setup);

=item 4. Only if the user has C<ssh_feature> and answers yes to the
testing, do I generate a test file.

I'm sure I could not have handled this complexity with EU::MM, but it
was very easy to do with M::B.

=back


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