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.

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.

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.

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.

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.

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.