Item 48: Submit your useful modules to the CPAN. | Effective Perl Programming: Writing Better Programs with Perl

Although the CPAN already contains many high-quality modules that do a wide variety of things, there are still many useful modules yet to be written in Perl.

If you are considering writing a module that does something of general interest, or if you have already written one, you might want to consider contributing your module to the CPAN. The process of contributing a module is a fairly simple onewhich is good, because we programmers hate it when paperwork becomes more time-consuming than the constructive work it supports. ^[4]

^[4] This Item relies on the PAUSE documentation available at the time of writing. The current version can be found under modules/04pause.html in the CPAN. Please check it before registering or contributing modules for the first time, as the procedure may have changed since this was written.

Discuss your module

The first thing you need to do, as a potential new contributor to the CPAN, is to discuss your new module(s) with some potential users. In most cases, the best thing to do is to post some sort of a "request for discussion" to comp.lang.perl.modules . Include the proposed name of the module, its key features, and if possible, a pointer to a man page and/or a sample implementation. You don't have to take all the responses to heart, but you should at least read and consider them. Some people are just naturally "bah humbuggers" while others are helpful and interested USENET has a lot of both kinds.

The following questions are ones that you need to have answered when you proceed:

Does this capability already exist?
Is the name I have chosen for the module appropriate? (This is very important.)
Is the interface to the module appropriate?
Do I have the resources and technical savvy to implement the module properly?

If or when you are ready to proceed, the next step is to register yourself with PAUSE.

Registering with PAUSE

As a new developer, you will need to register yourself with PAUSEthe Perl Authors Upload Server. You need to choose a username or " handle" for yourselfmine is JNH , my initials. You can use your first name, your favorite login, initials , or whatever, so long as it is reasonably short, and isn't already taken. For a list of current usernames and the corresponding author names , see authors/00whois.html in your favorite CPAN mirror.

The next step is to send a message to the Perl module maintainer's mailing listcurrently modules@ perl.org. Mailing list addresses tend to change, so check the current PAUSE document in the CPAN to verify it. The message should contain:

Your name
Preferred username
E-mail address, and home page if you have one
A description of your project
A description of each module in "module list format" ^[5]

^[5] See the module listing at modules/00modlist.long.html for a description of "DSLI" and proper module listing format.
Pointers to public discussion of the module

You soon should receive an e-mail message asking you for a password. You should respond with an encrypted password or message. If your system supports crypt , the simplest way to do this is with a short Perl script. The PAUSE document suggests the following command line (replace mysecret with your chosen password):

 perl -MHTTPD::UserAdmin \    -le 'print HTTPD::UserAdmin->new->encrypt(shift);' mysecret

You might also try a program like:

 $salt = pack "CC", time % 26 + 65, (time >> 8) % 26 + 65;  $pass = crypt "mysecret", $salt;  print "encrypted: $pass\n";

(Or just pick any two letters at random for the $salt variable.)

If you don't have crypt on your system, see the PAUSE document for other alternatives. Once your password is received and acknowledged , you're ready to upload your module and join the hallowed ranks of CPAN authors.

Uploading and maintaining modules

The easiest way to upload modules to the CPAN is to submit them via a secure CGI script that links directly to PAUSE. As of this writing, the URL is:

http://franz.ww.TU-Berlin.DE/perl/ user /add_uri

I hate to repeat myself , but these things tend to change and you should verify this URL in the PAUSE document.

You can submit a file in a number of ways. You can upload it to a holding area on the PAUSE server, then identify them in the CGI script. You can specify a URL where the server can go get it. You can also upload the file directly from your browser.

Your submission should be a "packed, compressed" module as generated by make module:tardist makefile target tardist (see Item 45). There are automatic scripts that take care of extracting README files and the like from it and inserting them into the CPAN. There are other CGI scripts that allow you to change your author information, delete files, and make urgent mirror requests ( generally to submit emergency bug fixes).

PAUSE and the CPAN are two of the best examples of "social anarchy " contributing to the betterment of mankindor at least programmer-kind. Contributing a useful module to the CPAN is one of the best ways you can, in turn , show your appreciation for the efforts of hundreds of programmers who have made Perl and the CPAN such a compellingly useful resource.