CPAN
view release on metacpan or search on metacpan
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
recommends_policy whether recommended prerequisites should be included
scan_cache controls scanning of cache ('atstart', 'atexit' or 'never')
shell your favorite shell
show_unparsable_versions
boolean if r command tells which modules are versionless
show_upload_date boolean if commands should try to determine upload date
show_zero_versions boolean if r command tells for which modules $version==0
suggests_policy whether suggested prerequisites should be included
tar location of external program tar
tar_verbosity verbosity level for the tar command
term_is_latin deprecated: if true Unicode is translated to ISO-8859-1
(and nonsense for characters outside latin range)
term_ornaments boolean to turn ReadLine ornamenting on/off
test_report email test reports (if CPAN::Reporter is installed)
trust_test_report_history
skip testing when previously tested ok (according to
CPAN::Reporter history)
unzip location of external program unzip
urllist arrayref to nearby CPAN sites (or equivalent locations)
urllist_ping_external
use external ping command when autoselecting mirrors
urllist_ping_verbose
increase verbosity when autoselecting mirrors
use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
username your username if you CPAN server wants one
version_timeout stops version parsing after this many seconds.
Default is 15 secs. Set to 0 to disable.
wait_list arrayref to a wait server to try (See CPAN::WAIT)
wget path to external prg
yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
yaml_module which module to use to read/write YAML files
You can set and query each of these options interactively in the cpan
shell with the "o conf" or the "o conf init" command as specified below.
"o conf <scalar option>"
prints the current value of the *scalar option*
"o conf <scalar option> <value>"
Sets the value of the *scalar option* to *value*
"o conf <list option>"
prints the current value of the *list option* in MakeMaker's neatvalue
format.
"o conf <list option> [shift|pop]"
shifts or pops the array in the *list option* variable
"o conf <list option> [unshift|push|splice] <list>"
works like the corresponding perl commands.
interactive editing: o conf init [MATCH|LIST]
Runs an interactive configuration dialog for matching variables.
Without argument runs the dialog over all supported config variables.
the recommendation for the owner of a CD-ROM with CPAN contents is:
include your local, possibly outdated CD-ROM as a "file" URL at the end
of urllist, e.g.
o conf urllist push file://localhost/CDROM/CPAN
CPAN.pm will then fetch the index files from one of the CPAN sites that
come at the beginning of urllist. It will later check for each module to
see whether there is a local copy of the most recent version.
Another peculiarity of urllist is that the site that we could
successfully fetch the last file from automatically gets a preference
token and is tried as the first site for the next request. So if you add
a new site at runtime it may happen that the previously preferred site
will be tried another time. This means that if you want to disallow a
site for the next transfer, it must be explicitly removed from urllist.
Maintaining the urllist parameter
If you have YAML.pm (or some other YAML module configured in
"yaml_module") installed, CPAN.pm collects a few statistical data about
recent downloads. You can view the statistics with the "hosts" command
or inspect them directly by looking into the "FTPstats.yml" file in your
"cpan_home" directory.
To get some interesting statistics, it is recommended that
"randomize_urllist" be set; this introduces some amount of randomness
into the URL selection.
The "requires" and "build_requires" dependency declarations
Since CPAN.pm version 1.88_51 modules declared as "build_requires" by a
distribution are treated differently depending on the config variable
"build_requires_install_policy". By setting
"build_requires_install_policy" to "no", such a module is not installed.
It is only built and tested, and then kept in the list of tested but
uninstalled modules. As such, it is available during the build of the
dependent module by integrating the path to the "blib/arch" and
"blib/lib" directories in the environment variable PERL5LIB. If
"build_requires_install_policy" is set to "yes", then both modules
declared as "requires" and those declared as "build_requires" are
treated alike. By setting to "ask/yes" or "ask/no", CPAN.pm asks the
user and sets the default accordingly.
Configuration of the allow_installing_* parameters
The "allow_installing_*" parameters are evaluated during the "make"
phase. If set to "yes", they allow the testing and the installation of
the current distro and otherwise have no effect. If set to "no", they
may abort the build (preventing testing and installing), depending on
the contents of the "blib/" directory. The "blib/" directory is the
directory that holds all the files that would usually be installed in
the "install" phase.
"allow_installing_outdated_dists" compares the "blib/" directory with
the CPAN index. If it finds something there that belongs, according to
the index, to a different dist, it aborts the current build.
"allow_installing_module_downgrades" compares the "blib/" directory with
already installed modules, actually their version numbers, as determined
by ExtUtils::MakeMaker or equivalent. If a to-be-installed module would
downgrade an already installed module, the current build is aborted.
An interesting twist occurs when a distroprefs document demands the
installation of an outdated dist via goto while
"allow_installing_outdated_dists" forbids it. Without additional
provisions, this would let the "allow_installing_outdated_dists" win and
the distroprefs lose. So the proper arrangement in such a case is to
write a second distroprefs document for the distro that "goto" points to
and overrule the "cpanconfig" there. E.g.:
---
match:
distribution: "^MAUKE/Keyword-Simple-0.04.tar.gz"
goto: "MAUKE/Keyword-Simple-0.03.tar.gz"
---
match:
distribution: "^MAUKE/Keyword-Simple-0.03.tar.gz"
cpanconfig:
allow_installing_outdated_dists: yes
Configuration for individual distributions (*Distroprefs*)
(Note: This feature has been introduced in CPAN.pm 1.8854)
Distributions on CPAN usually behave according to what we call the CPAN
mantra. Or since the advent of Module::Build we should talk about two
mantras:
perl Makefile.PL perl Build.PL
make ./Build
make test ./Build test
make install ./Build install
But some modules cannot be built with this mantra. They try to get some
extra data from the user via the environment, extra arguments, or
interactively--thus disturbing the installation of large bundles like
Phalanx100 or modules with many dependencies like Plagger.
The distroprefs system of "CPAN.pm" addresses this problem by allowing
the user to specify extra informations and recipes in YAML files to
either
* pass additional arguments to one of the four commands,
* set environment variables
* instantiate an Expect object that reads from the console, waits for
some regular expressions and enters some answers
* temporarily override assorted "CPAN.pm" configuration variables
* specify dependencies the original maintainer forgot
* disable the installation of an object altogether
See the YAML and Data::Dumper files that come with the "CPAN.pm"
distribution in the "distroprefs/" directory for examples.
Filenames
The YAML files themselves must have the ".yml" extension; all other
files are ignored (for two exceptions see *Fallback Data::Dumper and
Storable* below). The containing directory can be specified in "CPAN.pm"
in the "prefs_dir" config variable. Try "o conf init prefs_dir" in the
CPAN shell to set and activate the distroprefs system.
Every YAML file may contain arbitrary documents according to the YAML
specification, and every document is treated as an entity that can
specify the treatment of a single distribution.
Filenames can be picked arbitrarily; "CPAN.pm" always reads all files
(in alphabetical order) and takes the key "match" (see below in
*Language Specs*) as a hashref containing match criteria that determine
if the current distribution matches the YAML document or not.
Fallback Data::Dumper and Storable
If neither your configured "yaml_module" nor YAML.pm is installed,
CPAN.pm falls back to using Data::Dumper and Storable and looks for
files with the extensions ".dd" or ".st" in the "prefs_dir" directory.
These files are expected to contain one or more hashrefs. For
Data::Dumper generated files, this is expected to be done with by
defining $VAR1, $VAR2, etc. The YAML shell would produce these with the
command
ysh < somefile.yml > somefile.dd
For Storable files the rule is that they must be constructed such that
"Storable::retrieve(file)" returns an array reference and the array
elements represent one distropref object each. The conversion from YAML
would look like so:
perl -MYAML=LoadFile -MStorable=nstore -e '
@y=LoadFile(shift);
nstore(\@y, shift)' somefile.yml somefile.st
In bootstrapping situations it is usually sufficient to translate only a
few YAML files to Data::Dumper for crucial modules like "YAML::Syck",
"YAML.pm" and "Expect.pm". If you prefer Storable over Data::Dumper,
remember to pull out a Storable version that writes an older format than
all the other Storable versions that will need to read them.
Blueprint
The following example contains all supported keywords and structures
with the exception of "eexpect" which can be used instead of "expect".
---
comment: "Demo"
match:
module: "Dancing::Queen"
distribution: "^CHACHACHA/Dancing-"
not_distribution: "\.zip$"
perl: "/usr/local/cariba-perl/bin/perl"
perlconfig:
archname: "freebsd"
not_cc: "gcc"
env:
DANCING_FLOOR: "Shubiduh"
disabled: 1
cpanconfig:
make: gmake
pl:
args:
- "--somearg=specialcase"
env: {}
expect:
- "Which is your favorite fruit"
- "apple\n"
make:
args:
- all
- extra-all
env: {}
expect: []
disabled [boolean]
Specifies that this distribution shall not be processed at all.
features [array] *** EXPERIMENTAL FEATURE ***
Experimental implementation to deal with optional_features from
META.yml. Still needs coordination with installer software and
currently works only for META.yml declaring "dynamic_config=0". Use
with caution.
goto [string]
The canonical name of a delegate distribution to install instead.
Useful when a new version, although it tests OK itself, breaks
something else or a developer release or a fork is already uploaded
that is better than the last released version.
install [hash]
Processing instructions for the "make install" or "./Build install"
phase of the CPAN mantra. See below under *Processing Instructions*.
make [hash]
Processing instructions for the "make" or "./Build" phase of the
CPAN mantra. See below under *Processing Instructions*.
match [hash]
A hashref with one or more of the keys "distribution", "module",
"perl", "perlconfig", and "env" that specify whether a document is
targeted at a specific CPAN distribution or installation. Keys
prefixed with "not_" negates the corresponding match.
The corresponding values are interpreted as regular expressions. The
"distribution" related one will be matched against the canonical
distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
The "module" related one will be matched against *all* modules
contained in the distribution until one module matches.
The "perl" related one will be matched against $^X (but with the
absolute path).
The value associated with "perlconfig" is itself a hashref that is
matched against corresponding values in the %Config::Config hash
living in the "Config.pm" module. Keys prefixed with "not_" negates
the corresponding match.
The value associated with "env" is itself a hashref that is matched
against corresponding values in the %ENV hash. Keys prefixed with
"not_" negates the corresponding match.
If more than one restriction of "module", "distribution", etc. is
specified, the results of the separately computed match values must
all match. If so, the hashref represented by the YAML document is
returned as the preference structure for the current distribution.
patches [array]
An array of patches on CPAN or on the local disk to be applied in
order via an external patch program. If the value for the "-p"
parameter is 0 or 1 is determined by reading the patch beforehand.
The path to each patch is either an absolute path on the local
filesystem or relative to a patch directory specified in the
"patches_dir" configuration variable or in the format of a canonical
distro name. For examples please consult the distroprefs/ directory
in the CPAN.pm distribution (these examples are not installed by
default).
Note: if the "applypatch" program is installed and "CPAN::Config"
knows about it and a patch is written by the "makepatch" program,
then "CPAN.pm" lets "applypatch" apply the patch. Both "makepatch"
and "applypatch" are available from CPAN in the "JV/makepatch-*"
distribution.
pl [hash]
Processing instructions for the "perl Makefile.PL" or "perl
Build.PL" phase of the CPAN mantra. See below under *Processing
Instructions*.
test [hash]
Processing instructions for the "make test" or "./Build test" phase
of the CPAN mantra. See below under *Processing Instructions*.
Processing Instructions
args [array]
Arguments to be added to the command line
commandline
A full commandline to run via "system()". During execution, the
environment variable PERL is set to $^X (but with an absolute path).
If "commandline" is specified, "args" is not used.
eexpect [hash]
Extended "expect". This is a hash reference with four allowed keys,
"mode", "timeout", "reuse", and "talk".
You must install the "Expect" module to use "eexpect". CPAN.pm does
not install it for you.
"mode" may have the values "deterministic" for the case where all
questions come in the order written down and "anyorder" for the case
where the questions may come in any order. The default mode is
"deterministic".
"timeout" denotes a timeout in seconds. Floating-point timeouts are
OK. With "mode=deterministic", the timeout denotes the timeout per
question; with "mode=anyorder" it denotes the timeout per byte
received from the stream or questions.
"talk" is a reference to an array that contains alternating
questions and answers. Questions are regular expressions and answers
are literal strings. The Expect module watches the stream from the
execution of the external program ("perl Makefile.PL", "perl
Build.PL", "make", etc.).
For "mode=deterministic", the CPAN.pm injects the corresponding
answer as soon as the stream matches the regular expression.
For "mode=anyorder" CPAN.pm answers a question as soon as the
timeout is reached for the next byte in the input stream. In this
mode you can use the "reuse" parameter to decide what will happen
with a question-answer pair after it has been used. In the default
case (reuse=0) it is removed from the array, avoiding being used
again accidentally. If you want to answer the question "Do you
really want to do that" several times, then it must be included in
the array at least as often as you want this answer to be given.
Setting the parameter "reuse" to 1 makes this repetition
unnecessary.
env [hash]
Environment variables to be set during the command
expect [array]
You must install the "Expect" module to use "expect". CPAN.pm does
not install it for you.
"expect: <array>" is a short notation for this "eexpect":
eexpect:
mode: deterministic
timeout: 15
talk: <array>
Schema verification with "Kwalify"
If you have the "Kwalify" module installed (which is part of the
Bundle::CPANxxl), then all your distroprefs files are checked for
syntactic correctness.
Example Distroprefs Files
"CPAN.pm" comes with a collection of example YAML files. Note that these
are really just examples and should not be used without care because
they cannot fit everybody's purpose. After all, the authors of the
packages that ask questions had a need to ask, so you should watch their
questions and adjust the examples to your environment and your needs.
You have been warned:-)
PROGRAMMER'S INTERFACE
If you do not enter the shell, shell commands are available both as
methods ("CPAN::Shell->install(...)") and as functions in the calling
package ("install(...)"). Before calling low-level commands, it makes
sense to initialize components of CPAN you need, e.g.:
CPAN::HandleConfig->load;
CPAN::Shell::setup_output;
CPAN::Index->reload;
High-level commands do such initializations automatically.
There's currently only one class that has a stable interface -
CPAN::Shell. All commands that are available in the CPAN shell are
methods of the class CPAN::Shell. The arguments on the commandline are
passed as arguments to the method.
So if you take for example the shell command
notest install A B C
the actually executed command is
CPAN::Shell->notest("install","A","B","C");
Each of the commands that produce listings of modules ("r",
"autobundle", "u") also return a list of the IDs of all modules within
the list.
expand($type,@things)
The IDs of all objects available within a program are strings that can
be expanded to the corresponding real objects with the
"CPAN::Shell->expand("Module",@things)" method. Expand returns a list
of CPAN::Module objects according to the @things arguments given. In
scalar context, it returns only the first element of the list.
expandany(@things)
Like expand, but returns objects of the appropriate type, i.e.
CPAN::Bundle objects for bundles, CPAN::Module objects for modules,
and CPAN::Distribution objects for distributions. Note: it does not
expand to CPAN::Author objects.
Programming Examples
This enables the programmer to do operations that combine
functionalities that are available in the shell.
# install everything that is outdated on my disk:
perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
# install my favorite programs if necessary:
for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
CPAN::Shell->install($mod);
}
cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
there.
CPAN::Distribution::dir()
Returns the directory into which this distribution has been
unpacked.
CPAN::Distribution::force($method,@args)
Forces CPAN to perform a task that it normally would have refused to
do. 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. See also the section
above on the "force" and the "fforce" pragma.
CPAN::Distribution::get()
Downloads the distribution from CPAN and unpacks it. Does nothing if
the distribution has already been downloaded and unpacked within the
current session.
CPAN::Distribution::install()
Changes to the directory where the distribution has been unpacked
and runs the external command "make install" there. If "make" has
not yet been run, it will be run first. A "make test" is issued in
any case and if this fails, the install is cancelled. The
cancellation can be avoided by letting "force" run the "install" for
you.
This install method only has the power to install the distribution
if there are no dependencies in the way. To install an object along
with all its dependencies, use CPAN::Shell->install.
Note that install() gives no meaningful return value. See
uptodate().
CPAN::Distribution::isa_perl()
Returns 1 if this distribution file seems to be a perl distribution.
Normally this is derived from the file name only, but the index from
CPAN can contain a hint to achieve a return value of true for other
filenames too.
CPAN::Distribution::look()
Changes to the directory where the distribution has been unpacked
and opens a subshell there. Exiting the subshell returns.
CPAN::Distribution::make()
First runs the "get" method to make sure the distribution is
downloaded and unpacked. Changes to the directory where the
distribution has been unpacked and runs the external commands "perl
Makefile.PL" or "perl Build.PL" and "make" there.
CPAN::Distribution::perldoc()
Downloads the pod documentation of the file associated with a
distribution (in HTML format) and runs it through the external
command *lynx* specified in "$CPAN::Config->{lynx}". If *lynx* isn't
available, it converts it to plain text with the external command
*html2text* and runs it through the pager specified in
"$CPAN::Config->{pager}".
CPAN::Distribution::prefs()
Returns the hash reference from the first matching YAML file that
the user has deposited in the "prefs_dir/" directory. The first
succeeding match wins. The files in the "prefs_dir/" are processed
alphabetically, and the canonical distro name (e.g.
AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular
expressions stored in the $root->{match}{distribution} attribute
value. Additionally all module names contained in a distribution are
matched against the regular expressions in the
$root->{match}{module} attribute value. The two match values are
ANDed together. Each of the two attributes are optional.
CPAN::Distribution::prereq_pm()
Returns the hash reference that has been announced by a distribution
as the "requires" and "build_requires" elements. These can be
declared either by the "META.yml" (if authoritative) or can be
deposited after the run of "Build.PL" in the file "./_build/prereqs"
or after the run of "Makfile.PL" written as the "PREREQ_PM" hash in
a comment in the produced "Makefile". *Note*: this method only works
after an attempt has been made to "make" the distribution. Returns
undef otherwise.
CPAN::Distribution::readme()
Downloads the README file associated with a distribution and runs it
through the pager specified in "$CPAN::Config->{pager}".
CPAN::Distribution::reports()
Downloads report data for this distribution from www.cpantesters.org
and displays a subset of them.
CPAN::Distribution::read_yaml()
Returns the content of the META.yml of this distro as a hashref.
Note: works only after an attempt has been made to "make" the
distribution. Returns undef otherwise. Also returns undef if the
content of META.yml is not authoritative. (The rules about what
exactly makes the content authoritative are still in flux.)
CPAN::Distribution::test()
Changes to the directory where the distribution has been unpacked
and runs "make test" there.
CPAN::Distribution::uptodate()
Returns 1 if all the modules contained in the distribution are
up-to-date. Relies on containsmods.
CPAN::Index::force_reload()
Forces a reload of all indices.
CPAN::Index::reload()
Reloads all indices if they have not been read for more than
"$CPAN::Config->{index_expire}" days.
CPAN::InfoObj::dump()
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.
CPAN::Module::as_glimpse()
Returns a one-line description of the module in four columns: The
first column contains the word "Module", the second column consists
of one character: an equals sign if this module is already installed
and up-to-date, a less-than sign if this module is installed but can
be upgraded, and a space if the module is not installed. The third
( run in 0.604 second using v1.01-cache-2.11-cpan-0bb4e1dffa6 )