javonet-ruby-sdk 2.4.9 → 2.4.11

data/lib/javonet-ruby-sdk/Binaries/Perl/MacOs/X64/deps/lib/perl5/Module/Build/API.pod

@@ -1,2127 +0,0 @@
-=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<Module::Build>.
-Normally you won't need to deal with these methods unless you want to
-subclass C<Module::Build>.  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<Module::Build> object representing the current build.  You can use
-this object to query its L</notes()> 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<perl Build.PL>, 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<current()> method is currently implemented, there may be
-slight differences between the C<$build> object in Build.PL and the
-one in C<t/colortest.t>.  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<current()> will
-B<NOT> work correctly if you have changed out of the directory that
-C<Module::Build> 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</module_name> argument, or L</dist_name> and one of
-L</dist_version> or L</dist_version_from>.  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<clean> action
-is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)">
-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</feature($name)>) 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<auto_features> 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</requires> for the details of how
-requirements can be specified.
-
-=item autosplit
-
-[version 0.04]
-
-An optional C<autosplit> argument specifies a file which should be run
-through the L<AutoSplit::autosplit()|AutoSplit/autosplit> 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</subclass()>.  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<perl Build.PL> is executed, but you've listed in
-L</build_requires> 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<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item configure_requires
-
-[version 0.30]
-
-Modules listed in this section must be installed I<before> configuring
-this distribution (i.e. before running the F<Build.PL> script).
-This might be a specific minimum version of C<Module::Build> or any
-other module the F<Build.PL> needs in order to do its stuff.  Clients
-like C<CPAN.pm> or C<CPANPLUS> will be expected to pick
-C<configure_requires> out of the F<META.yml> file and install these
-items before running the C<Build.PL>.
-
-Module::Build may automatically add itself to configure_requires.
-See L</auto_configure_requires> for details.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-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<Module::Build::Authoring/"PREREQUISITES">
-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<install> action, just like C<ExtUtils::MakeMaker> does.
-The file is created in a subdirectory of the C<arch> 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<c_source> argument specifies a directory or a reference to array
-of directories which contain 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<Module::Build> (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<Module::Build::Authoring/"PREREQUISITES">
-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<LICENSE> file at the top level of your distribution, containing the
-full text of the author's chosen license.  This requires
-C<Software::License> on the author's machine, and further requires
-that the C<license> parameter specifies a license that it knows about.
-
-=item create_makefile_pl
-
-[version 0.19]
-
-This parameter lets you use C<Module::Build::Compat> during the
-C<distdir> (or C<dist>) action to automatically create a Makefile.PL
-for compatibility with C<ExtUtils::MakeMaker>.  The parameter's value
-should be one of the styles named in the L<Module::Build::Compat>
-documentation.
-
-Use of this parameter is L<discouraged|Module::Build::Compat/"WARNING">.
-
-=item create_readme
-
-[version 0.22]
-
-This parameter tells Module::Build to automatically create a F<README>
-file at the top level of your distribution.  Currently it will simply
-use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file
-indicated by C<dist_version_from> and put the result in the F<README>
-file.  This is by no means the only recommended style for writing a
-F<README>, but it seems to be one common one used on the CPAN.
-
-If you generate a F<README> in this way, it's probably a good idea to
-create a separate F<INSTALL> file if that information isn't in the
-generated F<README>.
-
-=item dist_abstract
-
-[version 0.20]
-
-This should be a short description of the distribution.  This is used when
-generating metadata for F<META.yml> and PPD files.  If it is not given
-then C<Module::Build> 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 <jdoe@example.com>", or if
-there are multiple authors, an anonymous array of strings may be
-specified.  This is used when generating metadata for F<META.yml> and
-PPD files.  If this is not specified, then C<Module::Build> 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<module_name> to set C<dist_name> to
-a reasonable default.  However, some agglomerative distributions like
-C<libwww-perl> or C<bioperl> have names that don't correspond directly
-to a module name, so C<dist_name> 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<dist_version> and
-C<release_status>.  When C<dist_version> does not have an underscore and
-C<release_status> is not 'stable', then C<dist_suffix> 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<must> override the default
-behavior for some particular purpose.
-
-=item dist_version
-
-[version 0.11]
-
-Specifies a version number for the distribution.  See L</module_name>
-or L</dist_version_from> 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</module_name>
-to set it to a reasonable default.
-
-The version is extracted from the specified file according to the same
-rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>.  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</dist_version_from> contains more than one package
-declaration, the version returned will be the one matching the configured
-L</module_name>.
-
-=item dynamic_config
-
-[version 0.07]
-
-A boolean flag indicating whether the F<Build.PL> file must be
-executed to determine prerequisites, or whether they can be determined
-solely from consulting its metadata file.  The main reason to set this
-to a true value is that your module adds or removes prerequisites
-dynamically in F<Build.PL>.  If the flag is omitted, it will be treated
-as 1 (true), because this is a safer way to behave.
-
-Currently C<Module::Build> doesn't actually do anything with this flag
-- it's up to higher-level tools like C<CPAN.pm> to do something useful
-with it.  It can also be very helpful for static analysis.  See
-L<CPAN::Meta::Spec/dynamic_config> for details on the metadata field.
-
-=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<Build.PL> or
-F<Build>, and they will be stored in the Module::Build object and can
-be accessed via the L</args()> method.  However, sometimes you want
-more flexibility out of your argument processing than this allows.  In
-such cases, use the C<get_options> parameter to pass in a hash
-reference of argument specifications, and the list of arguments to
-F<Build.PL> or F<Build> will be processed according to those
-specifications before they're passed on to C<Module::Build>'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<args()> 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<args()>.
-
-=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<args()>.  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<WARNING:> 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<install_path> 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<Config.pm>.  Valid values are: C<core>, C<site>,
-C<vendor>.  The default is C<site>.  See
-L<Module::Build/"INSTALL PATHS">
-
-=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<Software::License>
-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<http://apache.org/licenses/LICENSE-2.0>).
-
-=item apache_1_1
-
-The distribution is licensed under the Apache Software License, Version 1.1
-(L<http://apache.org/licenses/LICENSE-1.1>).
-
-=item artistic
-
-The distribution is licensed under the Artistic License, as specified
-by the F<Artistic> file in the standard Perl distribution.
-
-=item artistic_2
-
-The distribution is licensed under the Artistic 2.0 License
-(L<http://opensource.org/licenses/artistic-license-2.0.php>.)
-
-=item bsd
-
-The distribution is licensed under the BSD License
-(L<http://www.opensource.org/licenses/bsd-license.php>).
-
-=item gpl
-
-The distribution is licensed under the terms of the GNU General
-Public License (L<http://www.opensource.org/licenses/gpl-license.php>).
-
-=item lgpl
-
-The distribution is licensed under the terms of the GNU Lesser
-General Public License
-(L<http://www.opensource.org/licenses/lgpl-license.php>).
-
-=item mit
-
-The distribution is licensed under the MIT License
-(L<http://opensource.org/licenses/mit-license.php>).
-
-=item mozilla
-
-The distribution is licensed under the Mozilla Public
-License.  (L<http://opensource.org/licenses/mozilla1.0.php> or
-L<http://opensource.org/licenses/mozilla1.1.php>)
-
-=item open_source
-
-The distribution is licensed under some other Open Source
-Initiative-approved license listed at
-L<http://www.opensource.org/licenses/>.
-
-=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<not> 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<unknown> if you don't wish to
-specify your terms in the metadata.
-
-Also see the C<create_license> parameter.
-
-=item meta_add
-
-[version 0.28]
-
-A hash of key/value pairs that should be added to the F<META.yml> file
-during the C<distmeta> action.  Any existing entries with the same
-names will be overridden.
-
-See the L</"MODULE METADATA"> section for details.
-
-=item meta_merge
-
-[version 0.28]
-
-A hash of key/value pairs that should be merged into the F<META.yml>
-file during the C<distmeta> action.  Any existing entries with the
-same names will be overridden.
-
-The only difference between C<meta_add> and C<meta_merge> is their
-behavior on hash-valued and array-valued entries: C<meta_add> will
-completely blow away the existing hash or array value, but
-C<meta_merge> will merge the supplied data into the existing hash or
-array value.
-
-See the L</"MODULE METADATA"> section for details.
-
-=item module_name
-
-[version 0.03]
-
-The C<module_name> is a shortcut for setting default values of
-C<dist_name> and C<dist_version_from>, reflecting the fact that the
-majority of CPAN distributions are centered around one "main" module.
-For instance, if you set C<module_name> to C<Foo::Bar>, then
-C<dist_name> will default to C<Foo-Bar> and C<dist_version_from> will
-default to C<lib/Foo/Bar.pm>.  C<dist_version_from> will in turn be
-used to set C<dist_version>.
-
-Setting C<module_name> won't override a C<dist_*> parameter you
-specify explicitly.
-
-=item needs_compiler
-
-[version 0.36]
-
-The C<needs_compiler> parameter indicates whether a compiler is required to
-build the distribution.  The default is false, unless XS files are found or
-the C<c_source> parameter is set, in which case it is true.  If true,
-L<ExtUtils::CBuilder> is automatically added to C<build_requires> if needed.
-
-For a distribution where a compiler is I<optional>, e.g. a dual XS/pure-Perl
-distribution, C<needs_compiler> 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<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>.
-
-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<always> 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<lib/> and F<bin/>.
-
-
-=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<MakeMaker> distribution for a
-module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the
-distribution, you could specify your layout in your C<Build.PL> 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<lib/>, because this is where
-they would be found in a "normal" Module::Build-style distribution.
-
-Note also that the path specifications are I<always> given in
-Unix-like format, not in the style of the local system.
-
-=item pod_files
-
-[version 0.19]
-
-Just like C<pm_files>, but used for specifying the set of C<.pod>
-files in your distribution.
-
-=item recommends
-
-[version 0.08]
-
-This is just like the L</requires> 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<Module::Build::Authoring/"PREREQUISITES">
-for the details of how requirements can be specified.
-
-=item recursive_test_files
-
-[version 0.28]
-
-Normally, C<Module::Build> 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<release_status> 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<release_status> will default
-to 'stable' unless C<dist_version> contains an underscore, in which
-case it will default to 'testing'.
-
-It is an error to specify a C<release_status> of 'stable' when
-C<dist_version> contains an underscore character.
-
-=item requires
-
-[version 0.07]
-
-An optional C<requires> argument specifies any module prerequisites
-that the current module depends on.
-
-One note: currently C<Module::Build> doesn't actually I<require> the
-user to have dependencies installed, it just strongly urges.  In the
-future we may require it.  There's also a L</recommends> 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<requires> is C<prereq>, to help succour people
-transitioning from C<ExtUtils::MakeMaker>.  The C<requires> term is
-preferred, but the C<prereq> term will remain valid in future
-distributions.
-
-See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
-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<bin> directory at
-the top level of the distribution, minus any keys of L<PL_files>.
-
-For backward compatibility, you may use the parameter C<scripts>
-instead of C<script_files>.  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<File::ShareDir>.  The
-C<share_dir> property supports both distribution-level and
-module-level share files.
-
-The simplest use of C<share_dir> 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<share_dir> is a hashref, it may have C<dist> or
-C<module> 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<share_dir> is set, then File::ShareDir will automatically be added
-to the C<requires> hash.
-
-=item sign
-
-[version 0.16]
-
-If a true value is specified for this parameter, L<Module::Signature>
-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<Module::Signature> 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<TAP::Harness|TAP::Harness> documentation for details. Note that specifying
-this parameter will implicitly set C<use_tap_harness> to a true value. You
-must therefore be sure to add TAP::Harness as a requirement for your module in
-L</build_requires>.
-
-=item test_files
-
-[version 0.23]
-
-An optional parameter specifying a set of files that should be used as
-C<Test::Harness>-style regression tests to be run during the C<test>
-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<glob()> pattern
-specifying the files to use.
-
-The default is to look for a F<test.pl> script in the top-level
-directory of the distribution, and any files matching the glob pattern
-C<*.t> in the F<t/> subdirectory.  If the C<recursive_test_files>
-property is true, then the C<t/> 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</build_requires>. Implicitly set to a true value if C<tap_harness_args> is
-specified.
-
-=item xs_files
-
-[version 0.19]
-
-Just like C<pm_files>, 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<Build.PL> script (in other words,
-the base directory of a distribution), this method will run the F<Build.PL> and
-call C<resume()> to return the resulting C<Module::Build> object to the caller.
-Any key-value arguments given to C<new_from_context()> are essentially like
-command line arguments given to the F<Build.PL> 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<Build> script (and the C<new_from_context> method).  The
-C<new()> method is only called once, when the user runs C<perl Build.PL>.
-Thereafter, when the user runs C<Build test> or another action, the
-C<Module::Build> object is created using the C<resume()> method to
-re-instantiate with the settings given earlier to C<new()>.
-
-=item subclass()
-
-[version 0.06]
-
-This creates a new C<Module::Build> subclass on the fly, as described
-in the L<Module::Build::Authoring/"SUBCLASSING"> section.  The caller
-must provide either a C<class> or C<code> parameter, or both.  The
-C<class> parameter indicates the name to use for the new subclass, and
-defaults to C<MyModuleBuilder>.  The C<code> 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<module_name> and C<license>, are defined using this class method.
-
-The first argument to C<add_property()> 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<default>
-
-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<check>
-
-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<check> code reference
-should return true. If the value is not correct, it sends an error message to
-C<property_error()> 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<check> 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<process_foo_files()>.
-
-See also
-L<Module::Build::Cookbook/"Adding new file types to the build process">.
-
-=item add_to_cleanup(@files)
-
-[version 0.03]
-
-You may call C<< $self->add_to_cleanup(@patterns) >> to tell
-C<Module::Build> that certain files should be removed when the user
-performs the C<Build clean> action.  The arguments to the method are
-patterns suitable for passing to Perl's C<glob()> 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<Build.PL>) 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<Build.PL>, 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<Build.PL> or F<Build>, 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<AutoSplit> module on the C<$from> file, sending the
-output to the C<lib/auto> directory inside C<$to>.  C<$to> is
-typically the C<blib/> directory.
-
-=item base_dir()
-
-[version 0.14]
-
-Returns a string containing the root-level directory of this build,
-i.e. where the C<Build.PL> script and the C<lib> directory can be
-found.  This is usually the same as the current working directory,
-because the C<Build> script will C<chdir()> into this directory as
-soon as it begins execution.
-
-=item build_requires()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<build_requires>
-prerequisites that were passed to the C<new()> 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</requires>
-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<have> value
-will be the string C<< "<none>" >>.  Otherwise the C<have> 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<have> value will be C<undef> - this is why we don't use C<undef>
-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<check_installed_status()|/"check_installed_status($module, $version)">,
-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<check_installed_status> 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<version.pm>.
-
-=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<Config.pm> 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<config($key)>.
-
-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<Data::Dumper>.  For instance, if you write a
-module that can use a MySQL or PostgreSQL back-end, you might create
-configuration variables called C<mysql_connect> and
-C<postgres_connect>, 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<feature()|/"feature($name)"> and C<config_data()> methods represent
-Module::Build's main support for configuration of installed modules.
-See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
-
-=item conflicts()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<conflicts> prerequisites
-that were passed to the C<new()> method.
-
-=item contains_pod($file) [deprecated]
-
-[version 0.20]
-
-[Deprecated] Please see L<Module::Metadata> 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<from> parameter and copies it to the file in
-the C<to> parameter, or the directory in the C<to_dir> 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<from> will be copied into C<to_dir>; an optional C<flatten>
-parameter will copy into C<to_dir> without doing so.
-
-Returns the path to the destination file, or C<undef> 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<Build> 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<ExtUtils::MakeMaker>.  This method also creates some temporary
-data in a directory called C<_build/>.  Both of these will be removed
-when the C<realclean> 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<eval()>-ed to obtain the authoritative
-set of prerequisites, which might be different from the contents of
-F<META.yml> (because F<Build.PL> 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</invoked_action()> 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<invoke_actions_unless_already_invoked()> or something, but for
-better or worse (perhaps better!) we were still thinking in
-C<make>-like dependency terms when we created this method.
-
-See also L<dispatch()|/"dispatch($action, %args)">.  The main
-distinction between the two is that C<depends_on()> is meant to call
-an action from inside another action, whereas C<dispatch()> 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<File::Spec>
-doesn't really provide an easy way to figure this out (but
-C<Path::Class> 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<depends_on()|/"depends_on(@actions)">.  The main
-distinction between the two is that C<depends_on()> is meant to call
-an action from inside another action, whereas C<dispatch()> 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<dist> action.  The name is derived from the C<dist_name> and
-C<dist_version> properties.
-
-=item dist_name()
-
-[version 0.21]
-
-Returns the name of the current distribution, as passed to the
-C<new()> method in a C<dist_name> or modified C<module_name>
-parameter.
-
-=item dist_version()
-
-[version 0.21]
-
-Returns the version of the current distribution, as determined by the
-C<new()> method from a C<dist_version>, C<dist_version_from>, or
-C<module_name> parameter.
-
-=item do_system($cmd, @args)
-
-[version 0.21]
-
-This is a fairly simple wrapper around Perl's C<system()> built-in
-command.  Given a command and an array of optional arguments, this
-method will print the command to C<STDOUT>, and then execute it using
-Perl's C<system()>.  It returns true or false to indicate success or
-failure (the opposite of how C<system()> works, but more intuitive).
-
-Note that if you supply a single argument to C<do_system()>, 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<mysql_support> and C<postgres_support>, 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<feature()> and C<config_data()> methods represent
-Module::Build's main support for configuration of installed modules.
-See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
-
-=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<perl>"; 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<http://en.wikipedia.org/wiki/Shebang_%28Unix%29>.
-
-=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<install_base> 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<foo/bar>.)  The return value is a
-localized path based on C<$value>.
-
-Assigning the value C<undef> 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<lib>,
-C<arch>, C<bin>, or anything else returned by the L</install_types()>
-method) will be installed during the C<install> action.  Any settings
-for C<install_path>, C<install_base>, and C<prefix> 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<install_base()>.
-
-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<undef> 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<blib/>,
-and the list usually includes items such as C<lib>, C<arch>, C<bin>,
-C<script>, C<libdoc>, C<bindoc>, and if HTML documentation is to be
-built, C<libhtml> and C<binhtml>.  Other user-defined types may also
-exist.
-
-=item invoked_action()
-
-[version 0.28]
-
-This is the name of the original action invoked by the user.  This
-value is set when the user invokes F<Build.PL>, the F<Build> script,
-or programmatically through the L<dispatch()|/"dispatch($action, %args)">
-method.  It does not change as sub-actions are executed as
-dependencies are evaluated.
-
-To get the name of the currently executing dependency, see
-L</current_action()> above.
-
-=item notes()
-
-=item notes($key)
-
-=item notes($key => $value)
-
-[version 0.20]
-
-The C<notes()> value allows you to store your own persistent
-information about the build, and to share that information among
-different entities involved in the build.  See the example in the
-C<current()> method.
-
-The C<notes()> method is essentially a glorified hash access.  With no
-arguments, C<notes()> returns the entire hash of notes.  With one argument,
-C<notes($key)> returns the value associated with the given key.  With two
-arguments, C<notes($key, $value)> sets the value associated with the given key
-to C<$value> and returns the new value.
-
-The lifetime of the C<notes> data is for "a build" - that is, the
-C<notes> hash is created when C<perl Build.PL> is run (or when the
-C<new()> method is run, if the Module::Build Perl API is being used
-instead of called from a shell), and lasts until C<perl Build.PL> is
-run again or the C<clean> action is run.
-
-=item orig_dir()
-
-[version 0.28]
-
-Returns a string containing the working directory that was in effect
-before the F<Build> script chdir()-ed into the C<base_dir>.  This
-might be useful for writing wrapper tools that might need to chdir()
-back out.
-
-=item os_type()
-
-[version 0.04]
-
-If you're subclassing Module::Build and some code needs to alter its
-behavior based on the current platform, you may only need to know
-whether you're running on Windows, Unix, MacOS, VMS, etc., and not the
-fine-grained value of Perl's C<$^O> variable.  The C<os_type()> method
-will return a string like C<Windows>, C<Unix>, C<MacOS>, C<VMS>, or
-whatever is appropriate.  If you're running on an unknown platform, it
-will return C<undef> - there shouldn't be many unknown platforms
-though.
-
-=item is_vmsish()
-
-=item is_windowsish()
-
-=item is_unixish()
-
-Convenience functions that return a boolean value indicating whether
-this platform behaves respectively like VMS, Windows, or Unix.  For
-arbitrary reasons other platforms don't get their own such functions,
-at least not yet.
-
-
-=item prefix_relpaths()
-
-=item prefix_relpaths($installdirs)
-
-=item prefix_relpaths($installdirs, $type)
-
-=item prefix_relpaths($installdirs, $type => $path)
-
-[version 0.28]
-
-Set or retrieve the relative paths that are appended to C<prefix> 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 as defined by the current
-C<installdirs> setting.
-
-With a single argument, it returns a reference to a hash containing
-all elements and their respective values as defined by
-C<$installdirs>.
-
-The hash returned by the above calls should not be modified directly;
-use the three-argument below form to change values.
-
-The two 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<foo/bar>.)  The return value is a
-localized path based on C<$value>.
-
-Assigning the value C<undef> to an element causes it to be removed.
-
-=item get_metadata()
-
-[version 0.36]
-
-This method returns a hash reference of metadata that can be used to create a
-YAML datastream. It is provided for authors to override or customize the fields
-of F<META.yml>.   E.g.
-
-  package My::Builder;
-  use base 'Module::Build';
-
-  sub get_metadata {
-    my $self, @args = @_;
-    my $data = $self->SUPER::get_metadata(@args);
-    $data->{custom_field} = 'foo';
-    return $data;
-  }
-
-Valid arguments include:
-
-=over
-
-=item *
-
-C<fatal> -- indicates whether missing required
-metadata fields should be a fatal error or not.  For META creation, it
-generally should, but for MYMETA creation for end-users, it should not be
-fatal.
-
-=item *
-
-C<auto> -- indicates whether any necessary configure_requires should be
-automatically added.  This is used in META creation.
-
-=back
-
-This method is a wrapper around the old prepare_metadata API now that we
-no longer use YAML::Node to hold metadata.
-
-=item prepare_metadata() [deprecated]
-
-[version 0.36]
-
-[Deprecated] As of 0.36, authors should use C<get_metadata> instead.  This
-method is preserved for backwards compatibility only.
-
-It takes three positional arguments: a hashref (to which metadata will be
-added), an optional arrayref (to which metadata keys will be added in order if
-the arrayref exists), and a hashref of arguments (as provided to get_metadata).
-The latter argument is new as of 0.36.  Earlier versions are always fatal on
-errors.
-
-Prior to version 0.36, this method took a YAML::Node as an argument to hold
-assembled metadata.
-
-=item prereq_failures()
-
-[version 0.11]
-
-Returns a data structure containing information about any failed
-prerequisites (of any of the types described above), or C<undef> if
-all prerequisites are met.
-
-The data structure returned is a hash reference.  The top level keys
-are the type of prerequisite failed, one of "requires",
-"build_requires", "conflicts", or "recommends".  The associated values
-are hash references whose keys are the names of required (or
-conflicting) modules.  The associated values of those are hash
-references indicating some information about the failure.  For example:
-
-  {
-   have => '0.42',
-   need => '0.59',
-   message => 'Version 0.42 is installed, but we need version 0.59',
-  }
-
-or
-
-  {
-   have => '<none>',
-   need => '0.59',
-   message => 'Prerequisite Foo isn't installed',
-  }
-
-This hash has the same structure as the hash returned by the
-C<check_installed_status()> method, except that in the case of
-"conflicts" dependencies we change the "need" key to "conflicts" and
-construct a proper message.
-
-Examples:
-
-  # Check a required dependency on Foo::Bar
-  if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
-
-  # Check whether there were any failures
-  if ( $build->prereq_failures ) { ...
-
-  # Show messages for all failures
-  my $failures = $build->prereq_failures;
-  while (my ($type, $list) = each %$failures) {
-    while (my ($name, $hash) = each %$list) {
-      print "Failure for $name: $hash->{message}\n";
-    }
-  }
-
-=item prereq_data()
-
-[version 0.32]
-
-Returns a reference to a hash describing all prerequisites.  The keys of the
-hash will be the various prerequisite types ('requires', 'build_requires',
-'test_requires', 'configure_requires', 'recommends', or 'conflicts') and the values will be
-references to hashes of module names and version numbers.  Only prerequisites
-types that are defined will be included.  The C<prereq_data> action is just a
-thin wrapper around the C<prereq_data()> method and dumps the hash as a string
-that can be loaded using C<eval()>.
-
-=item prereq_report()
-
-[version 0.28]
-
-Returns a human-readable (table-form) string showing all
-prerequisites, the versions required, and the versions actually
-installed.  This can be useful for reviewing the configuration of your
-system prior to a build, or when compiling data to send for a bug
-report.  The C<prereq_report> action is just a thin wrapper around the
-C<prereq_report()> method.
-
-=item prompt($message, $default)
-
-[version 0.12]
-
-Asks the user a question and returns their response as a string.  The
-first argument specifies the message to display to the user (for
-example, C<"Where do you keep your money?">).  The second argument,
-which is optional, specifies a default answer (for example,
-C<"wallet">).  The user will be asked the question once.
-
-If C<prompt()> detects that it is not running interactively and there
-is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
-is set to true, the $default will be used without prompting.
-
-To prevent automated processes from blocking, the user must either set
-PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
-pipe/file containing a scripted set of answers or /dev/null.)
-
-If no $default is provided an empty string will be used instead.  In
-non-interactive mode, the absence of $default is an error (though
-explicitly passing C<undef()> as the default is valid as of 0.27.)
-
-This method may be called as a class or object method.
-
-=item recommends()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<recommends> prerequisites
-that were passed to the C<new()> method.
-
-=item requires()
-
-[version 0.21]
-
-Returns a hash reference indicating the C<requires> prerequisites that
-were passed to the C<new()> method.
-
-=item rscan_dir($dir, $pattern)
-
-[version 0.28]
-
-Uses C<File::Find> to traverse the directory C<$dir>, returning a
-reference to an array of entries matching C<$pattern>.  C<$pattern>
-may either be a regular expression (using C<qr//> or just a plain
-string), or a reference to a subroutine that will return true for
-wanted entries.  If C<$pattern> is not given, all entries will be
-returned.
-
-Examples:
-
- # All the *.pm files in lib/
- $m->rscan_dir('lib', qr/\.pm$/)
-
- # All the files in blib/ that aren't *.html files
- $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
-
- # All the files in t/
- $m->rscan_dir('t');
-
-=item runtime_params()
-
-=item runtime_params($key)
-
-[version 0.28]
-
-The C<runtime_params()> method stores the values passed on the command line
-for valid properties (that is, any command line options for which
-C<valid_property()> returns a true value).  The value on the command line may
-override the default value for a property, as well as any value specified in a
-call to C<new()>.  This allows you to programmatically tell if C<perl Build.PL>
-or any execution of C<./Build> had command line options specified that
-override valid properties.
-
-The C<runtime_params()> method is essentially a glorified read-only hash.  With
-no arguments, C<runtime_params()> returns the entire hash of properties
-specified on the command line.  With one argument, C<runtime_params($key)>
-returns the value associated with the given key.
-
-The lifetime of the C<runtime_params> data is for "a build" - that is, the
-C<runtime_params> hash is created when C<perl Build.PL> is run (or when the
-C<new()> method is called, if the Module::Build Perl API is being used instead
-of called from a shell), and lasts until C<perl Build.PL> is run again or the
-C<clean> action is run.
-
-=item script_files()
-
-[version 0.18]
-
-Returns a hash reference whose keys are the perl script files to be
-installed, if any.  This corresponds to the C<script_files> parameter to the
-C<new()> method.  With an optional argument, this parameter may be set
-dynamically.
-
-For backward compatibility, the C<scripts()> method does exactly the
-same thing as C<script_files()>.  C<scripts()> is deprecated, but it
-will stay around for several versions to give people time to
-transition.
-
-=item up_to_date($source_file, $derived_file)
-
-=item up_to_date(\@source_files, \@derived_files)
-
-[version 0.20]
-
-This method can be used to compare a set of source files to a set of
-derived files.  If any of the source files are newer than any of the
-derived files, it returns false.  Additionally, if any of the derived
-files do not exist, it returns false.  Otherwise it returns true.
-
-The arguments may be either a scalar or an array reference of file
-names.
-
-=item y_n($message, $default)
-
-[version 0.12]
-
-Asks the user a yes/no question using C<prompt()> and returns true or
-false accordingly.  The user will be asked the question repeatedly
-until they give an answer that looks like "yes" or "no".
-
-The first argument specifies the message to display to the user (for
-example, C<"Shall I invest your money for you?">), and the second
-argument specifies the default answer (for example, C<"y">).
-
-Note that the default is specified as a string like C<"y"> or C<"n">,
-and the return value is a Perl boolean value like 1 or 0.  I thought
-about this for a while and this seemed like the most useful way to do
-it.
-
-This method may be called as a class or object method.
-
-=back
-
-
-=head2 Autogenerated Accessors
-
-In addition to the aforementioned methods, there are also some get/set
-accessor methods for the following properties:
-
-=over 4
-
-=item PL_files()
-
-=item allow_mb_mismatch()
-
-=item allow_pureperl()
-
-=item auto_configure_requires()
-
-=item autosplit()
-
-=item base_dir()
-
-=item bindoc_dirs()
-
-=item blib()
-
-=item build_bat()
-
-=item build_class()
-
-=item build_elements()
-
-=item build_requires()
-
-=item build_script()
-
-=item bundle_inc()
-
-=item bundle_inc_preload()
-
-=item c_source()
-
-=item config_dir()
-
-=item configure_requires()
-
-=item conflicts()
-
-=item cover()
-
-=item cpan_client()
-
-=item create_license()
-
-=item create_makefile_pl()
-
-=item create_packlist()
-
-=item create_readme()
-
-=item debug()
-
-=item debugger()
-
-=item destdir()
-
-=item dynamic_config()
-
-=item extra_manify_args()
-
-=item get_options()
-
-=item html_css()
-
-=item include_dirs()
-
-=item install_base()
-
-=item installdirs()
-
-=item libdoc_dirs()
-
-=item license()
-
-=item magic_number()
-
-=item mb_version()
-
-=item meta_add()
-
-=item meta_merge()
-
-=item metafile()
-
-=item metafile2()
-
-=item module_name()
-
-=item mymetafile()
-
-=item mymetafile2()
-
-=item needs_compiler()
-
-=item orig_dir()
-
-=item perl()
-
-=item pm_files()
-
-=item pod_files()
-
-=item pollute()
-
-=item prefix()
-
-=item prereq_action_types()
-
-=item program_name()
-
-=item pureperl_only()
-
-=item quiet()
-
-=item recommends()
-
-=item recurse_into()
-
-=item recursive_test_files()
-
-=item requires()
-
-=item scripts()
-
-=item sign()
-
-=item tap_harness_args()
-
-=item test_file_exts()
-
-=item test_requires()
-
-=item use_rcfile()
-
-=item use_tap_harness()
-
-=item verbose()
-
-=item xs_files()
-
-=back
-
-=head1 MODULE METADATA
-
-If you would like to add other useful metadata, C<Module::Build>
-supports this with the C<meta_add> and C<meta_merge> arguments to
-L</new()>. The authoritative list of supported metadata can be found at
-L<CPAN::Meta::Spec> but for convenience - here are a few of the more useful ones:
-
-=over 4
-
-=item keywords
-
-For describing the distribution using keyword (or "tags") in order to
-make CPAN.org indexing and search more efficient and useful.
-
-=item resources
-
-A list of additional resources available for users of the
-distribution. This can include links to a homepage on the web, a
-bug tracker, the repository location, and even a subscription page for the
-distribution mailing list.
-
-=back
-
-
-=head1 AUTHOR
-
-Ken Williams <kwilliams@cpan.org>
-
-
-=head1 COPYRIGHT
-
-Copyright (c) 2001-2006 Ken Williams.  All rights reserved.
-
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-
-=head1 SEE ALSO
-
-perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
-L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3)
-
-F<META.yml> Specification:
-L<CPAN::Meta::Spec>
-
-=cut