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.
I've borrowed David Golden's terms for well defined.
Let me know if there are additional terms you think should be included, or if I've got anything wrong below.
package built-in..pm extension 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 package
built-in.
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 Games:: prefix,
and everything related to chess might be in Games::Chess::.
A well-formed package has a version number declared with a package
variable $VERSION:
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.
See the packages section in perlmod.
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 :: mapping
to a path separator (eg '/'). So HTTP::Tiny becomes HTTP/Tiny.pm.
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 Email::MIME::ContentType
can be found in the Email-MIME-ContentType distribution.
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
(typically .tar.gz or .zip).
My Module::Path module is released in the Module-Path distribution.
At the time of writing,
the last release I did was version 0.19 of Module::Path,
the release file for which was:
Module-Path-0.19.tar.gz
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,
such as cpan-upload.
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:
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
(e.g. MetaCPAN
and search.cpan.org).
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
(eg 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
CPAN::DistnameInfo.
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 06perms.txt,
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:
App::Web,JONASBN,f
App::Web,CWINTERS,c
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 Devel-Cover
distribution contains many modules, but the main module
is Devel::Cover.
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.
If you want to know whether a module is core, you can use the corelist script which is part of the Module-CoreList distribution:
% 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 good example is Getopt::Long, which was included in the first release of Perl 5, but is also released to CPAN in the Getopt-Long distribution.
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
in the Foo::Bar module:
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:
D/DA/DAGOLDEN/CPAN-Meta-Requirements-2.136-TRIAL.tar.gz
R/RJ/RJBS/PathTools-3.56_02.tar.gz
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