[Chapter 8] 8.35 CPAN

8.35 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.35.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.35.2 Bundles are

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 with the difference that it contains a special section that begins with:

=head1 CONTENTS

This section consists of lines like this:


Module_Name
 [
Version_String
] [- 
optional text
]

where



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 ).

8.35.3 Configuration

When the CPAN module is installed, a site-wide configuration file is created as 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 lists the keys defined in the hash reference $CPAN::Config and how to set and query them.

8.35.4 CD-ROM Support

The urllist parameter in the configuration table contains a list of URLs to 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