local-lib5/man/man3/Module::Build::Compat.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Module::Build::Compat 3"
 132 .TH Module::Build::Compat 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::Build::Compat \- Compatibility with ExtUtils::MakeMaker
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 7
 138 \&  # In a Build.PL :
 139 \&  use Module::Build;
 140 \&  my $build = Module::Build\->new
 141 \&    ( module_name => 'Foo::Bar',
 142 \&      license     => 'perl',
 143 \&      create_makefile_pl => 'passthrough' );
 144 \&  ...
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 Because \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR has been the standard way to distribute
 149 modules for a long time, many tools (\s-1CPAN\s0.pm, or your system
 150 administrator) may expect to find a working \fIMakefile.PL\fR in every
 151 distribution they download from \s-1CPAN\s0.  If you want to throw them a
 152 bone, you can use \f(CW\*(C`Module::Build::Compat\*(C'\fR to automatically generate a
 153 \&\fIMakefile.PL\fR for you, in one of several different styles.
 154 .PP
 155 \&\f(CW\*(C`Module::Build::Compat\*(C'\fR also provides some code that helps out the
 156 \&\fIMakefile.PL\fR at runtime.
 157 .SH "METHODS"
 158 .IX Header "METHODS"
 159 .ie n .IP "create_makefile_pl($style, $build)" 4
 160 .el .IP "create_makefile_pl($style, \f(CW$build\fR)" 4
 161 .IX Item "create_makefile_pl($style, $build)"
 162 Creates a \fIMakefile.PL\fR in the current directory in one of several
 163 styles, based on the supplied \f(CW\*(C`Module::Build\*(C'\fR object \f(CW$build\fR.  This is
 164 typically controlled by passing the desired style as the
 165 \&\f(CW\*(C`create_makefile_pl\*(C'\fR parameter to \f(CW\*(C`Module::Build\*(C'\fR's \f(CW\*(C`new()\*(C'\fR method;
 166 the \fIMakefile.PL\fR will then be automatically created during the
 167 \&\f(CW\*(C`distdir\*(C'\fR action.
 168 .Sp
 169 The currently supported styles are:
 170 .RS 4
 171 .IP "small" 4
 172 .IX Item "small"
 173 A small \fIMakefile.PL\fR will be created that passes all functionality
 174 through to the \fIBuild.PL\fR script in the same directory.  The user must
 175 already have \f(CW\*(C`Module::Build\*(C'\fR installed in order to use this, or else
 176 they'll get a module-not-found error.
 177 .IP "passthrough" 4
 178 .IX Item "passthrough"
 179 This is just like the \f(CW\*(C`small\*(C'\fR option above, but if \f(CW\*(C`Module::Build\*(C'\fR is
 180 not already installed on the user's system, the script will offer to
 181 use \f(CW\*(C`CPAN.pm\*(C'\fR to download it and install it before continuing with
 182 the build.
 183 .IP "traditional" 4
 184 .IX Item "traditional"
 185 A \fIMakefile.PL\fR will be created in the \*(L"traditional\*(R" style, i.e. it will
 186 use \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR and won't rely on \f(CW\*(C`Module::Build\*(C'\fR at all.
 187 In order to create the \fIMakefile.PL\fR, we'll include the \f(CW\*(C`requires\*(C'\fR and
 188 \&\f(CW\*(C`build_requires\*(C'\fR dependencies as the \f(CW\*(C`PREREQ_PM\*(C'\fR parameter.
 189 .Sp
 190 You don't want to use this style if during the \f(CW\*(C`perl Build.PL\*(C'\fR stage
 191 you ask the user questions, or do some auto-sensing about the user's
 192 environment, or if you subclass \f(CW\*(C`Module::Build\*(C'\fR to do some
 193 customization, because the vanilla \fIMakefile.PL\fR won't do any of that.
 194 .RE
 195 .RS 4
 196 .RE
 197 .IP "run_build_pl(args => \e@ARGV)" 4
 198 .IX Item "run_build_pl(args => @ARGV)"
 199 This method runs the \fIBuild.PL\fR script, passing it any arguments the
 200 user may have supplied to the \f(CW\*(C`perl Makefile.PL\*(C'\fR command.  Because
 201 \&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR and \f(CW\*(C`Module::Build\*(C'\fR accept different arguments, this
 202 method also performs some translation between the two.
 203 .Sp
 204 \&\f(CW\*(C`run_build_pl()\*(C'\fR accepts the following named parameters:
 205 .RS 4
 206 .IP "args" 4
 207 .IX Item "args"
 208 The \f(CW\*(C`args\*(C'\fR parameter specifies the parameters that would usually
 209 appear on the command line of the \f(CW\*(C`perl Makefile.PL\*(C'\fR command \-
 210 typically you'll just pass a reference to \f(CW@ARGV\fR.
 211 .IP "script" 4
 212 .IX Item "script"
 213 This is the filename of the script to run \- it defaults to \f(CW\*(C`Build.PL\*(C'\fR.
 214 .RE
 215 .RS 4
 216 .RE
 217 .IP "\fIwrite_makefile()\fR" 4
 218 .IX Item "write_makefile()"
 219 This method writes a 'dummy' \fIMakefile\fR that will pass all commands
 220 through to the corresponding \f(CW\*(C`Module::Build\*(C'\fR actions.
 221 .Sp
 222 \&\f(CW\*(C`write_makefile()\*(C'\fR accepts the following named parameters:
 223 .RS 4
 224 .IP "makefile" 4
 225 .IX Item "makefile"
 226 The name of the file to write \- defaults to the string \f(CW\*(C`Makefile\*(C'\fR.
 227 .RE
 228 .RS 4
 229 .RE
 230 .SH "SCENARIOS"
 231 .IX Header "SCENARIOS"
 232 So, some common scenarios are:
 233 .IP "1." 4
 234 Just include a \fIBuild.PL\fR script (without a \fIMakefile.PL\fR
 235 script), and give installation directions in a \fI\s-1README\s0\fR or \fI\s-1INSTALL\s0\fR
 236 document explaining how to install the module.  In particular, explain
 237 that the user must install \f(CW\*(C`Module::Build\*(C'\fR before installing your
 238 module.
 239 .Sp
 240 Note that if you do this, you may make things easier for yourself, but
 241 harder for people with older versions of \s-1CPAN\s0 or \s-1CPANPLUS\s0 on their
 242 system, because those tools generally only understand the
 243 \&\fIMakefile.PL\fR/\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR way of doing things.
 244 .IP "2." 4
 245 Include a \fIBuild.PL\fR script and a \*(L"traditional\*(R" \fIMakefile.PL\fR,
 246 created either manually or with \f(CW\*(C`create_makefile_pl()\*(C'\fR.  Users won't
 247 ever have to install \f(CW\*(C`Module::Build\*(C'\fR if they use the \fIMakefile.PL\fR, but
 248 they won't get to take advantage of \f(CW\*(C`Module::Build\*(C'\fR's extra features
 249 either.
 250 .Sp
 251 For good measure, of course, test both the \fIMakefile.PL\fR and the
 252 \&\fIBuild.PL\fR before shipping.
 253 .IP "3." 4
 254 Include a \fIBuild.PL\fR script and a \*(L"pass\-through\*(R" \fIMakefile.PL\fR
 255 built using \f(CW\*(C`Module::Build::Compat\*(C'\fR.  This will mean that people can
 256 continue to use the \*(L"old\*(R" installation commands, and they may never
 257 notice that it's actually doing something else behind the scenes.  It
 258 will also mean that your installation process is compatible with older
 259 versions of tools like \s-1CPAN\s0 and \s-1CPANPLUS\s0.
 260 .SH "AUTHOR"
 261 .IX Header "AUTHOR"
 262 Ken Williams <kwilliams@cpan.org>
 263 .SH "COPYRIGHT"
 264 .IX Header "COPYRIGHT"
 265 Copyright (c) 2001\-2006 Ken Williams.  All rights reserved.
 266 .PP
 267 This library is free software; you can redistribute it and/or
 268 modify it under the same terms as Perl itself.
 269 .SH "SEE ALSO"
 270 .IX Header "SEE ALSO"
 271 Module::Build(3), ExtUtils::MakeMaker(3)