"Fossies" - the Fresh Open Source Software Archive

Member "Module-Build-0.4229/lib/Module/Build.pm" (15 Apr 2019, 35409 Bytes) of package /linux/privat/Module-Build-0.4229.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Build.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 0.4224_vs_0.4229.

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