


Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


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

DESCRIPTION
       "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.

BASIC RECIPES
   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 Build.PL, then you're running a (newly-
       generated) script called 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 Build.PL script to create the
       Build script, then double-click on the Build script to run
       its "build", "test", and "install" actions.

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

   Modifying Config.pm values
       "Module::Build" relies heavily on various values from



perl v5.10.1                2009-10-12                          1





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


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

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

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

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

       In custom build code, the same thing can be accomplished
       by calling the "config" in Module::Build method:

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

   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 $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 "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.



perl v5.10.1                2009-10-12                          2





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


   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

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

   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 "install_base" or "prefix"
       parameters:

         ./Build install --install_base /foo/bar

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

   Installing in the same location as ExtUtils::MakeMaker
       With the introduction of "--prefix" in Module::Build 0.28
       and "INSTALL_BASE" in "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 "ExtUtils::MakeMaker".
       Prior versions have differing (and in some cases quite
       strange) installation behaviors.

       The following installation flags are equivalent between
       "ExtUtils::MakeMaker" and "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 "MakeMaker"
       modules with this command:

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



perl v5.10.1                2009-10-12                          3





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


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

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

       "prefix" vs "install_base"

       The behavior of "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 "prefix"
       will place your modules.

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

   Running a single test file
       "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 "t t/mytest.t" to run a single
       test.

ADVANCED RECIPES
   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 authors want to help
       users who have old versions, some form of Makefile.PL
       should be supplied.  The easiest way to accomplish this is
       to use the "create_makefile_pl" parameter to



perl v5.10.1                2009-10-12                          4





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


       "Module::Build->new()" in the "Build.PL" script, which can
       create various flavors of Makefile.PL during the "dist"
       action.

       As a best practice, we recommend using the "traditional"
       style of Makefile.PL unless your distribution has needs
       that can't be accomplished that way.

       The "Module::Build::Compat" module, which is part of
       "Module::Build"'s distribution, is responsible for
       creating these Makefile.PLs.  Please see
       Module::Build::Compat for the details.

   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 file types to the build process
       Sometimes you might have extra types of files that you
       want to install alongside the standard types like .pm and
       .pod files.  For instance, you might have a Bar.dat file
       containing some data related to the "Foo::Bar" module and
       you'd like for it to end up as Foo/Bar.dat somewhere in
       perl's @INC path so "Foo::Bar" can access it easily at
       runtime.  The following code from a sample "Build.PL" file
       demonstrates how to accomplish this:

         use Module::Build;
         my $build = Module::Build->new
           (
            module_name => 'Foo::Bar',
            ...other stuff here...
           );
         $build->add_build_element('dat');
         $build->create_build_script;

       This will find all .dat files in the lib/ directory, copy
       them to the blib/lib/ directory during the "build" action,



perl v5.10.1                2009-10-12                          5





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


       and install them during the "install" action.

       If your extra files aren't located in the "lib/" directory
       in your distribution, you can explicitly say where they
       are, just as you'd do with .pm or .pod files:

         use Module::Build;
         my $build = new Module::Build
           (
            module_name => 'Foo::Bar',
            dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
            ...other stuff here...
           );
         $build->add_build_element('dat');
         $build->create_build_script;

       If your extra files actually need to be created on the
       user's machine, or if they need some other kind of special
       processing, you'll probably want to subclass
       "Module::Build" and create a special method to process
       them, named "process_${kind}_files()":

         use Module::Build;
         my $class = Module::Build->subclass(code => <<'EOF');
           sub process_dat_files {
             my $self = shift;
             ... locate and process *.dat files,
             ... and create something in blib/lib/
           }
         EOF
         my $build = $class->new
           (
            module_name => 'Foo::Bar',
            ...other stuff here...
           );
         $build->add_build_element('dat');
         $build->create_build_script;

       If your extra files don't go in lib/ but in some other
       place, see "Adding new elements to the install process"
       for how to actually get them installed.

       Please note that these examples use some capabilities of
       Module::Build that first appeared in version 0.26.  Before
       that it could still be done, but the simple cases took a
       bit more work.

   Adding new elements to the install process
       By default, Module::Build creates seven subdirectories of
       the blib directory during the build process: lib, arch,
       bin, script, bindoc, libdoc, and html (some of these may
       be missing or empty if there's nothing to go in them).
       Anything copied to these directories during the build will
       eventually be installed during the "install" action (see



perl v5.10.1                2009-10-12                          6





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


       "INSTALL PATHS" in Module::Build.

       If you need to create a new custom type of installable
       element, e.g. "conf", then you need to tell Module::Build
       where things in blib/conf/ should be installed.  To do
       this, use the "install_path" parameter to the "new()"
       method:

         my $build = Module::Build->new
           (
            ...other stuff here...
            install_path => { conf => $installation_path }
           );

       Or you can call the "install_path()" method later:

         $build->install_path(conf => $installation_path);

       The user may also specify the path on the command line:

         perl Build.PL --install_path conf=/foo/path/etc

       The important part, though, is that somehow the install
       path needs to be set, or else nothing in the blib/conf/
       directory will get installed, and a runtime error during
       the "install" action will result.

       See also "Adding new file types to the build process" for
       how to create the stuff in blib/conf/ in the first place.

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.

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

       John Peacock, author of the "SVN-Notify-Mirror"
       distribution, says:

       1. Using "auto_features", I check to see whether two
       optional modules are available - SVN::Notify::Config and
       Net::SSH;
       2. If the S::N::Config module is loaded, I automatically
       generate test files for it during Build (using the
       "PL_files" property).
       3. If the "ssh_feature" is available, I ask if the user
       wishes to perform the ssh tests (since it requires a
       little preliminary setup);
       4. Only if the user has "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.



perl v5.10.1                2009-10-12                          7





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


   Modifying an action
       Sometimes you might need an to have an action, say
       "./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 "Module::Build" on the fly using the
       "subclass()" method and override the methods that perform
       the actions.  You may need to read through
       "Module::Build::Authoring" and "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 "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;

   Adding an action
       You can add a new "./Build" action simply by writing the
       method for it in your subclass.  Use "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
       "./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));



perl v5.10.1                2009-10-12                          8





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


         }
         SUBCLASS

   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 "configure_requires" to your minimum version of
       Module::Build.  See Module::Build::Authoring.

       But not every build system honors "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
       Your-Project/inc/Module-Build.  CPAN will not index
       anything in the 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
       Your-Project/inc/Module-Build/lib/perl5.

       Next, add this to the top of your 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 Build.PL normally.
       Module::Build will remember your change to @INC and use it



perl v5.10.1                2009-10-12                          9





Module::Build::CoPerloProgrammers RefeModule::Build::Cookbook(3p)


       when you run ./Build.

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

AUTHOR
       Ken Williams <kwilliams@cpan.org>

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

       This library is free software; you can redistribute it
       and/or modify it under the same terms as Perl itself.

SEE ALSO
       perl(1), Module::Build(3), Module::Build::Authoring(3),
       Module::Build::API(3)





































perl v5.10.1                2009-10-12                         10


