CPAN
view release on metacpan or search on metacpan
saving the config: o conf commit
Saves all config variables to the current config file
(CPAN/Config.pm or CPAN/MyConfig.pm that was loaded at start).
The configuration dialog can be started any time later again by issuing
the command " o conf init " in the CPAN shell. A subset of the
configuration dialog can be run by issuing "o conf init WORD" where WORD
is any valid config variable or a regular expression.
Config Variables
The following keys in the hash reference $CPAN::Config are currently
defined:
allow_installing_module_downgrades
allow or disallow installing module downgrades
allow_installing_outdated_dists
allow or disallow installing modules that are
indexed in the cpan index pointing to a distro
with a higher distro-version number
applypatch path to external prg
auto_commit commit all changes to config variables to disk
build_cache size of cache for directories to build modules
build_dir locally accessible directory to build modules
build_dir_reuse boolean if distros in build_dir are persistent
build_requires_install_policy
to install or not to install when a module is
only needed for building. yes|no|ask/yes|ask/no
bzip2 path to external prg
cache_metadata use serializer to cache metadata
check_sigs if signatures should be verified
cleanup_after_install
remove build directory immediately after a
successful install and remember that for the
duration of the session
colorize_debug Term::ANSIColor attributes for debugging output
colorize_output boolean if Term::ANSIColor should colorize output
colorize_print Term::ANSIColor attributes for normal output
colorize_warn Term::ANSIColor attributes for warnings
commandnumber_in_prompt
boolean if you want to see current command number
commands_quote preferred character to use for quoting external
commands when running them. Defaults to double
quote on Windows, single tick everywhere else;
can be set to space to disable quoting
connect_to_internet_ok
whether to ask if opening a connection is ok before
urllist is specified
cpan_home local directory reserved for this package
curl path to external prg
dontload_hash DEPRECATED
dontload_list arrayref: modules in the list will not be
loaded by the CPAN::has_inst() routine
ftp path to external prg
ftp_passive if set, the environment variable FTP_PASSIVE is set
for downloads
ftp_proxy proxy host for ftp requests
ftpstats_period max number of days to keep download statistics
ftpstats_size max number of items to keep in the download statistics
getcwd see below
gpg path to external prg
gzip location of external program gzip
halt_on_failure stop processing after the first failure of queued
items or dependencies
histfile file to maintain history between sessions
histsize maximum number of lines to keep in histfile
http_proxy proxy host for http requests
inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
after this many seconds inactivity. Set to 0 to
disable timeouts.
index_expire refetch index files after this many days
inhibit_startup_message
if true, suppress the startup message
keep_source_where directory in which to keep the source (if we do)
load_module_verbosity
report loading of optional modules used by CPAN.pm
lynx path to external prg
make location of external make program
make_arg arguments that should always be passed to 'make'
make_install_make_command
the make command for running 'make install', for
example 'sudo make'
make_install_arg same as make_arg for 'make install'
makepl_arg arguments passed to 'perl Makefile.PL'
mbuild_arg arguments passed to './Build'
mbuild_install_arg arguments passed to './Build install'
mbuild_install_build_command
command to use instead of './Build' when we are
in the install stage, for example 'sudo ./Build'
mbuildpl_arg arguments passed to 'perl Build.PL'
ncftp path to external prg
ncftpget path to external prg
no_proxy don't proxy to these hosts/domains (comma separated list)
pager location of external program more (or any pager)
password your password if you CPAN server wants one
patch path to external prg
patches_dir local directory containing patch files
perl5lib_verbosity verbosity level for PERL5LIB additions
plugin_list list of active hooks (see Plugin support above
and the CPAN::Plugin module)
prefer_external_tar
per default all untar operations are done with
Archive::Tar; by setting this variable to true
the external tar command is used if available
prefer_installer legal values are MB and EUMM: if a module comes
with both a Makefile.PL and a Build.PL, use the
former (EUMM) or the latter (MB); if the module
comes with only one of the two, that one will be
used no matter the setting
prerequisites_policy
what to do if you are missing module prerequisites
('follow' automatically, 'ask' me, or 'ignore')
For 'follow', also sets PERL_AUTOINSTALL and
PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if
not already set
prefs_dir local directory to store per-distro build options
proxy_user username for accessing an authenticating proxy
proxy_pass password for accessing an authenticating proxy
pushy_https use https to cpan.org when possible, otherwise use http
to cpan.org and issue a warning
randomize_urllist add some randomness to the sequence of the urllist
Data::Dumper dump. If an argument looks like a perl variable and
contains one of "$", "@" or "%", it is eval()ed and fed to Data::Dumper
directly.
Floppy, Zip, Offline Mode
CPAN.pm works nicely without network access, too. If you maintain
machines that are not networked at all, you should consider working with
"file:" URLs. You'll 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->{keep_source_where} (but not
$CPAN::Config->{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.
Basic Utilities for Programmers
has_inst($module)
Returns true if the module is installed. Used to load all modules into
the running CPAN.pm that are considered optional. The config variable
"dontload_list" intercepts the "has_inst()" call such that an optional
module is not loaded despite being available. For example, the
following command will prevent "YAML.pm" from being loaded:
cpan> o conf dontload_list push YAML
See the source for details.
use_inst($module)
Similary to has_inst() tries to load optional library but also dies if
library is not available
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.
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.
frontend()
frontend($new_frontend)
Getter/setter for frontend object. Method just allows to subclass
CPAN.pm.
SECURITY
There's no strong security layer in CPAN.pm. CPAN.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:
Cryptographically signed modules
Since release 1.77, CPAN.pm has been able to verify cryptographically
signed module distributions using Module::Signature. The CPAN modules
can be signed by their authors, thus giving more security. The simple
unsigned MD5 checksums that were used before by CPAN protect mainly
against accidental file corruption.
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 gpg tool installed.
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 HKP protocol).
The configuration parameter check_sigs is there to turn signature
checking on or off.
EXPORT
Most functions in package CPAN are exported by default. The reason for
this is that the primary use is intended for the cpan shell or for
one-liners.
ENVIRONMENT
When the CPAN shell enters a subshell via the look command, it sets the
environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
already set.
When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
to the ID of the running process. It also sets PERL5_CPANPLUS_IS_RUNNING
to prevent runaway processes which could happen with older versions of
Module::Install.
When running "perl Makefile.PL", the environment variable
"PERL5_CPAN_IS_EXECUTING" is set to the full path of the "Makefile.PL"
that is being executed. This prevents runaway processes with newer
versions of Module::Install.
When the config variable ftp_passive is set, all downloads will be run
with the environment variable FTP_PASSIVE set to this value. This is in
general a good idea as it influences both Net::FTP and LWP 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.
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 CPAN 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
cpan> install Bundle::my_bundle
then answer a few questions and go out for coffee (possibly even in a
different city).
Maintaining a bundle definition file means keeping track of two things:
dependencies and interactivity. CPAN.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 CPAN.pm to churn away
unattended.
( run in 1.056 second using v1.01-cache-2.11-cpan-df04353d9ac )