How do I release a Perl module to CPAN?

Question

I need to create a CPAN module, but I don't know where to start or how to do that. I've already written my modules in Perl, but I don't know how to continue. Could anyone help?

Answer 1

You need to do two main things before you can get started.

First of all, you need to create a PAUSE account. PAUSE is the service that maintains what goes into CPAN. It's a bit dated, but start here and read through it. It boils down to choosing a name, creating an account and waiting to be approved.

Next you have to decide how to package up your module. You can choose from various tools, or build your distribution yourself.

• perlnewmod explains this a little, and suggests Module::Starter, which is a very bare-bones tool.
• Dist::Zilla is a very large distribution builder with a lot of plugins that do things like create docs and run various tests for you, automatically list down who contributed to your code via your git, and a host of other things. There are also a few tools in the middle.
• I often use Minilla, which makes a new module scaffold, runs your tests, creates a dist and uploads it to CPAN, but nothing else.

You might also want to read the SEE ALSO section on each of the ones I've linked. They point to each other. Have a play around, and pick the one that speaks to you.

Then you have to chose a name for your distribution. There is some guidance on this in the PAUSE page I linked above.

Make sure to include useful documentation, write tests, and put your code on github. Put that into the meta data file.

Finally, you bundle it, and then upload it to PAUSE. The bundle is a tarbal with a specific name. You can create that manually or with one of the above-mentioned tools.

Uploading can be done manually through the website, with a command line tool like cpan-upload, or with the bundler if it includes that feature. After a while you get an email from PAUSE that tells you it's there and waiting for indexing (CPAN Upload: ...), and then it shows up on metacpan.org. You'll get another email from PAUSE (PAUSE Indexer report ...) telling you when it's ready.

After some more time, you might get emails from CPAN testers, which smoke tests all new uploads against a multitude of platforms. Sometimes stuff breaks, and you'll hear about it. This is why having good tests is important.

Here are some additional resources:

• An old question about rolling your own dist and its directory structure
• A step by step tutorial that uses Minilla
• What happens when you upload to CPAN?