ch02_04.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<blockquote><pre class="code">perl ppm.pl</pre></blockquote>

<p>The PPM prompt appears, and you can begin to enter PPM commands. The
available commands are:
</p>

<dl>
<dt><b><tt class="literal">help</tt><em class="replaceable"> </em><tt class="literal">[</tt><em class="replaceable">command</em><tt class="literal">]</tt></b></dt>
<dd>
Prints the list of commands and what they do, or help for a
particular command.
</p>
</dd>


<dt><b><tt class="literal">install</tt> <em class="replaceable">packages</em></b></dt>
<dd>
Installs the specified packages.</p>
</dd>


<dt><b><tt class="literal">quit</tt></b></dt>
<dd>
Leaves PPM.</p>
</dd>


<dt><b><tt class="literal">remove</tt> <em class="replaceable">packages</em></b></dt>
<dd>
Removes the specified packages from the system.</p>
</dd>


<dt><b><tt class="literal">search</tt></b></dt>
<dd>
Searches for information about available packages.</p>
</dd>


<dt><b><tt class="literal">set</tt></b></dt>
<dd>
Sets or displays current options.</p>
</dd>


<dt><b><tt class="literal">verify</tt></b></dt>
<dd>
Verifies that your current installation is up-to-date.</p>
</dd>

</dl>

</div>
</div>
<a name="perlnut2-CHP-2-SECT-4.4" /><div class="sect2">
<h3 class="sect2">2.4.4. Installing Modules with the CPAN Module</h3>

<p><a name="INDEX-94" />If you are just getting and installing
one or a few modules, it's not a big problem to
download the module's tarball and run through the
build process manually. But if you don't want to
cope with the brute-force approach when dealing with large module
installations (such as LWP and the CPAN bundle), there is an easier
way&#x2014;you can use the CPAN module. The CPAN module (CPAN.pm) can
be used interactively from the command line to locate, download, and
install Perl modules and their dependencies, or to identify modules
and authors. CPAN.pm was designed to automate the installation of
Perl modules; it includes searching capabilities and the ability to
retrieve files from one or more of the mirrored CPAN sites and unpack
them in a dedicated directory.
</p>

<p>To run the CPAN module interactively, enter:</p>

<blockquote><pre class="code">% perl -MCPAN -e shell</pre></blockquote>

<p>The first time you use the CPAN module, it takes you through a series
of setup questions and writes
<a name="INDEX-95" />CPAN::Config
if you run the above as root or your administrative user. If the
above is run as a user who does not have administrative permissions,
CPAN.pm determines who you are and writes
<em class="emphasis">MyConfig.pm</em><a name="INDEX-96" />
in a subdirectory of your home directory (defaults to
<em class="emphasis">~/.cpan/CPAN/MyConfig.pm</em>). After that, whenever
you use the CPAN module for downloading other modules, it uses
the<a name="INDEX-97" /> <em class="emphasis">.cpan</em> directory
as the general build and cache directory, saved as
<tt class="literal">cpan_home</tt> in the configuration file. If ReadLine
support is available (i.e., Term::ReadKey and Term::ReadLine are
installed), you can use command history and command completion as you
enter commands.
</p>

<p>When the module runs and is ready for commands to be entered,
you'll see the prompt:
</p>

<blockquote><pre class="code">cpan&gt;</pre></blockquote>

<p>You can then enter <tt class="literal">h</tt> to get a brief help message,
or just start entering commands. The commands are all methods in the
CPAN::Shell package. For commands that can operate on modules,
bundles, authors, or distributions, CPAN.pm treats arguments
containing a slash (<tt class="literal">/</tt><a name="INDEX-98" />) as distributions, arguments
beginning with
<tt class="literal">Bundle::</tt><a name="INDEX-99" /> as bundles, and everything else as
modules or authors. The following is a listing of the interactive
<a name="INDEX-100" />CPAN
commands.
</p>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>?</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
?
</pre><p>Displays brief help message. Same as <tt class="literal">h</tt> command.</p></div>

<a name="INDEX-101" /><a name="INDEX-102" /><a name="INDEX-103" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>!</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
! <em class="replaceable">perl-code</em>
</pre><p><tt class="literal">eval</tt>s a Perl command<a name="INDEX-101" /><a name="INDEX-102" /><a name="INDEX-103" />.
</p></div>

<a name="INDEX-104" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>a</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
a [<em class="replaceable">authorlist</em>]
</pre><p><a name="INDEX-104" />Searches
for CPAN authors. Arguments can be strings that must be matched
exactly or regular expressions, which must be enclosed in slashes and
are matched in case-insensitive fashion. With no arguments, it
returns a list of all authors, by CPAN ID. With arguments, it returns
a list of authors if there is more than one that matches the
criteria, or it returns additional information if a single author is
returned. String and regular expression arguments can be combined in
the same command.
</p><blockquote><pre class="code">cpan&gt; a /^nv/ LWALL
Author          NVPAT (Nathan V. Patwardhan)
Author          LWALL (Larry Wall. Author of Perl. Busy man.)
cpan&gt; a /^nv/
Author id = NVPAT
    EMAIL        [e-mail]
    FULLNAME     Nathan V. Patwardhan</pre></blockquote></div>

<a name="INDEX-105" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>autobundle</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
autobundle [<em class="replaceable">bundlelist</em>]
</pre><p><a name="INDEX-105" />Writes a bundle file containing a list
of all modules that are both available from CPAN and currently
installed within <tt class="literal">@INC</tt>. The file is written to the
<em class="emphasis">Bundle</em> subdirectory of
<tt class="literal">cpan_home</tt> with a name that contains the current
date and a counter&#x2014;for example,
<em class="emphasis">Snapshot_1998_04_27_00.pm</em>. You can use this file
as input to the <tt class="literal">install</tt> command to install the
latest versions of all the modules on your system:
</p><blockquote><pre class="code">perl -MCPAN -e 'install Bundle::Snapshot_1998_04_27_00'</pre></blockquote></div>

<a name="INDEX-106" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>b</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
b [<em class="replaceable">bundlelist</em>]
</pre><p><a name="INDEX-106" />Searches
for CPAN bundles. Arguments are the same as for the
<tt class="literal">a</tt> command, except they specify bundles. With a
single argument, <tt class="literal">b</tt> displays details about the
bundle; with multiple arguments, it displays a list.
</p></div>

<a name="INDEX-107" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>clean</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
clean [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-107" />Does
a <em class="emphasis">make clean</em> in the distribution
file's directory. <em class="replaceable"><tt>arglist</tt></em>can include one or more modules, bundles, distributions, or one of
the values <tt class="literal">r</tt> or <tt class="literal">u</tt> to reinstall
or uninstall.
</p></div>

<a name="INDEX-108" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>d</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
d [<em class="replaceable">distriblist</em>]
</pre><p><a name="INDEX-108" />Displays
information about module distributions for the distribution(s)
specified in <em class="replaceable"><tt>distriblist</tt></em>. Arguments are
the same as for the <tt class="literal">a</tt> command. Displays details
for a single argument, or a list if the output consists of multiple
distributions.
</p></div>

<a name="INDEX-109" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>force</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
force <em class="replaceable">method</em> [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-109" />Takes as a first argument the method
to invoke, which can be one of <tt class="literal">make</tt>,
<tt class="literal">test</tt>, or <tt class="literal">install</tt>, and executes
the command from scratch for each argument in
<em class="replaceable"><tt>arglist</tt></em>. The arguments may be modules or
distributions.
</p><p>Be warned that <tt class="literal">force</tt> also allows you to install
modules that have failed some or all of the module tests. If
installing modules that have failed their tests bothers you, then you
shouldn't use <tt class="literal">force</tt>.
</p></div>

<a name="INDEX-110" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>h</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
h
</pre><p><a name="INDEX-110" />Displays
brief help message. Same as <tt class="literal">?</tt>.
</p></div>

<a name="INDEX-111" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>i</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
i [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-111" />Displays
information about the arguments specified in
<em class="replaceable"><tt>arglist</tt></em>, which can be an author, module,
bundle, or distribution. Arguments and output are the same as for
<tt class="literal">a</tt>.
</p></div>

<a name="INDEX-112" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>install</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
install [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-112" />Installs the arguments specified in
<em class="replaceable"><tt>arglist</tt></em>, which can be modules or
distributions. Implies <tt class="literal">test</tt>. For a distribution,
<tt class="literal">install</tt> is run unconditionally. For a module,
CPAN.pm checks to see if the module is up-to-date, and if so, prints
a message to that effect and does not do the install. Otherwise, it
finds and processes the distribution that contains the module.
</p></div>

<a name="INDEX-113" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>look</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
look <em class="replaceable">arg</em>
</pre><p><a name="INDEX-113" />Takes
one argument, which is a module or distribution, gets and untars the
distribution file if necessary, changes to the appropriate directory,
and opens a subshell process in that directory.
</p></div>

<a name="INDEX-114" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>m</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
m [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-114" />Displays
information about modules. Arguments are the same as for the
<tt class="literal">a</tt> command. Displays details for a single module,
or a list if there is more than one in the output.
</p></div>

<a name="INDEX-115" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>make</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
make [<em class="replaceable">arglist</em>]
</pre><p><a name="INDEX-115" />Unconditionally runs a
<em class="emphasis">make</em> on each argument in
<em class="replaceable"><tt>arglist</tt></em>, which can be a module or a
distribution. For a module, CPAN.pm finds and processes the
distribution that contains the module.
</p></div>

<a name="INDEX-116" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>o</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
o <em class="replaceable">type</em> [<em class="replaceable">option</em>] [<em class="replaceable">value</em>]
</pre><p><a name="INDEX-116" />Sets and
queries options. Takes the following arguments:
</p><dl>
<dt><i><em class="replaceable"><tt>type</tt></em></i></dt>
<dd>
Type of options to set or query. The possible values are:</p>

<dl>
<dt><b><tt class="literal">debug</tt></b></dt>
<dd>
Debugging options. Prints CPAN module options for debugging the
package.
</p>
</dd>


<dt><b><tt class="literal">conf</tt></b></dt>
<dd>
Configuration options. Lists or sets values for CPAN module
configuration variables kept in the hash
<tt class="literal">%CPAN::Config</tt>. These configuration variables are:
</p>


<a name="ch02-24-fm2xml" /><table border="1" cellpadding="3">



<tr>
<th>
<p>Variable</p>
</th>
<th>
<p>Content</p>
</th>
</tr>


<tr>
<td>
<p><tt class="literal">build_cache</tt></p>
</td>
<td>
<p>Size of cache for directories to build modules</p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">build_dir</tt></p>
</td>
<td>
<p>Locally accessible directory to build modules</p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">index_expire</tt></p>
</td>
<td>