## 41.11. CPAN

The Comprehensive Perl Archive Network (CPAN), whose URL is http://www.cpan.org, is the place to get modules, scripts, and the Perl source code. This system is mirrored all over the world, so consult http://www.cpan.org/SITES.html or http://mirror.cpan.org for the server nearest you. There is a really complete CPAN FAQ that can be found at http://www.cpan.org/misc/cpan-faq.html.

This section covers obtaining and installing modules from CPAN. If your installation of Perl is up to date, module installation is trivial. If you've got a "unique" system, you may need to take matters into your own hands.

### 41.11.1. Installing Modules the Easy Way

In a fit of inspired genius (or madness), the CPAN module was created to automate the task of fetching and installing modules. If you want to install the Text::AutoFormat suite, it's as easy as becoming superuser on your system and typing:

>     # perl -MCPAN -e 'install Text::AutoFormat'

Perl has many command-line switches. Here, `-M` (equivalent to `use` `module`) and `-e` (execute the next argument as perl code) are used. If you've never run the CPAN module before, be prepared to answer a lot of questions about your network setup and where certain system binaries are. Luckily, you can usually accept the defaults safely. Once that's done, the CPAN module will go to the CPAN mirror you specified; find the latest version of the module you asked for; and download, unpack, configure, and install it for you with no additional typing. Now that's twenty-first-century library management! If your module depends on other modules not installed on your system, CPAN will attempt to fetch and install the missing modules. In fact, you can update the CPAN module itself with:

>     # perl -MCPAN -e 'install Bundle::CPAN'

The CPAN module also has an interactive shell you can access like this:

>     $ perl -MCPAN -e shell

Why bother with the interactive shell? Sometimes you want to install several unrelated modules at once. This is done more conveniently in the CPAN shell. Alternately, you may want only to download module archives without actualling installing them. The entire range of shell options can be found with the `h` command inside the shell. One of the most useful shell functions, the search function, can be used to look up available CPAN modules. For instance:

>     $ sudo perl -MCPAN -e shell

>     cpan shell -- CPAN exploration and modules installation (v1.59)
>     ReadLine support enabled

>     cpan> i /Text/
>     CPAN: Storable loaded ok
>     Going to read /usr/local/cpan/Metadata
>     Module          AddressBook::DB::Text (D/DL/DLEIGH/AddressBook-0.16.tar.gz)
>     Module          AnyData::Format::Text (J/JZ/JZUCKER/AnyData-0.05.tar.gz)
>     Module          Apache::PrettyText (C/CH/CHTHORMAN/Apache-PrettyText-1.03...
>     ...

>     401 items found
>     cpan> quit

Here, we use the `i` command to search for the regular expression `/Text/` in all the module names.

When you first run the CPAN module, you will be asked a series of configuration questions. The first question you'll be asked when configuring CPAN is to name a CPAN build and cache directory (where CPAN unpacks fetched module archives and builds them). Put this in a sensible place where you and other users can can get to it, such as /usr/local/cpan. You'll be asked to name the maximum size for the cache directory (the default is 10MB). The next question will ask when to perform size checks on the cache, `atstart` or `never`. Unless you have a compelling reason not to remove old module builds, accept the default of `atstart`. You then be asked whether CPAN metadata should be cached, and again, accept the default of `yes`.

The next question asks about what character set your terminal expects. Again, you should accept the default of `yes`. The configuration then asks what it should do when unfulfilled dependencies are encountered during a module installation. CPAN can automatically fetch the missing modules (`follow`), ask for confirmation before downloading them (`ask`), or do nothing (`ignore`). If you are on a fast Internet connection, you may want to set the policy to `follow`. The safest policy, and one that guards against runaway module fetching sessions, is `ask`.

The next several questions ask for the location of certain binaries (like lynx, make, gzip, etc.). Answer these appropriately. The next set of questions ask for additional make parameters. Again, accept the defaults. You will then be asked about your network setup. If you are behind a firewall that uses SOCKs or proxy servers for FTP and HTTP, you will need to enter those server names. CPAN will ask you to pick a CPAN mirror closest to you, by asking you for continent and country information. You'll be presented with a list of CPAN mirrors, and you can enter the numbers of the URLs in which you are interested. Generally, you'll only need to give one or two mirrors. The last question is about the WAIT system, to which you can safely accept the default. This concludes the CPAN configuration.

### 41.11.2. Installing Modules the Hard Way

Most modules on CPAN are gzipped tar archives that have some common files in them that makes installing them fairly simple. To install a CPAN module, unpack your archive and cd to the new directory that was just created. Now type:

>     $ perl Makefile.PL && make test

This is a similiar configure and compile idiom to the one shown in Section 41.3. If the tests all succeed, change to root and install the module with:

>     # make install

The module is now available to your system.

### 41.11.3. Browsing the CPAN Web Site

There's something to be said for browsing the CPAN archive with a web browser. In fact, there are all kinds of ancillary tidbits that are available only on the web site. However, CPAN's main purpose is to store and serve modules.

Modules on CPAN are arranged by author name, module name, category, and recentness. Of these, module name and category are perhaps the most useful for CPAN newbies. The full Perl documentation is linked to from CPAN, but you should have this on your system already. Of course, no serious web site these days is missing a search engine, and CPAN is no exception. In fact, the search engine has its own URL: http://search.cpan.org. This is an excellent resource for quickly finding modules that may solve your problem.

CPAN is an ocean of code that awaits your exploration.

-- JJ

Copyright © 2003 O'Reilly & Associates. All rights reserved.