module-build-checkins

[<kwi...@cv...>]

Author: kwilliams
Date: Fri Apr 14 18:52:34 2006
New Revision: 5904

Added:
   Module-Build/trunk/lib/Module/Build/API.pod
Modified:
   Module-Build/trunk/Changes
   Module-Build/trunk/MANIFEST
   Module-Build/trunk/inc/ModuleBuildBuilder.pm
   Module-Build/trunk/lib/Module/Build.pm
   Module-Build/trunk/lib/Module/Build/Authoring.pod
   Module-Build/trunk/lib/Module/Build/Compat.pm
   Module-Build/trunk/lib/Module/Build/Cookbook.pm
   Module-Build/trunk/lib/Module/Build/ModuleInfo.pm

Log:
Split off the API documentation out of Module::Build::Authoring into
its own document: Module::Build::API. (patch from Randy)

Modified: Module-Build/trunk/Changes
==============================================================================
--- Module-Build/trunk/Changes	(original)
+++ Module-Build/trunk/Changes	Fri Apr 14 18:52:34 2006
@@ -7,6 +7,9 @@
    existing directory. Document the search locations and the order
    searched. [Spotted by David Golden]
 
+ - Split the API documentation out of Module::Build::Authoring into
+   its own document: Module::Build::API.
+
  - We should not emit a warning if a Module::Build subclass is
    required in a Makefile.PL that is not bundled in the current
    distribution; it may be installed on the user's system. [Spotted by

Modified: Module-Build/trunk/MANIFEST
==============================================================================
--- Module-Build/trunk/MANIFEST	(original)
+++ Module-Build/trunk/MANIFEST	Fri Apr 14 18:52:34 2006
@@ -2,29 +2,30 @@
 Changes
 INSTALL
 lib/Module/Build.pm
+lib/Module/Build/API.pod
 lib/Module/Build/Authoring.pod
 lib/Module/Build/Base.pm
 lib/Module/Build/Compat.pm
 lib/Module/Build/Cookbook.pm
 lib/Module/Build/ModuleInfo.pm
 lib/Module/Build/Notes.pm
-lib/Module/Build/YAML.pm
-lib/Module/Build/Platform/aix.pm
+lib/Module/Build/PPMMaker.pm
 lib/Module/Build/Platform/Amiga.pm
-lib/Module/Build/Platform/cygwin.pm
-lib/Module/Build/Platform/darwin.pm
 lib/Module/Build/Platform/Default.pm
 lib/Module/Build/Platform/EBCDIC.pm
-lib/Module/Build/Platform/MacOS.pm
 lib/Module/Build/Platform/MPEiX.pm
-lib/Module/Build/Platform/os2.pm
+lib/Module/Build/Platform/MacOS.pm
 lib/Module/Build/Platform/RiscOS.pm
 lib/Module/Build/Platform/Unix.pm
 lib/Module/Build/Platform/VMS.pm
 lib/Module/Build/Platform/VOS.pm
 lib/Module/Build/Platform/Windows.pm
+lib/Module/Build/Platform/aix.pm
+lib/Module/Build/Platform/cygwin.pm
+lib/Module/Build/Platform/darwin.pm
+lib/Module/Build/Platform/os2.pm
 lib/Module/Build/PodParser.pm
-lib/Module/Build/PPMMaker.pm
+lib/Module/Build/YAML.pm
 Makefile.PL
 MANIFEST
 META.yml

Modified: Module-Build/trunk/inc/ModuleBuildBuilder.pm
==============================================================================
--- Module-Build/trunk/inc/ModuleBuildBuilder.pm	(original)
+++ Module-Build/trunk/inc/ModuleBuildBuilder.pm	Fri Apr 14 18:52:34 2006
@@ -9,10 +9,10 @@
   my $self = shift;
   $self->SUPER::ACTION_distdir(@_);
   
-  my $build_pl       = File::Spec->catfile($self->dist_dir, qw(Build.PL));
-  my $build_pm       = File::Spec->catfile($self->dist_dir, qw(lib Module Build.pm));
-  my $base_pm        = File::Spec->catfile($self->dist_dir, qw(lib Module Build Base.pm));
-  my $authoring_pod  = File::Spec->catfile($self->dist_dir, qw(lib Module Build Authoring.pod));
+  my $build_pl = File::Spec->catfile($self->dist_dir, qw(Build.PL));
+  my $build_pm = File::Spec->catfile($self->dist_dir, qw(lib Module Build.pm));
+  my $base_pm  = File::Spec->catfile($self->dist_dir, qw(lib Module Build Base.pm));
+  my $api_pod  = File::Spec->catfile($self->dist_dir, qw(lib Module Build API.pod));
 
   open my($fh), $base_pm or die "Couldn't read $base_pm: $!";
   my %subs = map {$_,1} map +(/^\s*sub (\w+)/)[0], <$fh>;
@@ -20,7 +20,7 @@
   # Replace "<autogenerated_accessors>" with some POD lists
   my @need_doc = sort grep !$subs{$_}, $self->valid_properties;
   $self->do_replace(qq[s{<autogenerated_accessors>}{ join "\\n\\n", map "=item \$_()", qw(@need_doc) }e],
-		    $authoring_pod);
+		    $api_pod);
 
   # Replace "<action_list>" with a list of actions
   my $action_text = $self->_action_listing(scalar $self->known_actions);

Modified: Module-Build/trunk/lib/Module/Build.pm
==============================================================================
--- Module-Build/trunk/lib/Module/Build.pm	(original)
+++ Module-Build/trunk/lib/Module/Build.pm	Fri Apr 14 18:52:34 2006
@@ -169,14 +169,14 @@
 
 =item Authoring Reference (L<Module::Build::Authoring>)
 
-This document describes the C<Module::Build> API for authors who are
+This document describes the structure and organization of
+C<Module::Build>, and the relevant concepts needed by authors who are
 writing F<Build.PL> scripts for a distribution or controlling
-C<Module::Build> processes programmatically.  It describes the
-methods available as well as providing general information on
-subclassing C<Module::Build> to alter and extend its behavior.  Also,
-there is a section on controlling the Build process from other
-scripts, including how to construct an object and how to invoke
-actions through it from an external script.
+C<Module::Build> processes programmatically.
+
+=item API Reference (L<Module::Build::API>)
+
+This is a reference to the C<Module::Build> API.
 
 =item Cookbook (L<Module::Build::Cookbook>)
 
@@ -397,7 +397,7 @@
 [version 0.01]
 
 This action will use C<ExtUtils::Install> to install the files from
-C<blib/> into the system.  See L<INSTALL PATHS>
+C<blib/> into the system.  See L<"INSTALL PATHS">
 for details about how Module::Build determines where to install
 things, and how to influence this process.
 
@@ -853,6 +853,7 @@
 
 =back
 
+
 =head2 About PREFIX Support
 
 [version 0.28]
@@ -955,7 +956,7 @@
 
   perl Makefile.PL PREFIX=/home/spurkis LIB=/home/spurkis/lib/perl5
 
-See L</INSTALL PATHS> for details on other
+See L</"INSTALL PATHS"> for details on other
 installation options available and how to configure them.
 
 =back
@@ -1066,8 +1067,8 @@
 
 =head1 SEE ALSO
 
-perl(1), Module::Build::Cookbook(3), Module::Build::Authoring(3),
-ExtUtils::MakeMaker(3), YAML(3)
+perl(1), L<Module::Build::Cookbook>(3), L<Module::Build::Authoring>(3),
+L<Module::Build::API>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
 
 F<META.yml> Specification:
 L<http://module-build.sourceforge.net/META-spec-v1.2.html>

Added: Module-Build/trunk/lib/Module/Build/API.pod
==============================================================================
--- (empty file)
+++ Module-Build/trunk/lib/Module/Build/API.pod	Fri Apr 14 18:52:34 2006
@@ -0,0 +1,1553 @@
+=head1 NAME
+
+Module::Build::API - API Reference for Module Authors
+
+
+=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 C<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 C<module_name> argument, or C<dist_name> and one of
+C<dist_version> or C<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 add_to_cleanup() method.
+
+=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 C<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 C<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
+C<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 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 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 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.
+
+=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_makefile_pl
+
+[version 0.19]
+
+This parameter lets you use Module::Build::Compat during the
+C<distdir> (or C<dist>) action to automatically create a Makefile.PL
+for compatibility with ExtUtils::MakeMaker.  The parameter's value
+should be one of the styles named in the Module::Build::Compat
+documentation.
+
+=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
+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.  It looks for the first line
+matching C<$package\s-\s(.+)>, and uses the captured text as the
+abstract.
+
+=item dist_author
+
+[version 0.20]
+
+This should be something like "John Doe <jd...@ex...>", 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_version
+
+[version 0.11]
+
+Specifies a version number for the distribution.  See C<module_name>
+or C<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 C<module_name>
+to set it to a reasonable default.
+
+The version is extracted from the specified file according to the same
+rules as C<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.
+
+=item dynamic_config
+
+[version 0.07]
+
+A boolean flag indicating whether the F<Build.PL> 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<META.yml> spec says that installation tools should
+treat it 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 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 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 C<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.
+
+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.  Valid options include:
+
+
+=over 4
+
+=item apache
+
+The distribution is licensed under the Apache Software License
+(http://opensource.org/licenses/apachepl.php).
+
+=item artistic
+
+The distribution is licensed under the Artistic License, as specified
+by the F<Artistic> file in the standard perl distribution.
+
+=item bsd
+
+The distribution is licensed under the BSD License
+(http://www.opensource.org/licenses/bsd-license.php).
+
+=item gpl
+
+The distribution is licensed under the terms of the Gnu General
+Public License (http://www.opensource.org/licenses/gpl-license.php).
+
+=item lgpl
+
+The distribution is licensed under the terms of the Gnu Lesser
+General Public License
+(http://www.opensource.org/licenses/lgpl-license.php).
+
+=item mit
+
+The distribution is licensed under the MIT License
+(http://opensource.org/licenses/mit-license.php).
+
+=item mozilla
+
+The distribution is licensed under the Mozilla Public
+License.  (http://opensource.org/licenses/mozilla1.0.php or
+http://opensource.org/licenses/mozilla1.1.php)
+
+=item open_source
+
+The distribution is licensed under some other Open Source
+Initiative-approved license listed at
+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
+documentation - this field only lets 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.
+
+It is a fatal error to use a license other than the ones mentioned
+above.  This is not because I wish to impose licensing terms on you -
+please let me know if you would like another license option to be
+added to the list.  You may also use a license type of C<unknown> if
+you don't wish to specify your terms (but this is usually not a good
+idea for you to do!).
+
+I just started out with a small set of licenses to keep things simple,
+figuring I'd let people with actual working knowledge in this area
+tell me what to do.  So if that's you, drop me a line.
+
+=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.
+
+=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.
+
+=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 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.  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'      => [],
+              }
+
+=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 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 C<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 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 C<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, or as a hash
+reference whose keys are the files (and whose values will currently be
+ignored).
+
+The default is to install no script files - in other words, there is
+no default location where Module::Build will look for script files to
+install.
+
+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 sign
+
+[version 0.16]
+
+If a true value is specified for this parameter, C<Module::Signature>
+will be used (via the 'distsign' action) t...
 
[truncated message content]