CPAN, the Comprehensive Perl Archive Network is the place where all the interesting Perl extension (libraries, modules) live. This article collects some of the resources needed to understand what is CPAN and how to use it. Both as a "user" and as an "author".

For users

CPAN itself is just an ftp server holding files in a way that is convenient to the authors, but almost unusable to users. Most people therefore use either Google, or one of the specialized search engines of CPAN. I recommend you use MetaCPAN. You visit MetaCPAN and just type in something you are looking for. Try giving words that might be part of the name of the module you are looking for, or part of the description of what it does.

There some extra tricks in using MetaCPAN. For example you can search for all Plack Middleware or Perl::Critic Policies or you can limit your search by distribution name, version number or author.

Installing modules from CPAN

Once you found a module that you would like to install, you'll need to find out how to install it.

Before that though, you should probably understand that the unit of of installation is the "distribution" (a .tar.gz or sometimes .zip file) for example HTML-Form, while the unit of direct usage is a "module" (a .pm file). (for example HTML::Form). A single distribution can contain one or more modules. (Well, it could also contain 0 modules, but that's rare.)

There is an article trying to explain the, sometimes overlapping, meaning of Packages, modules, distributions, and namespaces in Perl.

Two articles that you might find useful covering the process of module installation are:

Contributors

You can contribute to a CPAN module without being an author. Without taking on the full responsibility of becoming a maintainer. If you find a module on CPAN that has a bug that bothers you. Or one that you use, but a feature is missing. Or even if you have just managed to understand how to use the module and would like to provide a few examples or some explanation.

If the module is currently maintained by someone you can usually "send a patch" to make that change.

This article and screencast might give you some ideas how to do that:

Contributing to a Perl module on CPAN (using vim and Github)

New authors

If you'd like to upload a module to CPAN you will need to create an account on PAUSE, The Perl Authors Upload Server. Creating the account is a manual process, don't ask why it is the tradition. Anyway, you can click on "Request PAUSE account" link on that site, fill out the form including the short explanation why you would like to have a PAUSE ID. Potential good answers include "I'd like to become the maintainer of module ABC" and "I'd like to upload a module called ABC that will do DEF". Fill the placeholder with the appropriate information. You don't need to write an essay, but the admins need to see you are not a bot.

The only thing that you won't be able to change late is the "Desired ID". That will become your "PAUSE ID". (For example my PAUSE ID is SZABGAB). It is probably a good idea to check if the ID you are asking for isn't in use. You can check that by checking if the appropriate page exists on MetaCPAN. For example SZABGAB is the link to my account.

As far as I know it can take up to a few weeks to on of the admins to approve the request, so don't leave this to the last minute.

Once you got your account approved, you are considered an author, and thus the rest is in the next section.

Authors

If you'd like to discuss your plans for a new module there are two places for that: PrePAN, and the module-authors mailing list. The latter is also very good for discussing on-going maintenance issues.

Assuming you already have a PAUSE account (or at least you have already requested one), you will need to create a "distribution" and upload it The "distribution" is the tar.gz file, that CPAN authors upload to CPAN (or more precisely to PAUSE) and that is the thing end-users download and install.

Some of the articles that will be relevant to you as an author:

Minimal requirement to build a sane CPAN package

How to add images to the documentation of Perl modules on CPAN

Adding list of contributors to the CPAN META files

Version Control

While it is not a requirement to have a public version control system (VCS) for your CPAN module, it is usually very useful. It allows others to see your progress even between releases, it allows them to easily contribute to your effort and depending on which public VCS you are using it makes it super-easy for you to integrate their contribution. In the recent years Git became the de-facto leader for open source version control tools and GitHub became the most popular site where you can a have a public repository for your open source project. I'd strongly recommend you develop your perl module in such a repository.

It is also recommended to link to the public VCS from your module. You can add a link to the documentation of the module, but there is also a standardized way to do this in the META files of the module. (or more precisely of the distribution.) Once you include the VCS link in your meta files, MetaCPAN will be able to extract that information and display it next to your module. Having that link in the standard place will make it easier to anyone to contribute to your work.

Here is an article that explains how can you do this:

How to convince Meta CPAN to show a link to the version control system of a distribution?

Even if you don't have a public version control system, please use a private one.

License

One of the key features of Open Source software is its license. There are certain recommendations by TPF on how to add license information to your distribution, but one of the often overlooked aspect is to add the license to the META files. Again, to let MetaCPAN, or any other program, easily extract it.

This article explains how to add the license field to the META.yml and META.json files on CPAN.

Caveat

This article is "in progress". I decided to share it in its current form as I think it already provides some valuable information. If you'd like to get updates on this article and on plenty of other issues with Perl, make sure you subscribe to the newsletter. If you also would like to get the Pro articles and screencasts (see the list in the archive) then go ahead and subscribe to the Perl Maven Pro.