.\" Automatically generated by Pod::Man version 1.15
.\" Sun Jan 25 04:58:46 2004
.\"
.\" 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 Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.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.
.bd B 3
.    \" 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 "blib::lib::Module::Build::Cookbook 3"
.TH blib::lib::Module::Build::Cookbook 3 "perl v5.6.1" "2004-01-25" "User Contributed Perl Documentation"
.UC
.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.  I got the idea for writing this cookbook when
attending Brian Ingerson's \*(L"Extreme Programming Tools for Module
Authors\*(R" presentation at \s-1YAPC\s0 2003, when he said, straightforwardly,
\&\*(L"Write A Cookbook.\*(R"
.PP
The definitional of how stuff works is in the main \f(CW\*(C`Module::Build\*(C'\fR
documentation.  It's best to get familiar with that too.
.SH "BASIC RECIPES"
.IX Header "BASIC RECIPES"
.Sh "The basic installation recipe for modules that use Module::Build"
.IX Subsection "The basic installation recipe for modules that use Module::Build"
In most cases, you can just issue the following commands from your
shell:
.PP
.Vb 4
\& perl Build.PL
\& Build
\& Build test
\& Build install
.Ve
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.  If you know how to
do that on your system, you can get installation working.
.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
The \fIBuild\fR script knows what perl was used to run \f(CW\*(C`Build.PL\*(C'\fR, so
you don't need to reinvoke 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.
.PP
If the current directory (usually called '.') isn't in your path, you
can do \f(CW\*(C`./Build\*(C'\fR or \f(CW\*(C`perl Build\*(C'\fR to run the script:
.PP
.Vb 4
\& /usr/bin/perl Build.PL
\& ./Build
\& ./Build test
\& ./Build install
.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 8
\& 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);
.Ve
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
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken Williams, ken@mathforum.org
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIModule::Build\fR\|(3)