Submitting a CPAN module

Published by Patrick on

We’re in process of moving from our internal wiki from MediaWiki to XWiki. To achieve this goal, I’ve written a dialect plug-in to the HTML::WikiConverter, a framework that converts raw HTML to a given wiki dialect. More on that on that in a later article. To give the community the source back we’ve decided to submit the new module to CPAN, the Perl module archive.

To actually commit something you have to become a Perl author. To become a Perl author you need to apply for an account on the PAUSE (Perl Authors Upload Server). Using the PAUSE interface, it’s a matter of two minutes to fill in some fields. What could take a while is the approval process since its done by hand. After two hours, my account was ready and I was able to log in.

Packing the module

After getting my account info, I tried to locate information about what my packed model should contain. Failing to find anything on that matter (apart from the fact that every .pm needs to have a version), I’ve taken another module as a template.

My Module has the following structure:

/Changes
Short change history, not much as of now
/Makefile
Makefile, generated by perl MakefilePL
/Makefile.PL
Make file generator
/MANIFEST
List of files
/META.yml
Meta description of the module, built automatically
/README
Readme generated by perldoc
/lib/HTML/WikiConverter/XWiki.pm
My module
/t/00-load.t
Test if the module can be loaded
/t/boilerplate.t
Checks the README and Changes files
/t/pod-coverage.t
Checks if the package Test::Pod::Coverage is installed
/t/pod.t
Checks if the package Test::Pod is installed
/t/runtests.pl
Needed by xwiki.t
/t/xwiki.t
Runs a few tests (~90) to see if we’re generating sane output

With:

perl Makefile.PL
make dist

I’ve got all files tar’ed, zipped up and ready to upload.

Namespace or not?

After the upload you are encouraged to register your namespace. But it doesn’t say what that has to do with indexing or getting your module listed. Disregarding all that, I’ve registered the namespace HTML::WikiConverter::XWiki and am still awaiting confirmation.

Finally

Meanwhile the indexer has reached my module and it’s available for download here. Or, even more conveniently, via cpan:

perl -MCPAN -e 'install HTML::WikiConverter::XWiki'