/ 
CPAN-API-BuildPL-0.002
River stage zero No dependents
/ CPAN::API::BuildPL

NAME

CPAN::API::BuildPL - Documentation of the API for using Build.PL

VERSION

version 0.002

DESCRIPTION

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.

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).

USAGE

Build.PL program

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

  • 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:

'build' action

  • 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.

'test' action

(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

'install' action

  • 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

'clean' action

  • 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

'realclean' action

  • 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

  • should not create any files in the cleanup process

CONFIGURATION

(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".

Command Line Options

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

Environment variables

  • 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

INSTALL PATHS

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.

A build system *must* provide default installation locations for the following types of installable items:

lib

Usually pure-Perl module files ending in .pm.

arch

"Architecture-dependent" module files, usually produced by compiling XS, Inline, or similar code.

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.

bin

"Architecture-dependent" executable programs, i.e. compiled C code or something. Pretty rare to see this in a perl distribution, but it happens.

bindoc

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.

libdoc

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.

binhtml

This is the same as bindoc above, but applies to HTML documents.

libhtml

This is the same as bindoc above, but applies to HTML documents.

Five other parameters let you control various aspects of how installation paths are determined:

installdirs

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:

                        '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.

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
install_base

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
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 rpm or dpkg could create a package from), you can use the 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 File::Spec to make the pathnames work correctly on whatever platform you're installing on.

prefix

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.

SEE ALSO

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004