452 lines
11 KiB
HTML
452 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of CPAN</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>CPAN</H1>
|
|
Section: Perl Programmers Reference Guide (1)<BR>Updated: 2020-10-19<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
cpan - easily interact with CPAN from the command line
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# with arguments and no switches, installs specified modules
|
|
cpan module_name [ module_name ... ]
|
|
|
|
# with switches, installs modules with extra behavior
|
|
cpan [-cfFimtTw] module_name [ module_name ... ]
|
|
|
|
# use local::lib
|
|
cpan -I module_name [ module_name ... ]
|
|
|
|
# one time mirror override for faster mirrors
|
|
cpan -p ...
|
|
|
|
# with just the dot, install from the distribution in the
|
|
# current directory
|
|
cpan .
|
|
|
|
# without arguments, starts CPAN.pm shell
|
|
cpan
|
|
|
|
# without arguments, but some switches
|
|
cpan [-ahpruvACDLOPX]
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This script provides a command interface (not a shell) to <FONT SIZE="-1">CPAN.</FONT> At the
|
|
moment it uses <FONT SIZE="-1">CPAN</FONT>.pm to do the work, but it is not a one-shot command
|
|
runner for <FONT SIZE="-1">CPAN</FONT>.pm.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Options</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">-a<DD>
|
|
|
|
|
|
Creates a <FONT SIZE="-1">CPAN</FONT>.pm autobundle with CPAN::Shell->autobundle.
|
|
<DT id="2">-A module [ module ... ]<DD>
|
|
|
|
|
|
Shows the primary maintainers for the specified modules.
|
|
<DT id="3">-c module<DD>
|
|
|
|
|
|
Runs a `make clean` in the specified module's directories.
|
|
<DT id="4">-C module [ module ... ]<DD>
|
|
|
|
|
|
Show the <I>Changes</I> files for the specified modules
|
|
<DT id="5">-D module [ module ... ]<DD>
|
|
|
|
|
|
Show the module details. This prints one line for each out-of-date module
|
|
(meaning, modules locally installed but have newer versions on <FONT SIZE="-1">CPAN</FONT>).
|
|
Each line has three columns: module name, local version, and <FONT SIZE="-1">CPAN</FONT>
|
|
version.
|
|
<DT id="6">-f<DD>
|
|
|
|
|
|
Force the specified action, when it normally would have failed. Use this
|
|
to install a module even if its tests fail. When you use this option,
|
|
-i is not optional for installing a module when you need to force it:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
% cpan -f -i Module::Foo
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="7">-F<DD>
|
|
|
|
|
|
Turn off <FONT SIZE="-1">CPAN</FONT>.pm's attempts to lock anything. You should be careful with
|
|
this since you might end up with multiple scripts trying to muck in the
|
|
same directory. This isn't so much of a concern if you're loading a special
|
|
config with <TT>"-j"</TT>, and that config sets up its own work directories.
|
|
<DT id="8">-g module [ module ... ]<DD>
|
|
|
|
|
|
Downloads to the current directory the latest distribution of the module.
|
|
<DT id="9">-G module [ module ... ]<DD>
|
|
|
|
|
|
<FONT SIZE="-1">UNIMPLEMENTED</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Download to the current directory the latest distribution of the
|
|
modules, unpack each distribution, and create a git repository for each
|
|
distribution.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you want this feature, check out Yanick Champoux's <TT>"Git::CPAN::Patch"</TT>
|
|
distribution.
|
|
<DT id="10">-h<DD>
|
|
|
|
|
|
Print a help message and exit. When you specify <TT>"-h"</TT>, it ignores all
|
|
of the other options and arguments.
|
|
<DT id="11">-i module [ module ... ]<DD>
|
|
|
|
|
|
Install the specified modules. With no other switches, this switch
|
|
is implied.
|
|
<DT id="12">-I<DD>
|
|
|
|
|
|
Load <TT>"local::lib"</TT> (think like <TT>"-I"</TT> for loading lib paths). Too bad
|
|
<TT>"-l"</TT> was already taken.
|
|
<DT id="13">-j Config.pm<DD>
|
|
|
|
|
|
Load the file that has the <FONT SIZE="-1">CPAN</FONT> configuration data. This should have the
|
|
same format as the standard <I>CPAN/Config.pm</I> file, which defines
|
|
<TT>$CPAN::Config</TT> as an anonymous hash.
|
|
<DT id="14">-J<DD>
|
|
|
|
|
|
Dump the configuration in the same format that <FONT SIZE="-1">CPAN</FONT>.pm uses. This is useful
|
|
for checking the configuration as well as using the dump as a starting point
|
|
for a new, custom configuration.
|
|
<DT id="15">-l<DD>
|
|
|
|
|
|
List all installed modules with their versions
|
|
<DT id="16">-L author [ author ... ]<DD>
|
|
|
|
|
|
List the modules by the specified authors.
|
|
<DT id="17">-m<DD>
|
|
|
|
|
|
Make the specified modules.
|
|
<DT id="18">-M mirror1,mirror2,...<DD>
|
|
|
|
|
|
A comma-separated list of mirrors to use for just this run. The <TT>"-P"</TT>
|
|
option can find them for you automatically.
|
|
<DT id="19">-n<DD>
|
|
|
|
|
|
Do a dry run, but don't actually install anything. (unimplemented)
|
|
<DT id="20">-O<DD>
|
|
|
|
|
|
Show the out-of-date modules.
|
|
<DT id="21">-p<DD>
|
|
|
|
|
|
Ping the configured mirrors and print a report
|
|
<DT id="22">-P<DD>
|
|
|
|
|
|
Find the best mirrors you could be using and use them for the current
|
|
session.
|
|
<DT id="23">-r<DD>
|
|
|
|
|
|
Recompiles dynamically loaded modules with CPAN::Shell->recompile.
|
|
<DT id="24">-s<DD>
|
|
|
|
|
|
Drop in the <FONT SIZE="-1">CPAN</FONT>.pm shell. This command does this automatically if you don't
|
|
specify any arguments.
|
|
<DT id="25">-t module [ module ... ]<DD>
|
|
|
|
|
|
Run a `make test` on the specified modules.
|
|
<DT id="26">-T<DD>
|
|
|
|
|
|
Do not test modules. Simply install them.
|
|
<DT id="27">-u<DD>
|
|
|
|
|
|
Upgrade all installed modules. Blindly doing this can really break things,
|
|
so keep a backup.
|
|
<DT id="28">-v<DD>
|
|
|
|
|
|
Print the script version and <FONT SIZE="-1">CPAN</FONT>.pm version then exit.
|
|
<DT id="29">-V<DD>
|
|
|
|
|
|
Print detailed information about the cpan client.
|
|
<DT id="30">-w<DD>
|
|
|
|
|
|
<FONT SIZE="-1">UNIMPLEMENTED</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Turn on cpan warnings. This checks various things, like directory permissions,
|
|
and tells you about problems you might have.
|
|
<DT id="31">-x module [ module ... ]<DD>
|
|
|
|
|
|
Find close matches to the named modules that you think you might have
|
|
mistyped. This requires the optional installation of Text::Levenshtein or
|
|
Text::Levenshtein::Damerau.
|
|
<DT id="32">-X<DD>
|
|
|
|
|
|
Dump all the namespaces to standard output.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Examples</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# print a help message
|
|
cpan -h
|
|
|
|
# print the version numbers
|
|
cpan -v
|
|
|
|
# create an autobundle
|
|
cpan -a
|
|
|
|
# recompile modules
|
|
cpan -r
|
|
|
|
# upgrade all installed modules
|
|
cpan -u
|
|
|
|
# install modules ( sole -i is optional )
|
|
cpan -i Netscape::Booksmarks Business::ISBN
|
|
|
|
# force install modules ( must use -i )
|
|
cpan -fi CGI::Minimal URI
|
|
|
|
# install modules but without testing them
|
|
cpan -Ti CGI::Minimal URI
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Environment variables</H3>
|
|
|
|
|
|
|
|
There are several components in <FONT SIZE="-1">CPAN</FONT>.pm that use environment variables.
|
|
The build tools, ExtUtils::MakeMaker and Module::Build use some,
|
|
while others matter to the levels above them. Some of these are specified
|
|
by the Perl Toolchain Gang:
|
|
<P>
|
|
|
|
Lancaster Concensus: <<A HREF="https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md">https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md</A>>
|
|
<P>
|
|
|
|
Oslo Concensus: <<A HREF="https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/oslo-consensus.md">https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/oslo-consensus.md</A>>
|
|
<DL COMPACT>
|
|
<DT id="33"><FONT SIZE="-1">NONINTERACTIVE_TESTING</FONT><DD>
|
|
|
|
|
|
Assume no one is paying attention and skips prompts for distributions
|
|
that do that correctly. <TT><A HREF="/cgi-bin/man/man2html?1+cpan">cpan</A>(1)</TT> sets this to <TT>1</TT> unless it already
|
|
has a value (even if that value is false).
|
|
<DT id="34"><FONT SIZE="-1">PERL_MM_USE_DEFAULT</FONT><DD>
|
|
|
|
|
|
Use the default answer for a prompted questions. <TT><A HREF="/cgi-bin/man/man2html?1+cpan">cpan</A>(1)</TT> sets this
|
|
to <TT>1</TT> unless it already has a value (even if that value is false).
|
|
<DT id="35"><FONT SIZE="-1">CPAN_OPTS</FONT><DD>
|
|
|
|
|
|
As with <TT>"PERL5OPT"</TT>, a string of additional <TT><A HREF="/cgi-bin/man/man2html?1+cpan">cpan</A>(1)</TT> options to
|
|
add to those you specify on the command line.
|
|
<DT id="36"><FONT SIZE="-1">CPANSCRIPT_LOGLEVEL</FONT><DD>
|
|
|
|
|
|
The log level to use, with either the embedded, minimal logger or
|
|
Log::Log4perl if it is installed. Possible values are the same as
|
|
the <TT>"Log::Log4perl"</TT> levels: <TT>"TRACE"</TT>, <TT>"DEBUG"</TT>, <TT>"INFO"</TT>, <TT>"WARN"</TT>,
|
|
<TT>"ERROR"</TT>, and <TT>"FATAL"</TT>. The default is <TT>"INFO"</TT>.
|
|
<DT id="37"><FONT SIZE="-1">GIT_COMMAND</FONT><DD>
|
|
|
|
|
|
The path to the <TT>"git"</TT> binary to use for the Git features. The default
|
|
is <TT>"/usr/local/bin/git"</TT>.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>EXIT VALUES</H2>
|
|
|
|
|
|
|
|
The script exits with zero if it thinks that everything worked, or a
|
|
positive number if it thinks that something failed. Note, however, that
|
|
in some cases it has to divine a failure by the output of things it does
|
|
not control. For now, the exit codes are vague:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
1 An unknown error
|
|
|
|
2 The was an external problem
|
|
|
|
4 There was an internal problem with the script
|
|
|
|
8 A module failed to install
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>TO DO</H2>
|
|
|
|
|
|
|
|
* one shot configuration values from the command line
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
* none noted
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Most behaviour, including environment variables and configuration,
|
|
comes directly from <FONT SIZE="-1">CPAN</FONT>.pm.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SOURCE AVAILABILITY</H2>
|
|
|
|
|
|
|
|
This code is in Github in the <FONT SIZE="-1">CPAN</FONT>.pm repository:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
<A HREF="https://github.com/andk/cpanpm">https://github.com/andk/cpanpm</A>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The source used to be tracked separately in another GitHub repo,
|
|
but the canonical source is now in the above repo.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>CREDITS</H2>
|
|
|
|
|
|
|
|
Japheth Cleaver added the bits to allow a forced install (-f).
|
|
<P>
|
|
|
|
Jim Brandt suggest and provided the initial implementation for the
|
|
up-to-date and Changes features.
|
|
<P>
|
|
|
|
Adam Kennedy pointed out that <B>exit()</B> causes problems on Windows
|
|
where this script ends up with a .bat extension
|
|
<A NAME="lbAN"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
brian d foy, <TT>"<<A HREF="mailto:bdfoy@cpan.org">bdfoy@cpan.org</A>>"</TT>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (c) 2001-2015, brian d foy, All Rights Reserved.
|
|
<P>
|
|
|
|
You may redistribute this under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="38"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="39"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="40"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="41"><A HREF="#lbAE">Options</A><DD>
|
|
<DT id="42"><A HREF="#lbAF">Examples</A><DD>
|
|
<DT id="43"><A HREF="#lbAG">Environment variables</A><DD>
|
|
</DL>
|
|
<DT id="44"><A HREF="#lbAH">EXIT VALUES</A><DD>
|
|
<DT id="45"><A HREF="#lbAI">TO DO</A><DD>
|
|
<DT id="46"><A HREF="#lbAJ">BUGS</A><DD>
|
|
<DT id="47"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="48"><A HREF="#lbAL">SOURCE AVAILABILITY</A><DD>
|
|
<DT id="49"><A HREF="#lbAM">CREDITS</A><DD>
|
|
<DT id="50"><A HREF="#lbAN">AUTHOR</A><DD>
|
|
<DT id="51"><A HREF="#lbAO">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:09 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|