cpan.html
来自「perl教程」· HTML 代码 · 共 1,396 行 · 第 1/4 页
HTML
1,396 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../displayToc.js"></script>
<script language="JavaScript" src="../tocParas.js"></script>
<script language="JavaScript" src="../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../scineplex.css">
<title>CPAN - query, download and build perl modules from CPAN sites</title>
<link rel="stylesheet" href="../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',1);</script>
<h1><a>CPAN - query, download and build perl modules from CPAN sites</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#status">STATUS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#interactive_mode">Interactive Mode</a></li>
<li><a href="#cpan__shell">CPAN::Shell</a></li>
<li><a href="#autobundle">autobundle</a></li>
<li><a href="#recompile">recompile</a></li>
<li><a href="#the_four_cpan____classes__author__bundle__module__distribution">The four <code>CPAN::*</code> Classes: Author, Bundle, Module, Distribution</a></li>
<li><a href="#programmer_s_interface">Programmer's interface</a></li>
<li><a href="#methods_in_the_other_classes">Methods in the other Classes</a></li>
<li><a href="#cache_manager">Cache Manager</a></li>
<li><a href="#bundles">Bundles</a></li>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#finding_packages_and_version">Finding packages and VERSION</a></li>
<li><a href="#debugging">Debugging</a></li>
<li><a href="#floppy__zip__offline_mode">Floppy, Zip, Offline Mode</a></li>
</ul>
<li><a href="#configuration">CONFIGURATION</a></li>
<ul>
<li><a href="#note_on_urllist_parameter_s_format">Note on urllist parameter's format</a></li>
<li><a href="#urllist_parameter_has_cdrom_support">urllist parameter has CD-ROM support</a></li>
</ul>
<li><a href="#security">SECURITY</a></li>
<li><a href="#export">EXPORT</a></li>
<li><a href="#populate_an_installation_with_lots_of_modules">POPULATE AN INSTALLATION WITH LOTS OF MODULES</a></li>
<li><a href="#working_with_cpan_pm_behind_firewalls">WORKING WITH CPAN.pm BEHIND FIREWALLS</a></li>
<ul>
<li><a href="#three_basic_types_of_firewalls">Three basic types of firewalls</a></li>
<li><a href="#configuring_lynx_or_ncftp_for_going_through_a_firewall">Configuring lynx or ncftp for going through a firewall</a></li>
</ul>
<li><a href="#faq">FAQ</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#translations">TRANSLATIONS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>CPAN - query, download and build perl modules from CPAN sites</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>Interactive mode:</p>
<pre>
<span class="variable">perl</span> <span class="operator">-</span><span class="variable">MCPAN</span> <span class="keyword">-e</span> <span class="variable">shell</span><span class="operator">;</span>
</pre>
<p>Batch mode:</p>
<pre>
<span class="keyword">use</span> <span class="variable">CPAN</span><span class="operator">;</span>
</pre>
<pre>
autobundle, clean, install, make, recompile, test</pre>
<p>
</p>
<hr />
<h1><a name="status">STATUS</a></h1>
<p>This module will eventually be replaced by CPANPLUS. CPANPLUS is kind
of a modern rewrite from ground up with greater extensibility and more
features but no full compatibility. If you're new to CPAN.pm, you
probably should investigate if CPANPLUS is the better choice for you.
If you're already used to CPAN.pm you're welcome to continue using it,
if you accept that its development is mostly (though not completely)
stalled.</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The CPAN module is designed to automate the make and install of perl
modules and extensions. It includes some primitive searching capabilities and
knows how to use Net::FTP or LWP (or lynx or an external ftp client)
to fetch the raw data from the net.</p>
<p>Modules are fetched from one or more of the mirrored CPAN
(Comprehensive Perl Archive Network) sites and unpacked in a dedicated
directory.</p>
<p>The CPAN module also supports the concept of named and versioned
<em>bundles</em> of modules. Bundles simplify the handling of sets of
related modules. See Bundles below.</p>
<p>The package contains a session manager and a cache manager. There is
no status retained between sessions. The session manager keeps track
of what has been fetched, built and installed in the current
session. The cache manager keeps track of the disk space occupied by
the make processes and deletes excess space according to a simple FIFO
mechanism.</p>
<p>For extended searching capabilities there's a plugin for CPAN available,
<a href="../CPAN/WAIT.html"><code>CPAN::WAIT</code></a>. <code>CPAN::WAIT</code> is a full-text search engine
that indexes all documents available in CPAN authors directories. If
<code>CPAN::WAIT</code> is installed on your system, the interactive shell of
CPAN.pm will enable the <code>wq</code>, <code>wr</code>, <code>wd</code>, <code>wl</code>, and <code>wh</code> commands
which send queries to the WAIT server that has been configured for your
installation.</p>
<p>All other methods provided are accessible in a programmer style and in an
interactive shell style.</p>
<p>
</p>
<h2><a name="interactive_mode">Interactive Mode</a></h2>
<p>The interactive mode is entered by running</p>
<pre>
perl -MCPAN -e shell</pre>
<p>which puts you into a readline interface. You will have the most fun if
you install Term::ReadKey and Term::ReadLine to enjoy both history and
command completion.</p>
<p>Once you are on the command line, type 'h' and the rest should be
self-explanatory.</p>
<p>The function call <code>shell</code> takes two optional arguments, one is the
prompt, the second is the default initial command line (the latter
only works if a real ReadLine interface module is installed).</p>
<p>The most common uses of the interactive modes are</p>
<dl>
<dt><strong><a name="item_searching_for_authors_2c_bundles_2c_distribution_f">Searching for authors, bundles, distribution files and modules</a></strong>
<dd>
<p>There are corresponding one-letter commands <code>a</code>, <a href="../lib/Pod/perlguts.html#item_b"><code>b</code></a>, <a href="../lib/Pod/perlguts.html#item_d"><code>d</code></a>, and <a href="../lib/Pod/perlguts.html#item_m"><code>m</code></a>
for each of the four categories and another, <code>i</code> for any of the
mentioned four. Each of the four entities is implemented as a class
with slightly differing methods for displaying an object.</p>
</dd>
<dd>
<p>Arguments you pass to these commands are either strings exactly matching
the identification string of an object or regular expressions that are
then matched case-insensitively against various attributes of the
objects. The parser recognizes a regular expression only if you
enclose it between two slashes.</p>
</dd>
<dd>
<p>The principle is that the number of found objects influences how an
item is displayed. If the search finds one item, the result is
displayed with the rather verbose method <a href="#item_as_string"><code>as_string</code></a>, but if we find
more than one, we display each object with the terse method
<as_glimpse>.</p>
</dd>
</li>
<dt><strong><a name="item_make_2c_test_2c_install_2c_clean_modules_or_distri">make, test, install, clean modules or distributions</a></strong>
<dd>
<p>These commands take any number of arguments and investigate what is
necessary to perform the action. If the argument is a distribution
file name (recognized by embedded slashes), it is processed. If it is
a module, CPAN determines the distribution file in which this module
is included and processes that, following any dependencies named in
the module's Makefile.PL (this behavior is controlled by
<em>prerequisites_policy</em>.)</p>
</dd>
<dd>
<p>Any <a href="#item_make"><code>make</code></a> or <a href="#item_test"><code>test</code></a> are run unconditionally. An</p>
</dd>
<dd>
<pre>
install <distribution_file></pre>
</dd>
<dd>
<p>also is run unconditionally. But for</p>
</dd>
<dd>
<pre>
install <module></pre>
</dd>
<dd>
<p>CPAN checks if an install is actually needed for it and prints
<em>module up to date</em> in the case that the distribution file containing
the module doesn't need to be updated.</p>
</dd>
<dd>
<p>CPAN also keeps track of what it has done within the current session
and doesn't try to build a package a second time regardless if it
succeeded or not. The <a href="#item_force"><code>force</code></a> command takes as a first argument the
method to invoke (currently: <a href="#item_make"><code>make</code></a>, <a href="#item_test"><code>test</code></a>, or <a href="#item_install"><code>install</code></a>) and executes the
command from scratch.</p>
</dd>
<dd>
<p>Example:</p>
</dd>
<dd>
<pre>
cpan> install OpenGL
OpenGL is up to date.
cpan> force install OpenGL
Running make
OpenGL-0.4/
OpenGL-0.4/COPYRIGHT
[...]</pre>
</dd>
<dd>
<p>A <a href="#item_clean"><code>clean</code></a> command results in a</p>
</dd>
<dd>
<pre>
make clean</pre>
</dd>
<dd>
<p>being executed within the distribution file's working directory.</p>
</dd>
</li>
<dt><strong><a name="item_get_2c_readme_2c_look_module_or_distribution">get, readme, look module or distribution</a></strong>
<dd>
<p><a href="#item_get"><code>get</code></a> downloads a distribution file without further action. <a href="#item_readme"><code>readme</code></a>
displays the README file of the associated distribution. <code>Look</code> gets
and untars (if not yet done) the distribution file, changes to the
appropriate directory and opens a subshell process in that directory.</p>
</dd>
</li>
<dt><strong><a name="item_ls_author">ls author</a></strong>
<dd>
<p><code>ls</code> lists all distribution files in and below an author's CPAN
directory. Only those files that contain modules are listed and if
there is more than one for any given module, only the most recent one
is listed.</p>
</dd>
</li>
<dt><strong><a name="item_signals">Signals</a></strong>
<dd>
<p>CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
in the cpan-shell it is intended that you can press <code>^C</code> anytime and
return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
to clean up and leave the shell loop. You can emulate the effect of a
SIGTERM by sending two consecutive SIGINTs, which usually means by
pressing <code>^C</code> twice.</p>
</dd>
<dd>
<p>CPAN.pm ignores a SIGPIPE. If the user sets inactivity_timeout, a
SIGALRM is used during the run of the <code>perl Makefile.PL</code> subprocess.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="cpan__shell">CPAN::Shell</a></h2>
<p>The commands that are available in the shell interface are methods in
the package CPAN::Shell. If you enter the shell command, all your
input is split by the Text::ParseWords::shellwords() routine which
acts like most shells do. The first word is being interpreted as the
method to be called and the rest of the words are treated as arguments
to this method. Continuation lines are supported if a line ends with a
literal backslash.</p>
<p>
</p>
<h2><a name="autobundle">autobundle</a></h2>
<p><code>autobundle</code> writes a bundle file into the
<code>$CPAN::Config->{cpan_home}/Bundle</code> directory. The file contains
a list of all modules that are both available from CPAN and currently
installed within @INC. The name of the bundle file is based on the
current date and a counter.</p>
<p>
</p>
<h2><a name="recompile">recompile</a></h2>
<p><code>recompile()</code> is a very special command in that it takes no argument and
runs the make/test/install cycle with brute force over all installed
dynamically loadable extensions (aka XS modules) with 'force' in
effect. The primary purpose of this command is to finish a network
installation. Imagine, you have a common source tree for two different
architectures. You decide to do a completely independent fresh
installation. You start on one architecture with the help of a Bundle
file produced earlier. CPAN installs the whole Bundle for you, but
when you try to repeat the job on the second architecture, CPAN
responds with a <code>"Foo up to date"</code> message for all modules. So you
invoke CPAN's recompile on the second architecture and you're done.</p>
<p>Another popular use for <code>recompile</code> is to act as a rescue in case your
perl breaks binary compatibility. If one of the modules that CPAN uses
is in turn depending on binary compatibility (so you cannot run CPAN
commands), then you should try the CPAN::Nox module for recovery.</p>
<p>
</p>
<h2><a name="the_four_cpan____classes__author__bundle__module__distribution">The four <code>CPAN::*</code> Classes: Author, Bundle, Module, Distribution</a></h2>
<p>Although it may be considered internal, the class hierarchy does matter
for both users and programmer. CPAN.pm deals with above mentioned four
classes, and all those classes share a set of methods. A classical
single polymorphism is in effect. A metaclass object registers all
objects of all kinds and indexes them with a string. The strings
referencing objects have a separated namespace (well, not completely
separated):</p>
<pre>
Namespace Class</pre>
<pre>
words containing a "/" (slash) Distribution
words starting with Bundle:: Bundle
everything else Module or Author</pre>
<p>Modules know their associated Distribution objects. They always refer
to the most recent official release. Developers may mark their releases
as unstable development versions (by inserting an underbar into the
module version number which will also be reflected in the distribution
name when you run 'make dist'), so the really hottest and newest
distribution is not always the default. If a module Foo circulates
on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
way to install version 1.23 by saying</p>
<pre>
install Foo</pre>
<p>This would install the complete distribution file (say
BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
like to install version 1.23_90, you need to know where the
distribution file resides on CPAN relative to the authors/id/
directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
so you would have to say</p>
<pre>
install BAR/Foo-1.23_90.tar.gz</pre>
<p>The first example will be driven by an object of the class
CPAN::Module, the second by an object of class CPAN::Distribution.</p>
<p>
</p>
<h2><a name="programmer_s_interface">Programmer's interface</a></h2>
<p>If you do not enter the shell, the available shell commands are both
available as methods (<a href="#item_install"><code>CPAN::Shell->install(...)</code></a>) and as
functions in the calling package (<a href="#item_install"><code>install(...)</code></a>).</p>
<p>There's currently only one class that has a stable interface -
CPAN::Shell. All commands that are available in the CPAN shell are
methods of the class CPAN::Shell. Each of the commands that produce
listings of modules (<a href="../lib/Pod/perlguts.html#item_r"><code>r</code></a>, <code>autobundle</code>, <code>u</code>) also return a list of
the IDs of all modules within the list.</p>
<dl>
<dt><strong><a name="item_expand"><code>expand($type,@things)</code></a></strong>
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?