NAME

Module::Build::Cookbook - Examples of Module::Build Usage

DESCRIPTION

Module::Build isn't conceptually very complicated, but examples are always helpful. I got the idea for writing this cookbook when attending Brian Ingerson's "Extreme Programming Tools for Module Authors" presentation at YAPC 2003, when he said, straightforwardly, "Write A Cookbook."

The definitional of how stuff works is in the main Module::Build documentation. It's best to get familiar with that too.

BASIC RECIPES

The basic installation recipe for modules that use Module::Build

In most cases, you can just issue the following commands from your shell:

 perl Build.PL
 Build
 Build test
 Build install

There's nothing complicated here - first you're running a script called Build.PL, then you're running a (newly-generated) script called Build and passing it various arguments. If you know how to do that on your system, you can get installation working.

The exact commands may vary a bit depending on how you invoke perl scripts on your system. For instance, if you have multiple versions of perl installed, you can install to one particular perl's library directories like so:

 /usr/bin/perl5.8.1 Build.PL
 Build
 Build test
 Build install

The Build script knows what perl was used to run Build.PL, so you don't need to reinvoke the Build script with the complete perl path each time. If you invoke it with the wrong perl path, you'll get a warning.

If the current directory (usually called '.') isn't in your path, you can do ./Build or perl Build to run the script:

 /usr/bin/perl Build.PL
 ./Build
 ./Build test
 ./Build install

Making a CPAN.pm-compatible distribution

New versions of CPAN.pm understand how to use a Build.PL script, but old versions don't. If you want to help users who have old versions, do the following:

Create a file in your distribution named Makefile.PL, with the following contents:

 use Module::Build::Compat;
 Module::Build::Compat->run_build_pl(args => \@ARGV);
 Module::Build::Compat->write_makefile();

Now CPAN will work as usual, ie: `perl Makefile.PL`, `make`, `make test`, and `make install`.

Alternatively, see the create_makefile_pl parameter to the Module::Build->new() method.

Installing modules using the programmatic interface

If you need to build, test, and/or install modules from within some other perl code (as opposed to having the user type installation commands at the shell), you can use the programmatic interface. Create a Module::Build object (or an object of a custom Module::Build subclass) and then invoke its dispatch() method to run various actions.

 my $b = Module::Build->new(
   module_name => 'Foo::Bar',
   license => 'perl',
   requires => { 'Some::Module'   => '1.23' },
 );
 $b->dispatch('build');
 $b->dispatch('test', verbose => 1);
 $b->dispatch('install');

The first argument to dispatch() is the name of the action, and any following arguments are named parameters.

This is the interface we use to test Module::Build itself in the regression tests.

Installing to a temporary directory

To create packages for package managers like RedHat's rpm or Debian's deb, you may need to install to a temporary directory first and then create the package from that temporary installation. To do this, specify the destdir parameter to the install action:

 Build install destdir=/tmp/my-package-1.003

ADVANCED RECIPES

Adding new elements to the build process

If there's some new type of file (i.e. not a .pm file, or .xs file, or one of the other things Module::Build knows how to process) that you'd like to handle during the building of your module, you can do something the following in your Build.PL file:

  use Module::Build;
  
  my $class = Module::Build->subclass( code => <<'EOC' );
    sub process_foo_files {
      my $self = shift;
      ... locate and process foo files, and create something in blib/
    }
  }
  
  my $build = $class->new( ... );
  
  $build->add_build_element('foo');

This creates a custom subclass of Module::Build that knows how to build elements of type foo. It should place the elements in a subdirectory of blib/ corresponding to items that Module::Build knows how to install - to add new capabilities in that arena, see "Adding new types to the install process".

Changing the order of the build process

The build_elements property specifies the steps Module::Build will take when building a distribution. To change the build order, change the order of the entries in that property:

 # Process pod files first
 my @e = @{$build->build_elements};
 my $i = grep {$e[$_] eq 'pod'} 0..$#e;
 unshift @e, splice @e, $i, 1;

Currently, build_elements has the following default value:

  [qw( PL support pm xs pod script )]

Do take care when altering this property, since there may be non-obvious (and non-documented!) ordering dependencies in the Module::Build code.

Adding new types to the install process

... more to come ...

AUTHOR

Ken Williams, ken@mathforum.org

SEE ALSO

perl(1), Module::Build(3)

cpanm Module::Build

perl -MCPAN -e shell
install Module::Build