Add ExtUtils::Miniperl to the list of core modules for all versions >= 5.00504

[p5sagit/p5-mst-13.2.git] / lib / Module / Build / Authoring.pod

diff --git a/lib/Module/Build/Authoring.pod b/lib/Module/Build/Authoring.pod
index e9bbceb..871effd 100644 (file)
--- a/lib/Module/Build/Authoring.pod
+++ b/lib/Module/Build/Authoring.pod
@@ -141,20 +141,51 @@ method.
 
 =head1 PREREQUISITES
 
-There are three basic types of prerequisites that can be defined: 1)
-"requires" - are versions of modules that are required for certain
-functionality to be available; 2) "recommends" - are versions of
-modules that are recommended to provide enhanced functionality; and 3)
-"conflicts" - are versions of modules that conflict with, and that can
-cause problems with the distribution.
+=head2 Types of prerequisites
 
-Each of the three types of prerequisites listed above can be applied
-to different aspects of the Build process.  For the module distribution
-itself you simply define "requires", "recommends", or "conflicts".  The
-types can also apply to other aspects of the Build process.  Currently,
-only "build_requires" is defined which is used for modules which are
-required during the Build process.
+To specify what versions of other modules are used by this
+distribution, several types of prerequisites can be defined with the
+following parameters:
 
+=over 3
+
+=item configure_requires
+
+Items that 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>.
+
+*TODO* auto-add M::B?  In what circumstances?
+
+=item build_requires
+
+Items that are necessary for building and testing this distribution,
+but aren't necessary after installation.  This can help users who only
+want to install these items temporarily.  It also helps reduce the
+size of the CPAN dependency graph if everything isn't smooshed into
+C<requires>.
+
+=item requires
+
+Items that are necessary for basic functioning.
+
+=item recommends
+
+Items that are recommended for enhanced functionality, but there are
+ways to use this distribution without having them installed.  You
+might also think of this as "can use" or "is aware of" or "changes
+behavior in the presence of".
+
+=item conflicts
+
+Items that can cause problems with this distribution when installed.
+This is pretty rare.
+
+=back
 
 =head2 Format of prerequisites
 
@@ -168,7 +199,7 @@ the module names and the values are version specifiers:
                perl => '5.6.0'
               },
 
-These four version specifiers have different effects.  The value
+The above four version specifiers have different effects.  The value
 C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
 installed.  The value C<0> means that B<any> version of C<Bar::Module>
 is acceptable, even if C<Bar::Module> doesn't define a version.  The
@@ -182,6 +213,11 @@ interpreter that are supported by your module.  The same version
 dependency-checking semantics are available, except that we also
 understand perl's new double-dotted version numbers.
 
+=head2 XS Extensions
+
+Modules which need to compile XS code should list C<ExtUtils::CBuilder>
+as a C<build_requires> element.
+
 
 =head1 SAVING CONFIGURATION INFORMATION
 
@@ -210,8 +246,8 @@ library (thus the C<h> part) into perl extensions (thus the C<xs>
 part).
 
 These days, C<h2xs> has largely been superseded by modules like
-C<ExtUtils::ModuleMaker>, C<Module::Starter>, and C<Module::Maker>.
-They have varying degrees of support for C<Module::Build>.
+C<ExtUtils::ModuleMaker>, and C<Module::Starter>.  They have varying
+degrees of support for C<Module::Build>.
 
 
 =head1 AUTOMATION
@@ -274,7 +310,7 @@ perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
 L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
 
 F<META.yml> Specification:
-L<http://module-build.sourceforge.net/META-spec-v1.2.html>
+L<http://module-build.sourceforge.net/META-spec-current.html>
 
 L<http://www.dsmit.com/cons/>