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