 | Chapter 8 Standard Modules |  |
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:
Or:perl -MCPAN -eshell; #run from the command line
use CPAN;
my $obj = CPAN::Shell->install('ExtUtils::MakeMaker');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.
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.
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:
This section consists of lines like this:=head1 CONTENTS
whereModule_Name [Version_String] [- optional text]
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).
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.
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
|  | |
| 8.34 constant |  | 8.36 CPAN::FirstTime |