"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,
   83     etc., tasks.
   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,
  213       abstract, prerequisites, license, and various other data about the
  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 
  286         ./Build html --html_links 0
  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
  339       add your own stuff to it:
  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
  377       installed on your system.
  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 
  392         ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
  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 
  960 COPYRIGHT
  961 
  962     Copyright (c) 2001-2006 Ken Williams. All rights reserved.
  963 
  964     This library is free software; you can redistribute it and/or modify it
  965     under the same terms as Perl itself.
  966 
  967 SEE ALSO
  968 
  969     perl(1), Module::Build::Cookbook, Module::Build::Authoring,
  970     Module::Build::API, ExtUtils::MakeMaker
  971 
  972     META.yml Specification: CPAN::Meta::Spec
  973 
  974     http://www.dsmit.com/cons/
  975 
  976     http://search.cpan.org/dist/PerlBuildSystem/
  977