## "Fossies" - the Fresh Open Source Software Archive

### Member "Module-Build-0.4224/README" (30 May 2017, 34976 Bytes) of package /linux/privat/Module-Build-0.4224.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 0.4222_vs_0.4224.

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