--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Module::Build::Cookbook 3"
+.TH Module::Build::Cookbook 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Module::Build::Cookbook \- Examples of Module::Build Usage
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`Module::Build\*(C'\fR 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.
+.SH "BASIC RECIPES"
+.IX Header "BASIC RECIPES"
+.Sh "Installing modules that use Module::Build"
+.IX Subsection "Installing modules that use Module::Build"
+In most cases, you can just issue the following commands:
+.PP
+.Vb 4
+\& perl Build.PL
+\& ./Build
+\& ./Build test
+\& ./Build install
+.Ve
+.PP
+There's nothing complicated here \- first you're running a script
+called \fIBuild.PL\fR, then you're running a (newly\-generated) script
+called \fIBuild\fR and passing it various arguments.
+.PP
+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:
+.PP
+.Vb 4
+\& /usr/bin/perl5.8.1 Build.PL
+\& ./Build
+\& ./Build test
+\& ./Build install
+.Ve
+.PP
+If you're on Windows where the current directory is always searched
+first for scripts, you'll probably do something like this:
+.PP
+.Vb 4
+\& perl Build.PL
+\& Build
+\& Build test
+\& Build install
+.Ve
+.PP
+On the old Mac \s-1OS\s0 (version 9 or lower) using MacPerl, you can
+double-click on the \fIBuild.PL\fR script to create the \fIBuild\fR script,
+then double-click on the \fIBuild\fR script to run its \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`test\*(C'\fR,
+and \f(CW\*(C`install\*(C'\fR actions.
+.PP
+The \fIBuild\fR script knows what perl was used to run \fIBuild.PL\fR, so
+you don't need to re-invoke the \fIBuild\fR script with the complete perl
+path each time. If you invoke it with the \fIwrong\fR perl path, you'll
+get a warning or a fatal error.
+.Sh "Modifying Config.pm values"
+.IX Subsection "Modifying Config.pm values"
+\&\f(CW\*(C`Module::Build\*(C'\fR relies heavily on various values from perl's
+\&\f(CW\*(C`Config.pm\*(C'\fR to do its work. For example, default installation paths
+are given by \f(CW\*(C`installsitelib\*(C'\fR and \f(CW\*(C`installvendorman3dir\*(C'\fR and
+friends, C linker & compiler settings are given by \f(CW\*(C`ld\*(C'\fR,
+\&\f(CW\*(C`lddlflags\*(C'\fR, \f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR, and so on. \fIIf you're pretty sure
+you know what you're doing\fR, you can tell \f(CW\*(C`Module::Build\*(C'\fR to pretend
+there are different values in \fIConfig.pm\fR than what's really there,
+by passing arguments for the \f(CW\*(C`\-\-config\*(C'\fR parameter on the command
+line:
+.PP
+.Vb 1
+\& perl Build.PL \-\-config cc=gcc \-\-config ld=gcc
+.Ve
+.PP
+Inside the \f(CW\*(C`Build.PL\*(C'\fR script the same thing can be accomplished by
+passing values for the \f(CW\*(C`config\*(C'\fR parameter to \f(CW\*(C`new()\*(C'\fR:
+.PP
+.Vb 6
+\& my $build = Module::Build\->new
+\& (
+\& ...
+\& config => { cc => 'gcc', ld => 'gcc' },
+\& ...
+\& );
+.Ve
+.PP
+In custom build code, the same thing can be accomplished by calling
+the \*(L"config\*(R" in Module::Build method:
+.PP
+.Vb 4
+\& $build\->config( cc => 'gcc' ); # Set
+\& $build\->config( ld => 'gcc' ); # Set
+\& ...
+\& my $linker = $build\->config('ld'); # Get
+.Ve
+.Sh "Installing modules using the programmatic interface"
+.IX Subsection "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 \f(CW\*(C`dispatch()\*(C'\fR method to run various
+actions.
+.PP
+.Vb 9
+\& 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');
+.Ve
+.PP
+The first argument to \f(CW\*(C`dispatch()\*(C'\fR is the name of the action, and any
+following arguments are named parameters.
+.PP
+This is the interface we use to test Module::Build itself in the
+regression tests.
+.Sh "Installing to a temporary directory"
+.IX Subsection "Installing to a temporary directory"
+To create packages for package managers like RedHat's \f(CW\*(C`rpm\*(C'\fR or
+Debian's \f(CW\*(C`deb\*(C'\fR, you may need to install to a temporary directory
+first and then create the package from that temporary installation.
+To do this, specify the \f(CW\*(C`destdir\*(C'\fR parameter to the \f(CW\*(C`install\*(C'\fR action:
+.PP
+.Vb 1
+\& ./Build install \-\-destdir /tmp/my\-package\-1.003
+.Ve
+.PP
+This essentially just prepends all the installation paths with the
+\&\fI/tmp/my\-package\-1.003\fR directory.
+.Sh "Installing to a non-standard directory"
+.IX Subsection "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
+\&\f(CW\*(C`install_base\*(C'\fR or \f(CW\*(C`prefix\*(C'\fR parameters:
+.PP
+.Vb 1
+\& ./Build install \-\-install_base /foo/bar
+.Ve
+.PP
+See \*(L"\s-1INSTALL\s0 \s-1PATHS\s0\*(R" in Module::Build for a much more complete
+discussion of how installation paths are determined.
+.Sh "Installing in the same location as ExtUtils::MakeMaker"
+.IX Subsection "Installing in the same location as ExtUtils::MakeMaker"
+With the introduction of \f(CW\*(C`\-\-prefix\*(C'\fR in Module::Build 0.28 and
+\&\f(CW\*(C`INSTALL_BASE\*(C'\fR in \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR 6.31 its easy to get them both
+to install to the same locations.
+.PP
+First, ensure you have at least version 0.28 of Module::Build
+installed and 6.31 of \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. Prior versions have
+differing (and in some cases quite strange) installation behaviors.
+.PP
+The following installation flags are equivalent between
+\&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR and \f(CW\*(C`Module::Build\*(C'\fR.
+.PP
+.Vb 10
+\& 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
+.Ve
+.PP
+For example, if you are currently installing \f(CW\*(C`MakeMaker\*(C'\fR modules with
+this command:
+.PP
+.Vb 3
+\& perl Makefile.PL PREFIX=~
+\& make test
+\& make install UNINST=1
+.Ve
+.PP
+You can install into the same location with Module::Build using this:
+.PP
+.Vb 3
+\& perl Build.PL \-\-prefix ~
+\& ./Build test
+\& ./Build install \-\-uninst 1
+.Ve
+.PP
+\fI\f(CI\*(C`prefix\*(C'\fI vs \f(CI\*(C`install_base\*(C'\fI\fR
+.IX Subsection "prefix vs install_base"
+.PP
+The behavior of \f(CW\*(C`prefix\*(C'\fR 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 \f(CW\*(C`prefix\*(C'\fR will place your modules.
+.PP
+In contrast, \f(CW\*(C`install_base\*(C'\fR has predictable, easy to explain
+installation locations. Now that \f(CW\*(C`Module::Build\*(C'\fR and \f(CW\*(C`MakeMaker\*(C'\fR both
+have \f(CW\*(C`install_base\*(C'\fR there is little reason to use \f(CW\*(C`prefix\*(C'\fR other
+than to preserve your existing installation locations. If you are
+starting a fresh Perl installation we encourage you to use
+\&\f(CW\*(C`install_base\*(C'\fR. If you have an existing installation installed via
+\&\f(CW\*(C`prefix\*(C'\fR, consider moving it to an installation structure matching
+\&\f(CW\*(C`install_base\*(C'\fR and using that instead.
+.Sh "Running a single test file"
+.IX Subsection "Running a single test file"
+\&\f(CW\*(C`Module::Build\*(C'\fR supports running a single test, which enables you to
+track down errors more quickly. Use the following format:
+.PP
+.Vb 1
+\& ./Build test \-\-test_files t/mytest.t
+.Ve
+.PP
+In addition, you may want to run the test in verbose mode to get more
+informative output:
+.PP
+.Vb 1
+\& ./Build test \-\-test_files t/mytest.t \-\-verbose 1
+.Ve
+.PP
+I run this so frequently that I define the following shell alias:
+.PP
+.Vb 1
+\& alias t './Build test \-\-verbose 1 \-\-test_files'
+.Ve
+.PP
+So then I can just execute \f(CW\*(C`t t/mytest.t\*(C'\fR to run a single test.
+.SH "ADVANCED RECIPES"
+.IX Header "ADVANCED RECIPES"
+.Sh "Making a \s-1CPAN\s0.pm\-compatible distribution"
+.IX Subsection "Making a CPAN.pm-compatible distribution"
+New versions of \s-1CPAN\s0.pm understand how to use a \fIBuild.PL\fR script,
+but old versions don't. If authors want to help users who have old
+versions, some form of \fIMakefile.PL\fR should be supplied. The easiest
+way to accomplish this is to use the \f(CW\*(C`create_makefile_pl\*(C'\fR parameter to
+\&\f(CW\*(C`Module::Build\->new()\*(C'\fR in the \f(CW\*(C`Build.PL\*(C'\fR script, which can
+create various flavors of \fIMakefile.PL\fR during the \f(CW\*(C`dist\*(C'\fR action.
+.PP
+As a best practice, we recommend using the \*(L"traditional\*(R" style of
+\&\fIMakefile.PL\fR unless your distribution has needs that can't be
+accomplished that way.
+.PP
+The \f(CW\*(C`Module::Build::Compat\*(C'\fR module, which is part of
+\&\f(CW\*(C`Module::Build\*(C'\fR's distribution, is responsible for creating these
+\&\fIMakefile.PL\fRs. Please see Module::Build::Compat for the details.
+.Sh "Changing the order of the build process"
+.IX Subsection "Changing the order of the build process"
+The \f(CW\*(C`build_elements\*(C'\fR property specifies the steps \f(CW\*(C`Module::Build\*(C'\fR
+will take when building a distribution. To change the build order,
+change the order of the entries in that property:
+.PP
+.Vb 4
+\& # Process pod files first
+\& my @e = @{$build\->build_elements};
+\& my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
+\& unshift @e, splice @e, $i, 1;
+.Ve
+.PP
+Currently, \f(CW\*(C`build_elements\*(C'\fR has the following default value:
+.PP
+.Vb 1
+\& [qw( PL support pm xs pod script )]
+.Ve
+.PP
+Do take care when altering this property, since there may be
+non-obvious (and non\-documented!) ordering dependencies in the
+\&\f(CW\*(C`Module::Build\*(C'\fR code.
+.Sh "Adding new file types to the build process"
+.IX Subsection "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 \fI.pm\fR and \fI.pod\fR files. For
+instance, you might have a \fIBar.dat\fR file containing some data
+related to the \f(CW\*(C`Foo::Bar\*(C'\fR module and you'd like for it to end up as
+\&\fIFoo/Bar.dat\fR somewhere in perl's \f(CW@INC\fR path so \f(CW\*(C`Foo::Bar\*(C'\fR can
+access it easily at runtime. The following code from a sample
+\&\f(CW\*(C`Build.PL\*(C'\fR file demonstrates how to accomplish this:
+.PP
+.Vb 8
+\& use Module::Build;
+\& my $build = Module::Build\->new
+\& (
+\& module_name => 'Foo::Bar',
+\& ...other stuff here...
+\& );
+\& $build\->add_build_element('dat');
+\& $build\->create_build_script;
+.Ve
+.PP
+This will find all \fI.dat\fR files in the \fIlib/\fR directory, copy them
+to the \fIblib/lib/\fR directory during the \f(CW\*(C`build\*(C'\fR action, and install
+them during the \f(CW\*(C`install\*(C'\fR action.
+.PP
+If your extra files aren't located in the \f(CW\*(C`lib/\*(C'\fR directory in your
+distribution, you can explicitly say where they are, just as you'd do
+with \fI.pm\fR or \fI.pod\fR files:
+.PP
+.Vb 9
+\& 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;
+.Ve
+.PP
+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 \f(CW\*(C`Module::Build\*(C'\fR and create a special method to
+process them, named \f(CW\*(C`process_${kind}_files()\*(C'\fR:
+.PP
+.Vb 15
+\& 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;
+.Ve
+.PP
+If your extra files don't go in \fIlib/\fR but in some other place, see
+\&\*(L"Adding new elements to the install process\*(R" for how to actually
+get them installed.
+.PP
+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.
+.Sh "Adding new elements to the install process"
+.IX Subsection "Adding new elements to the install process"
+By default, Module::Build creates seven subdirectories of the \fIblib\fR
+directory during the build process: \fIlib\fR, \fIarch\fR, \fIbin\fR,
+\&\fIscript\fR, \fIbindoc\fR, \fIlibdoc\fR, and \fIhtml\fR (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 \f(CW\*(C`install\*(C'\fR action (see \*(L"\s-1INSTALL\s0 \s-1PATHS\s0\*(R" in Module::Build.
+.PP
+If you need to create a new custom type of installable element, e.g. \f(CW\*(C`conf\*(C'\fR,
+then you need to tell Module::Build where things in \fIblib/conf/\fR
+should be installed. To do this, use the \f(CW\*(C`install_path\*(C'\fR parameter to
+the \f(CW\*(C`new()\*(C'\fR method:
+.PP
+.Vb 5
+\& my $build = Module::Build\->new
+\& (
+\& ...other stuff here...
+\& install_path => { conf => $installation_path }
+\& );
+.Ve
+.PP
+Or you can call the \f(CW\*(C`install_path()\*(C'\fR method later:
+.PP
+.Vb 1
+\& $build\->install_path(conf => $installation_path);
+.Ve
+.PP
+The user may also specify the path on the command line:
+.PP
+.Vb 1
+\& perl Build.PL \-\-install_path conf=/foo/path/etc
+.Ve
+.PP
+The important part, though, is that \fIsomehow\fR the install path needs
+to be set, or else nothing in the \fIblib/conf/\fR directory will get
+installed, and a runtime error during the \f(CW\*(C`install\*(C'\fR action will
+result.
+.PP
+See also \*(L"Adding new file types to the build process\*(R" for how to
+create the stuff in \fIblib/conf/\fR in the first place.
+.SH "EXAMPLES ON CPAN"
+.IX Header "EXAMPLES ON CPAN"
+Several distributions on \s-1CPAN\s0 are making good use of various features
+of Module::Build. They can serve as real-world examples for others.
+.Sh "SVN-Notify-Mirror"
+.IX Subsection "SVN-Notify-Mirror"
+<http://search.cpan.org/~jpeacock/SVN\-Notify\-Mirror/>
+.PP
+John Peacock, author of the \f(CW\*(C`SVN\-Notify\-Mirror\*(C'\fR distribution, says:
+.ie n .IP "1. Using ""auto_features"", I check to see whether two optional modules are available \- SVN::Notify::Config and Net::SSH;" 4
+.el .IP "1. Using \f(CWauto_features\fR, I check to see whether two optional modules are available \- SVN::Notify::Config and Net::SSH;" 4
+.IX Item "1. Using auto_features, I check to see whether two optional modules are available - SVN::Notify::Config and Net::SSH;"
+.PD 0
+.ie n .IP "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the ""PL_files"" property)." 4
+.el .IP "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the \f(CWPL_files\fR property)." 4
+.IX Item "2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the PL_files property)."
+.ie n .IP "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
+.el .IP "3. If the \f(CWssh_feature\fR is available, I ask if the user wishes to perform the ssh tests (since it requires a little preliminary setup);" 4
+.IX Item "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);"
+.ie n .IP "4. Only if the user has ""ssh_feature"" and answers yes to the testing, do I generate a test file." 4
+.el .IP "4. Only if the user has \f(CWssh_feature\fR and answers yes to the testing, do I generate a test file." 4
+.IX Item "4. Only if the user has ssh_feature and answers yes to the testing, do I generate a test file."
+.PD
+I'm sure I could not have handled this complexity with \s-1EU::MM\s0, but it
+was very easy to do with M::B.
+.Sh "Modifying an action"
+.IX Subsection "Modifying an action"
+Sometimes you might need an to have an action, say \f(CW\*(C`./Build install\*(C'\fR,
+do something unusual. For instance, you might need to change the
+ownership of a file or do something else peculiar to your application.
+.PP
+You can subclass \f(CW\*(C`Module::Build\*(C'\fR on the fly using the \f(CW\*(C`subclass()\*(C'\fR
+method and override the methods that perform the actions. You may
+need to read through \f(CW\*(C`Module::Build::Authoring\*(C'\fR and
+\&\f(CW\*(C`Module::Build::API\*(C'\fR to find the methods you want to override. All
+\&\*(L"action\*(R" methods are implemented by a method called \*(L"\s-1ACTION_\s0\*(R" followed
+by the action's name, so here's an example of how it would work for
+the \f(CW\*(C`install\*(C'\fR action:
+.PP
+.Vb 5
+\& # Build.PL
+\& use Module::Build;
+\& my $class = Module::Build\->subclass(
+\& class => "Module::Build::Custom",
+\& code => <<'SUBCLASS' );
+.Ve
+.PP
+.Vb 6
+\& sub ACTION_install {
+\& my $self = shift;
+\& # YOUR CODE HERE
+\& $self\->SUPER::ACTION_install;
+\& }
+\& SUBCLASS
+.Ve
+.PP
+.Vb 4
+\& $class\->new(
+\& module_name => 'Your::Module',
+\& # rest of the usual Module::Build parameters
+\& )\->create_build_script;
+.Ve
+.Sh "Adding an action"
+.IX Subsection "Adding an action"
+You can add a new \f(CW\*(C`./Build\*(C'\fR action simply by writing the method for
+it in your subclass. Use \f(CW\*(C`depends_on\*(C'\fR to declare that another action
+must have been run before your action.
+.PP
+For example, let's say you wanted to be able to write \f(CW\*(C`./Build
+commit\*(C'\fR to test your code and commit it to Subversion.
+.PP
+.Vb 5
+\& # Build.PL
+\& use Module::Build;
+\& my $class = Module::Build\->subclass(
+\& class => "Module::Build::Custom",
+\& code => <<'SUBCLASS' );
+.Ve
+.PP
+.Vb 2
+\& sub ACTION_commit {
+\& my $self = shift;
+.Ve
+.PP
+.Vb 4
+\& $self\->depends_on("test");
+\& $self\->do_system(qw(svn commit));
+\& }
+\& SUBCLASS
+.Ve
+.Sh "Bundling Module::Build"
+.IX Subsection "Bundling Module::Build"
+Note: This section probably needs an update as the technology improves
+(see contrib/bundle.pl in the distribution).
+.PP
+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 \f(CW\*(C`configure_requires\*(C'\fR to your minimum version of
+Module::Build. See Module::Build::Authoring.
+.PP
+But not every build system honors \f(CW\*(C`configure_requires\*(C'\fR 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.
+.PP
+First, install Module::Build into \fIYour\-Project/inc/Module\-Build\fR.
+\&\s-1CPAN\s0 will not index anything in the \fIinc\fR directory so this copy will
+not show up in \s-1CPAN\s0 searches.
+.PP
+.Vb 4
+\& cd Module\-Build
+\& perl Build.PL \-\-install_base /path/to/Your\-Project/inc/Module\-Build
+\& ./Build test
+\& ./Build install
+.Ve
+.PP
+You should now have all the Module::Build .pm files in
+\&\fIYour\-Project/inc/Module\-Build/lib/perl5\fR.
+.PP
+Next, add this to the top of your \fIBuild.PL\fR.
+.PP
+.Vb 1
+\& my $Bundled_MB = 0.30; # or whatever version it was.
+.Ve
+.PP
+.Vb 4
+\& # 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";
+.Ve
+.PP
+.Vb 2
+\& # some operating systems put a newline at the end of every print.
+\& chomp $Installed_MB;
+.Ve
+.PP
+.Vb 1
+\& $Installed_MB = 0 if $?;
+.Ve
+.PP
+.Vb 2
+\& # 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;
+.Ve
+.PP
+.Vb 1
+\& require Module::Build;
+.Ve
+.PP
+And write the rest of your \fIBuild.PL\fR normally. Module::Build will
+remember your change to \f(CW@INC\fR and use it when you run \fI./Build\fR.
+.PP
+In the future, we hope to provide a more automated solution for this
+scenario; see \f(CW\*(C`inc/latest.pm\*(C'\fR in the Module::Build distribution for
+one indication of the direction we're moving.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Ken Williams <kwilliams@cpan.org>
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 2001\-2008 Ken Williams. All rights reserved.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIperl\fR\|(1), Module::Build(3), Module::Build::Authoring(3),
+Module::Build::API(3)
projects / catagits/Gitalist.git / blobdiff