/usr/share/man/man3/CPAN.3pm (112896B)
, for development status, support level,
language, interface and public licence respectively. The data for the
\&\s-1DSLIP\s0 status are collected by pause.perl.org when authors register
their namespaces. The values of the 5 hash elements are one-character
words whose meaning is described in the table below. There are also 5
hash elements \f(CW\*(C`DV\*(C'\fR, \f(CW\*(C`SV\*(C'\fR, \f(CW\*(C`LV\*(C'\fR, \f(CW\*(C`IV\*(C'\fR, and <\s-1PV\s0> that carry a more
verbose value of the 5 status variables.
.Sp
Where the '\s-1DSLIP\s0' characters have the following meanings:
.Sp
.Vb 7
\& D \- Development Stage (Note: *NO IMPLIED TIMESCALES*):
\& i \- Idea, listed to gain consensus or as a placeholder
\& c \- under construction but pre\-alpha (not yet released)
\& a/b \- Alpha/Beta testing
\& R \- Released
\& M \- Mature (no rigorous definition)
\& S \- Standard, supplied with Perl 5
\&
\& S \- Support Level:
\& m \- Mailing\-list
\& d \- Developer
\& u \- Usenet newsgroup comp.lang.perl.modules
\& n \- None known, try comp.lang.perl.modules
\& a \- abandoned; volunteers welcome to take over maintenance
\&
\& L \- Language Used:
\& p \- Perl\-only, no compiler needed, should be platform independent
\& c \- C and perl, a C compiler will be needed
\& h \- Hybrid, written in perl with optional C code, no compiler needed
\& + \- C++ and perl, a C++ compiler will be needed
\& o \- perl and another language other than C or C++
\&
\& I \- Interface Style
\& f \- plain Functions, no references used
\& h \- hybrid, object and function interfaces available
\& n \- no interface at all (huh?)
\& r \- some use of unblessed References or ties
\& O \- Object oriented using blessed references and/or inheritance
\&
\& P \- Public License
\& p \- Standard\-Perl: user may choose between GPL and Artistic
\& g \- GPL: GNU General Public License
\& l \- LGPL: "GNU Lesser General Public License" (previously known as
\& "GNU Library General Public License")
\& b \- BSD: The BSD License
\& a \- Artistic license alone
\& 2 \- Artistic license 2.0 or later
\& o \- open source: approved by www.opensource.org
\& d \- allows distribution without restrictions
\& r \- restricted distribution
\& n \- no license at all
.Ve
.IP "CPAN::Module::force($method,@args)" 4
.IX Item "CPAN::Module::force($method,@args)"
Forces \s-1CPAN\s0 to perform a task it would normally refuse to
do. Force takes as arguments a method name to be invoked and any number
of additional arguments to pass that method.
The internals of the object get the needed changes so that \s-1CPAN\s0.pm
does not refuse to take the action. See also the section above on the
\&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
.IP "\fICPAN::Module::get()\fR" 4
.IX Item "CPAN::Module::get()"
Runs a get on the distribution associated with this module.
.IP "\fICPAN::Module::inst_file()\fR" 4
.IX Item "CPAN::Module::inst_file()"
Returns the filename of the module found in \f(CW@INC\fR. The first file found
is reported, just as perl itself stops searching \f(CW@INC\fR once it finds a
module.
.IP "\fICPAN::Module::available_file()\fR" 4
.IX Item "CPAN::Module::available_file()"
Returns the filename of the module found in \s-1PERL5LIB\s0 or \f(CW@INC\fR. The
first file found is reported. The advantage of this method over
\&\f(CW\*(C`inst_file\*(C'\fR is that modules that have been tested but not yet
installed are included because \s-1PERL5LIB\s0 keeps track of tested modules.
.IP "\fICPAN::Module::inst_version()\fR" 4
.IX Item "CPAN::Module::inst_version()"
Returns the version number of the installed module in readable format.
.IP "\fICPAN::Module::available_version()\fR" 4
.IX Item "CPAN::Module::available_version()"
Returns the version number of the available module in readable format.
.IP "\fICPAN::Module::install()\fR" 4
.IX Item "CPAN::Module::install()"
Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module.
.IP "\fICPAN::Module::look()\fR" 4
.IX Item "CPAN::Module::look()"
Changes to the directory where the distribution associated with this
module has been unpacked and opens a subshell there. Exiting the
subshell returns.
.IP "\fICPAN::Module::make()\fR" 4
.IX Item "CPAN::Module::make()"
Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module.
.IP "\fICPAN::Module::manpage_headline()\fR" 4
.IX Item "CPAN::Module::manpage_headline()"
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 hasn't been installed yet.
.IP "\fICPAN::Module::perldoc()\fR" 4
.IX Item "CPAN::Module::perldoc()"
Runs a \f(CW\*(C`perldoc\*(C'\fR on this module.
.IP "\fICPAN::Module::readme()\fR" 4
.IX Item "CPAN::Module::readme()"
Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module.
.IP "\fICPAN::Module::reports()\fR" 4
.IX Item "CPAN::Module::reports()"
Calls the \fIreports()\fR method on the associated distribution object.
.IP "\fICPAN::Module::test()\fR" 4
.IX Item "CPAN::Module::test()"
Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module.
.IP "\fICPAN::Module::uptodate()\fR" 4
.IX Item "CPAN::Module::uptodate()"
Returns 1 if the module is installed and up-to-date.
.IP "\fICPAN::Module::userid()\fR" 4
.IX Item "CPAN::Module::userid()"
Returns the author's \s-1ID\s0 of the module.
.SS "Cache Manager"
.IX Subsection "Cache Manager"
Currently the cache manager only keeps track of the build directory
($CPAN::Config\->{build_dir}). It is a simple \s-1FIFO\s0 mechanism that
deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of
all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache}
(in \s-1MB\s0). The contents of this cache may be used for later
re-installations that you intend to do manually, but will never be
trusted by \s-1CPAN\s0 itself. This is due to the fact that the user might
use these directories for building modules on different architectures.
.PP
There is another directory ($CPAN::Config\->{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.
.SS "Bundles"
.IX Subsection "Bundles"
A bundle is just a perl module in the namespace Bundle:: that does not
define any functions or methods. It usually only contains documentation.
.PP
It starts like a perl module with a package declaration and a \f(CW$VERSION\fR
variable. After that the pod section looks like any other pod with the
only difference being that \fIone special pod section\fR exists starting with
(verbatim):
.PP
.Vb 1
\& =head1 CONTENTS
.Ve
.PP
In this pod section each line obeys the format
.PP
.Vb 1
\& Module_Name [Version_String] [\- optional text]
.Ve
.PP
The only required part is the first field, the name of a module
(e.g. Foo::Bar, i.e. \fInot\fR 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.
.PP
The distribution of a bundle should follow the same convention as
other distributions.
.PP
Bundles are treated specially in the \s-1CPAN\s0 package. If you say 'install
Bundle::Tkkit' (assuming such a bundle exists), \s-1CPAN\s0 will install all
the modules in the \s-1CONTENTS\s0 section of the pod. You can install your
own Bundles locally by placing a conformant Bundle file somewhere into
your \f(CW@INC\fR path. The \fIautobundle()\fR command which is available in the
shell interface does that for you by including all currently installed
modules in a snapshot bundle file.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
The \s-1CPAN\s0 program is trying to depend on as little as possible so the
user can use it in hostile environment. It works better the more goodies
the environment provides. For example if you try in the \s-1CPAN\s0 shell
.PP
.Vb 1
\& install Bundle::CPAN
.Ve
.PP
or
.PP
.Vb 1
\& install Bundle::CPANxxl
.Ve
.PP
you will find the shell more convenient than the bare shell before.
.PP
If you have a local mirror of \s-1CPAN\s0 and can access all files with
\&\*(L"file:\*(R" URLs, then you only need a perl later than perl5.003 to run
this module. Otherwise Net::FTP is strongly recommended. \s-1LWP\s0 may be
required for non-UNIX systems, or if your nearest \s-1CPAN\s0 site is
associated with a \s-1URL\s0 that is not \f(CW\*(C`ftp:\*(C'\fR.
.PP
If you have neither Net::FTP nor \s-1LWP\s0, there is a fallback mechanism
implemented for an external ftp command or for an external lynx
command.
.SH "UTILITIES"
.IX Header "UTILITIES"
.SS "Finding packages and \s-1VERSION\s0"
.IX Subsection "Finding packages and VERSION"
This module presumes that all packages on \s-1CPAN\s0
.IP "\(bu" 2
declare their \f(CW$VERSION\fR 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 \f(CW$VERSION\fR variable. Currently all programs that are dealing with
version use something like this
.Sp
.Vb 2
\& perl \-MExtUtils::MakeMaker \-le \e
\& \*(Aqprint MM\->parse_version(shift)\*(Aq filename
.Ve
.Sp
If you are author of a package and wonder if your \f(CW$VERSION\fR can be
parsed, please try the above method.
.IP "\(bu" 2
come as compressed or gzipped tarfiles or as zip files and contain a
\&\f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR (well, we try to handle a bit more, but
with little enthusiasm).
.SS "Debugging"
.IX Subsection "Debugging"
Debugging this module is more than a bit complex due to interference from
the software producing the indices on \s-1CPAN\s0, the mirroring process on \s-1CPAN\s0,
packaging, configuration, synchronicity, and even (gasp!) due to bugs
within the \s-1CPAN\s0.pm module itself.
.PP
For debugging the code of \s-1CPAN\s0.pm itself in interactive mode, some
debugging aid can be turned on for most packages within
\&\s-1CPAN\s0.pm with one of
.IP "o debug package..." 2
.IX Item "o debug package..."
sets debug mode for packages.
.IP "o debug \-package..." 2
.IX Item "o debug -package..."
unsets debug mode for packages.
.IP "o debug all" 2
.IX Item "o debug all"
turns debugging on for all packages.
.IP "o debug number" 2
.IX Item "o debug number"
.PP
which sets the debugging packages directly. Note that \f(CW\*(C`o debug 0\*(C'\fR
turns debugging off.
.PP
What seems a successful strategy is the combination of \f(CW\*(C`reload
cpan\*(C'\fR and the debugging switches. Add a new debug statement while
running in the shell and then issue a \f(CW\*(C`reload cpan\*(C'\fR and see the new
debugging messages immediately without losing the current context.
.PP
\&\f(CW\*(C`o debug\*(C'\fR without an argument lists the valid package names and the
current set of packages in debugging mode. \f(CW\*(C`o debug\*(C'\fR has built-in
completion support.
.PP
For debugging of \s-1CPAN\s0 data there is the \f(CW\*(C`dump\*(C'\fR command which takes
the same arguments as make/test/install and outputs each object's
Data::Dumper dump. If an argument looks like a perl variable and
contains one of \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, it is \fIeval()\fRed and fed to
Data::Dumper directly.
.SS "Floppy, Zip, Offline Mode"
.IX Subsection "Floppy, Zip, Offline Mode"
\&\s-1CPAN\s0.pm works nicely without network access, too. If you maintain machines
that are not networked at all, you should consider working with \f(CW\*(C`file:\*(C'\fR
URLs. You'll have to collect your modules somewhere first. So
you might use \s-1CPAN\s0.pm to put together all you need on a networked
machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not
\&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind
of a personal \s-1CPAN\s0. \s-1CPAN\s0.pm on the non-networked machines works nicely
with this floppy. See also below the paragraph about CD-ROM support.
.SS "Basic Utilities for Programmers"
.IX Subsection "Basic Utilities for Programmers"
.IP "has_inst($module)" 2
.IX Item "has_inst($module)"
Returns true if the module is installed. Used to load all modules into
the running \s-1CPAN\s0.pm that are considered optional. The config variable
\&\f(CW\*(C`dontload_list\*(C'\fR intercepts the \f(CW\*(C`has_inst()\*(C'\fR call such
that an optional module is not loaded despite being available. For
example, the following command will prevent \f(CW\*(C`YAML.pm\*(C'\fR from being
loaded:
.Sp
.Vb 1
\& cpan> o conf dontload_list push YAML
.Ve
.Sp
See the source for details.
.IP "use_inst($module)" 2
.IX Item "use_inst($module)"
Similary to \fIhas_inst()\fR tries to load optional library but also dies if
library is not available
.IP "has_usable($module)" 2
.IX Item "has_usable($module)"
Returns true if the module is installed and in a usable state. Only
useful for a handful of modules that are used internally. See the
source for details.
.IP "instance($module)" 2
.IX Item "instance($module)"
The constructor for all the singletons used to represent modules,
distributions, authors, and bundles. If the object already exists, this
method returns the object; otherwise, it calls the constructor.
.IP "\fIfrontend()\fR" 2
.IX Item "frontend()"
.PD 0
.IP "frontend($new_frontend)" 2
.IX Item "frontend($new_frontend)"
.PD
Getter/setter for frontend object. Method just allows to subclass \s-1CPAN\s0.pm.
.SH "SECURITY"
.IX Header "SECURITY"
There's no strong security layer in \s-1CPAN\s0.pm. \s-1CPAN\s0.pm helps you to
install foreign, unmasked, unsigned code on your machine. We compare
to a checksum that comes from the net just as the distribution file
itself. But we try to make it easy to add security on demand:
.SS "Cryptographically signed modules"
.IX Subsection "Cryptographically signed modules"
Since release 1.77, \s-1CPAN\s0.pm has been able to verify cryptographically
signed module distributions using Module::Signature. The \s-1CPAN\s0 modules
can be signed by their authors, thus giving more security. The simple
unsigned \s-1MD5\s0 checksums that were used before by \s-1CPAN\s0 protect mainly
against accidental file corruption.
.PP
You will need to have Module::Signature installed, which in turn
requires that you have at least one of Crypt::OpenPGP module or the
command-line \fIgpg\fR tool installed.
.PP
You will also need to be able to connect over the Internet to the public
key servers, like pgp.mit.edu, and their port 11731 (the \s-1HKP\s0 protocol).
.PP
The configuration parameter check_sigs is there to turn signature
checking on or off.
.SH "EXPORT"
.IX Header "EXPORT"
Most functions in package \s-1CPAN\s0 are exported by default. The reason
for this is that the primary use is intended for the cpan shell or for
one-liners.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
When the \s-1CPAN\s0 shell enters a subshell via the look command, it sets
the environment \s-1CPAN_SHELL_LEVEL\s0 to 1, or increments that variable if it is
already set.
.PP
When \s-1CPAN\s0 runs, it sets the environment variable \s-1PERL5_CPAN_IS_RUNNING\s0
to the \s-1ID\s0 of the running process. It also sets
\&\s-1PERL5_CPANPLUS_IS_RUNNING\s0 to prevent runaway processes which could
happen with older versions of Module::Install.
.PP
When running \f(CW\*(C`perl Makefile.PL\*(C'\fR, the environment variable
\&\f(CW\*(C`PERL5_CPAN_IS_EXECUTING\*(C'\fR is set to the full path of the
\&\f(CW\*(C`Makefile.PL\*(C'\fR that is being executed. This prevents runaway processes
with newer versions of Module::Install.
.PP
When the config variable ftp_passive is set, all downloads will be run
with the environment variable \s-1FTP_PASSIVE\s0 set to this value. This is
in general a good idea as it influences both Net::FTP and \s-1LWP\s0 based
connections. The same effect can be achieved by starting the cpan
shell with this environment variable set. For Net::FTP alone, one can
also always set passive mode by running libnetcfg.
.SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
.IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
Populating a freshly installed perl with one's favorite modules is pretty
easy if you maintain a private bundle definition file. To get a useful
blueprint of a bundle definition file, the command autobundle can be used
on the \s-1CPAN\s0 shell command line. This command writes a bundle definition
file for all modules installed for the current perl
interpreter. It's recommended to run this command once only, and from then
on maintain the file manually under a private name, say
Bundle/my_bundle.pm. With a clever bundle file you can then simply say
.PP
.Vb 1
\& cpan> install Bundle::my_bundle
.Ve
.PP
then answer a few questions and go out for coffee (possibly
even in a different city).
.PP
Maintaining a bundle definition file means keeping track of two
things: dependencies and interactivity. \s-1CPAN\s0.pm sometimes fails on
calculating dependencies because not all modules define all MakeMaker
attributes correctly, so a bundle definition file should specify
prerequisites as early as possible. On the other hand, it's
annoying that so many distributions need some interactive configuring. So
what you can try to accomplish in your private bundle file is to have the
packages that need to be configured early in the file and the gentle
ones later, so you can go out for coffee after a few minutes and leave \s-1CPAN\s0.pm
to churn away unattended.
.SH "WORKING WITH CPAN.pm BEHIND FIREWALLS"
.IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS"
Thanks to Graham Barr for contributing the following paragraphs about
the interaction between perl, and various firewall configurations. For
further information on firewalls, it is recommended to consult the
documentation that comes with the \fIncftp\fR program. If you are unable to
go through the firewall with a simple Perl setup, it is likely
that you can configure \fIncftp\fR so that it works through your firewall.
.SS "Three basic types of firewalls"
.IX Subsection "Three basic types of firewalls"
Firewalls can be categorized into three basic types.
.IP "http firewall" 4
.IX Item "http firewall"
This is when the firewall machine runs a web server, and to access the
outside world, you must do so via that web server. If you set environment
variables like http_proxy or ftp_proxy to values beginning with http://,
or in your web browser you've proxy information set, then you know
you are running behind an http firewall.
.Sp
To access servers outside these types of firewalls with perl (even for
ftp), you need \s-1LWP\s0 or HTTP::Tiny.
.IP "ftp firewall" 4
.IX Item "ftp firewall"
This where the firewall machine runs an ftp server. This kind of
firewall will only let you access ftp servers outside the firewall.
This is usually done by connecting to the firewall with ftp, then
entering a username like \*(L"user@outside.host.com\*(R".
.Sp
To access servers outside these type of firewalls with perl, you
need Net::FTP.
.IP "One-way visibility" 4
.IX Item "One-way visibility"
One-way visibility means these firewalls try to make themselves
invisible to users inside the firewall. An \s-1FTP\s0 data connection is
normally created by sending your \s-1IP\s0 address to the remote server and then
listening for the return connection. But the remote server will not be able to
connect to you because of the firewall. For these types of firewall,
\&\s-1FTP\s0 connections need to be done in a passive mode.
.Sp
There are two that I can think off.
.RS 4
.IP "\s-1SOCKS\s0" 4
.IX Item "SOCKS"
If you are using a \s-1SOCKS\s0 firewall, you will need to compile perl and link
it with the \s-1SOCKS\s0 library. This is what is normally called a 'socksified'
perl. With this executable you will be able to connect to servers outside
the firewall as if it were not there.
.IP "\s-1IP\s0 Masquerade" 4
.IX Item "IP Masquerade"
This is when the firewall implemented in the kernel (via \s-1NAT\s0, or networking
address translation), it allows you to hide a complete network behind one
\&\s-1IP\s0 address. With this firewall no special compiling is needed as you can
access hosts directly.
.Sp
For accessing ftp servers behind such firewalls you usually need to
set the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR or the config variable
ftp_passive to a true value.
.RE
.RS 4
.RE
.SS "Configuring lynx or ncftp for going through a firewall"
.IX Subsection "Configuring lynx or ncftp for going through a firewall"
If you can go through your firewall with e.g. lynx, presumably with a
command such as
.PP
.Vb 1
\& /usr/local/bin/lynx \-pscott:tiger
.Ve
.PP
then you would configure \s-1CPAN\s0.pm with the command
.PP
.Vb 1
\& o conf lynx "/usr/local/bin/lynx \-pscott:tiger"
.Ve
.PP
That's all. Similarly for ncftp or ftp, you would configure something
like
.PP
.Vb 1
\& o conf ncftp "/usr/bin/ncftp \-f /home/scott/ncftplogin.cfg"
.Ve
.PP
Your mileage may vary...
.SH "FAQ"
.IX Header "FAQ"
.IP "1)" 4
.IX Item "1)"
I installed a new version of module X but \s-1CPAN\s0 keeps saying,
I have the old version installed
.Sp
Probably you \fBdo\fR have the old version installed. This can
happen if a module installs itself into a different directory in the
\&\f(CW@INC\fR path than it was previously installed. This is not really a
\&\s-1CPAN\s0.pm problem, you would have the same problem when installing the
module manually. The easiest way to prevent this behaviour is to add
the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why
many people add this argument permanently by configuring
.Sp
.Vb 1
\& o conf make_install_arg UNINST=1
.Ve
.IP "2)" 4
.IX Item "2)"
So why is UNINST=1 not the default?
.Sp
Because there are people who have their precise expectations about who
may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In
fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage.
.IP "3)" 4
.IX Item "3)"
I want to clean up my mess, and install a new perl along with
all modules I have. How do I go about it?
.Sp
Run the autobundle command for your old perl and optionally rename the
resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
with the Configure option prefix, e.g.
.Sp
.Vb 1
\& ./Configure \-Dprefix=/usr/local/perl\-5.6.78.9
.Ve
.Sp
Install the bundle file you produced in the first step with something like
.Sp
.Vb 1
\& cpan> install Bundle::mybundle
.Ve
.Sp
and you're done.
.IP "4)" 4
.IX Item "4)"
When I install bundles or multiple modules with one command
there is too much output to keep track of.
.Sp
You may want to configure something like
.Sp
.Vb 2
\& o conf make_arg "| tee \-ai /root/.cpan/logs/make.out"
\& o conf make_install_arg "| tee \-ai /root/.cpan/logs/make_install.out"
.Ve
.Sp
so that \s-1STDOUT\s0 is captured in a file for later inspection.
.IP "5)" 4
.IX Item "5)"
I am not root, how can I install a module in a personal directory?
.Sp
As of \s-1CPAN\s0 1.9463, if you do not have permission to write the default perl
library directories, \s-1CPAN\s0's configuration process will ask you whether
you want to bootstrap