CPAN::API::BuildPL - Documentation of the API for using Build.PL
version 0.002
THIS DOCUMENT IS STILL A ROUGH DRAFT
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.
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.
configure_requires
The terms must, should, may and their negations have the usual IETF semantics.
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.
Portions of this document have been copied or adapted from the documentation of Module::Build (copyright Ken Williams).
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 [command] [options]
must carry out a 'build' action if no command is specified
must use the same perl executable that was used to run Build.PL
should not preserve @INC from Build.PL
A list of actions that must be supported follows:
must prepare the distribution for the test and install actions
must exit with 0 if the distribution is considered ready for testing/installation
must exit with a non-zero code if the distribution is not ready for testing/installation
Historically, this means compiling, copying files to blib, etc. and many existing tools may expect to find things in blib. This is not necessarily the right way to do thing forever and ever.
(Add purpose statement?)
must exit with 0 if the distribution is considered install-ready
must exit with a non-zero code if the distribution is not ready to install
should produce a human-readable result to STDOUT
may run the 'build' action
may consider having no tests to be a successful result
must exit with 0 if the distribution was installed successfully
must exit with a non-zero code if the distribution was not installed successfully
must install to the paths defined in other sections of this document
should not modify paths not defined in other sections of this document
should preserve the prior state of the system if installation is unsuccessful
must not require the test action to have been run
must exit with 0 if ran successfully, or non-zero if not
should remove all files generated by the build tool after the configuration (e.g. blib)
should not create any files in the cleanup process
must exit with 0 if ran successfully, or non-zero if not.
must remove all files removed by the 'clean' action
must additionally remove all files generated during configuration, including but not limited to the C<Build> script and the MYMETA files
(blah blah configuration blah blah)
During execution of Build.PL or Build, options should have the following precedence (from high to low):
@ARGV
$ENV{PERL_MB_OPT}
cached configuration from Build.PL (only when running Build)
Conceptually, options should be split on white space and then spliced together, with higher-precedence options following lower-precedence options. Options should then be processed "in order".
All command line arguments are accepted on action, even if they only affect one action.
--destdir <dir>
This sets the destdir as described in L</INSTALL PATHS>
--installdirs <type>
<type> must be one of C<site>, C<vendor> or C<core> as described in L</INSTALL PATHS>
--install_base <dir>
This sets the install_base as described in L</INSTALL PATHS>
--install_path <type>=<dir>
This sets the install_path for a type as described in L</INSTALL PATHS>
--uninst
If enabled this will cause old versions of the module to be uninstalled when the new version is installed.
--verbose
This instructs the build tool it should output additional information on what it's doing
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
When you invoke 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 Config.pm, and they may be overridden by using the install_path parameter. An install_base parameter lets you specify an alternative installation root like /home/foo, and a destdir lets you specify a temporary installation directory like /tmp/install in case you want to create bundled-up installable packages.
Build
install_path
install_base
destdir
A build system *must* provide default installation locations for the following types of installable items:
Usually pure-Perl module files ending in .pm.
"Architecture-dependent" module files, usually produced by compiling XS, Inline, or similar code.
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.
"Architecture-dependent" executable programs, i.e. compiled C code or something. Pretty rare to see this in a perl distribution, but it happens.
Documentation for the stuff in script and bin. Usually generated from the POD in those files. Under Unix, these are manual pages belonging to the 'man1' category.
script
bin
Documentation for the stuff in lib and arch. This is usually generated from the POD in .pm files. Under Unix, these are manual pages belonging to the 'man3' category.
lib
arch
This is the same as bindoc above, but applies to HTML documents.
bindoc
Five other parameters let you control various aspects of how installation paths are determined:
The default destinations for these installable things come from entries in your system's Config.pm. You can select from three different sets of default locations by setting the installdirs parameter as follows:
Config.pm
installdirs
'installdirs' set to: core site vendor uses the following defaults from Config.pm: lib => installprivlib installsitelib installvendorlib arch => installarchlib installsitearch installvendorarch script => installscript installsitescript installvendorscript 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 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 installdirs to "core" to overwrite the module in its present location.
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
You can also set the whole bunch of installation paths by supplying the install_base parameter to point to a directory on your system. For instance, if you set 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
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 rpm or dpkg could create a package from), you can use the destdir parameter:
rpm
dpkg
perl Build.PL --destdir /tmp/foo
./Build install --destdir /tmp/foo
This will effectively install to "/tmp/foo/$sitelib", "/tmp/foo/$sitearch", and the like, except that it will use File::Spec to make the pathnames work correctly on whatever platform you're installing on.
File::Spec
An implementation *may* implement this option for compatibility with ExtUtils::MakeMaker's PREFIX argument. If implemented it *must* behave the same as ExtUtils::MakeMaker 6.30 would given the PREFIX argument. In other words, the following examples must be equivalent.
perl Build.PL --prefix /tmp/foo perl Makefile.PL PREFIX=/tmp/foo
If an implementation opts not implement prefix, it *must* give a descriptive error at the earliest possible time if a user tries to use it.
CPAN
CPANPLUS
cpanm
Module::Build
Acme::Module::Build::Tiny
David Golden <dagolden@cpan.org>
This software is Copyright (c) 2023 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install CPAN::API::BuildPL, copy and paste the appropriate command in to your terminal.
cpanm CPAN::API::BuildPL
CPAN shell
perl -MCPAN -e shell install CPAN::API::BuildPL
For more information on module installation, please visit the detailed CPAN module installation guide.