package Module::Build::Cookbook;=head1 NAMEModule::Build::Cookbook - Examples of Module::Build Usage=head1 DESCRIPTIONC<Module::Build> isn't conceptually very complicated, but examples arealways helpful.  The following recipes should help developers and/orinstallers put together the pieces from the other parts of thedocumentation.=head1 BASIC RECIPES=head2 Installing modules that use Module::BuildIn most cases, you can just issue the following commands:  perl Build.PL  ./Build  ./Build test  ./Build installThere's nothing complicated here - first you're running a scriptcalled F<Build.PL>, then you're running a (newly-generated) scriptcalled F<Build> and passing it various arguments.The exact commands may vary a bit depending on how you invoke perlscripts on your system.  For instance, if you have multiple versionsof perl installed, you can install to one particular perl's librarydirectories like so:  /usr/bin/perl5.8.1 Build.PL  ./Build  ./Build test  ./Build installIf you're on Windows where the current directory is always searchedfirst for scripts, you'll probably do something like this:  perl Build.PL  Build  Build test  Build installOn the old Mac OS (version 9 or lower) using MacPerl, you candouble-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>, soyou don't need to re-invoke the F<Build> script with the complete perlpath each time.  If you invoke it with the I<wrong> perl path, you'llget a warning or a fatal error.=head2 Modifying Config.pm valuesC<Module::Build> relies heavily on various values from perl'sC<Config.pm> to do its work.  For example, default installation pathsare given by C<installsitelib> and C<installvendorman3dir> andfriends, C linker & compiler settings are given by C<ld>,C<lddlflags>, C<cc>, C<ccflags>, and so on.  I<If you're pretty sureyou know what you're doing>, you can tell C<Module::Build> to pretendthere are different values in F<Config.pm> than what's really there,by passing arguments for the C<--config> parameter on the commandline:  perl Build.PL --config cc=gcc --config ld=gccInside the C<Build.PL> script the same thing can be accomplished bypassing 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 callingthe 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 interfaceIf you need to build, test, and/or install modules from within someother perl code (as opposed to having the user type installationcommands at the shell), you can use the programmatic interface.Create a Module::Build object (or an object of a custom Module::Buildsubclass) and then invoke its C<dispatch()> method to run variousactions.  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 anyfollowing arguments are named parameters.This is the interface we use to test Module::Build itself in theregression tests.=head2 Installing to a temporary directoryTo create packages for package managers like RedHat's C<rpm> orDebian's C<deb>, you may need to install to a temporary directoryfirst 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.003This essentially just prepends all the installation paths with theF</tmp/my-package-1.003> directory.=head2 Installing to a non-standard directoryTo install to a non-standard directory (for example, if you don't havepermission to install in the system-wide directories), you can use theC<install_base> or C<prefix> parameters:  ./Build install --install_base /foo/barSee L<Module::Build/"INSTALL PATHS"> for a much more completediscussion of how installation paths are determined.=head2 Installing in the same location as ExtUtils::MakeMakerWith the introduction of C<--prefix> in Module::Build 0.28 andC<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them bothto install to the same locations.First, ensure you have at least version 0.28 of Module::Buildinstalled and 6.31 of ExtUtils::MakeMaker.  Prior versions havediffering (and in some cases quite strange) installation behaviors.The following installation flags are equivalent betweenExtUtils::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_POLLUTEFor example, if you are currently installing MakeMaker modules withthis command:    perl Makefile.PL PREFIX=~    make test    make install UNINST=1You 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 onhow your Perl is configured.  The resulting installation locationswill vary from machine to machine and even different installations ofPerl on the same machine.  Because of this, it's difficult to documentwhere C<prefix> will place your modules.In contrast, C<install_base> has predictable, easy to explaininstallation locations.  Now that Module::Build and MakeMaker bothhave C<install_base> there is little reason to use C<prefix> otherthan to preserve your existing installation locations.  If you arestarting a fresh Perl installation we encourage you to useC<install_base>.  If you have an existing installation installed viaC<prefix>, consider moving it to an installation structure matchingC<install_base> and using that instead.=head2 Running a single test fileC<Module::Build> supports running a single test, which enables you totrack down errors more quickly.  Use the following format:  ./Build test --test_files t/mytest.tIn addition, you may want to run the test in verbose mode to get moreinformative output:  ./Build test --test_files t/mytest.t --verbose 1I 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 distributionNew 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 oldversions, some form of F<Makefile.PL> should be supplied.  The easiestway to accomplish this is to use the C<create_makefile_pl> parameter toC<< Module::Build->new() >> in the C<Build.PL> script, which cancreate various flavors of F<Makefile.PL> during the C<dist> action.As a best practice, we recommend using the "traditional" style ofF<Makefile.PL> unless your distribution has needs that can't beaccomplished that way.The C<Module::Build::Compat> module, which is part ofC<Module::Build>'s distribution, is responsible for creating theseF<Makefile.PL>s.  Please see L<Module::Build::Compat> for the details.=head2 Changing the order of the build processThe C<build_elements> property specifies the steps C<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, C<build_elements> has the following default value:  [qw( PL support pm xs pod script )]Do take care when altering this property, since there may benon-obvious (and non-documented!) ordering dependencies in theC<Module::Build> code.=head2 Adding new file types to the build processSometimes you might have extra types of files that you want to installalongside the standard types like F<.pm> and F<.pod> files.  Forinstance, you might have a F<Bar.dat> file containing some datarelated to the C<Foo::Bar> module and you'd like for it to end up asF<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> canaccess it easily at runtime.  The following code from a sampleC<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 F<.dat> files in the F<lib/> directory, copy themto the F<blib/lib/> directory during the C<build> action, and installthem during the C<install> action.If your extra files aren't located in the C<lib/> directory in yourdistribution, you can explicitly say where they are, just as you'd dowith F<.pm> or F<.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 probablywant to subclass C<Module::Build> and create a special method toprocess them, named C<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 F<lib/> but in some other place, seeL<"Adding new elements to the install process"> for how to actuallyget them installed.Please note that these examples use some capabilities of Module::Buildthat first appeared in version 0.26.  Before that it couldstill be done, but the simple cases took a bit more work.=head2 Adding new elements to the install processBy default, Module::Build creates seven subdirectories of the F<blib>directory during the build process: F<lib>, F<arch>, F<bin>,F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may bemissing or empty if there's nothing to go in them).  Anything copiedto these directories during the build will eventually be installedduring the C<install> action (see L<Module::Build/"INSTALL PATHS">.If you need to create a new custom type of installable element, e.g. C<conf>,then you need to tell Module::Build where things in F<blib/conf/>should be installed.  To do this, use the C<install_path> parameter tothe C<new()> method:  my $build = Module::Build->new    (     ...other stuff here...     install_path => { conf => $installation_path }    );Or you can call the C<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/etcThe important part, though, is that I<somehow> the install path needsto be set, or else nothing in the F<blib/conf/> directory will getinstalled, and a runtime error during the C<install> action willresult.See also L<"Adding new file types to the build process"> for how tocreate the stuff in F<blib/conf/> in the first place.=head1 EXAMPLES ON CPANSeveral distributions on CPAN are making good use of various featuresof Module::Build.  They can serve as real-world examples for others.=head2 SVN-Notify-MirrorL<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 optionalmodules are available - SVN::Notify::Config and Net::SSH;=item 2. If the S::N::Config module is loaded, I automaticallygenerate testfiles for it during Build (using the C<PL_files>property).=item 3. If the C<ssh_feature> is available, I ask if the user wishesto perform the ssh tests (since it requires a little preliminarysetup);=item 4. Only if the user has C<ssh_feature> and answers yes to thetesting, do I generate a test file.I'm sure I could not have handled this complexity with EU::MM, but itwas very easy to do with M::B.=back 4=head2 Modifying an actionSometimes you might need an to have an action, say C<./Build install>,do something unusual.  For instance, you might need to change theownership 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 mayneed to read through C<Module::Build::Authoring> andC<Module::Build::API> to find the methods you want to override.  All"action" methods are implemented by a method called "ACTION_" followedby the action's name, so here's an example of how it would work forthe 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;=head1 AUTHORKen Williams <kwilliams@cpan.org>=head1 COPYRIGHTCopyright (c) 2001-2006 Ken Williams.  All rights reserved.This library is free software; you can redistribute it and/ormodify it under the same terms as Perl itself.=head1 SEE ALSOperl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),L<Module::Build::API>(3)=cut