cpan.html

来自「perl教程」· HTML 代码 · 共 1,396 行 · 第 1/4 页

</dd>
</li>
<dt><strong>CPAN::Distribution::test()</strong>

<dd>
<p>Changes to the directory where the distribution has been unpacked and
runs <code>make test</code> there.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::uptodate()</strong>

<dd>
<p>Returns 1 if all the modules contained in the distribution are
uptodate. Relies on containsmods.</p>
</dd>
</li>
<dt><strong><a name="item_force_reload">CPAN::Index::force_reload()</a></strong>

<dd>
<p>Forces a reload of all indices.</p>
</dd>
</li>
<dt><strong><a name="item_reload">CPAN::Index::reload()</a></strong>

<dd>
<p>Reloads all indices if they have been read more than
<code>$CPAN::Config-</code>{index_expire}&gt; days.</p>
</dd>
</li>
<dt><strong><a name="item_dump">CPAN::InfoObj::dump()</a></strong>

<dd>
<p>CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
inherit this method. It prints the data structure associated with an
object. Useful for debugging. Note: the data structure is considered
internal and thus subject to change without notice.</p>
</dd>
</li>
<dt><strong>CPAN::Module::as_glimpse()</strong>

<dd>
<p>Returns a one-line description of the module</p>
</dd>
</li>
<dt><strong>CPAN::Module::as_string()</strong>

<dd>
<p>Returns a multi-line description of the module</p>
</dd>
</li>
<dt><strong>CPAN::Module::clean()</strong>

<dd>
<p>Runs a clean on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong><a name="item_cpan_file">CPAN::Module::cpan_file()</a></strong>

<dd>
<p>Returns the filename on CPAN that is associated with the module.</p>
</dd>
</li>
<dt><strong><a name="item_cpan_version">CPAN::Module::cpan_version()</a></strong>

<dd>
<p>Returns the latest version of this module available on CPAN.</p>
</dd>
</li>
<dt><strong>CPAN::Module::cvs_import()</strong>

<dd>
<p>Runs a cvs_import on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong><a name="item_description">CPAN::Module::description()</a></strong>

<dd>
<p>Returns a 44 character description of this module. Only available for
modules listed in The Module List (CPAN/modules/00modlist.long.html
or 00modlist.long.txt.gz)</p>
</dd>
</li>
<dt><strong>CPAN::Module::force($method,@args)</strong>

<dd>
<p>Forces CPAN to perform a task that normally would have failed. Force
takes as arguments a method name to be called and any number of
additional arguments that should be passed to the called method. The
internals of the object get the needed changes so that CPAN.pm does
not refuse to take the action.</p>
</dd>
</li>
<dt><strong>CPAN::Module::get()</strong>

<dd>
<p>Runs a get on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong>CPAN::Module::inst_file()</strong>

<dd>
<p>Returns the filename of the module found in @INC. The first file found
is reported just like perl itself stops searching @INC when it finds a
module.</p>
</dd>
</li>
<dt><strong>CPAN::Module::inst_version()</strong>

<dd>
<p>Returns the version number of the module in readable format.</p>
</dd>
</li>
<dt><strong>CPAN::Module::install()</strong>

<dd>
<p>Runs an <a href="#item_install"><code>install</code></a> on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong>CPAN::Module::look()</strong>

<dd>
<p>Changes to the directory where the distribution associated with this
module has been unpacked and opens a subshell there. Exiting the
subshell returns.</p>
</dd>
</li>
<dt><strong>CPAN::Module::make()</strong>

<dd>
<p>Runs a <a href="#item_make"><code>make</code></a> on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong><a name="item_manpage_headline">CPAN::Module::manpage_headline()</a></strong>

<dd>
<p>If module is installed, peeks into the module's manpage, reads the
headline and returns it. Moreover, if the module has been downloaded
within this session, does the equivalent on the downloaded module even
if it is not installed.</p>
</dd>
</li>
<dt><strong>CPAN::Module::readme()</strong>

<dd>
<p>Runs a <a href="#item_readme"><code>readme</code></a> on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong>CPAN::Module::test()</strong>

<dd>
<p>Runs a <a href="#item_test"><code>test</code></a> on the distribution associated with this module.</p>
</dd>
</li>
<dt><strong>CPAN::Module::uptodate()</strong>

<dd>
<p>Returns 1 if the module is installed and up-to-date.</p>
</dd>
</li>
<dt><strong><a name="item_userid">CPAN::Module::userid()</a></strong>

<dd>
<p>Returns the author's ID of the module.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="cache_manager">Cache Manager</a></h2>
<p>Currently the cache manager only keeps track of the build directory
($CPAN::Config-&gt;{build_dir}). It is a simple FIFO mechanism that
deletes complete directories below <code>build_dir</code> as soon as the size of
all directories there gets bigger than $CPAN::Config-&gt;{build_cache}
(in MB). The contents of this cache may be used for later
re-installations that you intend to do manually, but will never be
trusted by CPAN itself. This is due to the fact that the user might
use these directories for building modules on different architectures.</p>
<p>There is another directory ($CPAN::Config-&gt;{keep_source_where}) where
the original distribution files are kept. This directory is not
covered by the cache manager and must be controlled by the user. If
you choose to have the same directory as build_dir and as
keep_source_where directory, then your sources will be deleted with
the same fifo mechanism.</p>
<p>
</p>
<h2><a name="bundles">Bundles</a></h2>
<p>A bundle is just a perl module in the namespace Bundle:: that does not
define any functions or methods. It usually only contains documentation.</p>
<p>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
only difference being that <em>one special pod section</em> exists starting with
(verbatim):</p>
<pre>
        =head1 CONTENTS</pre>
<p>In this pod section each line obeys the format</p>
<pre>
        Module_Name [Version_String] [- optional text]</pre>
<p>The only required part is the first field, the name of a module
(e.g. Foo::Bar, ie. <em>not</em> the name of the distribution file). The rest
of the line is optional. The comment part is delimited by a dash just
as in the man page header.</p>
<p>The distribution of a bundle should follow the same convention as
other distributions.</p>
<p>Bundles are treated specially in the CPAN package. If you say 'install
Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
the modules in the CONTENTS section of the pod. You can install your
own Bundles locally by placing a conformant Bundle file somewhere into
your @INC path. The <code>autobundle()</code> command which is available in the
shell interface does that for you by including all currently installed
modules in a snapshot bundle file.</p>
<p>
</p>
<h2><a name="prerequisites">Prerequisites</a></h2>
<p>If you have a local mirror of CPAN and can access all files with
&quot;file:&quot; URLs, then you only need a perl better than perl5.003 to run
this module. Otherwise Net::FTP is strongly recommended. LWP may be
required for non-UNIX systems or if your nearest CPAN site is
associated with a URL that is not <code>ftp:</code>.</p>
<p>If you have neither Net::FTP nor LWP, there is a fallback mechanism
implemented for an external ftp command or for an external lynx
command.</p>
<p>
</p>
<h2><a name="finding_packages_and_version">Finding packages and VERSION</a></h2>
<p>This module presumes that all packages on CPAN</p>
<ul>
<li>
<p>declare their $VERSION variable in an easy to parse manner. This
prerequisite can hardly be relaxed because it consumes far too much
memory to load all packages into the running program just to determine
the $VERSION variable. Currently all programs that are dealing with
version use something like this</p>
<pre>
    perl -MExtUtils::MakeMaker -le \
        'print MM-&gt;parse_version(shift)' filename</pre>
<p>If you are author of a package and wonder if your $VERSION can be
parsed, please try the above method.</p>
</li>
<li>
<p>come as compressed or gzipped tarfiles or as zip files and contain a
Makefile.PL (well, we try to handle a bit more, but without much
enthusiasm).</p>
</li>
</ul>
<p>
</p>
<h2><a name="debugging">Debugging</a></h2>
<p>The debugging of this module is a bit complex, because we have
interferences of the software producing the indices on CPAN, of the
mirroring process on CPAN, of packaging, of configuration, of
synchronicity, and of bugs within CPAN.pm.</p>
<p>For code debugging in interactive mode you can try &quot;o debug&quot; which
will list options for debugging the various parts of the code. You
should know that &quot;o debug&quot; has built-in completion support.</p>
<p>For data debugging there is the <a href="#item_dump"><code>dump</code></a> command which takes the same
arguments as make/test/install and outputs the object's Data::Dumper
dump.</p>
<p>
</p>
<h2><a name="floppy__zip__offline_mode">Floppy, Zip, Offline Mode</a></h2>
<p>CPAN.pm works nicely without network too. If you maintain machines
that are not networked at all, you should consider working with file:
URLs. Of course, you have to collect your modules somewhere first. So
you might use CPAN.pm to put together all you need on a networked
machine. Then copy the $CPAN::Config-&gt;{keep_source_where} (but not
$CPAN::Config-&gt;{build_dir}) directory on a floppy. This floppy is kind
of a personal CPAN. CPAN.pm on the non-networked machines works nicely
with this floppy. See also below the paragraph about CD-ROM support.</p>
<p>
</p>
<hr />
<h1><a name="configuration">CONFIGURATION</a></h1>
<p>When the CPAN module is used for the first time, a configuration
dialog tries to determine a couple of site specific options. The
result of the dialog is stored in a hash reference <code> $CPAN::Config </code>
in a file CPAN/Config.pm.</p>
<p>The default values defined in the CPAN/Config.pm file can be
overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
best placed in $HOME/.cpan/CPAN/MyConfig.pm, because $HOME/.cpan is
added to the search path of the CPAN module before the <a href="../lib/Pod/perlfunc.html#item_use"><code>use()</code></a> or
<a href="../lib/Pod/perlfunc.html#item_require"><code>require()</code></a> statements.</p>
<p>The configuration dialog can be started any time later again by
issueing the command <code> o conf init </code> in the CPAN shell.</p>
<p>Currently the following keys in the hash reference $CPAN::Config are
defined:</p>
<pre>
  build_cache        size of cache for directories to build modules
  build_dir          locally accessible directory to build modules
  index_expire       after this many days refetch index files
  cache_metadata     use serializer to cache metadata
  cpan_home          local directory reserved for this package
  dontload_hash      anonymous hash: modules in the keys will not be
                     loaded by the CPAN::has_inst() routine
  gzip               location of external program gzip
  histfile           file to maintain history between sessions
  histsize           maximum number of lines to keep in histfile
  inactivity_timeout breaks interactive Makefile.PLs after this
                     many seconds inactivity. Set to 0 to never break.
  inhibit_startup_message
                     if true, does not print the startup message
  keep_source_where  directory in which to keep the source (if we do)
  make               location of external make program
  make_arg           arguments that should always be passed to 'make'
  make_install_arg   same as make_arg for 'make install'
  makepl_arg         arguments passed to 'perl Makefile.PL'
  pager              location of external program more (or any pager)
  prerequisites_policy
                     what to do if you are missing module prerequisites
                     ('follow' automatically, 'ask' me, or 'ignore')
  proxy_user         username for accessing an authenticating proxy
  proxy_pass         password for accessing an authenticating proxy
  scan_cache         controls scanning of cache ('atstart' or 'never')
  tar                location of external program tar
  term_is_latin      if true internal UTF-8 is translated to ISO-8859-1
                     (and nonsense for characters outside latin range)
  unzip              location of external program unzip
  urllist            arrayref to nearby CPAN sites (or equivalent locations)
  wait_list          arrayref to a wait server to try (See CPAN::WAIT)
  ftp_proxy,      }  the three usual variables for configuring
    http_proxy,   }  proxy requests. Both as CPAN::Config variables
    no_proxy      }  and as environment variables configurable.</pre>
<p>You can set and query each of these options interactively in the cpan
shell with the command set defined within the <code>o conf</code> command:</p>
<dl>
<dt><strong><a name="item_o_conf__3cscalar_option_3e"><code>o conf &lt;scalar option&gt;</code></a></strong>

<dd>
<p>prints the current value of the <em>scalar option</em></p>
</dd>
</li>
<dt><strong><a name="item_o_conf__3cscalar_option_3e__3cvalue_3e"><code>o conf &lt;scalar option&gt; &lt;value&gt;</code></a></strong>

<dd>
<p>Sets the value of the <em>scalar option</em> to <em>value</em></p>
</dd>
</li>
<dt><strong><a name="item_o_conf__3clist_option_3e"><code>o conf &lt;list option&gt;</code></a></strong>

<dd>
<p>prints the current value of the <em>list option</em> in MakeMaker's
neatvalue format.</p>
</dd>
</li>
<dt><strong><a name="item_o_conf__3clist_option_3e__5bshift_7cpop_5d"><code>o conf &lt;list option&gt; [shift|pop]</code></a></strong>

<dd>
<p>shifts or pops the array in the <em>list option</em> variable</p>
</dd>
</li>