first draft

lib/CPAN/API/BuildPL.pm

@@ -1,44 +1,325 @@
+# vim:tw=72:
 use strict;
 use warnings;
 package CPAN::API::BuildPL;
-# ABSTRACT: a module for CPAN
+# ABSTRACT: Documentation of the API for using Build.PL
 
-# Dependencies
-use autodie 2.00;
-use Moose 0.99;
-use namespace::autoclean 0.09;
+1;
 
-# extends, roles, attributes, etc.
+__END__
 
-# methods
+=begin wikidoc
 
-__PACKAGE__->meta->make_immutable;
+= DESCRIPTION
 
-1;
+*THIS DOCUMENT IS STILL A ROUGH DRAFT*
 
-__END__
+This documentation describes an API for how a Build.PL file in a Perl
+distribution may be used to build and install the distribution.  This is
+primarily of interest to CPAN clients like [CPAN], [CPANPLUS] and
+[cpanm].
 
-=for Pod::Coverage::TrustPod
-  method_name_here
+While Build.PL originated with [Module::Build], there is no reason that
+alternative pure-Perl build systems can't use the same mechanism.  With
+the {configure_requires} key in distribution META files supported in the
+Perl core since version 5.10.1, it will be increasingly easy over time
+for other pure-Perl build system to flourish.
 
-=begin wikidoc
+The terms *must*, *should*, *may* and their negations have the usual
+IETF semantics.
 
-= SYNOPSIS
+The API described herein is a minimal feature sufficient for basic
+interoperability between a CPAN client and a pure-Perl build system to
+build, test and install Perl distributions.  Any build system *must*
+provide all of the features. The build system *may* provide additional
+features, but CPAN clients *should not* rely on them.
 
-  use CPAN::API::BuildPL;
+Portions of this document have been copied or adapted from the
+documentation of [Module::Build] (copyright Ken Williams).
 
-= DESCRIPTION
+= USAGE
 
-This module might be cool, but you'd never know it from the lack
-of documentation.
+== Build.PL program
 
-= USAGE
+  perl Build.PL [options]
+
+* *must* generate a Build file if configuration is successful
+* *must* exit with exit code of zero if configuration is successful
+* *must* not generate a Build file if configuration fails
+* *may* exit with a zero or non-zero exit code; clients *may* interpret
+a zero exit code with no Build file produced as a request to abort
+further action without signaling error to the user
+* *must* generate at least one MYMETA file following a version of the
+CPAN::Meta::Spec
+* *may* print warnings about unsatisfied prerequisties to STDOUT
+* *must* accept user configuration as described in this document
+* *must* cache user configuration for later use by 'Build'
+
+== Build program
+
+  ./Build [command] [options]
+
+* *must* carry out a 'build' action if no command is specified
+
+A list of actions that *must* be supported follows:
+
+=== 'build' action
+
+* (Need to define the expected structure under blib)
+
+=== 'test' action
+
+* *should* produce a TAP stream
+* (Need to define what to do about 'test.pl' and 'visual.pl')
+* (Need to define what to do with exit condition)
+
+=== 'install' action
+
+* (Need to define how blib structure maps to install paths)
+* (Need to figure out what to do about packlists)
+
+= CONFIGURATION
+
+(blah blah configuration blah blah)
+
+Precedence of configuration:
+
+* {@ARGV}
+* {$ENV{PERL_MB_OPT}}
+* cached configuration from Build.PL
+* configuration file
+
+== Command Line Options
+
+(write about them here, if only to refer to INSTALL_PATHS)
+
+Initial thoughts:
+
+* --dest_dir
+* --installdirs
+* --install_base
+* --install_path
+* --uninst
+* --verbose (?) (but connects to EU::Install)
+* --quiet (?)
+
+== Configuration file
+
+When Build.PL or Build runs, it *must* look for a configuration file
+in the following locations and *must* take the first file that it finds,
+if more than one exists:
+
+  $ENV{MODULEBUILDRC}
+  $ENV{HOME} . "/.modulebuildrc"
+  $ENV{USERPROFILE} . "/.modulebuldrc"
+
+If a configuration file exists, the options specified there *must* used
+as defaults as if they were typed on the command line, but the actual
+command line *must* override defaults from a configuration file.  The
+format of the configuration file is described below.
+
+As with Perl, a hash mark ({#}) begins a comment that continues to the
+end of the line it appears on.  Comments *must* be ignored.  Empty lines
+or lines with only white space *must* also be ignored.
+
+The first word on a configuration line describe the 'action' to which
+the options apply.  The 'action' is the command given to the 'Build'
+program.  An action *must* be followed by whitespace and then the
+options.  Options *must* be formed just as they would be on the command
+line (e.g.  separated by whitespace).  They can be separated by any
+amount of whitespace, including newlines, as long there is whitespace at
+the beginning of each continued line.  If more than one line begins with
+the same action name, those lines are merged into one set of options in
+the order they appear.
+
+There are three special pseudo-actions: an {*} (asterisk) denotes global
+options that *must* be applied whenever 'Build.PL' or 'Build' is run,
+the pseudo-action 'build' *must* be applied when 'Build' is run without
+a command like 'test' or 'install', and the key 'Build_PL' specifies
+options that *must* be applied when 'Build.PL' is run.
+
+For example:
+
+  *           verbose=1   # global options
+  install     --install_base /home/ken
+              --install_path html=/home/ken/docs/html
+
+Unrecognized actions *should* be ignored and *must not* be treated as
+errors.
+
+== Environment variables
+
+* MODULEBUILDRC -- specifies the preferred location of a configuration
+file
+* PERL_MB_OPT -- provides option as if they were specified on the command
+line to Build.PL or any Build action, but with precedence lower than
+actual command line options .  The string *must* be split on whitespace
+as the shell would and the result prepended to any actual command-line
+arguments in {@ARGV}
+
+
+=end wikidoc
+
+=head1 INSTALL PATHS
+
+When you invoke C<Build>, it needs to figure
+out where to install things.  The nutshell version of how this works
+is that default installation locations are determined from
+F<Config.pm>, and they may be overridden by using the C<install_path>
+parameter.  An C<install_base> parameter lets you specify an
+alternative installation root like F</home/foo>, and a C<destdir> lets
+you specify a temporary installation directory like F</tmp/install> in
+case you want to create bundled-up installable packages.
+
+A build system *must* provide default installation locations for
+the following types of installable items:
+
+=over 4
 
-Good luck!
+=item lib
+
+Usually pure-Perl module files ending in F<.pm>.
+
+=item arch
+
+"Architecture-dependent" module files, usually produced by compiling
+XS, L<Inline>, or similar code.
+
+=item script
+
+Programs written in pure Perl.  In order to improve reuse, try to make
+these as small as possible - put the code into modules whenever
+possible.
+
+=item bin
+
+"Architecture-dependent" executable programs, i.e. compiled C code or
+something.  Pretty rare to see this in a perl distribution, but it
+happens.
+
+=item bindoc
+
+Documentation for the stuff in C<script> and C<bin>.  Usually
+generated from the POD in those files.  Under Unix, these are manual
+pages belonging to the 'man1' category.
+
+=item libdoc
+
+Documentation for the stuff in C<lib> and C<arch>.  This is usually
+generated from the POD in F<.pm> files.  Under Unix, these are manual
+pages belonging to the 'man3' category.
+
+=item binhtml
+
+This is the same as C<bindoc> above, but applies to HTML documents.
+
+=item libhtml
+
+This is the same as C<bindoc> above, but applies to HTML documents.
+
+=back
+
+Four other parameters let you control various aspects of how
+installation paths are determined:
+
+=over 4
+
+=item installdirs
+
+The default destinations for these installable things come from
+entries in your system's C<Config.pm>.  You can select from three
+different sets of default locations by setting the C<installdirs>
+parameter as follows:
+
+                          'installdirs' set to:
+                   core          site                vendor
+
+              uses the following defaults from Config.pm:
+
+  lib     => installprivlib  installsitelib      installvendorlib
+  arch    => installarchlib  installsitearch     installvendorarch
+  script  => installscript   installsitebin      installvendorbin
+  bin     => installbin      installsitebin      installvendorbin
+  bindoc  => installman1dir  installsiteman1dir  installvendorman1dir
+  libdoc  => installman3dir  installsiteman3dir  installvendorman3dir
+  binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
+  libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
+
+  * Under some OS (eg. MSWin32) the destination for HTML documents is
+    determined by the C<Config.pm> entry C<installhtmldir>.
+
+The default value of C<installdirs> is "site".  If you're creating
+vendor distributions of module packages, you may want to do something
+like this:
+
+  perl Build.PL --installdirs vendor
+
+or
+
+  ./Build install --installdirs vendor
+
+If you're installing an updated version of a module that was included
+with perl itself (i.e. a "core module"), then you may set
+C<installdirs> to "core" to overwrite the module in its present
+location.
+
+=item install_path
+
+Once the defaults have been set, you can override them.
+
+On the command line, that would look like this:
+
+  perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
+
+or this:
+
+  ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
+
+=item install_base
+
+You can also set the whole bunch of installation paths by supplying the
+C<install_base> parameter to point to a directory on your system.  For
+instance, if you set C<install_base> to "/home/ken" on a Linux
+system, you'll install as follows:
+
+  lib     => /home/ken/lib/perl5
+  arch    => /home/ken/lib/perl5/i386-linux
+  script  => /home/ken/bin
+  bin     => /home/ken/bin
+  bindoc  => /home/ken/man/man1
+  libdoc  => /home/ken/man/man3
+  binhtml => /home/ken/html
+  libhtml => /home/ken/html
+
+=item destdir
+
+If you want to install everything into a temporary directory first
+(for instance, if you want to create a directory tree that a package
+manager like C<rpm> or C<dpkg> could create a package from), you can
+use the C<destdir> parameter:
+
+  perl Build.PL --destdir /tmp/foo
+
+or
+
+  ./Build install --destdir /tmp/foo
+
+This will effectively install to "/tmp/foo/$sitelib",
+"/tmp/foo/$sitearch", and the like, except that it will use
+C<File::Spec> to make the pathnames work correctly on whatever
+platform you're installing on.
+
+=back
+
+=begin wikidoc
 
 = SEE ALSO
 
-Maybe other modules do related things.
+* [CPAN]
+* [CPANPLUS]
+* [cpanm]
+* [Module::Build]
+* [Acme::Module::Build::Tiny]
 
 =end wikidoc