Besides allowing others in your organization receive the benefits of these wonderful modules and distributions you’ve created, you may wish to contribute to the Perl community at large. The mechanism for sharing your work is called the Comprehensive Perl Archive Network, or CPAN for short.
The CPAN is the result of many volunteers working together, many of whom were originally operating their own little (or big) Perl FTP sites back before that Web thing came along. They got coordinated on their perl-packrats mailing list in late 1993 and decided that disk was getting cheap enough that the same information should be replicated on all sites, rather than having specialization on each site. The idea took about a year to ferment, and Jarkko Hietaniemi established his Finnish FTP site as the CPAN mothership, from which all other mirrors could draw their daily or hourly updates.
Part of the work involved rearranging and organizing the separate archives. Places were established for Perl binaries for non-Unix architectures, scripts, and Perl’s source code itself. But the modules portion has come to be the largest and most interesting part of the CPAN.
The modules in the CPAN are organized as a symbolic-link tree in
hierarchical functional categories, pointing to author directories
where the actual files are located. The modules area also contains
indicies that are generally in easy-to-parse-with-Perl formats, such
as the Data::Dumper output for the detailed module
index. Of course, these indicies are all derived automatically from
databases at the master server using Perl programs. (Often, the
mirroring of the CPAN from one server to another is done with a
now-ancient Perl program called mirror.pl.)
From its small start of a few mirror machines, the CPAN has now grown to over 200 public archives in all corners of the Net, all churning away updating at least daily, sometimes as frequently as hourly. No matter where you are in the world, you can find a nearby CPAN mirror from which to pull the latest goodies.
To contribute to the CPAN, you need two things:
The PAUSE ID is your ticket to contributing to the CPAN. You get a PAUSE ID just for the asking. The details are described at http://www.cpan.org/modules/04pause.html. You need to fill out a web form (linked from there) with a few basic details such as your name, home web page, email address, and your preferred PAUSE ID. At the moment, PAUSE IDs must be between four and nine characters. (Some legacy PAUSE IDs are only three characters long.)[106]
Once you have your PAUSE ID, you need to think globally about your contribution. Because your module will probably be used in programs along with other modules from other authors, you need to ensure that the package names for modules don’t collide or confuse. Consult with the module-naming volunteers listening at the modules@perl.org mailing list to get a name or hierarchy of names for your module or related modules.
Before you send your first email to the module czars, it’s probably a good idea to do a few things first:
Look at the current module list. Get an idea for how things are named. Better yet, are you just reinventing a subset of something that already exists, or can you simply contribute your work as a patch to another module?
Visit the list archives (pointers can be found at http://lists.perl.org) to see what the typical conversations look like. That might help you to avoid shock at your response, or better phrase your initial request.
Above all, get it in your head that this whole process is run by volunteers who aren’t perfect and are doing this in their spare time for the good of the Perl community. Have patience. Have tolerance.
Once you’ve gotten your module name settled and you’ve tested your module with its new name (if needed), you should make sure your distribution is ready for prime time. While this is similar to releasing a distribution inhouse, as described in Chapter 14, you might want to ensure a few additional things about your distribution:
Create a
README file. This file is automatically extracted
to a separate file on the CPAN archives and lets someone view or
download just the key facts about your distribution before fetching
or unpacking the rest.
Make and test your
Makefile.PL. Modules without a
Makefile.PL are accepted via PAUSE to go into the
CPAN but usually get a grimace from those of us who download your
stuff because we might have to figure out how to build and install
your distribution.
Bring your
MANIFEST up to date. If you add files that should
be part of the distribution, they also need to be in the
MANIFEST. One quick trick is to clean things up as
you would want them in the distribution, and then invoke
make manifest, which updates the
MANIFEST file to be exactly what you are holding
at the moment.
Have a logical distribution version
number. The Makefile.PL file should specify either
a VERSION value or a
VERSION_FROM value. If you have a single module
(such as a .pm file) in your distribution,
it’s usually best to grab the version number from
there with VERSION_FROM. If you have multiple
files, either designate one of them as the one
you’ll always update just before a new release or
use the VERSION within the
Makefile.PL instead. Also keep in mind that your
version number must always increase numerically for newer versions of
your distribution.
Have tests! Reread Chapter 14 if you must. There’s nothing that builds more confidence in an installed distribution than at least a few dozen tests that are run during the installation phase.
Invoke
make
disttest, which builds a
distribution archive of everything in MANIFEST,
unpacks the archive into a separate directory, and then runs the
tests on your distribution. If that doesn’t work for
you, you can’t expect it to work for anyone else who
downloads your distribution from the CPAN.
Once you have your distribution ready to share, visit the PAUSE web page at http://pause.perl.org/ and log in using your PAUSE ID and PAUSE password. The menu has many things you can do; there are two processes to complete for your distribution:
Upload the distribution archive
Edit the module metadata
First is the upload, which you can do using an HTTP upload, a web fetch, or an FTP transfer. The HTTP upload is convenient if the distribution archive is on the same computer as your web browser. Otherwise, if you can move the file into a place where it can be fetched (even a private URL will do), you can use the web fetch. If neither option works, then FTP the file to PAUSE FTP server.
After the file is uploaded, you should edit the metadata. Again, select the appropriate menu item from the PAUSE page and follow the instructions. The metadata helps others decide if you’re just releasing an alpha version instead of a final release, and whether or not the module needs additional support, like a C compiler.
Within a short period of time, your upload will appear in the mothership CPAN archive, and then over the following day, will propagate around the world, just waiting for its first download.
Of course, nobody will know that your module exists until they notice it. Your module gets noticed automatically in many places, such as:
The “Recent modules” page of http://search.cpan.org
The “new modules” section of http://use.perl.org
A daily announcement in the “perl news” mailing list
An IRC ‘bot on a few of the Perl-related IRC channels announces uploads as soon as they become available
An update or an uninstalled module in the CPAN shell,
CPAN.pm
For greater visibility, you can also prepare a short notice to be posted to the Usenet comp.lang.perl.announce newsgroup. Just post the notice, and within a day or two, your news posting will be whisking around to news servers all over the globe.
Many volunteers have organized a
smoke test of your module on many platforms.
Simply as a result of uploading your registered module to the CPAN,
your module will be downloaded and make
test‘ed on many different kinds
of machines. You can view the results of the tests at http://testers.cpan.org. You should note any
failures and consider using the feedback to release a new
distribution that works more portably.
Many of the short talks at Perl conferences involve the author of a distribution talking about their own work. After all, who is better qualified to help others use your module than you?
If the idea of proposing a conference talk intimidates you a bit, or you don’t want to wait that long, look to your local Perl user group. They’re generally looking for speakers (usually for the meeting coming up in the next week or two), and the group size is usually small enough to be a nice casual setting. You can generally find a Perl user group near you by looking on the Perl Mongers web site at http://www.pm.org. If you can’t find one, start one!
The answers for all exercises can be found in Section A.12.
[106] Originally, the PAUSE IDs had to be five
characters or less, until Randal wanted his MERLYN
ID, and the appropriate accommodation was made.