There is now a hierarchical index of scripts on CPAN!
Most readers of TPJ are intimately familiar with CPAN, the Comprehensive Perl Archive Network. Recently, a new area was added to the Archive--the scripts repository. This is an area where you can find useful Perl programs, and where you can publish your own programs.
Script authors have always been able to upload scripts to CPAN, but until now, there was no formal organization for them. There was an earlier attempt at a scripts repository, which still exists (but is no longer updated) at https://www.perl.com/CPAN/scripts/legacy.html.
What is CPAN?
In case you weren't familiar with it, CPAN is a worldwide collection of FTP servers. Tom Christiansen has made it easy to find a CPAN site near you with his multiplexer, available at https://www.perl.com/CPAN. Note that there is no slash at the end of this URL.
How Can I Find a Script?
The index of scripts can be found at:
https://www.perl.com/CPAN/scripts/index.html
Scripts are arranged by category, and there is also a list arranged alphabetically by script name.
How Do I Create a Script?
First, you'll need to come up with a problem (in technical jargon, this is known as 'the easy part'). If you've determined that your problem hasn't been solved already (by someone else's script or module), write it.
When your script is written and debugged, you'll need to give it a version number. It's recommended that you start with version number 0.01; that your version numbers contain only numeric characters, period (.), and underscore (_); and that you only insert an underscore in 'unstable' or 'development' version numbers. Use the version number as the last part of the filename, and also assign this number to the $VERSION variable in your script.
To appear in the scripts area of CPAN, your script will need to contain some identifying information, in the form of pod documentation (if you're not familiar with pod, read the perlpod documentation bundled with Perl). There are several sections that you may wish to add to your script; the only essential one is the SCRIPT CATEGORIES section. This section tells CPAN that your file should appear in the scripts index; it must contain a list of categories (no more than three!) to which this script belongs. A more lengthy description of the format, along with an example script, can be seen at:
https://www.perl.com/CPAN/scripts/submitting.html
How Will I Choose a Script Category?
First, take a look at the currently existing categories. As of this writing, there are six:
CGI
CGI/Filter
CPAN
CPAN/Administrative
Win32
Win32/Utilities
If your script fits into one of these, great! If not, dream up your own--but you've got a little bit of work to do. Category creation is based on a peer review process; in this case, your peers are the members of the scripts@perl.org mailing list. To participate in the process, first join the mailing list by sending email to majordomo@cpan.org with a message body of subscribe scripts; then send email to the list explaining what your script does, and what new category you'd like to create. List members will discuss your proposal with you, and then, unless somebody comes up with a very good reason why your script doesn't belong in that category (or you withdraw your proposal), an administrator will inform you that the category has been created.
How Can I Upload a Script?
In order to have upload privileges, you will need a user ID on PAUSE (the Perl Authors Upload SErver). Instructions for registering your user ID and uploading files are published at
https://www.perl.com/CPAN/modules/04pause.html
Once you have an ID, you can put files on CPAN. First, you'll upload your script via anonymous FTP to ftp://pause.kbx.de/incoming/. Then, you'll claim ownership of it (so that it will go into your personal CPAN directory, and will also appear in the scripts index). You claim ownership at https://pause.kbx.de/perl/user/add_uri.
Finally!
Once you click Submit, your file is on its way to CPAN; it will appear in about two hours (some CPAN sites mirror less frequently than others, so your mileage may vary). Tell your friends!
What Next?
After you've been through this process once, you might want to create more scripts! Consider using the additional pod sections (PREREQUISITES, COREQUISITES, OSNAMES, and README); or include a script in a tarfile that contains scripts, modules, and documentation.
Still to Come
The scripts index is in its early stages of development, and comments, suggestions, and submissions are welcomed.
Improvements likely in the near term include a more attractive hierarchical index; keyword searching; display of brief descriptions in the index; and an alphabetical listing split into multiple pages.
Acknowledgments
Andreas König very generously gave me an account on the PAUSE server, and patiently explained many details of PAUSE, MakeMaker, and CPAN.
Jarkko Hietaniemi helped work out some of the kinks in the scripts directory structure, and made many helpful suggestions along the way. And in dozens of email messages about broken hyperlinks, he never once used profanity.
Nathan Torkington (on behalf of The Perl Institute) was instrumental in encouraging the CPAN team to actually get something done.
Uploading a Script Step by Step
Get a PAUSE ID:
To: modules@perl.org Subject: PAUSE registration Hello, My name is J. Random Perlhacker. My email address is jrp@int.netorg.edu. My homepage is https://www.netorg.edu/~jrp/. I've written some system administration scripts that I'd like to upload.
Join scripts@perl.org:
To: majordomo@perl.org subscribe scripts
Discuss possible script categories. Send mail:
To: scripts@perl.org Subject: New category proposal Hello, I've written some scripts for administering both NT and UNIX systems remotely; I think that "Administration/Cross-Platform" would be a good category for them. Comments?
Wait for a response. New categories don't get created automatically! If the community agrees (or fails to disagree) with your suggestion for a new category, the category will be created on CPAN and you'll receive mail to that effect.
Add identifying documentation. Invoke your favorite editor on your script, and insert the following:
$VERSION = 0.01;
=head1 SCRIPT CATEGORIES
Administration/Cross-Platform
=cut
=pod OSNAMES
solaris
linux
MSWin32
=cut
Name the script: mv myscript myscript-0.01
Upload it:
% ftp pause.kbx.de Connected to dubravka.kbx.de. 220 pause.kbx.de FTP server . . . . Name (pause.kbx.de:jrp): anonymous 331 Password required for anonymous Password: 230 User anonymous logged in. Remote system type is UNIX. Using binary mode to transfer files. ftp> cd incoming ftp> put myscript-0.01 ftp> quit
Register your upload at https://pause.kbx.de/perl/user/add_uri.
Tell your friends, and wait for your mailbox to fill up with comments and bug reports!
Kurt Starsinic is the maintainer of the Perl scripts area. His interests include collaborative computing, and helping other people compute collaboratively. He works at the Institute for Scientific Information as a Technical Specialist (Internetworking). Drop him a line: kstar@isinet.com.