Where the Files Are

Under the main CPAN directory, you'll see at least the following subdirectories:

• authors. This directory contains numerous subdirectories, one for each contributor of software. For example, if you wanted to find Lincoln Stein's great CGI module, and you knew for a fact that he wrote it, you could look in authors/Lincoln_Stein. If you didn't know he wrote it, you could look in the modules directory explained below.

• doc. A directory containing all manner of Perl documentation. This includes all official documentation (manpages) in several formats (such as ASCII text, HTML, PostScript, and Perl's native POD format), plus the FAQs and interesting supplementary documents.

• modules. This directory contains unbundled modules written in C, Perl, or both. Extensions allow you to emulate or access the functionality of other software, such as Tk graphical facilities, the UNIX curses library, and math libraries. They also give you a way to interact with databases (Oracle, Sybase, etc.), and to manage HTML files and CGI scripts.

• ports. This directory contains the source code and/or binaries for Perl ports to operating systems not directly supported in the standard distribution. These ports are the individual efforts of their respective authors, and may not all function precisely as described in this book. For example, none of the MS-DOS ports implement the fork function, for some reason.

• scripts. A collection of diverse scripts from all over the world. If you need to find out how to do something, or if you just want to see how other people write programs, check this out. The subdirectory nutshell contains the examples from this book. (You can also find these sources at the O'Reilly & Associates ftp.oreilly.com site, in /pub/examples/nutshell/programming_perl2/.)

• src. Within this directory you will find the source for the standard Perl distribution. The current production release is always in the file that is called src/latest.tar.gz,[3] which as of this writing is a symbolic link to the file src/5.0/perl5.003.tar.gz, but will likely point to a higher version number by the time you read this. This very large file contains full source and documentation for Perl. Configuration and installation should be relatively straightforward on UNIX and UNIX-like systems, as well as VMS and OS/2.

  [3] The trailing .tar.gz means that it's in the standard Internet format of a GNU-zipped, tar archive.

Using Anonymous FTP

In the event you've never used anonymous FTP, here is a quick primer in the form of a sample session with comments. Text in bold typewriter font is what you should type; comments are in italics. The % represents your prompt, and should not be typed.

% ftp ftp.CPAN.org (ftp.CPAN.org is not a real site)
Connected to ftp.CPAN.org.
220 CPAN FTP server (Version wu-2.4(1) Fri Dec 1 00:00:00 EST 1995) ready.
Name (ftp.CPAN.org:CPAN): anonymous
331 Guest login ok, send your complete e-mail address as password.
Password: [email protected] (Use your user name and host here.)
230 Guest login ok, access restrictions apply.
ftp> cd pub/perl/CPAN/src
250 CWD command successful.
ftp> binary (You must specify binary transfer for compressed files.)
200 Type set to I.
ftp> get latest.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for FILE.
226 Transfer complete.
         .
         .      (repeat this step for each file you want)
         .
ftp> quit
221 Goodbye.
%

Once you have the files, first unzip and untar them, and then configure, build, and install Perl:

% gunzip < latest.tar.gz | tar xvf -
% cd perl5.003      (Use actual directory name.)

Now either one of these next two lines:
% sh configure      (Lowercase "c" for automatic configuration)
% sh Configure      (Capital "C" for manual configuration)

% make              (Build all of Perl.)
% make test         (Make sure it works.)
% make install      (You should be the superuser for this.)

http://www.perl.com/cgi-bin/cpan_mod?module=CoolMod

% gunzip < CoolMod-2.34.tar.gz | tar xvf -
% cd CoolMod-2.34
% perl Makefile.PL  (Creates the real Makefile)

% make              (Build the whole module.)
% make test         (Make sure it works.)
% make install      (Probably should be the superuser)