18

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?

simbabque
  • 53,749
  • 8
  • 73
  • 136
Zsolt
  • 304
  • 2
  • 8
  • 2
    To get started see [perlnewmod](https://perldoc.perl.org/perlnewmod) and [Dist::Zilla::Starter](https://metacpan.org/pod/Dist::Zilla::Starter) – Håkon Hægland Jul 02 '21 at 08:07
  • 1
    While I agree with the points you make @Chris, I disagree that they apply to this question. Whenever There Is More Than One Way To Do It, official documentation really doesn't cover it. In my experience, programming problems often also boil down to finding and identifying the right documentation. One of Stack Overflow's strengths in my opinion is providing help with that. The question prompted me to use my knowledge and back it up with research, and to write it all down in a place where it will be found. Nobody else has done that before, and I wouldn't have without the question. – simbabque Jul 09 '21 at 08:16
  • Consider reading [those slides](https://www.slideshare.net/brian_d_foy/create-and-upload-to-cpan) from a talk by brian d foy at YAPC::EU. I use this document as a reference many time, it provides all what is needed to understand Perl modules authoring. – smonff Jan 07 '22 at 07:00

1 Answers1

20

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:

simbabque
  • 53,749
  • 8
  • 73
  • 136