This is a collection of terms related to CPAN and CPAN distributions. I've often looked for such a thing, wanting to link from it in blog posts and the like, or somewhere to direct people to (such as PRC participants).
The definitions here are as they relate to CPAN; the same terms are widely used and have different meanings depending on the context.
Let me know if there are additional terms you think should be included, or if I've got anything wrong below.
.pmextension that contains either a collection of functions, or a Perl class. Typically a module contains a package of the corresponding name.
A package is a namespace for a block of perl,
introduced with the
A perl file (eg script or module) may contain any number of packages.
package Foo::Bar; # some code here package Foo::Baz; # some other code here
You can define a hierarchy of namespaces, separating levels with ::,
so all packages related to games might have a
and everything related to chess might be in
A well-formed package has a version number declared with a package
our $VERSION = '1.01';
You can also declare the version as part of the package statement:
package Foo::Bar 1.01; package Foo::Baz v1.0.1;
but this capability was only introduced in Perl 5.12.0, so unless you're already requiring 5.12 or later, stick with the more traditional approach.
A module is a
.pm file that contains either a collection
of functions or a class.
By convention a module contains a package of the corresponding name,
and that's what people generally mean when they use the term 'module'.
A multi-level namespace maps into a relative path, with
to a path separator (eg '/'). So
A well-formed module is one which contains a single package of the expected name, and which has a version number.
A distribution is a collection of one or more modules that are related in some way, and that make sense to share with others as a group. A distribution will typically contain various other files as well, such as tests, a README, possible scripts, examples, documentation, and more.
Many CPAN distributions contain just one module, and the name of the
distribution must be derived from the module name: each '::' in the module
name becomes '-' in the distribution name.
So the module
can be found in the
A well-formed distribution contains a module of the corresponding name — a main module, defined below.
A release is a particular instance of a distribution
that was uploaded to CPAN with a particular version number.
A release is usually uploaded to CPAN as a tarball, the name
of which contains three parts: the distribution name, the version number,
and a suffix that identifies the type of tarball
Module::Path module is released in the
At the time of writing,
the last release I did was version 0.19 of
the release file for which was:
A well-formed release contains one or more modules that have the same version number as the release itself.
The Perl Authors Upload SErver, or PAUSE, is the website that is used to upload releases onto CPAN. If you've got a module that you want to share with the world, then you need to create a PAUSE account. Your PAUSE username is usually referred to as your PAUSE id, and will usually be given in upper case. Mine is NEILB.
You can upload releases using the web interface directly,
but most authors use command-line tools for uploading,
The CPAN Index is a file that has an entry for every package on CPAN, giving the latest version of the module on CPAN and the release that contains it.
Notice that I said package and not module. Most of the time people use those terms interchangeably, but the difference will be clear once you've read about cuckoo packages, below.
Here's the entry from the index for
Devel::Cover 1.20 P/PJ/PJCJ/Devel-Cover-1.20.tar.gz
The second field is the module version number, which doesn't have to match the distribution release version which is part of the third field. For example:
Devel::DumpTrace::PPI 0.23 M/MO/MOB/Devel-DumpTrace-0.24.tar.gz
It makes life easier for everyone if you do keep package version numbers in sync with distribution release version numbers.
The index is used by CPAN clients and search engines
When you say
install Devel::Cover, your CPAN client will
check what version you have installed locally,
and if it's lower than the version
listed in the index, then there's a new release to install.
I told a little white lie above. The index doesn't contain every module on CPAN, just those where the uploader had permissions, and only for non developer releases. See relevant sections below to learn about those.
Once you know about them, you'll see those partial release paths
P/PJ/PJCJ/Devel-Cover-1.20.tar.gz) in a lot of places.
If you ever find yourself wanting to extract the constituent parts
of that path, you should know about
The index is generated as the file
02packages.details.txt by PAUSE.
You can download it yourself from CPAN, but if you do, please grab
the gzip'd version:
If you are the first person to upload a package to PAUSE, then PAUSE grants you first-come rights over the package name. This essentially makes you the package's owner.
If you upload a package to PAUSE, and you have first-come rights, then the package will be added to the index.
As the owner of a package name, you can grant co-maint rights to other PAUSE ids. If you upload a package that you have co-maint rights on, it will also be added to the index. Only the owner of a package can grant co-maint rights.
PAUSE periodically dumps all permissions to a file called
which is available on CPAN.
As with the index, you should get the gzip'd version:
The body of the file is a CSV, with three fields per row: package name, PAUSE id, and permission. Here's an example:
The 'f' indicates 'first-come' and 'c' indicates 'co-maint'. You'll also see 'm', which is a historical permission that means 'registered on module list'. This used to be a way you could reserve a package name before releasing it. It also indicates ownership, and takes precedence over 'f'. You can no longer register package names in this way, and it's gradually being phased out.
For most distributions, the main module is the one which has
a name which matches the distribution name.
For example, the
distribution contains many modules, but the main module
These days PAUSE requires new distributions to have a module with matching name, but older distributions didn't have to (and are allowed by PAUSE to continue that way).
A core module is one that is included with Perl 5 itself, so if your script or module uses only core modules then people won't have to install anything else before they can use your code.
There's one caveat to that: some modules have always been core modules — they were included in the very first release of Perl 5. But other core modules were first included in a later release.
% corelist File::Temp Data for 2015-04-20 File::Temp was first released with perl v5.6.1
The underlying Module::CoreList module is updated after every release of Perl 5, so make sure you're running a recent version.
A dual-life module is a core module that is also released to CPAN as part of a distribution separate from Perl itself.
A cuckoo package is one that is defined in a module of a different name.
In the example below,
Foo::Bar::Item is a cuckoo package defined
package Foo::Bar; # lots of Foo::Bar stuff package Foo::Bar::Item; 1;
There are a number of problems associated with cuckoo packages, so in general you should split them out into separate modules.
A developer release is uploaded to PAUSE in the usual way, but is not added to the CPAN Index. If someone tries to install your module, they won't get the version from your developer release, but will get the version that was in your most recent non developer release.
Developer releases are indicated either by appending
TRIAL to the
version number in the release tarball, or by appending an underscore
followed by one or more digits. Examples:
Developer releases let you get feedback from some of your users, without affecting people who want a stable version of your module.
Some people run automated smoke testers which download all new releases to CPAN, run their tests, and upload results to CPAN Testers. Most of the smoke testers run tests on developer releases, so doing a developer release gets you useful feedback across a range of operating systems, Perl versions and configurations.
If there are other CPAN distributions relying on yours, then you should consider doing developer releases first for all but trivial changes.comments powered by Disqus