local-lib5/man/man3/Module::Build::Authoring.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::Authoring 3"
 132 .TH Module::Build::Authoring 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::Build::Authoring \- Authoring Module::Build modules
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 When creating a \f(CW\*(C`Build.PL\*(C'\fR script for a module, something like the
 138 following code will typically be used:
 139 .PP
 140 .Vb 12
 141 \&  use Module::Build;
 142 \&  my $build = Module::Build\->new
 143 \&    (
 144 \&     module_name => 'Foo::Bar',
 145 \&     license  => 'perl',
 146 \&     requires => {
 147 \&                  'perl'          => '5.6.1',
 148 \&                  'Some::Module'  => '1.23',
 149 \&                  'Other::Module' => '>= 1.2, != 1.5, < 2.0',
 150 \&                 },
 151 \&    );
 152 \&  $build\->create_build_script;
 153 .Ve
 154 .PP
 155 A simple module could get away with something as short as this for its
 156 \&\f(CW\*(C`Build.PL\*(C'\fR script:
 157 .PP
 158 .Vb 5
 159 \&  use Module::Build;
 160 \&  Module::Build\->new(
 161 \&    module_name => 'Foo::Bar',
 162 \&    license     => 'perl',
 163 \&  )\->create_build_script;
 164 .Ve
 165 .PP
 166 The model used by \f(CW\*(C`Module::Build\*(C'\fR is a lot like the \f(CW\*(C`MakeMaker\*(C'\fR
 167 metaphor, with the following correspondences:
 168 .PP
 169 .Vb 5
 170 \&   In Module::Build                 In ExtUtils::MakeMaker
 171 \&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-      \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 172 \&   Build.PL (initial script)        Makefile.PL (initial script)
 173 \&   Build (a short perl script)      Makefile (a long Makefile)
 174 \&   _build/ (saved state info)       various config text in the Makefile
 175 .Ve
 176 .PP
 177 Any customization can be done simply by subclassing \f(CW\*(C`Module::Build\*(C'\fR
 178 and adding a method called (for example) \f(CW\*(C`ACTION_test\*(C'\fR, overriding
 179 the default 'test' action.  You could also add a method called
 180 \&\f(CW\*(C`ACTION_whatever\*(C'\fR, and then you could perform the action \f(CW\*(C`Build
 181 whatever\*(C'\fR.
 182 .PP
 183 For information on providing compatibility with
 184 \&\f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR, see Module::Build::Compat and
 185 <http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
 186 .SH "STRUCTURE"
 187 .IX Header "STRUCTURE"
 188 Module::Build creates a class hierarchy conducive to customization.
 189 Here is the parent-child class hierarchy in classy \s-1ASCII\s0 art:
 190 .PP
 191 .Vb 18
 192 \&   /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e
 193 \&   |   Your::Parent     |  (If you subclass Module::Build)
 194 \&   \e\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-/
 195 \&            |
 196 \&            |
 197 \&   /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e  (Doesn't define any functionality
 198 \&   |   Module::Build    |   of its own \- just figures out what
 199 \&   \e\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-/   other modules to load.)
 200 \&            |
 201 \&            |
 202 \&   /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e  (Some values of $^O may
 203 \&   |   Module::Build::Platform::$^O    |   define specialized functionality.
 204 \&   \e\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-/   Otherwise it's ...::Default, a
 205 \&            |                              pass\-through class.)
 206 \&            |
 207 \&   /\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e
 208 \&   |   Module::Build::Base    |  (Most of the functionality of
 209 \&   \e\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-/   Module::Build is defined here.)
 210 .Ve
 211 .SH "SUBCLASSING"
 212 .IX Header "SUBCLASSING"
 213 Right now, there are two ways to subclass Module::Build.  The first
 214 way is to create a regular module (in a \f(CW\*(C`.pm\*(C'\fR file) that inherits
 215 from Module::Build, and use that module's class instead of using
 216 Module::Build directly:
 217 .PP
 218 .Vb 2
 219 \&  \-\-\-\-\-\- in Build.PL: \-\-\-\-\-\-\-\-\-\-
 220 \&  #!/usr/bin/perl
 221 .Ve
 222 .PP
 223 .Vb 2
 224 \&  use lib q(/nonstandard/library/path);
 225 \&  use My::Builder;  # Or whatever you want to call it
 226 .Ve
 227 .PP
 228 .Vb 8
 229 \&  my $build = My::Builder\->new
 230 \&    (
 231 \&     module_name => 'Foo::Bar',  # All the regular args...
 232 \&     license     => 'perl',
 233 \&     dist_author => 'A N Other <me@here.net.au>',
 234 \&     requires    => { Carp => 0 }
 235 \&    );
 236 \&  $build\->create_build_script;
 237 .Ve
 238 .PP
 239 This is relatively straightforward, and is the best way to do things
 240 if your My::Builder class contains lots of code.  The
 241 \&\f(CW\*(C`create_build_script()\*(C'\fR method will ensure that the current value of
 242 \&\f(CW@INC\fR (including the \f(CW\*(C`/nonstandard/library/path\*(C'\fR) is propagated to
 243 the Build script, so that My::Builder can be found when running build
 244 actions.  If you find that you need to \f(CW\*(C`chdir\*(C'\fR into a different directories
 245 in your subclass methods or actions, be sure to always return to the original
 246 directory (available via the \f(CW\*(C`base_dir()\*(C'\fR method before returning control
 247 to the parent class.  This is important to avoid data serialization problems.
 248 .PP
 249 For very small additions, Module::Build provides a \f(CW\*(C`subclass()\*(C'\fR
 250 method that lets you subclass Module::Build more conveniently, without
 251 creating a separate file for your module:
 252 .PP
 253 .Vb 2
 254 \&  \-\-\-\-\-\- in Build.PL: \-\-\-\-\-\-\-\-\-\-
 255 \&  #!/usr/bin/perl
 256 .Ve
 257 .PP
 258 .Vb 10
 259 \&  use Module::Build;
 260 \&  my $class = Module::Build\->subclass
 261 \&    (
 262 \&     class => 'My::Builder',
 263 \&     code => q{
 264 \&       sub ACTION_foo {
 265 \&         print "I'm fooing to death!\en";
 266 \&       }
 267 \&     },
 268 \&    );
 269 .Ve
 270 .PP
 271 .Vb 8
 272 \&  my $build = $class\->new
 273 \&    (
 274 \&     module_name => 'Foo::Bar',  # All the regular args...
 275 \&     license     => 'perl',
 276 \&     dist_author => 'A N Other <me@here.net.au>',
 277 \&     requires    => { Carp => 0 }
 278 \&    );
 279 \&  $build\->create_build_script;
 280 .Ve
 281 .PP
 282 Behind the scenes, this actually does create a \f(CW\*(C`.pm\*(C'\fR file, since the
 283 code you provide must persist after Build.PL is run if it is to be
 284 very useful.
 285 .PP
 286 See also the documentation for the \*(L"\fIsubclass()\fR\*(R" in Module::Build::API
 287 method.
 288 .SH "PREREQUISITES"
 289 .IX Header "PREREQUISITES"
 290 .Sh "Types of prerequisites"
 291 .IX Subsection "Types of prerequisites"
 292 To specify what versions of other modules are used by this
 293 distribution, several types of prerequisites can be defined with the
 294 following parameters:
 295 .IP "configure_requires" 3
 296 .IX Item "configure_requires"
 297 Items that must be installed \fIbefore\fR configuring this distribution
 298 (i.e. before running the \fIBuild.PL\fR script).  This might be a
 299 specific minimum version of \f(CW\*(C`Module::Build\*(C'\fR or any other module the
 300 \&\fIBuild.PL\fR needs in order to do its stuff.  Clients like \f(CW\*(C`CPAN.pm\*(C'\fR
 301 or \f(CW\*(C`CPANPLUS\*(C'\fR will be expected to pick \f(CW\*(C`configure_requires\*(C'\fR out of the
 302 \&\fI\s-1META\s0.yml\fR file and install these items before running the
 303 \&\f(CW\*(C`Build.PL\*(C'\fR.
 304 .Sp
 305 If no configure_requires is specified, the current version of Module::Build
 306 is automatically added to configure_requires.
 307 .IP "build_requires" 3
 308 .IX Item "build_requires"
 309 Items that are necessary for building and testing this distribution,
 310 but aren't necessary after installation.  This can help users who only
 311 want to install these items temporarily.  It also helps reduce the
 312 size of the \s-1CPAN\s0 dependency graph if everything isn't smooshed into
 313 \&\f(CW\*(C`requires\*(C'\fR.
 314 .IP "requires" 3
 315 .IX Item "requires"
 316 Items that are necessary for basic functioning.
 317 .IP "recommends" 3
 318 .IX Item "recommends"
 319 Items that are recommended for enhanced functionality, but there are
 320 ways to use this distribution without having them installed.  You
 321 might also think of this as \*(L"can use\*(R" or \*(L"is aware of\*(R" or \*(L"changes
 322 behavior in the presence of\*(R".
 323 .IP "conflicts" 3
 324 .IX Item "conflicts"
 325 Items that can cause problems with this distribution when installed.
 326 This is pretty rare.
 327 .Sh "Format of prerequisites"
 328 .IX Subsection "Format of prerequisites"
 329 The prerequisites are given in a hash reference, where the keys are
 330 the module names and the values are version specifiers:
 331 .PP
 332 .Vb 6
 333 \&  requires => {
 334 \&               Foo::Module => '2.4',
 335 \&               Bar::Module => 0,
 336 \&               Ken::Module => '>= 1.2, != 1.5, < 2.0',
 337 \&               perl => '5.6.0'
 338 \&              },
 339 .Ve
 340 .PP
 341 The above four version specifiers have different effects.  The value
 342 \&\f(CW'2.4'\fR means that \fBat least\fR version 2.4 of \f(CW\*(C`Foo::Module\*(C'\fR must be
 343 installed.  The value \f(CW0\fR means that \fBany\fR version of \f(CW\*(C`Bar::Module\*(C'\fR
 344 is acceptable, even if \f(CW\*(C`Bar::Module\*(C'\fR doesn't define a version.  The
 345 more verbose value \f(CW'>= 1.2, != 1.5, < 2.0'\fR means that
 346 \&\f(CW\*(C`Ken::Module\*(C'\fR's version must be \fBat least\fR 1.2, \fBless than\fR 2.0,
 347 and \fBnot equal to\fR 1.5.  The list of criteria is separated by commas,
 348 and all criteria must be satisfied.
 349 .PP
 350 A special \f(CW\*(C`perl\*(C'\fR entry lets you specify the versions of the Perl
 351 interpreter that are supported by your module.  The same version
 352 dependency-checking semantics are available, except that we also
 353 understand perl's new double-dotted version numbers.
 354 .Sh "\s-1XS\s0 Extensions"
 355 .IX Subsection "XS Extensions"
 356 Modules which need to compile \s-1XS\s0 code should list \f(CW\*(C`ExtUtils::CBuilder\*(C'\fR
 357 as a \f(CW\*(C`build_requires\*(C'\fR element.
 358 .SH "SAVING CONFIGURATION INFORMATION"
 359 .IX Header "SAVING CONFIGURATION INFORMATION"
 360 Module::Build provides a very convenient way to save configuration
 361 information that your installed modules (or your regression tests) can
 362 access.  If your Build process calls the \f(CW\*(C`feature()\*(C'\fR or
 363 \&\f(CW\*(C`config_data()\*(C'\fR methods, then a \f(CW\*(C`Foo::Bar::ConfigData\*(C'\fR module will
 364 automatically be created for you, where \f(CW\*(C`Foo::Bar\*(C'\fR is the
 365 \&\f(CW\*(C`module_name\*(C'\fR parameter as passed to \f(CW\*(C`new()\*(C'\fR.  This module provides
 366 access to the data saved by these methods, and a way to update the
 367 values.  There is also a utility script called \f(CW\*(C`config_data\*(C'\fR
 368 distributed with Module::Build that provides a command line interface
 369 to this same functionality.  See also the generated
 370 \&\f(CW\*(C`Foo::Bar::ConfigData\*(C'\fR documentation, and the \f(CW\*(C`config_data\*(C'\fR
 371 script's documentation, for more information.
 372 .SH "STARTING MODULE DEVELOPMENT"
 373 .IX Header "STARTING MODULE DEVELOPMENT"
 374 When starting development on a new module, it's rarely worth your time
 375 to create a tree of all the files by hand.  Some automatic
 376 module-creators are available: the oldest is \f(CW\*(C`h2xs\*(C'\fR, which has
 377 shipped with perl itself for a long time.  Its name reflects the fact
 378 that modules were originally conceived of as a way to wrap up a C
 379 library (thus the \f(CW\*(C`h\*(C'\fR part) into perl extensions (thus the \f(CW\*(C`xs\*(C'\fR
 380 part).
 381 .PP
 382 These days, \f(CW\*(C`h2xs\*(C'\fR has largely been superseded by modules like
 383 \&\f(CW\*(C`ExtUtils::ModuleMaker\*(C'\fR, and \f(CW\*(C`Module::Starter\*(C'\fR.  They have varying
 384 degrees of support for \f(CW\*(C`Module::Build\*(C'\fR.
 385 .SH "AUTOMATION"
 386 .IX Header "AUTOMATION"
 387 One advantage of Module::Build is that since it's implemented as Perl
 388 methods, you can invoke these methods directly if you want to install
 389 a module non\-interactively.  For instance, the following Perl script
 390 will invoke the entire build/install procedure:
 391 .PP
 392 .Vb 4
 393 \&  my $build = Module::Build\->new(module_name => 'MyModule');
 394 \&  $build\->dispatch('build');
 395 \&  $build\->dispatch('test');
 396 \&  $build\->dispatch('install');
 397 .Ve
 398 .PP
 399 If any of these steps encounters an error, it will throw a fatal
 400 exception.
 401 .PP
 402 You can also pass arguments as part of the build process:
 403 .PP
 404 .Vb 4
 405 \&  my $build = Module::Build\->new(module_name => 'MyModule');
 406 \&  $build\->dispatch('build');
 407 \&  $build\->dispatch('test', verbose => 1);
 408 \&  $build\->dispatch('install', sitelib => '/my/secret/place/');
 409 .Ve
 410 .PP
 411 Building and installing modules in this way skips creating the
 412 \&\f(CW\*(C`Build\*(C'\fR script.
 413 .SH "MIGRATION"
 414 .IX Header "MIGRATION"
 415 Note that if you want to provide both a \fIMakefile.PL\fR and a
 416 \&\fIBuild.PL\fR for your distribution, you probably want to add the
 417 following to \f(CW\*(C`WriteMakefile\*(C'\fR in your \fIMakefile.PL\fR so that \f(CW\*(C`MakeMaker\*(C'\fR
 418 doesn't try to run your \fIBuild.PL\fR as a normal \fI.PL\fR file:
 419 .PP
 420 .Vb 1
 421 \&  PL_FILES => {},
 422 .Ve
 423 .PP
 424 You may also be interested in looking at the \f(CW\*(C`Module::Build::Compat\*(C'\fR
 425 module, which can automatically create various kinds of \fIMakefile.PL\fR
 426 compatibility layers.
 427 .SH "AUTHOR"
 428 .IX Header "AUTHOR"
 429 Ken Williams <kwilliams@cpan.org>
 430 .PP
 431 Development questions, bug reports, and patches should be sent to the
 432 Module-Build mailing list at <module\-build@perl.org>.
 433 .PP
 434 Bug reports are also welcome at
 435 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module\-Build>.
 436 .PP
 437 The latest development version is available from the Subversion
 438 repository at <https://svn.perl.org/modules/Module\-Build/trunk/>
 439 .SH "SEE ALSO"
 440 .IX Header "SEE ALSO"
 441 \&\fIperl\fR\|(1), Module::Build(3), Module::Build::API(3),
 442 Module::Build::Cookbook(3), ExtUtils::MakeMaker(3), \s-1YAML\s0(3)
 443 .PP
 444 \&\fI\s-1META\s0.yml\fR Specification:
 445 <http://module\-build.sourceforge.net/META\-spec\-current.html>
 446 .PP
 447 <http://www.dsmit.com/cons/>
 448 .PP
 449 <http://search.cpan.org/dist/PerlBuildSystem/>