view release on metacpan or  search on metacpan

inc/inc_Module-Build/Module/Build/Cookbook.pm  view on Meta::CPAN

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

=head1 DESCRIPTION

C<Module::Build> isn't conceptually very complicated, but examples are
always helpful.  The following recipes should help developers and/or
installers put together the pieces from the other parts of the
documentation.


=head1 BASIC RECIPES


=head2 Installing modules that use Module::Build

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

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

There's nothing complicated here - first you're running a script
called F<Build.PL>, then you're running a (newly-generated) script
called F<Build> and passing it various arguments.

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

If you're on Windows where the current directory is always searched
first for scripts, you'll probably do something like this:

  perl Build.PL
  Build
  Build test
  Build install

On the old Mac OS (version 9 or lower) using MacPerl, you can
double-click on the F<Build.PL> script to create the F<Build> script,
then double-click on the F<Build> script to run its C<build>, C<test>,
and C<install> actions.

The F<Build> script knows what perl was used to run F<Build.PL>, so
you don't need to re-invoke the F<Build> script with the complete perl
path each time.  If you invoke it with the I<wrong> perl path, you'll
get a warning or a fatal error.

=head2 Modifying Config.pm values

C<Module::Build> relies heavily on various values from perl's
C<Config.pm> to do its work.  For example, default installation paths
are given by C<installsitelib> and C<installvendorman3dir> and
friends, C linker & compiler settings are given by C<ld>,
C<lddlflags>, C<cc>, C<ccflags>, and so on.  I<If you're pretty sure
you know what you're doing>, you can tell C<Module::Build> to pretend
there are different values in F<Config.pm> than what's really there,
by passing arguments for the C<--config> parameter on the command
line:

  perl Build.PL --config cc=gcc --config ld=gcc

Inside the C<Build.PL> script the same thing can be accomplished by
passing values for the C<config> parameter to C<new()>:

 my $build = Module::Build->new
   (
    ...
    config => { cc => 'gcc', ld => 'gcc' },
    ...
   );

In custom build code, the same thing can be accomplished by calling
the L<Module::Build/config> method:

 $build->config( cc => 'gcc' );     # Set
 $build->config( ld => 'gcc' );     # Set
 ...
 my $linker = $build->config('ld'); # Get


=head2 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 C<dispatch()> method to run various
actions.

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

The first argument to C<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.


=head2 Installing to a temporary directory

To create packages for package managers like RedHat's C<rpm> or
Debian's C<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 C<destdir> parameter to the C<install> action:

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

This essentially just prepends all the installation paths with the
F</tmp/my-package-1.003> directory.


=head2 Installing to a non-standard directory

To install to a non-standard directory (for example, if you don't have
permission to install in the system-wide directories), you can use the
C<install_base> or C<prefix> parameters:

  ./Build install --install_base /foo/bar

See L<Module::Build/"INSTALL PATHS"> for a much more complete
discussion of how installation paths are determined.


=head2 Installing in the same location as ExtUtils::MakeMaker

With the introduction of C<--prefix> in Module::Build 0.28 and
C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both
to install to the same locations.

First, ensure you have at least version 0.28 of Module::Build
installed and 6.31 of C<ExtUtils::MakeMaker>.  Prior versions have
differing (and in some cases quite strange) installation behaviors.

The following installation flags are equivalent between
C<ExtUtils::MakeMaker> and C<Module::Build>.

    MakeMaker             Module::Build
    PREFIX=...            --prefix ...
    INSTALL_BASE=...      --install_base ...
    DESTDIR=...           --destdir ...
    LIB=...               --install_path lib=...
    INSTALLDIRS=...       --installdirs ...
    INSTALLDIRS=perl      --installdirs core
    UNINST=...            --uninst ...
    INC=...               --extra_compiler_flags ...
    POLLUTE=1             --extra_compiler_flags -DPERL_POLLUTE

For example, if you are currently installing C<MakeMaker> modules with
this command:

    perl Makefile.PL PREFIX=~
    make test
    make install UNINST=1

You can install into the same location with Module::Build using this:

    perl Build.PL --prefix ~
    ./Build test
    ./Build install --uninst 1

=head3 C<prefix> vs C<install_base>

The behavior of C<prefix> is complicated and depends on
how your Perl is configured.  The resulting installation locations
will vary from machine to machine and even different installations of
Perl on the same machine.  Because of this, it's difficult to document
where C<prefix> will place your modules.

In contrast, C<install_base> has predictable, easy to explain
installation locations.  Now that C<Module::Build> and C<MakeMaker> both
have C<install_base> there is little reason to use C<prefix> other
than to preserve your existing installation locations.  If you are
starting a fresh Perl installation we encourage you to use
C<install_base>.  If you have an existing installation installed via
C<prefix>, consider moving it to an installation structure matching
C<install_base> and using that instead.


=head2 Running a single test file

C<Module::Build> supports running a single test, which enables you to
track down errors more quickly.  Use the following format:

  ./Build test --test_files t/mytest.t

In addition, you may want to run the test in verbose mode to get more
informative output:

  ./Build test --test_files t/mytest.t --verbose 1

I run this so frequently that I define the following shell alias:

  alias t './Build test --verbose 1 --test_files'

So then I can just execute C<t t/mytest.t> to run a single test.


=head1 ADVANCED RECIPES


=head2 Making a CPAN.pm-compatible distribution

New versions of CPAN.pm understand how to use a F<Build.PL> script,
but old versions don't.  If authors want to help users who have old
versions, some form of F<Makefile.PL> should be supplied.  The easiest
way to accomplish this is to use the C<create_makefile_pl> parameter to