| 1 | package Module::Build; |
| 2 | |
| 3 | # This module doesn't do much of anything itself, it inherits from the |
| 4 | # modules that do the real work. The only real thing it has to do is |
| 5 | # figure out which OS-specific module to pull in. Many of the |
| 6 | # OS-specific modules don't do anything either - most of the work is |
| 7 | # done in Module::Build::Base. |
| 8 | |
| 9 | use strict; |
| 10 | use File::Spec (); |
| 11 | use File::Path (); |
| 12 | use File::Basename (); |
| 13 | |
| 14 | use Module::Build::Base; |
| 15 | |
| 16 | use vars qw($VERSION @ISA); |
| 17 | @ISA = qw(Module::Build::Base); |
| 18 | $VERSION = '0.2806_01'; |
| 19 | $VERSION = eval $VERSION; |
| 20 | |
| 21 | # Okay, this is the brute-force method of finding out what kind of |
| 22 | # platform we're on. I don't know of a systematic way. These values |
| 23 | # came from the latest (bleadperl) perlport.pod. |
| 24 | |
| 25 | my %OSTYPES = qw( |
| 26 | aix Unix |
| 27 | bsdos Unix |
| 28 | dgux Unix |
| 29 | dragonfly Unix |
| 30 | dynixptx Unix |
| 31 | freebsd Unix |
| 32 | linux Unix |
| 33 | hpux Unix |
| 34 | irix Unix |
| 35 | darwin Unix |
| 36 | machten Unix |
| 37 | next Unix |
| 38 | openbsd Unix |
| 39 | netbsd Unix |
| 40 | dec_osf Unix |
| 41 | svr4 Unix |
| 42 | svr5 Unix |
| 43 | sco_sv Unix |
| 44 | unicos Unix |
| 45 | unicosmk Unix |
| 46 | solaris Unix |
| 47 | sunos Unix |
| 48 | cygwin Unix |
| 49 | os2 Unix |
| 50 | interix Unix |
| 51 | |
| 52 | dos Windows |
| 53 | MSWin32 Windows |
| 54 | |
| 55 | os390 EBCDIC |
| 56 | os400 EBCDIC |
| 57 | posix-bc EBCDIC |
| 58 | vmesa EBCDIC |
| 59 | |
| 60 | MacOS MacOS |
| 61 | VMS VMS |
| 62 | VOS VOS |
| 63 | riscos RiscOS |
| 64 | amigaos Amiga |
| 65 | mpeix MPEiX |
| 66 | ); |
| 67 | |
| 68 | # Inserts the given module into the @ISA hierarchy between |
| 69 | # Module::Build and its immediate parent |
| 70 | sub _interpose_module { |
| 71 | my ($self, $mod) = @_; |
| 72 | eval "use $mod"; |
| 73 | die $@ if $@; |
| 74 | |
| 75 | no strict 'refs'; |
| 76 | my $top_class = $mod; |
| 77 | while (@{"${top_class}::ISA"}) { |
| 78 | last if ${"${top_class}::ISA"}[0] eq $ISA[0]; |
| 79 | $top_class = ${"${top_class}::ISA"}[0]; |
| 80 | } |
| 81 | |
| 82 | @{"${top_class}::ISA"} = @ISA; |
| 83 | @ISA = ($mod); |
| 84 | } |
| 85 | |
| 86 | if (grep {-e File::Spec->catfile($_, qw(Module Build Platform), $^O) . '.pm'} @INC) { |
| 87 | __PACKAGE__->_interpose_module("Module::Build::Platform::$^O"); |
| 88 | |
| 89 | } elsif (exists $OSTYPES{$^O}) { |
| 90 | __PACKAGE__->_interpose_module("Module::Build::Platform::$OSTYPES{$^O}"); |
| 91 | |
| 92 | } else { |
| 93 | warn "Unknown OS type '$^O' - using default settings\n"; |
| 94 | } |
| 95 | |
| 96 | sub os_type { $OSTYPES{$^O} } |
| 97 | |
| 98 | 1; |
| 99 | |
| 100 | __END__ |
| 101 | |
| 102 | |
| 103 | =head1 NAME |
| 104 | |
| 105 | Module::Build - Build and install Perl modules |
| 106 | |
| 107 | |
| 108 | =head1 SYNOPSIS |
| 109 | |
| 110 | Standard process for building & installing modules: |
| 111 | |
| 112 | perl Build.PL |
| 113 | ./Build |
| 114 | ./Build test |
| 115 | ./Build install |
| 116 | |
| 117 | Or, if you're on a platform (like DOS or Windows) that doesn't require |
| 118 | the "./" notation, you can do this: |
| 119 | |
| 120 | perl Build.PL |
| 121 | Build |
| 122 | Build test |
| 123 | Build install |
| 124 | |
| 125 | |
| 126 | =head1 DESCRIPTION |
| 127 | |
| 128 | C<Module::Build> is a system for building, testing, and installing |
| 129 | Perl modules. It is meant to be an alternative to |
| 130 | C<ExtUtils::MakeMaker>. Developers may alter the behavior of the |
| 131 | module through subclassing in a much more straightforward way than |
| 132 | with C<MakeMaker>. It also does not require a C<make> on your system |
| 133 | - most of the C<Module::Build> code is pure-perl and written in a very |
| 134 | cross-platform way. In fact, you don't even need a shell, so even |
| 135 | platforms like MacOS (traditional) can use it fairly easily. Its only |
| 136 | prerequisites are modules that are included with perl 5.6.0, and it |
| 137 | works fine on perl 5.005 if you can install a few additional modules. |
| 138 | |
| 139 | See L<"MOTIVATIONS"> for more comparisons between C<ExtUtils::MakeMaker> |
| 140 | and C<Module::Build>. |
| 141 | |
| 142 | To install C<Module::Build>, and any other module that uses |
| 143 | C<Module::Build> for its installation process, do the following: |
| 144 | |
| 145 | perl Build.PL # 'Build.PL' script creates the 'Build' script |
| 146 | ./Build # Need ./ to ensure we're using this "Build" script |
| 147 | ./Build test # and not another one that happens to be in the PATH |
| 148 | ./Build install |
| 149 | |
| 150 | This illustrates initial configuration and the running of three |
| 151 | 'actions'. In this case the actions run are 'build' (the default |
| 152 | action), 'test', and 'install'. Other actions defined so far include: |
| 153 | |
| 154 | build manifest |
| 155 | clean manpages |
| 156 | code pardist |
| 157 | config_data ppd |
| 158 | diff ppmdist |
| 159 | dist prereq_report |
| 160 | distcheck pure_install |
| 161 | distclean realclean |
| 162 | distdir retest |
| 163 | distmeta skipcheck |
| 164 | distsign test |
| 165 | disttest testcover |
| 166 | docs testdb |
| 167 | fakeinstall testpod |
| 168 | help testpodcoverage |
| 169 | html versioninstall |
| 170 | install |
| 171 | |
| 172 | |
| 173 | You can run the 'help' action for a complete list of actions. |
| 174 | |
| 175 | |
| 176 | =head1 GUIDE TO DOCUMENTATION |
| 177 | |
| 178 | The documentation for C<Module::Build> is broken up into three sections: |
| 179 | |
| 180 | =over |
| 181 | |
| 182 | =item General Usage (L<Module::Build>) |
| 183 | |
| 184 | This is the document you are currently reading. It describes basic |
| 185 | usage and background information. Its main purpose is to assist the |
| 186 | user who wants to learn how to invoke and control C<Module::Build> |
| 187 | scripts at the command line. |
| 188 | |
| 189 | =item Authoring Reference (L<Module::Build::Authoring>) |
| 190 | |
| 191 | This document describes the structure and organization of |
| 192 | C<Module::Build>, and the relevant concepts needed by authors who are |
| 193 | writing F<Build.PL> scripts for a distribution or controlling |
| 194 | C<Module::Build> processes programmatically. |
| 195 | |
| 196 | =item API Reference (L<Module::Build::API>) |
| 197 | |
| 198 | This is a reference to the C<Module::Build> API. |
| 199 | |
| 200 | =item Cookbook (L<Module::Build::Cookbook>) |
| 201 | |
| 202 | This document demonstrates how to accomplish many common tasks. It |
| 203 | covers general command line usage and authoring of F<Build.PL> |
| 204 | scripts. Includes working examples. |
| 205 | |
| 206 | =back |
| 207 | |
| 208 | |
| 209 | =head1 ACTIONS |
| 210 | |
| 211 | There are some general principles at work here. First, each task when |
| 212 | building a module is called an "action". These actions are listed |
| 213 | above; they correspond to the building, testing, installing, |
| 214 | packaging, etc., tasks. |
| 215 | |
| 216 | Second, arguments are processed in a very systematic way. Arguments |
| 217 | are always key=value pairs. They may be specified at C<perl Build.PL> |
| 218 | time (i.e. C<perl Build.PL destdir=/my/secret/place>), in which case |
| 219 | their values last for the lifetime of the C<Build> script. They may |
| 220 | also be specified when executing a particular action (i.e. |
| 221 | C<Build test verbose=1>), in which case their values last only for the |
| 222 | lifetime of that command. Per-action command line parameters take |
| 223 | precedence over parameters specified at C<perl Build.PL> time. |
| 224 | |
| 225 | The build process also relies heavily on the C<Config.pm> module, and |
| 226 | all the key=value pairs in C<Config.pm> are available in |
| 227 | |
| 228 | C<< $self->{config} >>. If the user wishes to override any of the |
| 229 | values in C<Config.pm>, she may specify them like so: |
| 230 | |
| 231 | perl Build.PL --config cc=gcc --config ld=gcc |
| 232 | |
| 233 | The following build actions are provided by default. |
| 234 | |
| 235 | =over 4 |
| 236 | |
| 237 | =item build |
| 238 | |
| 239 | [version 0.01] |
| 240 | |
| 241 | If you run the C<Build> script without any arguments, it runs the |
| 242 | C<build> action, which in turn runs the C<code> and C<docs> actions. |
| 243 | |
| 244 | This is analogous to the MakeMaker 'make all' target. |
| 245 | |
| 246 | =item clean |
| 247 | |
| 248 | [version 0.01] |
| 249 | |
| 250 | This action will clean up any files that the build process may have |
| 251 | created, including the C<blib/> directory (but not including the |
| 252 | C<_build/> directory and the C<Build> script itself). |
| 253 | |
| 254 | =item code |
| 255 | |
| 256 | [version 0.20] |
| 257 | |
| 258 | This action builds your codebase. |
| 259 | |
| 260 | By default it just creates a C<blib/> directory and copies any C<.pm> |
| 261 | and C<.pod> files from your C<lib/> directory into the C<blib/> |
| 262 | directory. It also compiles any C<.xs> files from C<lib/> and places |
| 263 | them in C<blib/>. Of course, you need a working C compiler (probably |
| 264 | the same one that built perl itself) for the compilation to work |
| 265 | properly. |
| 266 | |
| 267 | The C<code> action also runs any C<.PL> files in your F<lib/> |
| 268 | directory. Typically these create other files, named the same but |
| 269 | without the C<.PL> ending. For example, a file F<lib/Foo/Bar.pm.PL> |
| 270 | could create the file F<lib/Foo/Bar.pm>. The C<.PL> files are |
| 271 | processed first, so any C<.pm> files (or other kinds that we deal |
| 272 | with) will get copied correctly. |
| 273 | |
| 274 | =item config_data |
| 275 | |
| 276 | [version 0.26] |
| 277 | |
| 278 | ... |
| 279 | |
| 280 | =item diff |
| 281 | |
| 282 | [version 0.14] |
| 283 | |
| 284 | This action will compare the files about to be installed with their |
| 285 | installed counterparts. For .pm and .pod files, a diff will be shown |
| 286 | (this currently requires a 'diff' program to be in your PATH). For |
| 287 | other files like compiled binary files, we simply report whether they |
| 288 | differ. |
| 289 | |
| 290 | A C<flags> parameter may be passed to the action, which will be passed |
| 291 | to the 'diff' program. Consult your 'diff' documentation for the |
| 292 | parameters it will accept - a good one is C<-u>: |
| 293 | |
| 294 | ./Build diff flags=-u |
| 295 | |
| 296 | =item dist |
| 297 | |
| 298 | [version 0.02] |
| 299 | |
| 300 | This action is helpful for module authors who want to package up their |
| 301 | module for source distribution through a medium like CPAN. It will create a |
| 302 | tarball of the files listed in F<MANIFEST> and compress the tarball using |
| 303 | GZIP compression. |
| 304 | |
| 305 | By default, this action will use the external C<tar> and C<gzip> |
| 306 | executables on Unix-like platforms, and the C<Archive::Tar> module |
| 307 | elsewhere. However, you can force it to use whatever executable you |
| 308 | want by supplying an explicit C<tar> (and optional C<gzip>) parameter: |
| 309 | |
| 310 | ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe |
| 311 | |
| 312 | =item distcheck |
| 313 | |
| 314 | [version 0.05] |
| 315 | |
| 316 | Reports which files are in the build directory but not in the |
| 317 | F<MANIFEST> file, and vice versa. (See L<manifest> for details.) |
| 318 | |
| 319 | =item distclean |
| 320 | |
| 321 | [version 0.05] |
| 322 | |
| 323 | Performs the 'realclean' action and then the 'distcheck' action. |
| 324 | |
| 325 | =item distdir |
| 326 | |
| 327 | [version 0.05] |
| 328 | |
| 329 | Creates a "distribution directory" named C<$dist_name-$dist_version> |
| 330 | (if that directory already exists, it will be removed first), then |
| 331 | copies all the files listed in the F<MANIFEST> file to that directory. |
| 332 | This directory is what the distribution tarball is created from. |
| 333 | |
| 334 | =item distmeta |
| 335 | |
| 336 | [version 0.21] |
| 337 | |
| 338 | Creates the F<META.yml> file that describes the distribution. |
| 339 | |
| 340 | F<META.yml> is a file containing various bits of "metadata" about the |
| 341 | distribution. The metadata includes the distribution name, version, |
| 342 | abstract, prerequisites, license, and various other data about the |
| 343 | distribution. This file is created as F<META.yml> in YAML format. |
| 344 | It is recommended that the C<YAML> module be installed to create it. |
| 345 | If the C<YAML> module is not installed, an internal module supplied |
| 346 | with Module::Build will be used to write the META.yml file, and this |
| 347 | will most likely be fine. |
| 348 | |
| 349 | F<META.yml> file must also be listed in F<MANIFEST> - if it's not, a |
| 350 | warning will be issued. |
| 351 | |
| 352 | The current version of the F<META.yml> specification can be found at |
| 353 | L<http://module-build.sourceforge.net/META-spec-current.html> |
| 354 | |
| 355 | =item distsign |
| 356 | |
| 357 | [version 0.16] |
| 358 | |
| 359 | Uses C<Module::Signature> to create a SIGNATURE file for your |
| 360 | distribution, and adds the SIGNATURE file to the distribution's |
| 361 | MANIFEST. |
| 362 | |
| 363 | =item disttest |
| 364 | |
| 365 | [version 0.05] |
| 366 | |
| 367 | Performs the 'distdir' action, then switches into that directory and |
| 368 | runs a C<perl Build.PL>, followed by the 'build' and 'test' actions in |
| 369 | that directory. |
| 370 | |
| 371 | =item docs |
| 372 | |
| 373 | [version 0.20] |
| 374 | |
| 375 | This will generate documentation (e.g. Unix man pages and html |
| 376 | documents) for any installable items under B<blib/> that |
| 377 | contain POD. If there are no C<bindoc> or C<libdoc> installation |
| 378 | targets defined (as will be the case on systems that don't support |
| 379 | Unix manpages) no action is taken for manpages. If there are no |
| 380 | C<binhtml> or C<libhtml> installation targets defined no action is |
| 381 | taken for html documents. |
| 382 | |
| 383 | =item fakeinstall |
| 384 | |
| 385 | [version 0.02] |
| 386 | |
| 387 | This is just like the C<install> action, but it won't actually do |
| 388 | anything, it will just report what it I<would> have done if you had |
| 389 | actually run the C<install> action. |
| 390 | |
| 391 | =item help |
| 392 | |
| 393 | [version 0.03] |
| 394 | |
| 395 | This action will simply print out a message that is meant to help you |
| 396 | use the build process. It will show you a list of available build |
| 397 | actions too. |
| 398 | |
| 399 | With an optional argument specifying an action name (e.g. C<Build help |
| 400 | test>), the 'help' action will show you any POD documentation it can |
| 401 | find for that action. |
| 402 | |
| 403 | =item html |
| 404 | |
| 405 | [version 0.26] |
| 406 | |
| 407 | This will generate HTML documentation for any binary or library files |
| 408 | under B<blib/> that contain POD. The HTML documentation will only be |
| 409 | installed if the install paths can be determined from values in |
| 410 | C<Config.pm>. You can also supply or override install paths on the |
| 411 | command line by specifying C<install_path> values for the C<binhtml> |
| 412 | and/or C<libhtml> installation targets. |
| 413 | |
| 414 | =item install |
| 415 | |
| 416 | [version 0.01] |
| 417 | |
| 418 | This action will use C<ExtUtils::Install> to install the files from |
| 419 | C<blib/> into the system. See L<"INSTALL PATHS"> |
| 420 | for details about how Module::Build determines where to install |
| 421 | things, and how to influence this process. |
| 422 | |
| 423 | If you want the installation process to look around in C<@INC> for |
| 424 | other versions of the stuff you're installing and try to delete it, |
| 425 | you can use the C<uninst> parameter, which tells C<ExtUtils::Install> to |
| 426 | do so: |
| 427 | |
| 428 | ./Build install uninst=1 |
| 429 | |
| 430 | This can be a good idea, as it helps prevent multiple versions of a |
| 431 | module from being present on your system, which can be a confusing |
| 432 | situation indeed. |
| 433 | |
| 434 | =item manifest |
| 435 | |
| 436 | [version 0.05] |
| 437 | |
| 438 | This is an action intended for use by module authors, not people |
| 439 | installing modules. It will bring the F<MANIFEST> up to date with the |
| 440 | files currently present in the distribution. You may use a |
| 441 | F<MANIFEST.SKIP> file to exclude certain files or directories from |
| 442 | inclusion in the F<MANIFEST>. F<MANIFEST.SKIP> should contain a bunch |
| 443 | of regular expressions, one per line. If a file in the distribution |
| 444 | directory matches any of the regular expressions, it won't be included |
| 445 | in the F<MANIFEST>. |
| 446 | |
| 447 | The following is a reasonable F<MANIFEST.SKIP> starting point, you can |
| 448 | add your own stuff to it: |
| 449 | |
| 450 | ^_build |
| 451 | ^Build$ |
| 452 | ^blib |
| 453 | ~$ |
| 454 | \.bak$ |
| 455 | ^MANIFEST\.SKIP$ |
| 456 | CVS |
| 457 | |
| 458 | See the L<distcheck> and L<skipcheck> actions if you want to find out |
| 459 | what the C<manifest> action would do, without actually doing anything. |
| 460 | |
| 461 | =item manpages |
| 462 | |
| 463 | [version 0.28] |
| 464 | |
| 465 | This will generate man pages for any binary or library files under |
| 466 | B<blib/> that contain POD. The man pages will only be installed if the |
| 467 | install paths can be determined from values in C<Config.pm>. You can |
| 468 | also supply or override install paths by specifying there values on |
| 469 | the command line with the C<bindoc> and C<libdoc> installation |
| 470 | targets. |
| 471 | |
| 472 | =item pardist |
| 473 | |
| 474 | [version 0.2806] |
| 475 | |
| 476 | Generates a PAR binary distribution for use with L<PAR> or L<PAR::Dist>. |
| 477 | |
| 478 | It requires that the PAR::Dist module (version 0.17 and up) is |
| 479 | installed on your system. |
| 480 | |
| 481 | =item ppd |
| 482 | |
| 483 | [version 0.20] |
| 484 | |
| 485 | Build a PPD file for your distribution. |
| 486 | |
| 487 | This action takes an optional argument C<codebase> which is used in |
| 488 | the generated ppd file to specify the (usually relative) URL of the |
| 489 | distribution. By default, this value is the distribution name without |
| 490 | any path information. |
| 491 | |
| 492 | Example: |
| 493 | |
| 494 | ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz" |
| 495 | |
| 496 | =item ppmdist |
| 497 | |
| 498 | [version 0.23] |
| 499 | |
| 500 | Generates a PPM binary distribution and a PPD description file. This |
| 501 | action also invokes the 'ppd' action, so it can accept the same |
| 502 | C<codebase> argument described under that action. |
| 503 | |
| 504 | This uses the same mechanism as the C<dist> action to tar & zip its |
| 505 | output, so you can supply C<tar> and/or C<gzip> parameters to affect |
| 506 | the result. |
| 507 | |
| 508 | =item prereq_report |
| 509 | |
| 510 | [version 0.28] |
| 511 | |
| 512 | This action prints out a list of all prerequisites, the versions required, and |
| 513 | the versions actually installed. This can be useful for reviewing the |
| 514 | configuration of your system prior to a build, or when compiling data to send |
| 515 | for a bug report. |
| 516 | |
| 517 | =item pure_install |
| 518 | |
| 519 | [version 0.28] |
| 520 | |
| 521 | This action is identical to the C<install> action. In the future, |
| 522 | though, if C<install> starts writing to the file file |
| 523 | F<$(INSTALLARCHLIB)/perllocal.pod>, C<pure_install> won't, and that |
| 524 | will be the only difference between them. |
| 525 | |
| 526 | =item realclean |
| 527 | |
| 528 | [version 0.01] |
| 529 | |
| 530 | This action is just like the C<clean> action, but also removes the |
| 531 | C<_build> directory and the C<Build> script. If you run the |
| 532 | C<realclean> action, you are essentially starting over, so you will |
| 533 | have to re-create the C<Build> script again. |
| 534 | |
| 535 | =item retest |
| 536 | |
| 537 | [version 0.2806] |
| 538 | |
| 539 | This is just like the C<test> action, but doesn't actually build the |
| 540 | distribution first, and doesn't add F<blib/> to the load path, and |
| 541 | therefore will test against a I<previously> installed version of the |
| 542 | distribution. This can be used to verify that a certain installed |
| 543 | distribution still works, or to see whether newer versions of a |
| 544 | distribution still pass the old regression tests, and so on. |
| 545 | |
| 546 | =item skipcheck |
| 547 | |
| 548 | [version 0.05] |
| 549 | |
| 550 | Reports which files are skipped due to the entries in the |
| 551 | F<MANIFEST.SKIP> file (See L<manifest> for details) |
| 552 | |
| 553 | =item test |
| 554 | |
| 555 | [version 0.01] |
| 556 | |
| 557 | This will use C<Test::Harness> to run any regression tests and report |
| 558 | their results. Tests can be defined in the standard places: a file |
| 559 | called C<test.pl> in the top-level directory, or several files ending |
| 560 | with C<.t> in a C<t/> directory. |
| 561 | |
| 562 | If you want tests to be 'verbose', i.e. show details of test execution |
| 563 | rather than just summary information, pass the argument C<verbose=1>. |
| 564 | |
| 565 | If you want to run tests under the perl debugger, pass the argument |
| 566 | C<debugger=1>. |
| 567 | |
| 568 | In addition, if a file called C<visual.pl> exists in the top-level |
| 569 | directory, this file will be executed as a Perl script and its output |
| 570 | will be shown to the user. This is a good place to put speed tests or |
| 571 | other tests that don't use the C<Test::Harness> format for output. |
| 572 | |
| 573 | To override the choice of tests to run, you may pass a C<test_files> |
| 574 | argument whose value is a whitespace-separated list of test scripts to |
| 575 | run. This is especially useful in development, when you only want to |
| 576 | run a single test to see whether you've squashed a certain bug yet: |
| 577 | |
| 578 | ./Build test --test_files t/something_failing.t |
| 579 | |
| 580 | You may also pass several C<test_files> arguments separately: |
| 581 | |
| 582 | ./Build test --test_files t/one.t --test_files t/two.t |
| 583 | |
| 584 | or use a C<glob()>-style pattern: |
| 585 | |
| 586 | ./Build test --test_files 't/01-*.t' |
| 587 | |
| 588 | =item testcover |
| 589 | |
| 590 | [version 0.26] |
| 591 | |
| 592 | Runs the C<test> action using C<Devel::Cover>, generating a |
| 593 | code-coverage report showing which parts of the code were actually |
| 594 | exercised during the tests. |
| 595 | |
| 596 | To pass options to C<Devel::Cover>, set the C<$DEVEL_COVER_OPTIONS> |
| 597 | environment variable: |
| 598 | |
| 599 | DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover |
| 600 | |
| 601 | =item testdb |
| 602 | |
| 603 | [version 0.05] |
| 604 | |
| 605 | This is a synonym for the 'test' action with the C<debugger=1> |
| 606 | argument. |
| 607 | |
| 608 | =item testpod |
| 609 | |
| 610 | [version 0.25] |
| 611 | |
| 612 | This checks all the files described in the C<docs> action and |
| 613 | produces C<Test::Harness>-style output. If you are a module author, |
| 614 | this is useful to run before creating a new release. |
| 615 | |
| 616 | =item testpodcoverage |
| 617 | |
| 618 | [version 0.28] |
| 619 | |
| 620 | This checks the pod coverage of the distribution and |
| 621 | produces C<Test::Harness>-style output. If you are a module author, |
| 622 | this is useful to run before creating a new release. |
| 623 | |
| 624 | =item versioninstall |
| 625 | |
| 626 | [version 0.16] |
| 627 | |
| 628 | ** Note: since C<only.pm> is so new, and since we just recently added |
| 629 | support for it here too, this feature is to be considered |
| 630 | experimental. ** |
| 631 | |
| 632 | If you have the C<only.pm> module installed on your system, you can |
| 633 | use this action to install a module into the version-specific library |
| 634 | trees. This means that you can have several versions of the same |
| 635 | module installed and C<use> a specific one like this: |
| 636 | |
| 637 | use only MyModule => 0.55; |
| 638 | |
| 639 | To override the default installation libraries in C<only::config>, |
| 640 | specify the C<versionlib> parameter when you run the C<Build.PL> script: |
| 641 | |
| 642 | perl Build.PL --versionlib /my/version/place/ |
| 643 | |
| 644 | To override which version the module is installed as, specify the |
| 645 | C<versionlib> parameter when you run the C<Build.PL> script: |
| 646 | |
| 647 | perl Build.PL --version 0.50 |
| 648 | |
| 649 | See the C<only.pm> documentation for more information on |
| 650 | version-specific installs. |
| 651 | |
| 652 | =back |
| 653 | |
| 654 | |
| 655 | =head1 OPTIONS |
| 656 | |
| 657 | =head2 Command Line Options |
| 658 | |
| 659 | The following options can be used during any invocation of C<Build.PL> |
| 660 | or the Build script, during any action. For information on other |
| 661 | options specific to an action, see the documentation for the |
| 662 | respective action. |
| 663 | |
| 664 | NOTE: There is some preliminary support for options to use the more |
| 665 | familiar long option style. Most options can be preceded with the |
| 666 | C<--> long option prefix, and the underscores changed to dashes |
| 667 | (e.g. --use-rcfile). Additionally, the argument to boolean options is |
| 668 | optional, and boolean options can be negated by prefixing them with |
| 669 | 'no' or 'no-' (e.g. --noverbose or --no-verbose). |
| 670 | |
| 671 | =over 4 |
| 672 | |
| 673 | =item quiet |
| 674 | |
| 675 | Suppress informative messages on output. |
| 676 | |
| 677 | =item use_rcfile |
| 678 | |
| 679 | Load the F<~/.modulebuildrc> option file. This option can be set to |
| 680 | false to prevent the custom resource file from being loaded. |
| 681 | |
| 682 | =item verbose |
| 683 | |
| 684 | Display extra information about the Build on output. |
| 685 | |
| 686 | =item allow_mb_mismatch |
| 687 | |
| 688 | Suppresses the check upon startup that the version of Module::Build |
| 689 | we're now running under is the same version that was initially invoked |
| 690 | when building the distribution (i.e. when the C<Build.PL> script was |
| 691 | first run). Use with caution. |
| 692 | |
| 693 | =back |
| 694 | |
| 695 | |
| 696 | =head2 Default Options File (F<.modulebuildrc>) |
| 697 | |
| 698 | [version 0.28] |
| 699 | |
| 700 | When Module::Build starts up, it will look first for a file, |
| 701 | F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look |
| 702 | in the the F<.modulebuildrc> file in the directories referred to by |
| 703 | the environment variables C<HOMEDRIVE> + C<HOMEDIR>, C<USERPROFILE>, |
| 704 | C<APPDATA>, C<WINDIR>, C<SYS$LOGIN>. If the file exists, the options |
| 705 | specified there will be used as defaults, as if they were typed on the |
| 706 | command line. The defaults can be overridden by specifying new values |
| 707 | on the command line. |
| 708 | |
| 709 | The action name must come at the beginning of the line, followed by any |
| 710 | amount of whitespace and then the options. Options are given the same |
| 711 | as they would be on the command line. They can be separated by any |
| 712 | amount of whitespace, including newlines, as long there is whitespace at |
| 713 | the beginning of each continued line. Anything following a hash mark (C<#>) |
| 714 | is considered a comment, and is stripped before parsing. If more than |
| 715 | one line begins with the same action name, those lines are merged into |
| 716 | one set of options. |
| 717 | |
| 718 | Besides the regular actions, there are two special pseudo-actions: the |
| 719 | key C<*> (asterisk) denotes any global options that should be applied |
| 720 | to all actions, and the key 'Build_PL' specifies options to be applied |
| 721 | when you invoke C<perl Build.PL>. |
| 722 | |
| 723 | * verbose=1 # global options |
| 724 | diff flags=-u |
| 725 | install --install_base /home/ken |
| 726 | --install_path html=/home/ken/docs/html |
| 727 | |
| 728 | If you wish to locate your resource file in a different location, you |
| 729 | can set the environment variable 'MODULEBUILDRC' to the complete |
| 730 | absolute path of the file containing your options. |
| 731 | |
| 732 | |
| 733 | =head1 INSTALL PATHS |
| 734 | |
| 735 | [version 0.19] |
| 736 | |
| 737 | When you invoke Module::Build's C<build> action, it needs to figure |
| 738 | out where to install things. The nutshell version of how this works |
| 739 | is that default installation locations are determined from |
| 740 | F<Config.pm>, and they may be overridden by using the C<install_path> |
| 741 | parameter. An C<install_base> parameter lets you specify an |
| 742 | alternative installation root like F</home/foo>, and a C<destdir> lets |
| 743 | you specify a temporary installation directory like F</tmp/install> in |
| 744 | case you want to create bundled-up installable packages. |
| 745 | |
| 746 | Natively, Module::Build provides default installation locations for |
| 747 | the following types of installable items: |
| 748 | |
| 749 | =over 4 |
| 750 | |
| 751 | =item lib |
| 752 | |
| 753 | Usually pure-Perl module files ending in F<.pm>. |
| 754 | |
| 755 | =item arch |
| 756 | |
| 757 | "Architecture-dependent" module files, usually produced by compiling |
| 758 | XS, Inline, or similar code. |
| 759 | |
| 760 | =item script |
| 761 | |
| 762 | Programs written in pure Perl. In order to improve reuse, try to make |
| 763 | these as small as possible - put the code into modules whenever |
| 764 | possible. |
| 765 | |
| 766 | =item bin |
| 767 | |
| 768 | "Architecture-dependent" executable programs, i.e. compiled C code or |
| 769 | something. Pretty rare to see this in a perl distribution, but it |
| 770 | happens. |
| 771 | |
| 772 | =item bindoc |
| 773 | |
| 774 | Documentation for the stuff in C<script> and C<bin>. Usually |
| 775 | generated from the POD in those files. Under Unix, these are manual |
| 776 | pages belonging to the 'man1' category. |
| 777 | |
| 778 | =item libdoc |
| 779 | |
| 780 | Documentation for the stuff in C<lib> and C<arch>. This is usually |
| 781 | generated from the POD in F<.pm> files. Under Unix, these are manual |
| 782 | pages belonging to the 'man3' category. |
| 783 | |
| 784 | =item binhtml |
| 785 | |
| 786 | This is the same as C<bindoc> above, but applies to html documents. |
| 787 | |
| 788 | =item libhtml |
| 789 | |
| 790 | This is the same as C<bindoc> above, but applies to html documents. |
| 791 | |
| 792 | =back |
| 793 | |
| 794 | Four other parameters let you control various aspects of how |
| 795 | installation paths are determined: |
| 796 | |
| 797 | =over 4 |
| 798 | |
| 799 | =item installdirs |
| 800 | |
| 801 | The default destinations for these installable things come from |
| 802 | entries in your system's C<Config.pm>. You can select from three |
| 803 | different sets of default locations by setting the C<installdirs> |
| 804 | parameter as follows: |
| 805 | |
| 806 | 'installdirs' set to: |
| 807 | core site vendor |
| 808 | |
| 809 | uses the following defaults from Config.pm: |
| 810 | |
| 811 | lib => installprivlib installsitelib installvendorlib |
| 812 | arch => installarchlib installsitearch installvendorarch |
| 813 | script => installscript installsitebin installvendorbin |
| 814 | bin => installbin installsitebin installvendorbin |
| 815 | bindoc => installman1dir installsiteman1dir installvendorman1dir |
| 816 | libdoc => installman3dir installsiteman3dir installvendorman3dir |
| 817 | binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*] |
| 818 | libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*] |
| 819 | |
| 820 | * Under some OS (eg. MSWin32) the destination for html documents is |
| 821 | determined by the C<Config.pm> entry C<installhtmldir>. |
| 822 | |
| 823 | The default value of C<installdirs> is "site". If you're creating |
| 824 | vendor distributions of module packages, you may want to do something |
| 825 | like this: |
| 826 | |
| 827 | perl Build.PL --installdirs vendor |
| 828 | |
| 829 | or |
| 830 | |
| 831 | ./Build install --installdirs vendor |
| 832 | |
| 833 | If you're installing an updated version of a module that was included |
| 834 | with perl itself (i.e. a "core module"), then you may set |
| 835 | C<installdirs> to "core" to overwrite the module in its present |
| 836 | location. |
| 837 | |
| 838 | (Note that the 'script' line is different from MakeMaker - |
| 839 | unfortunately there's no such thing as "installsitescript" or |
| 840 | "installvendorscript" entry in C<Config.pm>, so we use the |
| 841 | "installsitebin" and "installvendorbin" entries to at least get the |
| 842 | general location right. In the future, if C<Config.pm> adds some more |
| 843 | appropriate entries, we'll start using those.) |
| 844 | |
| 845 | =item install_path |
| 846 | |
| 847 | Once the defaults have been set, you can override them. |
| 848 | |
| 849 | On the command line, that would look like this: |
| 850 | |
| 851 | perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch |
| 852 | |
| 853 | or this: |
| 854 | |
| 855 | ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch |
| 856 | |
| 857 | =item install_base |
| 858 | |
| 859 | You can also set the whole bunch of installation paths by supplying the |
| 860 | C<install_base> parameter to point to a directory on your system. For |
| 861 | instance, if you set C<install_base> to "/home/ken" on a Linux |
| 862 | system, you'll install as follows: |
| 863 | |
| 864 | lib => /home/ken/lib/perl5 |
| 865 | arch => /home/ken/lib/perl5/i386-linux |
| 866 | script => /home/ken/bin |
| 867 | bin => /home/ken/bin |
| 868 | bindoc => /home/ken/man/man1 |
| 869 | libdoc => /home/ken/man/man3 |
| 870 | binhtml => /home/ken/html |
| 871 | libhtml => /home/ken/html |
| 872 | |
| 873 | Note that this is I<different> from how MakeMaker's C<PREFIX> |
| 874 | parameter works. C<install_base> just gives you a default layout under the |
| 875 | directory you specify, which may have little to do with the |
| 876 | C<installdirs=site> layout. |
| 877 | |
| 878 | The exact layout under the directory you specify may vary by system - |
| 879 | we try to do the "sensible" thing on each platform. |
| 880 | |
| 881 | =item destdir |
| 882 | |
| 883 | If you want to install everything into a temporary directory first |
| 884 | (for instance, if you want to create a directory tree that a package |
| 885 | manager like C<rpm> or C<dpkg> could create a package from), you can |
| 886 | use the C<destdir> parameter: |
| 887 | |
| 888 | perl Build.PL --destdir /tmp/foo |
| 889 | |
| 890 | or |
| 891 | |
| 892 | ./Build install --destdir /tmp/foo |
| 893 | |
| 894 | This will effectively install to "/tmp/foo/$sitelib", |
| 895 | "/tmp/foo/$sitearch", and the like, except that it will use |
| 896 | C<File::Spec> to make the pathnames work correctly on whatever |
| 897 | platform you're installing on. |
| 898 | |
| 899 | =item prefix |
| 900 | |
| 901 | Provided for compatibility with ExtUtils::MakeMaker's PREFIX argument. |
| 902 | C<prefix> should be used when you wish Module::Build to install your |
| 903 | modules, documentation and scripts in the same place |
| 904 | ExtUtils::MakeMaker does. |
| 905 | |
| 906 | The following are equivalent. |
| 907 | |
| 908 | perl Build.PL --prefix /tmp/foo |
| 909 | perl Makefile.PL PREFIX=/tmp/foo |
| 910 | |
| 911 | Because of the very complex nature of the prefixification logic, the |
| 912 | behavior of PREFIX in MakeMaker has changed subtly over time. |
| 913 | Module::Build's --prefix logic is equivalent to the PREFIX logic found |
| 914 | in ExtUtils::MakeMaker 6.30. |
| 915 | |
| 916 | If you do not need to retain compatibility with ExtUtils::MakeMaker or |
| 917 | are starting a fresh Perl installation we recommand you use |
| 918 | C<install_base> instead (and C<INSTALL_BASE> in ExtUtils::MakeMaker). |
| 919 | See L<Module::Build::Cookbook/Instaling in the same location as |
| 920 | ExtUtils::MakeMaker> for further information. |
| 921 | |
| 922 | |
| 923 | =back |
| 924 | |
| 925 | |
| 926 | =head1 MOTIVATIONS |
| 927 | |
| 928 | There are several reasons I wanted to start over, and not just fix |
| 929 | what I didn't like about MakeMaker: |
| 930 | |
| 931 | =over 4 |
| 932 | |
| 933 | =item * |
| 934 | |
| 935 | I don't like the core idea of MakeMaker, namely that C<make> should be |
| 936 | involved in the build process. Here are my reasons: |
| 937 | |
| 938 | =over 4 |
| 939 | |
| 940 | =item + |
| 941 | |
| 942 | When a person is installing a Perl module, what can you assume about |
| 943 | their environment? Can you assume they have C<make>? No, but you can |
| 944 | assume they have some version of Perl. |
| 945 | |
| 946 | =item + |
| 947 | |
| 948 | When a person is writing a Perl module for intended distribution, can |
| 949 | you assume that they know how to build a Makefile, so they can |
| 950 | customize their build process? No, but you can assume they know Perl, |
| 951 | and could customize that way. |
| 952 | |
| 953 | =back |
| 954 | |
| 955 | For years, these things have been a barrier to people getting the |
| 956 | build/install process to do what they want. |
| 957 | |
| 958 | =item * |
| 959 | |
| 960 | There are several architectural decisions in MakeMaker that make it |
| 961 | very difficult to customize its behavior. For instance, when using |
| 962 | MakeMaker you do C<use ExtUtils::MakeMaker>, but the object created in |
| 963 | C<WriteMakefile()> is actually blessed into a package name that's |
| 964 | created on the fly, so you can't simply subclass |
| 965 | C<ExtUtils::MakeMaker>. There is a workaround C<MY> package that lets |
| 966 | you override certain MakeMaker methods, but only certain explicitly |
| 967 | preselected (by MakeMaker) methods can be overridden. Also, the method |
| 968 | of customization is very crude: you have to modify a string containing |
| 969 | the Makefile text for the particular target. Since these strings |
| 970 | aren't documented, and I<can't> be documented (they take on different |
| 971 | values depending on the platform, version of perl, version of |
| 972 | MakeMaker, etc.), you have no guarantee that your modifications will |
| 973 | work on someone else's machine or after an upgrade of MakeMaker or |
| 974 | perl. |
| 975 | |
| 976 | =item * |
| 977 | |
| 978 | It is risky to make major changes to MakeMaker, since it does so many |
| 979 | things, is so important, and generally works. C<Module::Build> is an |
| 980 | entirely separate package so that I can work on it all I want, without |
| 981 | worrying about backward compatibility. |
| 982 | |
| 983 | =item * |
| 984 | |
| 985 | Finally, Perl is said to be a language for system administration. |
| 986 | Could it really be the case that Perl isn't up to the task of building |
| 987 | and installing software? Even if that software is a bunch of stupid |
| 988 | little C<.pm> files that just need to be copied from one place to |
| 989 | another? My sense was that we could design a system to accomplish |
| 990 | this in a flexible, extensible, and friendly manner. Or die trying. |
| 991 | |
| 992 | =back |
| 993 | |
| 994 | |
| 995 | =head1 TO DO |
| 996 | |
| 997 | The current method of relying on time stamps to determine whether a |
| 998 | derived file is out of date isn't likely to scale well, since it |
| 999 | requires tracing all dependencies backward, it runs into problems on |
| 1000 | NFS, and it's just generally flimsy. It would be better to use an MD5 |
| 1001 | signature or the like, if available. See C<cons> for an example. |
| 1002 | |
| 1003 | - append to perllocal.pod |
| 1004 | - add a 'plugin' functionality |
| 1005 | |
| 1006 | |
| 1007 | =head1 AUTHOR |
| 1008 | |
| 1009 | Ken Williams <kwilliams@cpan.org> |
| 1010 | |
| 1011 | Development questions, bug reports, and patches should be sent to the |
| 1012 | Module-Build mailing list at <module-build@perl.org>. |
| 1013 | |
| 1014 | Bug reports are also welcome at |
| 1015 | <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. |
| 1016 | |
| 1017 | The latest development version is available from the Subversion |
| 1018 | repository at <https://svn.perl.org/modules/Module-Build/trunk/> |
| 1019 | |
| 1020 | |
| 1021 | =head1 COPYRIGHT |
| 1022 | |
| 1023 | Copyright (c) 2001-2006 Ken Williams. All rights reserved. |
| 1024 | |
| 1025 | This library is free software; you can redistribute it and/or |
| 1026 | modify it under the same terms as Perl itself. |
| 1027 | |
| 1028 | |
| 1029 | =head1 SEE ALSO |
| 1030 | |
| 1031 | perl(1), L<Module::Build::Cookbook>, L<Module::Build::Authoring>, |
| 1032 | L<Module::Build::API>, L<ExtUtils::MakeMaker>, L<YAML> |
| 1033 | |
| 1034 | F<META.yml> Specification: |
| 1035 | L<http://module-build.sourceforge.net/META-spec-current.html> |
| 1036 | |
| 1037 | L<http://www.dsmit.com/cons/> |
| 1038 | |
| 1039 | L<http://search.cpan.org/dist/PerlBuildSystem/> |
| 1040 | |
| 1041 | =cut |