|
CPAN - query, download and build perl modules from CPAN sites
Interactive mode:
perl -MCPAN -e shell
--or--
cpan
Basic commands:
cpan> install Acme::Meta # in the shell
CPAN::Shell->install("Acme::Meta");
cpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell
CPAN::Shell->
install("NWCLARK/Acme-Meta-0.02.tar.gz");
$mo = CPAN::Shell->expandany($mod);
$mo = CPAN::Shell->expand("Module",$mod);
$do = CPAN::Shell->expand("Module",$mod)->distribution;
$do = CPAN::Shell->expandany($distro);
$do = CPAN::Shell->expand("Distribution",
$distro);
The CPAN module automates or at least simplifies the make and install
of perl modules and extensions. It includes some primitive searching
capabilities and knows how to use Net::FTP or LWP or some external
download clients to fetch the distributions from the net.
These are fetched from one or more of the mirrored CPAN (Comprehensive
Perl Archive Network) sites and unpacked in a dedicated directory.
The CPAN module also supports the concept of named and versioned
bundles of modules. Bundles simplify the handling of sets of
related modules. See Bundles below.
The package contains a session manager and a cache manager. The
session manager keeps track of what has been fetched, built and
installed in the current session. The cache manager keeps track of the
disk space occupied by the make processes and deletes excess space
according to a simple FIFO mechanism.
All methods provided are accessible in a programmer style and in an
interactive shell style.
The interactive mode is entered by running
perl -MCPAN -e shell
or
cpan
which puts you into a readline interface. If Term::ReadKey and
either Term::ReadLine::Perl or Term::ReadLine::Gnu are installed
it supports both history and command completion.
Once you are on the command line, type h to get a one page help
screen and the rest should be self-explanatory.
The function call shell takes two optional arguments, one is the
prompt, the second is the default initial command line (the latter
only works if a real ReadLine interface module is installed).
The most common uses of the interactive modes are
- Searching for authors, bundles, distribution files and modules
-
There are corresponding one-letter commands a, b, d, and m
for each of the four categories and another, i for any of the
mentioned four. Each of the four entities is implemented as a class
with slightly differing methods for displaying an object.
Arguments you pass to these commands are either strings exactly matching
the identification string of an object or regular expressions that are
then matched case-insensitively against various attributes of the
objects. The parser recognizes a regular expression only if you
enclose it between two slashes.
The principle is that the number of found objects influences how an
item is displayed. If the search finds one item, the result is
displayed with the rather verbose method as_string, but if we find
more than one, we display each object with the terse method
as_glimpse.
get, make, test, install, clean modules or distributions-
These commands take any number of arguments and investigate what is
necessary to perform the action. If the argument is a distribution
file name (recognized by embedded slashes), it is processed. If it is
a module, CPAN determines the distribution file in which this module
is included and processes that, following any dependencies named in
the module's META.yml or Makefile.PL (this behavior is controlled by
the configuration parameter prerequisites_policy.)
get downloads a distribution file and untars or unzips it, make
builds it, test runs the test suite, and install installs it.
Any make or test are run unconditionally. An
install <distribution_file>
also is run unconditionally. But for
install <module>
CPAN checks if an install is actually needed for it and prints
module up to date in the case that the distribution file containing
the module doesn't need to be updated.
CPAN also keeps track of what it has done within the current session
and doesn't try to build a package a second time regardless if it
succeeded or not. It does not repeat a test run if the test
has been run successfully before. Same for install runs.
The force pragma may precede another command (currently: get,
make, test, or install) and executes the command from scratch
and tries to continue in case of some errors. See the section below on
the force and the fforce pragma.
The notest pragma may be used to skip the test part in the build
process.
Example:
cpan> notest install Tk
A clean command results in a
make clean
being executed within the distribution file's working directory.
readme, perldoc, look module or distribution-
readme displays the README file of the associated distribution.
Look gets and untars (if not yet done) the distribution file,
changes to the appropriate directory and opens a subshell process in
that directory. perldoc displays the pod documentation of the
module in html or plain text format.
ls authorls globbing_expression-
The first form lists all distribution files in and below an author's
CPAN directory as they are stored in the CHECKUMS files distributed on
CPAN. The listing goes recursive into all subdirectories.
The second form allows to limit or expand the output with shell
globbing as in the following examples:
ls JV/make*
ls GSAR/*make*
ls */*make*
The last example is very slow and outputs extra progress indicators
that break the alignment of the result.
Note that globbing only lists directories explicitly asked for, for
example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be
regarded as a bug and may be changed in future versions.
failed-
The failed command reports all distributions that failed on one of
make, test or install for some reason in the currently
running shell session.
- Persistence between sessions
-
If the YAML or the YAML::Syck module is installed a record of
the internal state of all modules is written to disk after each step.
The files contain a signature of the currently running perl version
for later perusal.
If the configurations variable build_dir_reuse is set to a true
value, then CPAN.pm reads the collected YAML files. If the stored
signature matches the currently running perl the stored state is
loaded into memory such that effectively persistence between sessions
is established.
- The
force and the fforce pragma
-
To speed things up in complex installation scenarios, CPAN.pm keeps
track of what it has already done and refuses to do some things a
second time. A get, a make, and an install are not repeated.
A test is only repeated if the previous test was unsuccessful. The
diagnostic message when CPAN.pm refuses to do something a second time
is one of Has already been unwrapped|made|tested successfully or
something similar. Another situation where CPAN refuses to act is an
install if the according test was not successful.
In all these cases, the user can override the goatish behaviour by
prepending the command with the word force, for example:
cpan> force get Foo
cpan> force make AUTHOR/Bar-3.14.tar.gz
cpan> force test Baz
cpan> force install Acme::Meta
Each forced command is executed with the according part of its
memory erased.
The fforce pragma is a variant that emulates a force get which
erases the entire memory followed by the action specified, effectively
restarting the whole get/make/test/install procedure from scratch.
- Lockfile
-
Interactive sessions maintain a lockfile, per default ~/.cpan/.lock.
Batch jobs can run without a lockfile and do not disturb each other.
The shell offers to run in degraded mode when another process is
holding the lockfile. This is an experimental feature that is not yet
tested very well. This second shell then does not write the history
file, does not use the metadata file and has a different prompt.
- Signals
-
CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
in the cpan-shell it is intended that you can press ^C anytime and
return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
to clean up and leave the shell loop. You can emulate the effect of a
SIGTERM by sending two consecutive SIGINTs, which usually means by
pressing ^C twice.
CPAN.pm ignores a SIGPIPE. If the user sets inactivity_timeout, a
SIGALRM is used during the run of the perl Makefile.PL or perl
Build.PL subprocess.
The commands that are available in the shell interface are methods in
the package CPAN::Shell. If you enter the shell command, all your
input is split by the Text::ParseWords::shellwords() routine which
acts like most shells do. The first word is being interpreted as the
method to be called and the rest of the words are treated as arguments
to this method. Continuation lines are supported if a line ends with a
literal backslash.
autobundle writes a bundle file into the
$CPAN::Config->{cpan_home}/Bundle directory. The file contains
a list of all modules that are both available from CPAN and currently
installed within @INC. The name of the bundle file is based on the
current date and a counter.
Note: this feature is still in alpha state and may change in future
versions of CPAN.pm
This commands provides a statistical overview over recent download
activities. The data for this is collected in the YAML file
FTPstats.yml in your cpan_home directory. If no YAML module is
configured or YAML not installed, then no stats are provided.
mkmyconfig() writes your own CPAN::MyConfig file into your ~/.cpan/
directory so that you can save your own preferences instead of the
system wide ones.
The recent command downloads a list of recent uploads to CPAN and
displays them slowly. While the command is running $SIG{INT} is
defined to mean that the loop shall be left after having displayed the
current item.
Note: This command requires XML::LibXML installed.
Note: This whole command currently is a bit klunky and will
probably change in future versions of CPAN.pm but the general
approach will likely stay.
Note: See also smoke
recompile() is a very special command in that it takes no argument and
runs the make/test/install cycle with brute force over all installed
dynamically loadable extensions (aka XS modules) with 'force' in
effect. The primary purpose of this command is to finish a network
installation. Imagine, you have a common source tree for two different
architectures. You decide to do a completely independent fresh
installation. You start on one architecture with the help of a Bundle
file produced earlier. CPAN installs the whole Bundle for you, but
when you try to repeat the job on the second architecture, CPAN
responds with a "Foo up to date" message for all modules. So you
invoke CPAN's recompile on the second architecture and you're done.
Another popular use for recompile is to act as a rescue in case your
perl breaks binary compatibility. If one of the modules that CPAN uses
is in turn depending on binary compatibility (so you cannot run CPAN
commands), then you should try the CPAN::Nox module for recovery.
The report command temporarily turns on the test_report config
variable, then runs the force test command with the given
arguments. The force pragma is used to re-run the tests and repeat
every step that might have failed before.
*** WARNING: this command downloads and executes software from CPAN to
your computer of completely unknown status. You should never do
this with your normal account and better have a dedicated well
separated and secured machine to do this. ***
The smoke command takes the list of recent uploads to CPAN as
provided by the recent command and tests them all. While the
command is running $SIG{INT} is defined to mean that the current item
shall be skipped.
Note: This whole command currently is a bit klunky and will
probably change in future versions of CPAN.pm but the general
approach will likely stay.
Note: See also recent
The upgrade command first runs an r command with the given
arguments and then installs the newest versions of all modules that
were listed by that.
Although it may be considered internal, the class hierarchy does matter
for both users and programmer. CPAN.pm deals with above mentioned four
classes, and all those classes share a set of methods. A classical
single polymorphism is in effect. A metaclass object registers all
objects of all kinds and indexes them with a string. The strings
referencing objects have a separated namespace (well, not completely
separated):
Namespace Class
words containing a "/" (slash) Distribution
words starting with Bundle:: Bundle
everything else Module or Author
Modules know their associated Distribution objects. They always refer
to the most recent official release. Developers may mark their releases
as unstable development versions (by inserting an underbar into the
module version number which will also be reflected in the distribution
name when you run 'make dist'), so the really hottest and newest
distribution is not always the default. If a module Foo circulates
on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
way to install version 1.23 by saying
install Foo
This would install the complete distribution file (say
BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
like to install version 1.23_90, you need to know where the
distribution file resides on CPAN relative to the authors/id/
directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
so you would have to say
install BAR/Foo-1.23_90.tar.gz
The first example will be driven by an object of the class
CPAN::Module, the second by an object of class CPAN::Distribution.
Note: this feature is still in alpha state and may change in future
versions of CPAN.pm
Distribution objects are normally distributions from the CPAN, but
there is a slightly degenerate case for Distribution objects, too, of
projects held on the local disk. These distribution objects have the
same name as the local directory and end with a dot. A dot by itself
is also allowed for the current directory at the time CPAN.pm was
used. All actions such as make, test, and install are applied
directly to that directory. This gives the command cpan . an
interesting touch: while the normal mantra of installing a CPAN module
without CPAN.pm is one of
perl Makefile.PL perl Build.PL
( go and get prerequisites )
make ./Build
make test ./Build test
make install ./Build install
the command cpan . does all of this at once. It figures out which
of the two mantras is appropriate, fetches and installs all
prerequisites, cares for them recursively and finally finishes the
installation of the module in the current directory, be it a CPAN
module or not.
The typical usage case is for private modules or working copies of
projects from remote repositories on the local disk.
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 $CPAN::Config
in a file CPAN/Config.pm.
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 use() or
require() statements. The mkmyconfig command writes this file for you.
The o conf command has various bells and whistles:
- completion support
-
If you have a ReadLine module installed, you can hit TAB at any point
of the commandline and o conf will offer you completion for the
built-in subcommands and/or config variable names.
- displaying some help: o conf help
-
Displays a short help
- displaying current values: o conf [KEY]
-
Displays the current value(s) for this config variable. Without KEY
displays all subcommands and config variables.
Example:
o conf shell
If KEY starts and ends with a slash the string in between is
interpreted as a regular expression and only keys matching this regex
are displayed
Example:
o conf /color/
- changing of scalar values: o conf KEY VALUE
-
Sets the config variable KEY to VALUE. The empty string can be
specified as usual in shells, with '' or ""
Example:
o conf wget /usr/bin/wget
- changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
-
If a config variable name ends with list, it is a list. o conf
KEY shift removes the first element of the list, o conf KEY pop
removes the last element of the list. o conf KEYS unshift LIST
prepends a list of values to the list, o conf KEYS push LIST
appends a list of valued to the list.
Likewise, o conf KEY splice LIST passes the LIST to the according
splice command.
Finally, any other list of arguments is taken as a new list value for
the KEY variable discarding the previous value.
Examples:
o conf urllist unshift http://cpan.dev.local/CPAN
o conf urllist splice 3 1
o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
- reverting to saved: o conf defaults
-
Reverts all config variables to the state in the saved config file.
- 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.
Currently the following keys in the hash reference $CPAN::Config are
defined:
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
commands_quote prefered 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
check_sigs if signatures should be verified
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
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 envariable FTP_PASSIVE is set for downloads
ftp_proxy proxy host for ftp requests
getcwd see below
gpg path to external prg
gzip location of external program gzip
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
never break.
index_expire after this many days refetch index files
inhibit_startup_message
if true, does not print 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 | 
