CPAN (Perl in a Nutshell, 2nd Edition)

8.46. CPAN

Lets you access CPAN; search for a module, a bundle, an author, or a distribution; download a module or distribution; install it; and make it. The CPAN module can be used either interactively from the command line or programmatically:

perl -MCPAN -eshell;          # Run from the command line

or:

use CPAN;

my $obj = CPAN::Shell->install('ExtUtils::MakeMaker');

This section describes the use of the CPAN module from a program. See Chapter 2, "Installing Perl" for information on using it interactively and for details of the available commands. These commands, available interactively from the shell, are methods of the class CPAN::Shell. From a program, they are available both as methods (e.g., CPAN::Shell->install(...)) and as functions in the calling package (e.g., install(...)).

Each of the commands that produce listings of modules (r, autobundle, and u) returns a list of the IDs of all modules within the list. The IDs of all objects available within a program are strings that can be expanded to the corresponding real objects with the CPAN::Shell->expand("Module",@things) method. expand returns a list of CPAN::Module objects according to the @things arguments. In scalar context, it returns only the first element of the list.

8.46.1. Session and Cache Managers

The CPAN module contains a session manager, which keeps track of objects that have been fetched, built, and installed in the current session. No status is retained between sessions.

There is also a cache manager, which keeps track of disk space used and deletes extra space. The cache manager keeps track of the build directory, $CPAN::Config->{build_dir}, and uses a simple FIFO mechanism to delete directories below build_dir when they grow bigger than $CPAN::Config->{build_cache}.

The original distribution files are kept in the directory $CPAN::Config->{keep_source_where}. This directory is not covered by the cache manager but must be controlled by the user. If the same directory is used as both build_dir and keep_source_where, your sources are deleted with the same FIFO mechanism.

8.46.2. Bundles

The CPAN module recognizes a bundle as a Perl module in the namespace Bundle:: that does not define any functions or methods and usually contains only pod documentation. It starts like a Perl module with a package declaration and a $VERSION variable. After that, the pod section looks like any other pod except that it contains a special section that begins with:

=head1 CONTENTS

This section consists of lines such as:

Module_Name [Version_String] [- optional text]

in which Module_Name is the name of a module (for example, Term::ReadLine), not the name of a distribution file, and the version and text are optional. If there is text, it is preceded by a -. The distribution of a bundle should follow the same convention as other distributions.

Bundles are treated specially in the CPAN package. When you tell CPAN to install a bundle, it installs all the modules in the CONTENTS section of the pod. You can install your own bundles locally by placing a conforming bundle file somewhere in your @INC path. The autobundle command available in the shell interface does that for you by including all currently installed modules in a snapshot bundle file (see Chapter 2, "Installing Perl").

8.46.3. Configuration

When the CPAN module is installed, a site-wide configuration file is created: CPAN/Config.pm. The default values defined there can be overridden locally in the file CPAN/MyConfig.pm. You can store this file in $HOME/.cpan/CPAN/MyConfig.pm, because $HOME/.cpan is added to the search path of the CPAN module before the use or require statements. Chapter 2, "Installing Perl" lists the keys defined in the hash reference $CPAN::Config and how to set and query them.

8.46.4. CD-ROM Support

The urllist parameter in the configuration table contains a list of URLs that will be used for downloading. If the list contains any file URLs, CPAN looks there first for files (except index files). So if you are using a CD-ROM containing the CPAN contents, include the CD-ROM as a file URL at the end of urllist since it is likely to be out-of-date. You can do this with:

o conf urllist push file://localhost/CDROM/CPAN