CPAN contains the collected wisdom of the entire Perl community: hundreds of Perl utilities, several books' worth of documentation, and the entire Perl distribution. If it's written in Perl, and it's helpful and free, it's in CPAN.

The CPAN architecture is the creation of Jarkko Hietaniemi and Andreas König. Andreas and Tim Bunce jointly maintain the The Perl 5 Module List, which is like this document but has more about creating modules and less about what existing modules do. (If you just want to install Perl, you can grab the Perl distribution from the CPAN.)

This document is CPAN.html, a "front end" to CPAN. Part of this document is about what's in CPAN and part is about how you can contribute to this worldwide effort by submitting utilities for the rest of the world to use. The bulk of this document used to be descriptions of all the modules in CPAN, but now there are too many modules for that, and the best we can do at the moment is refer you to the smooth and speedy search.cpan.org so that you can enter search terms to find utilities.

What's a module?

You'll find a technical explanation in the perlmod documentation, but here's the gist: a module is a freely available Perl 5 utility that you can download and use from your Perl 5 programs. Many modules are single Perl files ending in .pm. Others are more complex, and need to be compiled on your machine, typically because they make use of C under the hood.

Another difficulty is that some modules depend on others. While the CPAN administrators, module writers, and Makemaker gurus have tried to make downloading and installing modules as easy as possible (and see Andreas König's CPAN.pm module for a way to automate the process), it's a little frustrating to install a sleek new module only to find that it depends on something you don't have. That's where CPAN bundles come in: a bundle is a colllection of modules that comprise a cohesive unit, like the libwww bundle, which contains lots of modules to help you tangle with the World Wide Web.

If you clicked on the above link CPAN.pm, or libwww, you (hopefully!) were transported to directories containing the appropriate files. Which machine served them to you? I don't know. It depends on where you're connecting from. That's the beauty of Tom Christiansen's CPAN multiplexer: it automagically reroutes you to a nearby CPAN site, for some definition of "nearby." (If it doesn't work, perhaps the site is busy, and you should try again.) If you don't like the multiplexer's choice of site, select one from the list of CPAN sites.

What's on CPAN?

The CPAN has a dozen-odd top-level entries.

• CPAN.html This file.
• ENDINGS What file extensions like .zip and .gz and .tar mean.
• MIRRORED.BY Information about sites mirroring this one.
• MIRRORING.FROM Information about sites this one mirrors.
• README and README.html A brief introduction to CPAN.
• RECENT and RECENT.html What's changed recently in CPAN.
• authors/ modules (and extensions), listed by author
• clpa/ archive of the comp.lang.perl.announce Usenet newsgroup
• doc/ Perl documentation and FAQs
• indices/ various index views of CPAN
• misc/ Miscellany:
• modules/ modules (and extensions), listed by module name
• ports/ non-UNIX Perl ports, both as executables and source
• scripts/ Perl utilities that aren't modules. New submissions are now being accepted, thanks to Kurt Starsinic; send mail to scripts@perl.org for more information.
• src/ The Perl distribution.

IF YOU'RE SEARCHING FOR A PARTICULAR UTILITY, use http://search.cpan.org to find it. There are more other CPAN search utilities: WAIT, which uses approximate matching to search module documentation, and Randy Kobes' CPAN Search Engine, which lets you throw boolean queries against CPAN module names, files and directories, author names, and the Perl documentation.

The easiest way to install a module on CPAN is to use the CPAN.pm module. Of course, you'll need to install that the hard way; see my perlmodinstall documentation (bundled with Perl) for instructions on how to manually install modules.

To use a module, you must a) install it, and b) place use YourModuleName;" near the top of your program.

WHAT ABOUT DOCUMENTATION? In Perl, there is a convention of embedding documentation inside your source code. (That way, you never lose it.) This embedded documentation is in a format called "pod" (for Plain Old Documentation); when you look through a module and see lines like =head1 or =cut, that's pod. Pod is designed to be easily readable and translatable into whatever format you like. Use one of the programs in the pod2x directory (in your Perl distribution) to extract the documentation and convert to HTML, FrameMaker, a Unix man page, TeXinfo, or just plain text.

IF YOU'RE LOOKING FOR AN ANSWER TO A PERL QUESTION, the first thing to do is read The Perl FAQ. There are other, more specialized, FAQs in the FAQs directory.

IF YOU'D LIKE TO READ THE PERL DOCUMENTATION, good for you! Pick an appropriate directory in doc/manual/html. I recommend starting with perl.html, which contains links to all other sections of the documentation.

How You Can Help-- derived from the original CPAN.html by Jarkko Hietaniemi

Comment

You can send email to the CPAN administrators, cpan@perl.org. We especially love the half-dozen of you that have us confused with C-SPAN, the U.S. politics cable channel, which has happened about a half-dozen times. ("Yes, we'll make it our top priority to give Ralph Nader more CPAN coverage. Thanks for your support!")

Inform

If you know of some Perl resources that seem not to be in CPAN, please tell us. We will grab it (if it is small and/or stable) or set up regular mirroring (if it is not).

Contribute

If you have some modules/scripts/documentation yourself that you would like to contribute to CPAN, please read the file modules/04pause.html and let us know.

Register

If you have a reliable and well-connected ftp site where you can keep CPAN (about 750 MB currently), more mirror sites are welcome. Feel free to volunteer and contact the CPAN administrators describing your mirroring setup, please see the top of the file MIRRORED.BY Of course, first check (see the host list) whether your area (network-connectivity-and-bandwidth-wise) is already well covered. Redundancy and fault-tolerance are good things for FTP archives like CPAN but virtues can be exaggerated. Mirroring software is available from CPAN itself.

Private/Local Mirroring

If you want to set up a private/local mirror of CPAN but do not want to advertise it you do not need to contact the CPAN admistrators. You need to assess which of the public CPAN sites would give the best FTP bandwidth for you (during the nighttime, mind) and then contact the email address dst_contact given in the MIRRORED.BY file to learn the best time of the day to do your mirror. Mirroring software is available from CPAN itself.

Copyright This document is Copyright 1996, 1997, 1998, 2000 Jon Orwant. All Rights Reserved. The CPAN itself is a collection of individual works, many of which have their own copyright statements; you'll have to look at the individual work to determine the distribution terms. Most are licensed under the same terms as Perl itself, which means that you can freely copy it under either the Gnu GPL or Larry Wall's Artistic License -- your choice.

Enjoy!