This book discusses many Perl modules that may not be included with your system. This appendix contains instructions for installing modules from CPAN. It also discusses how to use perldoc to access documentation.
CPAN is the Comprehensive Perl Archive Network, found at http://www.cpan.org/ and at numerous mirrors around the world (see http://www.cpan.org/SITES.html). From CPAN you can download source code and binary distributions of Perl, plus all of the modules we mentioned in this book and many other scripts and modules.
You can browse the very long list of modules at http://www.cpan.org/modules/00modlist.long.html. If you know the name of a module you wish to download, then you can generally find it via the first word of the module’s name. For example, you can download Digest::MD5 from http://www.cpan.org/modules/by-module/Digest/. The filename within that directory is Digest-MD5-2.09.tar.gz (note that the version number, 2.09, will likely change by the time you read this book).
All Perl modules distributed on CPAN follow a consistent install process, but some modules are easier to install than others. Some have dependencies on other modules, and some include C source code that must be compiled and often linked to other libraries on your system.
You may have difficulty compiling the modules that contain C code. Most commercial distributions of Unix do not include an ANSI C compiler. You can generally obtain a prebuilt binary of the gcc compiler instead. Check software archive sites specific to your platform (for example, http://www.sun.com/sunsite/ for Solaris and http://hpux.cae.wisc.edu/ for HP/UX). Linux and BSD systems should already have the tools you need.
If you are using ActiveState’s release of Perl on Win32, then you can use the Perl Package Manager to download pre-built binary modules from ActiveState. Visit http://www.activestate.com/PPM/ for more information.
The simplest way to install modules on Unix and compatible systems is to use the CPAN.pm module. You can invoke it like this, typically as the superuser:
# perl -MCPAN -e shell
It creates an interactive shell, from which you to get information about modules on CPAN and install or update modules on your system. The first time you run CPAN, it will prompt you for configuration information that tells it what tools are available for downloading modules, and what CPAN mirrors to use.
Once CPAN is configured, you can install a module by simply typing install followed by the name of the module:
cpan> install Digest::MD5
CPAN will fetch the requested module and install it. CPAN recognizes dependencies on other modules and will automatically install required modules for you. There are several other commands available besides install; you can get a full list by entering a question mark at the prompt.
Occasionally, CPAN will not be able to install a module for you. In that case, you will have to install a module manually. On Unix and compatible systems, you should use the following steps after you have downloaded a module:
$ gzip -dc Digest-MD5-2.09.tar.gz | tar xvf - $ cd Digest-MD5-2.09 $ perl Makefile.PL $ make $ make test $ su # make install
If make or make test fails, then you will need to find and fix the problem. Check the documentation included with the module for assistance. If the module you have downloaded contains C code that links to other libraries, verify that the versions of your libraries match what the Perl module expects. You might also search past newsgroup postings for anyone who already encountered and solved the same problem. You can use http://www.deja.com/usenet/ for this; navigate to the advanced news search and search comp.lang.perl.modules for related terms.
If you have verified any version dependencies, cannot find any answers in the documentation, cannot find any answers in past newsgroup postings, and cannot solve the problem yourself, then post a polite, detailed message to news:comp.lang.perl.modules explaining the problem and asking for assistance. You probably should not use deja.com for this, however. Unfortunately, some of the most knowledgeable and helpful Perl coders filter out news messages posted from deja.com (for the same reason, you may want to avoid sending your message from a Microsoft mail application, too).
Developers new to Perl often overlook a very valuable source of information: perldoc. perldoc is Perl’s documentation viewer; it allows you to read documentation in Perl’s pod (plain old documentation) format. This provides a wealth of information about Perl, plus modules. Virtually every module included with Perl and available on CPAN includes pod.
If perl works on your system but the perldoc command does not, you may need to search your system for it. It is installed with Perl by default, but depending on the installation, it may not have been installed in a standard executable directory. You can also fall back to using man instead. pod pages are typically converted to manpages when they are installed.
To get started, try the following command:
$ perldoc perl
This provides a basic description of Perl along with a list of the Perl manual sections available. For instance, typing:
$ perldoc perlsec
will display the Perl security section. perldoc has a number of options; you can get the usage of perldoc this way:
$ perldoc perldoc
perldoc is very useful with modules. You can view the extensive documentation for CGI.pm this way:
$ perldoc CGI
This sequence works for multiple-word modules:
$ perldoc Digest::MD5
Note that the requested module must be present; perldoc does not fetch documentation from CPAN. In addition to package names, you can also supply a filename to perldoc; this allows you to view the documentation for a module before it is installed:
$perldoc ./MD5.pm
pod is typically stored within .pm files, although separate .pod files are possible.
Finally, if you prefer a graphical interface, you may wish to look at the Tk::Pod module.