Submitting a Perl module to CPAN

Last May, I finally made available for download the first version of Webservice::Viddler on CPAN (Comprehensive Perl Archive Network) after having written about it in March. One of the reasons for the delay in making the packaged source code available for download had to do with one simple fact, the Viddler module was my first ever submitted for public consumption.

Now, don’t misunderstand me, Webservice::Viddler is not the first Perl module I have ever written. I’ve been writing code in Perl for about as long as CPAN has existed. However, as is the case with my current work in PHP for Orbit Media Studios, most of the Perl code I wrote over the years was on behalf of a employer of some sort. As such the ownership of the code, and the right to distribute, rested with them, not me.

So then, why the delay? Well there are a couple of reasons. First of all, the code I posted in March was a proof of concept based on some work I did for Orbit at the time. While the basic framework of the module worked the “proto-module” didn’t implement all of the functionally provided by the Viddler Web API.

Secondly, I needed to organize the source code for proper distribution on CPAN as well as get the packaged distribution uploaded and made available.

The Packaging
Before I did anything, I wanted to make sure that my module had all of the necessary files. In doing a little googling, I came across a blog post entitled Submitting a CPAN module which outlines the basic steps:

1. Apply for an account on PAUSE (Perl Authors Upload Server)

2. Organize your code

3. Profit

Not too complex, granted, but organized how?

As the author notes there doesn’t seem to be any “what the package must have” rules. However, as anyone who has worked with third-party Perl modules knows, there is an accepted process and organization of code that all modules tend to adhere to.

After a little more googling I came across module-starter, a handy command-line interface to a Perl module, Module::Starter, which does all the work of creating a base module for distribution. After adding in my code and documentation I quickly had something close to ready.

Close, but not complete. Besides making the package useful to install, I wanted to make the code useful to modify. For that I turned to perltidy a Perl script which indents and reformats Perl code to makes it easier to read and follow.

Great! Now here is where this can get interesting (and where a lot of suggestions, if not outright rules, do exist). If you follow the steps in the order above, good, because that means while waiting for a PAUSE account to come online¹, proper considerations can be made for the naming of the module.

The Namespace
The PAUSE documentation On The Naming of Modules notes that “a module name must accomplish quite a bit in a few characters”, such as provide context as to what the module does or problem it addresses. Also of importance is the fact that “once chosen, you rarely have the opportunity to change it after people start using it.”

So a little careful consideration is in order.

Also, it is important to note that namespaces, by definition, are unique. Besides providing a singular meaning, the name cannot be shared with some other module, public or otherwise. As such it is recommend that PAUSE developers register the namespace of the module written. Again, this isn’t a hard and fast rule per se, but a recommendation to avoid duplication and improve searchability.

That about covers the basics. Now, if you will excuse me, I need to take some time to address these test results.