Pulse
Boards
Reference
This document provides guidelines for various aspects of packaging modules on CPAN into operating system packages, to be distributed and installed independent of CPAN. As such this is directed at operating system packagers, to explain what they should expect to recieve from CPAN and how to interact with it. Most of this information is also available elsewhere, but not in one place. The other documents in this repository provide further details on many aspects of it.
The installation process of a CPAN module goes through four sequential phases:
Expectations before running the configure phase:
Expectations after the configuration phase if successful:
Before running this phase, the configure phase must have been successfully completed.
This phase is expected to do everything needed before the distribution can be tested and/or installed.
Before running this phase, the build phase must have been successfully completed. This phase is technically optional, but highly recommended. This phase will run all tests, and report success or failure.
Before running this phase, the build phase must have been successfully completed. This will install the distribution files to the designated location.
There are two active versions of the meta file specification: 2.0, stored in META.json; and 1.4, stored in META.yml. Consumers must prefer the former over the latter if both exist. It is recommended to use CPAN::Meta to interact with these files, as it can automatically upconvert 1.4 to 2.0.
There are two stages of these files: META.json and MYMETA.json. META.json is generated by the authoring tool, and is authoritative on all metadata except non-configure prerequisites. MYMETA.json is generated during the configuration, and is the authoritative source for all other prerequisites. If and only if the dynamic_config entry in the META.json file is set to 0, META and MYMETA will be identical and all META prereqs may be treated as authoritative.
As defined in the Meta 2.0 specification, there are four prerequisite phases for dependencies on other CPAN modules:
These dependencies must be available before even trying to configure the distribution and must remain available until the install phase is finished; they are not required to be available after install. These are usually the only requirements that should be taken from the META.json file. Typically this would be the install tool (e.g. Module::Build or Module::Build::Tiny) and may be empty (e.g. when using ExtUtils::MakeMaker).
If only a Build.PL file is available (no Makefile.PL), and the configure requirements are empty, packages should inject Module::Build as an implicit dependency.
These must be available before entering the build phase and should remain available until the install phase is finished; they are not required to be available after install. Typically this would be empty.
These must be available before entering the test phase; they are not required to be available after testing. Typically this would include various modules such as Test::More or Test2::V0.
These are only the dependencies that must be available when the install phase has finished; in a binary packaging system these are the only dependencies that need to be declared in the final package. They must be available before the build phase starts.
As defined in the Meta 2.0 specification, there are four relationship types for dependencies on other CPAN modules:
These dependencies must be installed for proper completion of the phase.
Recommended dependencies are strongly encouraged and should be satisfied except in resource constrained environments. All "must"s regarding the different phases mentioned above should be interpreted as "should".
Experience has shown that recommendations sometimes include cyclical dependencies, these should be handled mindfully or else these are better skipped entirely.
These dependencies are optional, but are suggested for enhanced operation of the described distribution.
Like recommends, these are probably better skipped if the system can't handle cyclic dependencies.
These libraries cannot be installed when the phase is in operation. In practice this is not used as no CPAN client ever implemented it, so it can probably be ignored.
The CPAN installation involves Perl's own configuration parameters. Most obviously the various arguments for setting the installation directories. It defines three types of install directories:
This is where all modules that ship with perl itself are installed. Packagers should generally not install anything to this destination.
This is where vendor packages should go. This is not enabled by default because a local install doesn't need it, but for a distributor it's generally recommended to use this.
This is where users can install their own modules; typically this would be under /usr/local.
For each of the three install dirs, six categories are installed that each have their own installation location.
This is where pure-perl modules will be installed
This is where perl modules with binary components will be installed
This is where executable scripts are installed
This is where executable binaries are installed. Usually this is the same location as script
This is where man pages for scripts and binaries are installed
This is where man pages for libraries are installed
There are three different protocols for installing. All of them follow the four build phases described above (configure, build, test, install)
This is the original protocol. It does not have a specification, but in practice is defined by the ExtUtils::MakeMaker implementation. The four phases look like
perl Makefile.PL
make
make test
make install
This protocol originates in Module::Build, but now has more implementations. It is defined by the Build.PL spec , and packages should not stray beyond the options defined by it (or request extending the spec with additional options). The four phases look like:
perl Build.PL
./Build
./Build test
./Build install
If both a Makefile.PL and Build.PL file are present, the packager should prefer the Build.PL file.
Packagers may use the Static Install Spec to install the distribution if the x_static_install entry in the META file is set to a supported version of the static install specification. In such a case, they may ignore the configure dependencies.
It is encouraged to pass all arguments at configuration time, even if it's often possible to do so in later stages. In practice, there are only a few types of arguments that should be common for packagers:
The destdir is used to install all files to a staging directory, that is typically then tarred into a package. In Makefile.PL it's set using the DESTDIR argument (e.g. «perl Makefile.PL DESTDIR=/tmp/abcdef»), in Build.PL it's set using the --destdir argument (e.g. «perl Build.PL --destdir /tmp/abcdef»).
The installdir can be set to any of the three values mentioned in the "Install Dirs" section: 'perl' (Makefile.PL) / 'core' (Build.PL), 'vendor' or 'site' (default). This can be used to set the installdir type. Typically a packager would use «INSTALLDIRS=vendor» (Makefile.PL) or «--installdirs vendor» (Build.PL) to ensure the distribution is installed to the vendor paths.
On CPAN, dependencies are declared on modules, not on distributions. As such, any declared dependency should first be mapped from module to distribution, before it is mapped to the native package.
Versions in Perl work a bit differently than in other systems. This can cause problems, especially when CPAN authors change their version scheme or length without understanding the consequences
There are two types of versions in perl. Decimal versions, which work essentially as a normal number, and dotted decimal versions, which works more like one expects from semantic versions.
Decimal versions acting like numbers means that the version "1.2" is equal to the versions "1.20" and "1.200". In practice that means that CPAN authors shortening their versions can break things for downstream vendors that use a more semantic versioning scheme.
Dotted decimal is typically prefixed with a "v" e.g. "v1.2.3". They work by comparing each number sequentially. Unlike typical semantic versioning they null-extend much like decimals though ("v1.2.3" equals "v1.2.3.0").
Decimals can be mapped to dotted-decimal by splitting them by 3 digits. So "1.2345" equals "v1.234.500". When using decimal versions, CPAN authors are advised to use a multiple of three digits, and when using dotted decimals to use the components in the 0-999 range.
Development releases of CPAN modules can contain underscores. Generally speaking packages should not package such versions and as such these should not be their concern.
CPAN packages typically declare their license using the license field of their meta files. They may also declare an SPDX expression in their x_spdx_expression field. If absent, the license may be derived from the LICENSE, COPYING or README file, or from the module's documentation.
PERL_MM_USE_DEFAULTIf set to true, configure time prompts will always use the default value, even if its stdin is a tty.
AUTOMATED_TESTINGIf true, tests are being run by an automated testing facility and not as part of the installation of a module.
EXTENDED_TESTINGIf true, the user or process running tests is willing to run optional tests that may take extra time or resources to complete.
NO_NETWORK_TESTINGIf true, this signals that tests requiring internet access should be skipped.
NONINTERACTIVE_TESTINGif true, tests should not attempt to interact with a user; output may not be seen and prompts will not be answered.
Document created on 2025-03-20 21:54:41 +0100 by Leon Timmermans.