From 342e672574c4e67d510e46ab6acd0e21a7d0cf54 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 26 Apr 2015 22:16:26 +0000 Subject: (tl)perl 5.20.2 for windows, from siep git-svn-id: svn://tug.org/texlive/trunk@37064 c570f23f-e606-0410-a88d-b1316a301751 --- Master/tlpkg/tlperl/lib/Module/Build.pm | 18 +- Master/tlpkg/tlperl/lib/Module/Build/API.pod | 2124 ++++++++++++++++++++ Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod | 326 +++ Master/tlpkg/tlperl/lib/Module/Build/Base.pm | 565 +++--- Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod | 147 ++ Master/tlpkg/tlperl/lib/Module/Build/Compat.pm | 7 +- Master/tlpkg/tlperl/lib/Module/Build/Config.pm | 2 +- Master/tlpkg/tlperl/lib/Module/Build/ConfigData.pm | 64 +- Master/tlpkg/tlperl/lib/Module/Build/Cookbook.pm | 2 +- Master/tlpkg/tlperl/lib/Module/Build/Dumper.pm | 2 +- Master/tlpkg/tlperl/lib/Module/Build/ModuleInfo.pm | 2 +- Master/tlpkg/tlperl/lib/Module/Build/Notes.pm | 20 +- Master/tlpkg/tlperl/lib/Module/Build/PPMMaker.pm | 10 +- .../tlperl/lib/Module/Build/Platform/Amiga.pm | 34 - .../tlperl/lib/Module/Build/Platform/Default.pm | 2 +- .../tlperl/lib/Module/Build/Platform/EBCDIC.pm | 34 - .../tlperl/lib/Module/Build/Platform/MPEiX.pm | 34 - .../tlperl/lib/Module/Build/Platform/MacOS.pm | 2 +- .../tlperl/lib/Module/Build/Platform/RiscOS.pm | 34 - .../tlpkg/tlperl/lib/Module/Build/Platform/Unix.pm | 6 +- .../tlpkg/tlperl/lib/Module/Build/Platform/VMS.pm | 47 +- .../tlpkg/tlperl/lib/Module/Build/Platform/VOS.pm | 2 +- .../tlperl/lib/Module/Build/Platform/Windows.pm | 13 +- .../tlpkg/tlperl/lib/Module/Build/Platform/aix.pm | 2 +- .../tlperl/lib/Module/Build/Platform/cygwin.pm | 2 +- .../tlperl/lib/Module/Build/Platform/darwin.pm | 2 +- .../tlpkg/tlperl/lib/Module/Build/Platform/os2.pm | 2 +- Master/tlpkg/tlperl/lib/Module/Build/PodParser.pm | 6 +- Master/tlpkg/tlperl/lib/Module/CoreList.pm | 2053 ++++++++++++++++++- Master/tlpkg/tlperl/lib/Module/CoreList.pod | 251 +++ .../tlperl/lib/Module/CoreList/TieHashDelta.pm | 6 +- Master/tlpkg/tlperl/lib/Module/CoreList/Utils.pm | 133 +- Master/tlpkg/tlperl/lib/Module/Load.pm | 214 +- Master/tlpkg/tlperl/lib/Module/Load/Conditional.pm | 35 +- Master/tlpkg/tlperl/lib/Module/Metadata.pm | 125 +- Master/tlpkg/tlperl/lib/Module/Pluggable.pm | 457 ----- Master/tlpkg/tlperl/lib/Module/Pluggable/Object.pm | 405 ---- 37 files changed, 5685 insertions(+), 1505 deletions(-) create mode 100644 Master/tlpkg/tlperl/lib/Module/Build/API.pod create mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod create mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod delete mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Platform/Amiga.pm delete mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Platform/EBCDIC.pm delete mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Platform/MPEiX.pm delete mode 100644 Master/tlpkg/tlperl/lib/Module/Build/Platform/RiscOS.pm create mode 100644 Master/tlpkg/tlperl/lib/Module/CoreList.pod delete mode 100644 Master/tlpkg/tlperl/lib/Module/Pluggable.pm delete mode 100644 Master/tlpkg/tlperl/lib/Module/Pluggable/Object.pm (limited to 'Master/tlpkg/tlperl/lib/Module') diff --git a/Master/tlpkg/tlperl/lib/Module/Build.pm b/Master/tlpkg/tlperl/lib/Module/Build.pm index fd835fc0659..aee7b44c1f5 100644 --- a/Master/tlpkg/tlperl/lib/Module/Build.pm +++ b/Master/tlpkg/tlperl/lib/Module/Build.pm @@ -1,5 +1,7 @@ package Module::Build; +use if $] >= 5.019, 'deprecate'; + # This module doesn't do much of anything itself, it inherits from the # modules that do the real work. The only real thing it has to do is # figure out which OS-specific module to pull in. Many of the @@ -16,10 +18,9 @@ use Module::Build::Base; use vars qw($VERSION @ISA); @ISA = qw(Module::Build::Base); -$VERSION = '0.4003'; +$VERSION = '0.4205'; $VERSION = eval $VERSION; - # Inserts the given module into the @ISA hierarchy between # Module::Build and its immediate parent sub _interpose_module { @@ -94,10 +95,7 @@ C. Developers may alter the behavior of the module through subclassing in a much more straightforward way than with C. It also does not require a C on your system - most of the C code is pure-perl and written in a very -cross-platform way. In fact, you don't even need a shell, so even -platforms like MacOS (traditional) can use it fairly easily. Its only -prerequisites are modules that are included with perl 5.6.0, and it -works fine on perl 5.005 if you can install a few additional modules. +cross-platform way. See L<"MOTIVATIONS"> for more comparisons between C and C. @@ -379,6 +377,12 @@ C. You can also supply or override install paths on the command line by specifying C values for the C and/or C installation targets. +With an optional C argument set to a false value, you can +skip the search for other documentation to link to, because that can +waste a lot of time if there aren't any links to generate anyway: + + ./Build html --html_links 0 + =item install [version 0.01] @@ -747,7 +751,7 @@ executed build actions. When Module::Build starts up, it will look first for a file, F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look -in the the F<.modulebuildrc> file in the directories referred to by +in the F<.modulebuildrc> file in the directories referred to by the environment variables C + C, C, C, C, C. If the file exists, the options specified there will be used as defaults, as if they were typed on the diff --git a/Master/tlpkg/tlperl/lib/Module/Build/API.pod b/Master/tlpkg/tlperl/lib/Module/Build/API.pod new file mode 100644 index 00000000000..af859e7fe40 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Module/Build/API.pod @@ -0,0 +1,2124 @@ +=head1 NAME + +Module::Build::API - API Reference for Module Authors + +=for :stopwords apache bsd distdir distsign gpl installdirs lgpl mit mozilla packlists + +=head1 DESCRIPTION + +I list here some of the most important methods in C. +Normally you won't need to deal with these methods unless you want to +subclass C. But since one of the reasons I created +this module in the first place was so that subclassing is possible +(and easy), I will certainly write more docs as the interface +stabilizes. + + +=head2 CONSTRUCTORS + +=over 4 + +=item current() + +[version 0.20] + +This method returns a reasonable facsimile of the currently-executing +C object representing the current build. You can use +this object to query its L method, inquire about installed +modules, and so on. This is a great way to share information between +different parts of your build process. For instance, you can ask +the user a question during C, then use their answer +during a regression test: + + # In Build.PL: + my $color = $build->prompt("What is your favorite color?"); + $build->notes(color => $color); + + # In t/colortest.t: + use Module::Build; + my $build = Module::Build->current; + my $color = $build->notes('color'); + ... + +The way the C method is currently implemented, there may be +slight differences between the C<$build> object in Build.PL and the +one in C. It is our goal to minimize these differences +in future releases of Module::Build, so please report any anomalies +you find. + +One important caveat: in its current implementation, C will +B work correctly if you have changed out of the directory that +C was invoked from. + +=item new() + +[version 0.03] + +Creates a new Module::Build object. Arguments to the new() method are +listed below. Most arguments are optional, but you must provide +either the L argument, or L and one of +L or L. In other words, you must +provide enough information to determine both a distribution name and +version. + + +=over 4 + +=item add_to_cleanup + +[version 0.19] + +An array reference of files to be cleaned up when the C action +is performed. See also the L +method. + +=item allow_pureperl + +[version 0.4005] + +A bool indicating the module is still functional without its xs parts. +When an XS module is build with --pureperl_only, it will otherwise fail. + +=item auto_configure_requires + +[version 0.34] + +This parameter determines whether Module::Build will add itself +automatically to configure_requires (and build_requires) if Module::Build +is not already there. The required version will be the last 'major' release, +as defined by the decimal version truncated to two decimal places (e.g. 0.34, +instead of 0.3402). The default value is true. + +=item auto_features + +[version 0.26] + +This parameter supports the setting of features (see +L) automatically based on a set of prerequisites. For +instance, for a module that could optionally use either MySQL or +PostgreSQL databases, you might use C like this: + + my $build = Module::Build->new + ( + ...other stuff here... + auto_features => { + pg_support => { + description => "Interface with Postgres databases", + requires => { 'DBD::Pg' => 23.3, + 'DateTime::Format::Pg' => 0 }, + }, + mysql_support => { + description => "Interface with MySQL databases", + requires => { 'DBD::mysql' => 17.9, + 'DateTime::Format::MySQL' => 0 }, + }, + } + ); + +For each feature named, the required prerequisites will be checked, and +if there are no failures, the feature will be enabled (set to C<1>). +Otherwise the failures will be displayed to the user and the feature +will be disabled (set to C<0>). + +See the documentation for L for the details of how +requirements can be specified. + +=item autosplit + +[version 0.04] + +An optional C argument specifies a file which should be run +through the L function. +If multiple files should be split, the argument may be given as an +array of the files to split. + +In general I don't consider autosplitting a great idea, because it's +not always clear that autosplitting achieves its intended performance +benefits. It may even harm performance in environments like mod_perl, +where as much as possible of a module's code should be loaded during +startup. + +=item build_class + +[version 0.28] + +The Module::Build class or subclass to use in the build script. +Defaults to "Module::Build" or the class name passed to or created by +a call to L. This property is useful if you're +writing a custom Module::Build subclass and have a bootstrapping +problem--that is, your subclass requires modules that may not be +installed when C is executed, but you've listed in +L so that they should be available when C<./Build> is +executed. + +=item build_requires + +[version 0.07] + +Modules listed in this section are necessary to build and install the +given module, but are not necessary for regular usage of it. This is +actually an important distinction - it allows for tighter control over +the body of installed modules, and facilitates correct dependency +checking on binary/packaged distributions of the module. + +See the documentation for L +for the details of how requirements can be specified. + +=item configure_requires + +[version 0.30] + +Modules listed in this section must be installed I configuring +this distribution (i.e. before running the F script). +This might be a specific minimum version of C or any +other module the F needs in order to do its stuff. Clients +like C or C will be expected to pick +C out of the F file and install these +items before running the C. + +Module::Build may automatically add itself to configure_requires. +See L for details. + +See the documentation for L +for the details of how requirements can be specified. + +=item test_requires + +[version 0.4004] + +Modules listed in this section must be installed before testing the distribution. + +See the documentation for L +for the details of how requirements can be specified. + +=item create_packlist + +[version 0.28] + +If true, this parameter tells Module::Build to create a F<.packlist> +file during the C action, just like C does. +The file is created in a subdirectory of the C installation +location. It is used by some other tools (CPAN, CPANPLUS, etc.) for +determining what files are part of an install. + +The default value is true. This parameter was introduced in +Module::Build version 0.2609; previously no packlists were ever +created by Module::Build. + +=item c_source + +[version 0.04] + +An optional C argument specifies a directory which contains +C source files that the rest of the build may depend on. Any C<.c> +files in the directory will be compiled to object files. The +directory will be added to the search path during the compilation and +linking phases of any C or XS files. + +[version 0.3604] + +A list of directories can be supplied using an anonymous array +reference of strings. + +=item conflicts + +[version 0.07] + +Modules listed in this section conflict in some serious way with the +given module. C (or some higher-level tool) will +refuse to install the given module if the given module/version is also +installed. + +See the documentation for L +for the details of how requirements can be specified. + +=item create_license + +[version 0.31] + +This parameter tells Module::Build to automatically create a +F file at the top level of your distribution, containing the +full text of the author's chosen license. This requires +C on the author's machine, and further requires +that the C parameter specifies a license that it knows about. + +=item create_makefile_pl + +[version 0.19] + +This parameter lets you use C during the +C (or C) action to automatically create a Makefile.PL +for compatibility with C. The parameter's value +should be one of the styles named in the L +documentation. + +=item create_readme + +[version 0.22] + +This parameter tells Module::Build to automatically create a F +file at the top level of your distribution. Currently it will simply +use C (or C if it's installed) on the file +indicated by C and put the result in the F +file. This is by no means the only recommended style for writing a +F, but it seems to be one common one used on the CPAN. + +If you generate a F in this way, it's probably a good idea to +create a separate F file if that information isn't in the +generated F. + +=item dist_abstract + +[version 0.20] + +This should be a short description of the distribution. This is used when +generating metadata for F and PPD files. If it is not given +then C looks in the POD of the module from which it gets +the distribution's version. If it finds a POD section marked "=head1 +NAME", then it looks for the first line matching C<\s+-\s+(.+)>, +and uses the captured text as the abstract. + +=item dist_author + +[version 0.20] + +This should be something like "John Doe ", or if +there are multiple authors, an anonymous array of strings may be +specified. This is used when generating metadata for F and +PPD files. If this is not specified, then C looks at +the module from which it gets the distribution's version. If it finds +a POD section marked "=head1 AUTHOR", then it uses the contents of +this section. + +=item dist_name + +[version 0.11] + +Specifies the name for this distribution. Most authors won't need to +set this directly, they can use C to set C to +a reasonable default. However, some agglomerative distributions like +C or C have names that don't correspond directly +to a module name, so C can be set independently. + +=item dist_suffix + +[version 0.37] + +Specifies an optional suffix to include after the version number +in the distribution directory (and tarball) name. The only suffix +currently recognized by PAUSE is 'TRIAL', which indicates that the +distribution should not be indexed. For example: + + Foo-Bar-1.23-TRIAL.tar.gz + +This will automatically do the "right thing" depending on C and +C. When C does not have an underscore and +C is not 'stable', then C will default to 'TRIAL'. +Otherwise it will default to the empty string, disabling the suffix. + +In general, authors should only set this if they B override the default +behavior for some particular purpose. + +=item dist_version + +[version 0.11] + +Specifies a version number for the distribution. See L +or L for ways to have this set automatically from a +C<$VERSION> variable in a module. One way or another, a version +number needs to be set. + +=item dist_version_from + +[version 0.11] + +Specifies a file to look for the distribution version in. Most +authors won't need to set this directly, they can use L +to set it to a reasonable default. + +The version is extracted from the specified file according to the same +rules as L and C. It involves finding +the first line that matches the regular expression + + /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/ + +eval()-ing that line, then checking the value of the C<$VERSION> +variable. Quite ugly, really, but all the modules on CPAN depend on +this process, so there's no real opportunity to change to something +better. + +If the target file of L contains more than one package +declaration, the version returned will be the one matching the configured +L. + +=item dynamic_config + +[version 0.07] + +A boolean flag indicating whether the F file must be +executed, or whether this module can be built, tested and installed +solely from consulting its metadata file. The main reason to set this +to a true value is that your module performs some dynamic +configuration as part of its build/install process. If the flag is +omitted, the F spec says that installation tools should +treat it as 1 (true), because this is a safer way to behave. + +Currently C doesn't actually do anything with this flag +- it's up to higher-level tools like C to do something useful +with it. It can potentially bring lots of security, packaging, and +convenience improvements. + +=item extra_compiler_flags + +=item extra_linker_flags + +[version 0.19] + +These parameters can contain array references (or strings, in which +case they will be split into arrays) to pass through to the compiler +and linker phases when compiling/linking C code. For example, to tell +the compiler that your code is C++, you might do: + + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + extra_compiler_flags => ['-x', 'c++'], + ); + +To link your XS code against glib you might write something like: + + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + dynamic_config => 1, + extra_compiler_flags => scalar `glib-config --cflags`, + extra_linker_flags => scalar `glib-config --libs`, + ); + +=item extra_manify_args + +[version 0.4006] + +Any extra arguments to pass to C<< Pod::Man->new() >> when building +man pages. One common choice might be C<< utf8 => 1 >> to get Unicode +support. + +=item get_options + +[version 0.26] + +You can pass arbitrary command line options to F or +F, and they will be stored in the Module::Build object and can +be accessed via the L method. However, sometimes you want +more flexibility out of your argument processing than this allows. In +such cases, use the C parameter to pass in a hash +reference of argument specifications, and the list of arguments to +F or F will be processed according to those +specifications before they're passed on to C's own +argument processing. + +The supported option specification hash keys are: + + +=over 4 + +=item type + +The type of option. The types are those supported by Getopt::Long; consult +its documentation for a complete list. Typical types are C<=s> for strings, +C<+> for additive options, and C for negatable options. If the +type is not specified, it will be considered a boolean, i.e. no +argument is taken and a value of 1 will be assigned when the option is +encountered. + +=item store + +A reference to a scalar in which to store the value passed to the option. +If not specified, the value will be stored under the option name in the +hash returned by the C method. + +=item default + +A default value for the option. If no default value is specified and no option +is passed, then the option key will not exist in the hash returned by +C. + +=back + + +You can combine references to your own variables or subroutines with +unreferenced specifications, for which the result will also be stored in the +hash returned by C. For example: + + my $loud = 0; + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + get_options => { + Loud => { store => \$loud }, + Dbd => { type => '=s' }, + Quantity => { type => '+' }, + } + ); + + print STDERR "HEY, ARE YOU LISTENING??\n" if $loud; + print "We'll use the ", $build->args('Dbd'), " DBI driver\n"; + print "Are you sure you want that many?\n" + if $build->args('Quantity') > 2; + +The arguments for such a specification can be called like so: + + perl Build.PL --Loud --Dbd=DBD::pg --Quantity --Quantity --Quantity + +B Any option specifications that conflict with Module::Build's own +options (defined by its properties) will throw an exception. Use capitalized +option names to avoid unintended conflicts with future Module::Build options. + +Consult the Getopt::Long documentation for details on its usage. + +=item include_dirs + +[version 0.24] + +Specifies any additional directories in which to search for C header +files. May be given as a string indicating a single directory, or as +a list reference indicating multiple directories. + +=item install_path + +[version 0.19] + +You can set paths for individual installable elements by using the +C parameter: + + my $build = Module::Build->new + ( + ...other stuff here... + install_path => { + lib => '/foo/lib', + arch => '/foo/lib/arch', + } + ); + +=item installdirs + +[version 0.19] + +Determines where files are installed within the normal perl hierarchy +as determined by F. Valid values are: C, C, +C. The default is C. See +L + +=item license + +[version 0.07] + +Specifies the licensing terms of your distribution. + +As of Module::Build version 0.36_14, you may use a L +subclass name (e.g. 'Apache_2_0') instead of one of the keys below. + +The legacy list of valid license values include: + +=over 4 + +=item apache + +The distribution is licensed under the Apache License, Version 2.0 +(L). + +=item apache_1_1 + +The distribution is licensed under the Apache Software License, Version 1.1 +(L). + +=item artistic + +The distribution is licensed under the Artistic License, as specified +by the F file in the standard Perl distribution. + +=item artistic_2 + +The distribution is licensed under the Artistic 2.0 License +(L.) + +=item bsd + +The distribution is licensed under the BSD License +(L). + +=item gpl + +The distribution is licensed under the terms of the GNU General +Public License (L). + +=item lgpl + +The distribution is licensed under the terms of the GNU Lesser +General Public License +(L). + +=item mit + +The distribution is licensed under the MIT License +(L). + +=item mozilla + +The distribution is licensed under the Mozilla Public +License. (L or +L) + +=item open_source + +The distribution is licensed under some other Open Source +Initiative-approved license listed at +L. + +=item perl + +The distribution may be copied and redistributed under the same terms +as Perl itself (this is by far the most common licensing option for +modules on CPAN). This is a dual license, in which the user may +choose between either the GPL or the Artistic license. + +=item restrictive + +The distribution may not be redistributed without special permission +from the author and/or copyright holder. + +=item unrestricted + +The distribution is licensed under a license that is B approved +by www.opensource.org but that allows distribution without +restrictions. + +=back + +Note that you must still include the terms of your license in your +code and documentation - this field only sets the information that is included +in distribution metadata to let automated tools figure out your +licensing restrictions. Humans still need something to read. If you +choose to provide this field, you should make sure that you keep it in +sync with your written documentation if you ever change your licensing +terms. + +You may also use a license type of C if you don't wish to +specify your terms in the metadata. + +Also see the C parameter. + +=item meta_add + +[version 0.28] + +A hash of key/value pairs that should be added to the F file +during the C action. Any existing entries with the same +names will be overridden. + +See the L section for details. + +=item meta_merge + +[version 0.28] + +A hash of key/value pairs that should be merged into the F +file during the C action. Any existing entries with the +same names will be overridden. + +The only difference between C and C is their +behavior on hash-valued and array-valued entries: C will +completely blow away the existing hash or array value, but +C will merge the supplied data into the existing hash or +array value. + +See the L section for details. + +=item module_name + +[version 0.03] + +The C is a shortcut for setting default values of +C and C, reflecting the fact that the +majority of CPAN distributions are centered around one "main" module. +For instance, if you set C to C, then +C will default to C and C will +default to C. C will in turn be +used to set C. + +Setting C won't override a C parameter you +specify explicitly. + +=item needs_compiler + +[version 0.36] + +The C parameter indicates whether a compiler is required to +build the distribution. The default is false, unless XS files are found or +the C parameter is set, in which case it is true. If true, +L is automatically added to C if needed. + +For a distribution where a compiler is I, e.g. a dual XS/pure-Perl +distribution, C should explicitly be set to a false value. + +=item PL_files + +[version 0.06] + +An optional parameter specifying a set of C<.PL> files in your +distribution. These will be run as Perl scripts prior to processing +the rest of the files in your distribution with the name of the file +they're generating as an argument. They are usually used as templates +for creating other files dynamically, so that a file like +C might create the file C. + +The files are specified with the C<.PL> files as hash keys, and the +file(s) they generate as hash values, like so: + + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + ... + PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' }, + ); + +Note that the path specifications are I given in Unix-like +format, not in the style of the local system. + +If your C<.PL> scripts don't create any files, or if they create files +with unexpected names, or even if they create multiple files, you can +indicate that so that Module::Build can properly handle these created +files: + + PL_files => { + 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm', + 'lib/something.PL' => ['/lib/something', '/lib/else'], + 'lib/funny.PL' => [], + } + +Here's an example of a simple PL file. + + my $output_file = shift; + open my $fh, ">", $output_file or die "Can't open $output_file: $!"; + + print $fh <<'END'; + #!/usr/bin/perl + + print "Hello, world!\n"; + END + +PL files are not installed by default, so its safe to put them in +F and F. + + +=item pm_files + +[version 0.19] + +An optional parameter specifying the set of C<.pm> files in this +distribution, specified as a hash reference whose keys are the files' +locations in the distributions, and whose values are their logical +locations based on their package name, i.e. where they would be found +in a "normal" Module::Build-style distribution. This parameter is +mainly intended to support alternative layouts of files. + +For instance, if you have an old-style C distribution for a +module called C and a F file at the top level of the +distribution, you could specify your layout in your C like +this: + + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + ... + pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' }, + ); + +Note that the values should include C, because this is where +they would be found in a "normal" Module::Build-style distribution. + +Note also that the path specifications are I given in +Unix-like format, not in the style of the local system. + +=item pod_files + +[version 0.19] + +Just like C, but used for specifying the set of C<.pod> +files in your distribution. + +=item recommends + +[version 0.08] + +This is just like the L argument, except that modules listed +in this section aren't essential, just a good idea. We'll just print +a friendly warning if one of these modules aren't found, but we'll +continue running. + +If a module is recommended but not required, all tests should still +pass if the module isn't installed. This may mean that some tests +may be skipped if recommended dependencies aren't present. + +Automated tools like CPAN.pm should inform the user when recommended +modules aren't installed, and it should offer to install them if it +wants to be helpful. + +See the documentation for L +for the details of how requirements can be specified. + +=item recursive_test_files + +[version 0.28] + +Normally, C does not search subdirectories when looking +for tests to run. When this options is set it will search recursively +in all subdirectories of the standard 't' test directory. + +=item release_status + +[version 0.37] + +The CPAN Meta Spec version 2 adds C to allow authors +to specify how a distribution should be indexed. Consistent with the +spec, this parameter can only have one three values: 'stable', +'testing' or 'unstable'. + +Unless explicitly set by the author, C will default +to 'stable' unless C contains an underscore, in which +case it will default to 'testing'. + +It is an error to specify a C of 'stable' when +C contains an underscore character. + +=item requires + +[version 0.07] + +An optional C argument specifies any module prerequisites +that the current module depends on. + +One note: currently C doesn't actually I the +user to have dependencies installed, it just strongly urges. In the +future we may require it. There's also a L section for +things that aren't absolutely required. + +Automated tools like CPAN.pm should refuse to install a module if one +of its dependencies isn't satisfied, unless a "force" command is given +by the user. If the tools are helpful, they should also offer to +install the dependencies. + +A synonym for C is C, to help succour people +transitioning from C. The C term is +preferred, but the C term will remain valid in future +distributions. + +See the documentation for L +for the details of how requirements can be specified. + +=item script_files + +[version 0.18] + +An optional parameter specifying a set of files that should be +installed as executable Perl scripts when the module is installed. +May be given as an array reference of the files, as a hash reference +whose keys are the files (and whose values will currently be ignored), +as a string giving the name of a directory in which to find scripts, +or as a string giving the name of a single script file. + +The default is to install any scripts found in a F directory at +the top level of the distribution, minus any keys of L. + +For backward compatibility, you may use the parameter C +instead of C. Please consider this usage deprecated, +though it will continue to exist for several version releases. + +=item share_dir + +[version 0.36] + +An optional parameter specifying directories of static data files to +be installed as read-only files for use with L. The +C property supports both distribution-level and +module-level share files. + +The simplest use of C is to set it to a directory name or an +arrayref of directory names containing files to be installed in the +distribution-level share directory. + + share_dir => 'share' + +Alternatively, if C is a hashref, it may have C or +C keys providing full flexibility in defining how share +directories should be installed. + + share_dir => { + dist => [ 'examples', 'more_examples' ], + module => { + Foo::Templates => ['share/html', 'share/text'], + Foo::Config => 'share/config', + } + } + +If C is set, then File::ShareDir will automatically be added +to the C hash. + +=item sign + +[version 0.16] + +If a true value is specified for this parameter, L +will be used (via the 'distsign' action) to create a SIGNATURE file +for your distribution during the 'distdir' action, and to add the +SIGNATURE file to the MANIFEST (therefore, don't add it yourself). + +The default value is false. In the future, the default may change to +true if you have C installed on your system. + +=item tap_harness_args + +[version 0.2808_03] + +An optional parameter specifying parameters to be passed to TAP::Harness when +running tests. Must be given as a hash reference of parameters; see the +L documentation for details. Note that specifying +this parameter will implicitly set C to a true value. You +must therefore be sure to add TAP::Harness as a requirement for your module in +L. + +=item test_files + +[version 0.23] + +An optional parameter specifying a set of files that should be used as +C-style regression tests to be run during the C +action. May be given as an array reference of the files, or as a hash +reference whose keys are the files (and whose values will currently be +ignored). If the argument is given as a single string (not in an +array reference), that string will be treated as a C pattern +specifying the files to use. + +The default is to look for a F script in the top-level +directory of the distribution, and any files matching the glob pattern +C<*.t> in the F subdirectory. If the C +property is true, then the C directory will be scanned recursively +for C<*.t> files. + +=item use_tap_harness + +[version 0.2808_03] + +An optional parameter indicating whether or not to use TAP::Harness for +testing rather than Test::Harness. Defaults to false. If set to true, you must +therefore be sure to add TAP::Harness as a requirement for your module in +L. Implicitly set to a true value if C is +specified. + +=item xs_files + +[version 0.19] + +Just like C, but used for specifying the set of C<.xs> +files in your distribution. + +=back + + +=item new_from_context(%args) + +[version 0.28] + +When called from a directory containing a F script (in other words, +the base directory of a distribution), this method will run the F and +call C to return the resulting C object to the caller. +Any key-value arguments given to C are essentially like +command line arguments given to the F script, so for example you +could pass C<< verbose => 1 >> to this method to turn on verbosity. + +=item resume() + +[version 0.03] + +You'll probably never call this method directly, it's only called from the +auto-generated C script (and the C method). The +C method is only called once, when the user runs C. +Thereafter, when the user runs C or another action, the +C object is created using the C method to +re-instantiate with the settings given earlier to C. + +=item subclass() + +[version 0.06] + +This creates a new C subclass on the fly, as described +in the L section. The caller +must provide either a C or C parameter, or both. The +C parameter indicates the name to use for the new subclass, and +defaults to C. The C parameter specifies Perl +code to use as the body of the subclass. + +=item add_property + +[version 0.31] + + package 'My::Build'; + use base 'Module::Build'; + __PACKAGE__->add_property( 'pedantic' ); + __PACKAGE__->add_property( answer => 42 ); + __PACKAGE__->add_property( + 'epoch', + default => sub { time }, + check => sub { + return 1 if /^\d+$/; + shift->property_error( "'$_' is not an epoch time" ); + return 0; + }, + ); + +Adds a property to a Module::Build class. Properties are those attributes of a +Module::Build object which can be passed to the constructor and which have +accessors to get and set them. All of the core properties, such as +C and C, are defined using this class method. + +The first argument to C is always the name of the property. +The second argument can be either a default value for the property, or a list +of key/value pairs. The supported keys are: + +=over + +=item C + +The default value. May optionally be specified as a code reference, in which +case the return value from the execution of the code reference will be used. +If you need the default to be a code reference, just use a code reference to +return it, e.g.: + + default => sub { sub { ... } }, + +=item C + +A code reference that checks that a value specified for the property is valid. +During the execution of the code reference, the new value will be included in +the C<$_> variable. If the value is correct, the C code reference +should return true. If the value is not correct, it sends an error message to +C and returns false. + +=back + +When this method is called, a new property will be installed in the +Module::Build class, and an accessor will be built to allow the property to be +get or set on the build object. + + print $build->pedantic, $/; + $build->pedantic(0); + +If the default value is a hash reference, this generates a special-case +accessor method, wherein individual key/value pairs may be set or fetched: + + print "stuff{foo} is: ", $build->stuff( 'foo' ), $/; + $build->stuff( foo => 'bar' ); + print $build->stuff( 'foo' ), $/; # Outputs "bar" + +Of course, you can still set the entire hash reference at once, as well: + + $build->stuff( { foo => 'bar', baz => 'yo' } ); + +In either case, if a C has been specified for the property, it will be +applied to the entire hash. So the check code reference should look something +like: + + check => sub { + return 1 if defined $_ && exists $_->{foo}; + shift->property_error(qq{Property "stuff" needs "foo"}); + return 0; + }, + +=item property_error + +[version 0.31] + +=back + + +=head2 METHODS + +=over 4 + +=item add_build_element($type) + +[version 0.26] + +Adds a new type of entry to the build process. Accepts a single +string specifying its type-name. There must also be a method defined +to process things of that type, e.g. if you add a build element called +C<'foo'>, then you must also define a method called +C. + +See also +L. + +=item add_to_cleanup(@files) + +[version 0.03] + +You may call C<< $self->add_to_cleanup(@patterns) >> to tell +C that certain files should be removed when the user +performs the C action. The arguments to the method are +patterns suitable for passing to Perl's C function, specified +in either Unix format or the current machine's native format. It's +usually convenient to use Unix format when you hard-code the filenames +(e.g. in F) and the native format when the names are +programmatically generated (e.g. in a testing script). + +I decided to provide a dynamic method of the C<$build> object, rather +than just use a static list of files named in the F, because +these static lists can get difficult to manage. I usually prefer to +keep the responsibility for registering temporary files close to the +code that creates them. + +=item args() + +[version 0.26] + + my $args_href = $build->args; + my %args = $build->args; + my $arg_value = $build->args($key); + $build->args($key, $value); + +This method is the preferred interface for retrieving the arguments passed via +command line options to F or F, minus the Module-Build +specific options. + +When called in a scalar context with no arguments, this method returns a +reference to the hash storing all of the arguments; in an array context, it +returns the hash itself. When passed a single argument, it returns the value +stored in the args hash for that option key. When called with two arguments, +the second argument is assigned to the args hash under the key passed as the +first argument. + +=item autosplit_file($from, $to) + +[version 0.28] + +Invokes the L module on the C<$from> file, sending the +output to the C directory inside C<$to>. C<$to> is +typically the C directory. + +=item base_dir() + +[version 0.14] + +Returns a string containing the root-level directory of this build, +i.e. where the C script and the C directory can be +found. This is usually the same as the current working directory, +because the C script will C into this directory as +soon as it begins execution. + +=item build_requires() + +[version 0.21] + +Returns a hash reference indicating the C +prerequisites that were passed to the C method. + +=item can_action( $action ) + +Returns a reference to the method that defines C<$action>, or false +otherwise. This is handy for actions defined (or maybe not!) in subclasses. + +[version 0.32_xx] + +=item cbuilder() + +[version 0.2809] + +Returns the internal ExtUtils::CBuilder object that can be used for +compiling & linking C code. If no such object is available (e.g. if +the system has no compiler installed) an exception will be thrown. + +=item check_installed_status($module, $version) + +[version 0.11] + +This method returns a hash reference indicating whether a version +dependency on a certain module is satisfied. The C<$module> argument +is given as a string like C<"Data::Dumper"> or C<"perl">, and the +C<$version> argument can take any of the forms described in L +above. This allows very fine-grained version checking. + +The returned hash reference has the following structure: + + { + ok => $whether_the_dependency_is_satisfied, + have => $version_already_installed, + need => $version_requested, # Same as incoming $version argument + message => $informative_error_message, + } + +If no version of C<$module> is currently installed, the C value +will be the string C<< "" >>. Otherwise the C value will +simply be the version of the installed module. Note that this means +that if C<$module> is installed but doesn't define a version number, +the C value will be C - this is why we don't use C +for the case when C<$module> isn't installed at all. + +This method may be called either as an object method +(C<< $build->check_installed_status($module, $version) >>) +or as a class method +(C<< Module::Build->check_installed_status($module, $version) >>). + +=item check_installed_version($module, $version) + +[version 0.05] + +Like L, +but simply returns true or false depending on whether module +C<$module> satisfies the dependency C<$version>. + +If the check succeeds, the return value is the actual version of +C<$module> installed on the system. This allows you to do the +following: + + my $installed = $build->check_installed_version('DBI', '1.15'); + if ($installed) { + print "Congratulations, version $installed of DBI is installed.\n"; + } else { + die "Sorry, you must install DBI.\n"; + } + +If the check fails, we return false and set C<$@> to an informative +error message. + +If C<$version> is any non-true value (notably zero) and any version of +C<$module> is installed, we return true. In this case, if C<$module> +doesn't define a version, or if its version is zero, we return the +special value "0 but true", which is numerically zero, but logically +true. + +In general you might prefer to use C if you +need detailed information, or this method if you just need a yes/no +answer. + +=item compare_versions($v1, $op, $v2) + +[version 0.28] + +Compares two module versions C<$v1> and C<$v2> using the operator +C<$op>, which should be one of Perl's numeric operators like C or +C<< >= >> or the like. We do at least a halfway-decent job of +handling versions that aren't strictly numeric, like C<0.27_02>, but +exotic stuff will likely cause problems. + +In the future, the guts of this method might be replaced with a call +out to C. + +=item config($key) + +=item config($key, $value) + +=item config() [deprecated] + +[version 0.22] + +With a single argument C<$key>, returns the value associated with that +key in the C hash, including any changes the author or user +has specified. + +With C<$key> and C<$value> arguments, sets the value for future +callers of C. + +With no arguments, returns a hash reference containing all such +key-value pairs. This usage is deprecated, though, because it's a +resource hog and violates encapsulation. + +=item config_data($name) + +=item config_data($name => $value) + +[version 0.26] + +With a single argument, returns the value of the configuration +variable C<$name>. With two arguments, sets the given configuration +variable to the given value. The value may be any Perl scalar that's +serializable with C. For instance, if you write a +module that can use a MySQL or PostgreSQL back-end, you might create +configuration variables called C and +C, and set each to an array of connection parameters +for C<< DBI->connect() >>. + +Configuration values set in this way using the Module::Build object +will be available for querying during the build/test process and after +installation via the generated C<...::ConfigData> module, as +C<< ...::ConfigData->config($name) >>. + +The L and C methods represent +Module::Build's main support for configuration of installed modules. +See also L. + +=item conflicts() + +[version 0.21] + +Returns a hash reference indicating the C prerequisites +that were passed to the C method. + +=item contains_pod($file) [deprecated] + +[version 0.20] + +[Deprecated] Please see L instead. + +Returns true if the given file appears to contain POD documentation. +Currently this checks whether the file has a line beginning with +'=pod', '=head', or '=item', but the exact semantics may change in the +future. + +=item copy_if_modified(%parameters) + +[version 0.19] + +Takes the file in the C parameter and copies it to the file in +the C parameter, or the directory in the C parameter, if +the file has changed since it was last copied (or if it doesn't exist +in the new location). By default the entire directory structure of +C will be copied into C; an optional C +parameter will copy into C without doing so. + +Returns the path to the destination file, or C if nothing +needed to be copied. + +Any directories that need to be created in order to perform the +copying will be automatically created. + +The destination file is set to read-only. If the source file has the +executable bit set, then the destination file will be made executable. + +=item create_build_script() + +[version 0.05] + +Creates an executable script called C in the current directory +that will be used to execute further user actions. This script is +roughly analogous (in function, not in form) to the Makefile created +by C. This method also creates some temporary +data in a directory called C<_build/>. Both of these will be removed +when the C action is performed. + +Among the files created in C<_build/> is a F<_build/prereqs> file +containing the set of prerequisites for this distribution, as a hash +of hashes. This file may be C-ed to obtain the authoritative +set of prerequisites, which might be different from the contents of +F (because F might have set them dynamically). +But fancy developers take heed: do not put any fancy custom runtime +code in the F<_build/prereqs> file, leave it as a static declaration +containing only strings and numbers. Similarly, do not alter the +structure of the internal C<< $self->{properties}{requires} >> (etc.) +data members, because that's where this data comes from. + +=item current_action() + +[version 0.28] + +Returns the name of the currently-running action, such as "build" or +"test". This action is not necessarily the action that was originally +invoked by the user. For example, if the user invoked the "test" +action, current_action() would initially return "test". However, +action "test" depends on action "code", so current_action() will +return "code" while that dependency is being executed. Once that +action has completed, current_action() will again return "test". + +If you need to know the name of the original action invoked by the +user, see L below. + +=item depends_on(@actions) + +[version 0.28] + +Invokes the named action or list of actions in sequence. Using this +method is preferred to calling the action explicitly because it +performs some internal record-keeping, and it ensures that the same +action is not invoked multiple times (note: in future versions of +Module::Build it's conceivable that this run-only-once mechanism will +be changed to something more intelligent). + +Note that the name of this method is something of a misnomer; it +should really be called something like +C or something, but for +better or worse (perhaps better!) we were still thinking in +C-like dependency terms when we created this method. + +See also L. The main +distinction between the two is that C is meant to call +an action from inside another action, whereas C is meant +to set the very top action in motion. + +=item dir_contains($first_dir, $second_dir) + +[version 0.28] + +Returns true if the first directory logically contains the second +directory. This is just a convenience function because C +doesn't really provide an easy way to figure this out (but +C does...). + +=item dispatch($action, %args) + +[version 0.03] + +Invokes the build action C<$action>. Optionally, a list of options +and their values can be passed in. This is equivalent to invoking an +action at the command line, passing in a list of options. + +Custom options that have not been registered must be passed in as a +hash reference in a key named "args": + + $build->dispatch('foo', verbose => 1, args => { my_option => 'value' }); + +This method is intended to be used to programmatically invoke build +actions, e.g. by applications controlling Module::Build-based builds +rather than by subclasses. + +See also L. The main +distinction between the two is that C is meant to call +an action from inside another action, whereas C is meant +to set the very top action in motion. + +=item dist_dir() + +[version 0.28] + +Returns the name of the directory that will be created during the +C action. The name is derived from the C and +C properties. + +=item dist_name() + +[version 0.21] + +Returns the name of the current distribution, as passed to the +C method in a C or modified C +parameter. + +=item dist_version() + +[version 0.21] + +Returns the version of the current distribution, as determined by the +C method from a C, C, or +C parameter. + +=item do_system($cmd, @args) + +[version 0.21] + +This is a fairly simple wrapper around Perl's C built-in +command. Given a command and an array of optional arguments, this +method will print the command to C, and then execute it using +Perl's C. It returns true or false to indicate success or +failure (the opposite of how C works, but more intuitive). + +Note that if you supply a single argument to C, it +will/may be processed by the system's shell, and any special +characters will do their special things. If you supply multiple +arguments, no shell will get involved and the command will be executed +directly. + +=item extra_compiler_flags() + +=item extra_compiler_flags(@flags) + +[version 0.25] + +Set or retrieve the extra compiler flags. Returns an arrayref of flags. + +=item extra_linker_flags() + +=item extra_linker_flags(@flags) + +[version 0.25] + +Set or retrieve the extra linker flags. Returns an arrayref of flags. + +=item feature($name) + +=item feature($name => $value) + +[version 0.26] + +With a single argument, returns true if the given feature is set. +With two arguments, sets the given feature to the given boolean value. +In this context, a "feature" is any optional functionality of an +installed module. For instance, if you write a module that could +optionally support a MySQL or PostgreSQL backend, you might create +features called C and C, and set them +to true/false depending on whether the user has the proper databases +installed and configured. + +Features set in this way using the Module::Build object will be +available for querying during the build/test process and after +installation via the generated C<...::ConfigData> module, as +C<< ...::ConfigData->feature($name) >>. + +The C and C methods represent +Module::Build's main support for configuration of installed modules. +See also L. + +=item fix_shebang_line(@files) + +[version 0.??] + +Modify any "shebang" line in the specified files to use the path to the +perl executable being used for the current build. Files are modified +in-place. The existing shebang line must have a command that contains +"C"; arguments to the command do not count. In particular, this +means that the use of C<#!/usr/bin/env perl> will not be changed. + +For an explanation of shebang lines, see +L. + +=item have_c_compiler() + +[version 0.21] + +Returns true if the current system seems to have a working C compiler. +We currently determine this by attempting to compile a simple C source +file and reporting whether the attempt was successful. + +=item install_base_relpaths() + +=item install_base_relpaths($type) + +=item install_base_relpaths($type => $path) + +[version 0.28] + +Set or retrieve the relative paths that are appended to +C for any installable element. This is useful if you +want to set the relative install path for custom build elements. + +With no argument, it returns a reference to a hash containing all +elements and their respective values. This hash should not be modified +directly; use the multiple argument below form to change values. + +The single argument form returns the value associated with the +element C<$type>. + +The multiple argument form allows you to set the paths for element types. +C<$value> must be a relative path using Unix-like paths. (A series of +directories separated by slashes, e.g. C.) The return value is a +localized path based on C<$value>. + +Assigning the value C to an element causes it to be removed. + +=item install_destination($type) + +[version 0.28] + +Returns the directory in which items of type C<$type> (e.g. C, +C, C, or anything else returned by the L +method) will be installed during the C action. Any settings +for C, C, and C are taken into +account when determining the return value. + +=item install_path() + +=item install_path($type) + +=item install_path($type => $path) + +[version 0.28] + +Set or retrieve paths for specific installable elements. This is +useful when you want to examine any explicit install paths specified +by the user on the command line, or if you want to set the install +path for a specific installable element based on another attribute +like C. + +With no argument, it returns a reference to a hash containing all +elements and their respective values. This hash should not be modified +directly; use the multiple argument below form to change values. + +The single argument form returns the value associated with the +element C<$type>. + +The multiple argument form allows you to set the paths for element types. +The supplied C<$path> should be an absolute path to install elements +of C<$type>. The return value is C<$path>. + +Assigning the value C to an element causes it to be removed. + +=item install_types() + +[version 0.28] + +Returns a list of installable types that this build knows about. +These types each correspond to the name of a directory in F, +and the list usually includes items such as C, C, C, +C