--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "CPAN 3"
+.TH CPAN 3 "2009-06-27" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+CPAN \- query, download and build perl modules from CPAN sites
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+Interactive mode:
+.PP
+.Vb 1
+\& perl \-MCPAN \-e shell
+.Ve
+.PP
+\&\-\-or\*(--
+.PP
+.Vb 1
+\& cpan
+.Ve
+.PP
+Basic commands:
+.PP
+.Vb 1
+\& # Modules:
+.Ve
+.PP
+.Vb 1
+\& cpan> install Acme::Meta # in the shell
+.Ve
+.PP
+.Vb 1
+\& CPAN::Shell\->install("Acme::Meta"); # in perl
+.Ve
+.PP
+.Vb 1
+\& # Distributions:
+.Ve
+.PP
+.Vb 1
+\& cpan> install NWCLARK/Acme\-Meta\-0.02.tar.gz # in the shell
+.Ve
+.PP
+.Vb 2
+\& CPAN::Shell\->
+\& install("NWCLARK/Acme\-Meta\-0.02.tar.gz"); # in perl
+.Ve
+.PP
+.Vb 1
+\& # module objects:
+.Ve
+.PP
+.Vb 2
+\& $mo = CPAN::Shell\->expandany($mod);
+\& $mo = CPAN::Shell\->expand("Module",$mod); # same thing
+.Ve
+.PP
+.Vb 1
+\& # distribution objects:
+.Ve
+.PP
+.Vb 4
+\& $do = CPAN::Shell\->expand("Module",$mod)\->distribution;
+\& $do = CPAN::Shell\->expandany($distro); # same thing
+\& $do = CPAN::Shell\->expand("Distribution",
+\& $distro); # same thing
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \s-1CPAN\s0 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, \s-1LWP\s0, and certain external
+download clients to fetch distributions from the net.
+.PP
+These are fetched from one or more mirrored \s-1CPAN\s0 (Comprehensive
+Perl Archive Network) sites and unpacked in a dedicated directory.
+.PP
+The \s-1CPAN\s0 module also supports named and versioned
+\&\fIbundles\fR of modules. Bundles simplify handling of sets of
+related modules. See Bundles below.
+.PP
+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
+using a simple \s-1FIFO\s0 mechanism.
+.PP
+All methods provided are accessible in a programmer style and in an
+interactive shell style.
+.ie n .Sh "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
+.el .Sh "CPAN::shell([$prompt, \f(CW$command\fP]) Starting Interactive Mode"
+.IX Subsection "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
+Enter interactive mode by running
+.PP
+.Vb 1
+\& perl \-MCPAN \-e shell
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\& cpan
+.Ve
+.PP
+which puts you into a readline interface. If \f(CW\*(C`Term::ReadKey\*(C'\fR and
+either of \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR or \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR are installed,
+history and command completion are supported.
+.PP
+Once at the command line, type \f(CW\*(C`h\*(C'\fR for one-page help
+screen; the rest should be self\-explanatory.
+.PP
+The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments: one the
+prompt, the second the default initial command line (the latter
+only works if a real ReadLine interface module is installed).
+.PP
+The most common uses of the interactive modes are
+.IP "Searching for authors, bundles, distribution files and modules" 2
+.IX Item "Searching for authors, bundles, distribution files and modules"
+There are corresponding one-letter commands \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`d\*(C'\fR, and \f(CW\*(C`m\*(C'\fR
+for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the
+mentioned four. Each of the four entities is implemented as a class
+with slightly differing methods for displaying an object.
+.Sp
+Arguments to these commands are either strings exactly matching
+the identification string of an object, or regular expressions
+matched case-insensitively against various attributes of the
+objects. The parser only recognizes a regular expression when you
+enclose it with slashes.
+.Sp
+The principle is that the number of objects found influences how an
+item is displayed. If the search finds one item, the result is
+displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if
+more than one is found, each object is displayed with the terse method
+\&\f(CW\*(C`as_glimpse\*(C'\fR.
+.Sp
+Examples:
+.Sp
+.Vb 28
+\& cpan> m Acme::MetaSyntactic
+\& Module id = Acme::MetaSyntactic
+\& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
+\& CPAN_VERSION 0.99
+\& CPAN_FILE B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\& UPLOAD_DATE 2006\-11\-06
+\& MANPAGE Acme::MetaSyntactic \- Themed metasyntactic variables names
+\& INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
+\& INST_VERSION 0.99
+\& cpan> a BOOK
+\& Author id = BOOK
+\& EMAIL [...]
+\& FULLNAME Philippe Bruhat (BooK)
+\& cpan> d BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\& Distribution id = B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
+\& CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
+\& UPLOAD_DATE 2006\-11\-06
+\& cpan> m /lorem/
+\& Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme\-MetaSyntactic\-0.99.tar.gz)
+\& Module Text::Lorem (ADEOLA/Text\-Lorem\-0.3.tar.gz)
+\& Module Text::Lorem::More (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
+\& Module Text::Lorem::More::Source (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
+\& cpan> i /berlin/
+\& Distribution BEATNIK/Filter\-NumberLines\-0.02.tar.gz
+\& Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime\-TimeZone\-0.7904.tar.gz)
+\& Module Filter::NumberLines (BEATNIK/Filter\-NumberLines\-0.02.tar.gz)
+\& Author [...]
+.Ve
+.Sp
+The examples illustrate several aspects: the first three queries
+target modules, authors, or distros directly and yield exactly one
+result. The last two use regular expressions and yield several
+results. The last one targets all of bundles, modules, authors, and
+distros simultaneously. When more than one result is available, they
+are printed in one-line format.
+.ie n .IP """get""\fR, \f(CW""make""\fR, \f(CW""test""\fR, \f(CW""install""\fR, \f(CW""clean"" modules or distributions" 2
+.el .IP "\f(CWget\fR, \f(CWmake\fR, \f(CWtest\fR, \f(CWinstall\fR, \f(CWclean\fR modules or distributions" 2
+.IX Item "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, \s-1CPAN\s0 determines the distribution file in which this module
+is included and processes that, following any dependencies named in
+the module's \s-1META\s0.yml or Makefile.PL (this behavior is controlled by
+the configuration parameter \f(CW\*(C`prerequisites_policy\*(C'\fR.)
+.Sp
+\&\f(CW\*(C`get\*(C'\fR downloads a distribution file and untars or unzips it, \f(CW\*(C`make\*(C'\fR
+builds it, \f(CW\*(C`test\*(C'\fR runs the test suite, and \f(CW\*(C`install\*(C'\fR installs it.
+.Sp
+Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR is run unconditionally. An
+.Sp
+.Vb 1
+\& install <distribution_file>
+.Ve
+.Sp
+is also run unconditionally. But for
+.Sp
+.Vb 1
+\& install <module>
+.Ve
+.Sp
+\&\s-1CPAN\s0 checks whether an install is needed and prints
+\&\fImodule up to date\fR if the distribution file containing
+the module doesn't need updating.
+.Sp
+\&\s-1CPAN\s0 also keeps track of what it has done within the current session
+and doesn't try to build a package a second time regardless of whether it
+succeeded or not. It does not repeat a test run if the test
+has been run successfully before. Same for install runs.
+.Sp
+The \f(CW\*(C`force\*(C'\fR pragma may precede another command (currently: \f(CW\*(C`get\*(C'\fR,
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, or \f(CW\*(C`install\*(C'\fR) to execute the command from scratch
+and attempt to continue past certain errors. See the section below on
+the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.Sp
+The \f(CW\*(C`notest\*(C'\fR pragma skips the test part in the build
+process.
+.Sp
+Example:
+.Sp
+.Vb 1
+\& cpan> notest install Tk
+.Ve
+.Sp
+A \f(CW\*(C`clean\*(C'\fR command results in a
+.Sp
+.Vb 1
+\& make clean
+.Ve
+.Sp
+being executed within the distribution file's working directory.
+.ie n .IP """readme""\fR, \f(CW""perldoc""\fR, \f(CW""look"" module or distribution" 2
+.el .IP "\f(CWreadme\fR, \f(CWperldoc\fR, \f(CWlook\fR module or distribution" 2
+.IX Item "readme, perldoc, look module or distribution"
+\&\f(CW\*(C`readme\*(C'\fR displays the \s-1README\s0 file of the associated distribution.
+\&\f(CW\*(C`Look\*(C'\fR gets and untars (if not yet done) the distribution file,
+changes to the appropriate directory and opens a subshell process in
+that directory. \f(CW\*(C`perldoc\*(C'\fR displays the module's pod documentation
+in html or plain text format.
+.ie n .IP """ls"" author" 2
+.el .IP "\f(CWls\fR author" 2
+.IX Item "ls author"
+.PD 0
+.ie n .IP """ls"" globbing_expression" 2
+.el .IP "\f(CWls\fR globbing_expression" 2
+.IX Item "ls globbing_expression"
+.PD
+The first form lists all distribution files in and below an author's
+\&\s-1CPAN\s0 directory as stored in the \s-1CHECKUMS\s0 files distributed on
+\&\s-1CPAN\s0. The listing recurses into subdirectories.
+.Sp
+The second form limits or expands the output with shell
+globbing as in the following examples:
+.Sp
+.Vb 3
+\& ls JV/make*
+\& ls GSAR/*make*
+\& ls */*make*
+.Ve
+.Sp
+The last example is very slow and outputs extra progress indicators
+that break the alignment of the result.
+.Sp
+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 that may be changed in some future version.
+.ie n .IP """failed""" 2
+.el .IP "\f(CWfailed\fR" 2
+.IX Item "failed"
+The \f(CW\*(C`failed\*(C'\fR command reports all distributions that failed on one of
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR or \f(CW\*(C`install\*(C'\fR for some reason in the currently
+running shell session.
+.IP "Persistence between sessions" 2
+.IX Item "Persistence between sessions"
+If the \f(CW\*(C`YAML\*(C'\fR or the \f(CW\*(C`YAML::Syck\*(C'\fR 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.
+.Sp
+If the configurations variable \f(CW\*(C`build_dir_reuse\*(C'\fR is set to a true
+value, then \s-1CPAN\s0.pm reads the collected \s-1YAML\s0 files. If the stored
+signature matches the currently running perl, the stored state is
+loaded into memory such that persistence between sessions
+is effectively established.
+.ie n .IP "The ""force""\fR and the \f(CW""fforce"" pragma" 2
+.el .IP "The \f(CWforce\fR and the \f(CWfforce\fR pragma" 2
+.IX Item "The force and the fforce pragma"
+To speed things up in complex installation scenarios, \s-1CPAN\s0.pm keeps
+track of what it has already done and refuses to do some things a
+second time. A \f(CW\*(C`get\*(C'\fR, a \f(CW\*(C`make\*(C'\fR, and an \f(CW\*(C`install\*(C'\fR are not repeated.
+A \f(CW\*(C`test\*(C'\fR is repeated only if the previous test was unsuccessful. The
+diagnostic message when \s-1CPAN\s0.pm refuses to do something a second time
+is one of \fIHas already been \fR\f(CW\*(C`unwrapped|made|tested successfully\*(C'\fR or
+something similar. Another situation where \s-1CPAN\s0 refuses to act is an
+\&\f(CW\*(C`install\*(C'\fR if the corresponding \f(CW\*(C`test\*(C'\fR was not successful.
+.Sp
+In all these cases, the user can override this stubborn behaviour by
+prepending the command with the word force, for example:
+.Sp
+.Vb 4
+\& cpan> force get Foo
+\& cpan> force make AUTHOR/Bar\-3.14.tar.gz
+\& cpan> force test Baz
+\& cpan> force install Acme::Meta
+.Ve
+.Sp
+Each \fIforced\fR command is executed with the corresponding part of its
+memory erased.
+.Sp
+The \f(CW\*(C`fforce\*(C'\fR pragma is a variant that emulates a \f(CW\*(C`force get\*(C'\fR which
+erases the entire memory followed by the action specified, effectively
+restarting the whole get/make/test/install procedure from scratch.
+.IP "Lockfile" 2
+.IX Item "Lockfile"
+Interactive sessions maintain a lockfile, by default \f(CW\*(C`~/.cpan/.lock\*(C'\fR.
+Batch jobs can run without a lockfile and not disturb each other.
+.Sp
+The shell offers to run in \fIdowngraded mode\fR 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.
+.IP "Signals" 2
+.IX Item "Signals"
+\&\s-1CPAN\s0.pm installs signal handlers for \s-1SIGINT\s0 and \s-1SIGTERM\s0. While you are
+in the cpan\-shell, it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and
+return to the cpan-shell prompt. A \s-1SIGTERM\s0 will cause the cpan-shell
+to clean up and leave the shell loop. You can emulate the effect of a
+\&\s-1SIGTERM\s0 by sending two consecutive SIGINTs, which usually means by
+pressing \f(CW\*(C`^C\*(C'\fR twice.
+.Sp
+\&\s-1CPAN\s0.pm ignores \s-1SIGPIPE\s0. If the user sets \f(CW\*(C`inactivity_timeout\*(C'\fR, a
+\&\s-1SIGALRM\s0 is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
+Build.PL\*(C'\fR subprocess.
+.Sh "CPAN::Shell"
+.IX Subsection "CPAN::Shell"
+The commands available in the shell interface are methods in
+the package CPAN::Shell. If you enter the shell command, your
+input is split by the \fIText::ParseWords::shellwords()\fR routine, which
+acts like most shells do. The first word is interpreted as the
+method to be invoked, and the rest of the words are treated as the method's arguments.
+Continuation lines are supported by ending a line with a
+literal backslash.
+.Sh "autobundle"
+.IX Subsection "autobundle"
+\&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the
+\&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains
+a list of all modules that are both available from \s-1CPAN\s0 and currently
+installed within \f(CW@INC\fR. The name of the bundle file is based on the
+current date and a counter.
+.Sh "hosts"
+.IX Subsection "hosts"
+Note: this feature is still in alpha state and may change in future
+versions of \s-1CPAN\s0.pm
+.PP
+This commands provides a statistical overview over recent download
+activities. The data for this is collected in the \s-1YAML\s0 file
+\&\f(CW\*(C`FTPstats.yml\*(C'\fR in your \f(CW\*(C`cpan_home\*(C'\fR directory. If no \s-1YAML\s0 module is
+configured or \s-1YAML\s0 not installed, no stats are provided.
+.Sh "mkmyconfig"
+.IX Subsection "mkmyconfig"
+\&\fImkmyconfig()\fR writes your own CPAN::MyConfig file into your \f(CW\*(C`~/.cpan/\*(C'\fR
+directory so that you can save your own preferences instead of the
+system-wide ones.
+.Sh "recent ***EXPERIMENTAL COMMAND***"
+.IX Subsection "recent ***EXPERIMENTAL COMMAND***"
+The \f(CW\*(C`recent\*(C'\fR command downloads a list of recent uploads to \s-1CPAN\s0 and
+displays them \fIslowly\fR. While the command is running, a \f(CW$SIG\fR{\s-1INT\s0}
+exits the loop after displaying the current item.
+.PP
+\&\fBNote\fR: This command requires XML::LibXML installed.
+.PP
+\&\fBNote\fR: This whole command currently is just a hack and will
+probably change in future versions of \s-1CPAN\s0.pm, but the general
+approach will likely remain.
+.PP
+\&\fBNote\fR: See also smoke
+.Sh "recompile"
+.IX Subsection "recompile"
+\&\fIrecompile()\fR is a special command that takes no argument and
+runs the make/test/install cycle with brute force over all installed
+dynamically loadable extensions (aka \s-1XS\s0 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. \s-1CPAN\s0 installs the whole Bundle for you, but
+when you try to repeat the job on the second architecture, \s-1CPAN\s0
+responds with a \f(CW"Foo up to date"\fR message for all modules. So you
+invoke \s-1CPAN\s0's recompile on the second architecture and you're done.
+.PP
+Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your
+perl breaks binary compatibility. If one of the modules that \s-1CPAN\s0 uses
+is in turn depending on binary compatibility (so you cannot run \s-1CPAN\s0
+commands), then you should try the CPAN::Nox module for recovery.
+.Sh "report Bundle|Distribution|Module"
+.IX Subsection "report Bundle|Distribution|Module"
+The \f(CW\*(C`report\*(C'\fR command temporarily turns on the \f(CW\*(C`test_report\*(C'\fR config
+variable, then runs the \f(CW\*(C`force test\*(C'\fR command with the given
+arguments. The \f(CW\*(C`force\*(C'\fR pragma reruns the tests and repeats
+every step that might have failed before.
+.Sh "smoke ***EXPERIMENTAL COMMAND***"
+.IX Subsection "smoke ***EXPERIMENTAL COMMAND***"
+\&\fB*** \s-1WARNING:\s0 this command downloads and executes software from \s-1CPAN\s0 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. ***\fR
+.PP
+The \f(CW\*(C`smoke\*(C'\fR command takes the list of recent uploads to \s-1CPAN\s0 as
+provided by the \f(CW\*(C`recent\*(C'\fR command and tests them all. While the
+command is running \f(CW$SIG\fR{\s-1INT\s0} is defined to mean that the current item
+shall be skipped.
+.PP
+\&\fBNote\fR: This whole command currently is just a hack and will
+probably change in future versions of \s-1CPAN\s0.pm, but the general
+approach will likely remain.
+.PP
+\&\fBNote\fR: See also recent
+.Sh "upgrade [Module|/Regex/]..."
+.IX Subsection "upgrade [Module|/Regex/]..."
+The \f(CW\*(C`upgrade\*(C'\fR command first runs an \f(CW\*(C`r\*(C'\fR command with the given
+arguments and then installs the newest versions of all modules that
+were listed by that.
+.ie n .Sh "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution"
+.el .Sh "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution"
+.IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution"
+Although it may be considered internal, the class hierarchy does matter
+for both users and programmer. \s-1CPAN\s0.pm deals with the four
+classes mentioned above, and those classes all share a set of methods. 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):
+.PP
+.Vb 1
+\& Namespace Class
+.Ve
+.PP
+.Vb 3
+\& words containing a "/" (slash) Distribution
+\& words starting with Bundle:: Bundle
+\& everything else Module or Author
+.Ve
+.PP
+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 \s-1CPAN\s0 in both version 1.23 and 1.23_90, \s-1CPAN\s0.pm offers a convenient
+way to install version 1.23 by saying
+.PP
+.Vb 1
+\& install Foo
+.Ve
+.PP
+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 \s-1CPAN\s0 relative to the authors/id/
+directory. If the author is \s-1BAR\s0, this might be BAR/Foo\-1.23_90.tar.gz;
+so you would have to say
+.PP
+.Vb 1
+\& install BAR/Foo\-1.23_90.tar.gz
+.Ve
+.PP
+The first example will be driven by an object of the class
+CPAN::Module, the second by an object of class CPAN::Distribution.
+.Sh "Integrating local directories"
+.IX Subsection "Integrating local directories"
+Note: this feature is still in alpha state and may change in future
+versions of \s-1CPAN\s0.pm
+.PP
+Distribution objects are normally distributions from the \s-1CPAN\s0, 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 \s-1CPAN\s0.pm was
+used. All actions such as \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`install\*(C'\fR are applied
+directly to that directory. This gives the command \f(CW\*(C`cpan .\*(C'\fR an
+interesting touch: while the normal mantra of installing a \s-1CPAN\s0 module
+without \s-1CPAN\s0.pm is one of
+.PP
+.Vb 5
+\& perl Makefile.PL perl Build.PL
+\& ( go and get prerequisites )
+\& make ./Build
+\& make test ./Build test
+\& make install ./Build install
+.Ve
+.PP
+the command \f(CW\*(C`cpan .\*(C'\fR does all of this at once. It figures out which
+of the two mantras is appropriate, fetches and installs all
+prerequisites, takes care of them recursively, and finally finishes the
+installation of the module in the current directory, be it a \s-1CPAN\s0
+module or not.
+.PP
+The typical usage case is for private modules or working copies of
+projects from remote repositories on the local disk.
+.Sh "Redirection"
+.IX Subsection "Redirection"
+The usual shell redirection symbols \f(CW\*(C` | \*(C'\fR and \f(CW\*(C`>\*(C'\fR are recognized
+by the cpan shell \fBonly when surrounded by whitespace\fR. So piping to
+pager or redirecting output into a file works somewhat as in a normal
+shell, with the stipulation that you must type extra spaces.
+.SH "CONFIGURATION"
+.IX Header "CONFIGURATION"
+When the \s-1CPAN\s0 module is used for the first time, a configuration
+dialogue tries to determine a couple of site specific options. The
+result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR
+in a file CPAN/Config.pm.
+.PP
+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 \f(CW\*(C`$HOME/.cpan/CPAN/MyConfig.pm\*(C'\fR, because \f(CW\*(C`$HOME/.cpan\*(C'\fR is
+added to the search path of the \s-1CPAN\s0 module before the \fIuse()\fR or
+\&\fIrequire()\fR statements. The mkmyconfig command writes this file for you.
+.PP
+The \f(CW\*(C`o conf\*(C'\fR command has various bells and whistles:
+.IP "completion support" 4
+.IX Item "completion support"
+If you have a ReadLine module installed, you can hit \s-1TAB\s0 at any point
+of the commandline and \f(CW\*(C`o conf\*(C'\fR will offer you completion for the
+built-in subcommands and/or config variable names.
+.IP "displaying some help: o conf help" 4
+.IX Item "displaying some help: o conf help"
+Displays a short help
+.IP "displaying current values: o conf [\s-1KEY\s0]" 4
+.IX Item "displaying current values: o conf [KEY]"
+Displays the current value(s) for this config variable. Without \s-1KEY\s0,
+displays all subcommands and config variables.
+.Sp
+Example:
+.Sp
+.Vb 1
+\& o conf shell
+.Ve
+.Sp
+If \s-1KEY\s0 starts and ends with a slash, the string in between is
+treated as a regular expression and only keys matching this regex
+are displayed
+.Sp
+Example:
+.Sp
+.Vb 1
+\& o conf /color/
+.Ve
+.IP "changing of scalar values: o conf \s-1KEY\s0 \s-1VALUE\s0" 4
+.IX Item "changing of scalar values: o conf KEY VALUE"
+Sets the config variable \s-1KEY\s0 to \s-1VALUE\s0. The empty string can be
+specified as usual in shells, with \f(CW''\fR or \f(CW""\fR
+.Sp
+Example:
+.Sp
+.Vb 1
+\& o conf wget /usr/bin/wget
+.Ve
+.IP "changing of list values: o conf \s-1KEY\s0 SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" 4
+.IX Item "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST"
+If a config variable name ends with \f(CW\*(C`list\*(C'\fR, it is a list. \f(CW\*(C`o conf
+KEY shift\*(C'\fR removes the first element of the list, \f(CW\*(C`o conf KEY pop\*(C'\fR
+removes the last element of the list. \f(CW\*(C`o conf KEYS unshift LIST\*(C'\fR
+prepends a list of values to the list, \f(CW\*(C`o conf KEYS push LIST\*(C'\fR
+appends a list of valued to the list.
+.Sp
+Likewise, \f(CW\*(C`o conf KEY splice LIST\*(C'\fR passes the \s-1LIST\s0 to the corresponding
+splice command.
+.Sp
+Finally, any other list of arguments is taken as a new list value for
+the \s-1KEY\s0 variable discarding the previous value.
+.Sp
+Examples:
+.Sp
+.Vb 3
+\& 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
+.Ve
+.IP "reverting to saved: o conf defaults" 4
+.IX Item "reverting to saved: o conf defaults"
+Reverts all config variables to the state in the saved config file.
+.IP "saving the config: o conf commit" 4
+.IX Item "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).
+.PP
+The configuration dialog can be started any time later again by
+issuing the command \f(CW\*(C` o conf init \*(C'\fR in the \s-1CPAN\s0 shell. A subset of
+the configuration dialog can be run by issuing \f(CW\*(C`o conf init WORD\*(C'\fR
+where \s-1WORD\s0 is any valid config variable or a regular expression.
+.Sh "Config Variables"
+.IX Subsection "Config Variables"
+The following keys in the hash reference \f(CW$CPAN::Config\fR are
+currently defined:
+.PP
+.Vb 108
+\& 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
+\& 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 envariable 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
+\& 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')
+\& 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
+\& randomize_urllist add some randomness to the sequence of the urllist
+\& scan_cache controls scanning of cache ('atstart' 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
+\& 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)
+\& use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
+\& username your username if you CPAN server wants one
+\& 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
+.Ve
+.PP
+You can set and query each of these options interactively in the cpan
+shell with the \f(CW\*(C`o conf\*(C'\fR or the \f(CW\*(C`o conf init\*(C'\fR command as specified below.
+.ie n .IP """o conf <scalar option>""" 2
+.el .IP "\f(CWo conf <scalar option>\fR" 2
+.IX Item "o conf <scalar option>"
+prints the current value of the \fIscalar option\fR
+.ie n .IP """o conf <scalar option> <value>""" 2
+.el .IP "\f(CWo conf <scalar option> <value>\fR" 2
+.IX Item "o conf <scalar option> <value>"
+Sets the value of the \fIscalar option\fR to \fIvalue\fR
+.ie n .IP """o conf <list option>""" 2
+.el .IP "\f(CWo conf <list option>\fR" 2
+.IX Item "o conf <list option>"
+prints the current value of the \fIlist option\fR in MakeMaker's
+neatvalue format.
+.ie n .IP """o conf <list option> [shift|pop]""" 2
+.el .IP "\f(CWo conf <list option> [shift|pop]\fR" 2
+.IX Item "o conf <list option> [shift|pop]"
+shifts or pops the array in the \fIlist option\fR variable
+.ie n .IP """o conf <list option> [unshift|push|splice] <list>""" 2
+.el .IP "\f(CWo conf <list option> [unshift|push|splice] <list>\fR" 2
+.IX Item "o conf <list option> [unshift|push|splice] <list>"
+works like the corresponding perl commands.
+.IP "interactive editing: o conf init [MATCH|LIST]" 2
+.IX Item "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.
+To specify a \s-1MATCH\s0 the argument must be enclosed by slashes.
+.Sp
+Examples:
+.Sp
+.Vb 2
+\& o conf init ftp_passive ftp_proxy
+\& o conf init /color/
+.Ve
+.Sp
+Note: this method of setting config variables often provides more
+explanation about the functioning of a variable than the manpage.
+.Sh "CPAN::anycwd($path): Note on config variable getcwd"
+.IX Subsection "CPAN::anycwd($path): Note on config variable getcwd"
+\&\s-1CPAN\s0.pm changes the current working directory often and needs to
+determine its own current working directory. By default it uses
+Cwd::cwd, but if for some reason this doesn't work on your system,
+configure alternatives according to the following table:
+.IP "cwd" 4
+.IX Item "cwd"
+Calls Cwd::cwd
+.IP "getcwd" 4
+.IX Item "getcwd"
+Calls Cwd::getcwd
+.IP "fastcwd" 4
+.IX Item "fastcwd"
+Calls Cwd::fastcwd
+.IP "backtickcwd" 4
+.IX Item "backtickcwd"
+Calls the external command cwd.
+.Sh "Note on the format of the urllist parameter"
+.IX Subsection "Note on the format of the urllist parameter"
+urllist parameters are URLs according to \s-1RFC\s0 1738. We do a little
+guessing if your \s-1URL\s0 is not compliant, but if you have problems with
+\&\f(CW\*(C`file\*(C'\fR URLs, please try the correct format. Either:
+.PP
+.Vb 1
+\& file://localhost/whatever/ftp/pub/CPAN/
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\& file:///home/ftp/pub/CPAN/
+.Ve
+.Sh "The urllist parameter has CD-ROM support"
+.IX Subsection "The urllist parameter has CD-ROM support"
+The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of
+URLs used for downloading. If the list contains any
+\&\f(CW\*(C`file\*(C'\fR URLs, \s-1CPAN\s0 always tries there first. This
+feature is disabled for index files. So the recommendation for the
+owner of a CD-ROM with \s-1CPAN\s0 contents is: include your local, possibly
+outdated CD-ROM as a \f(CW\*(C`file\*(C'\fR \s-1URL\s0 at the end of urllist, e.g.
+.PP
+.Vb 1
+\& o conf urllist push file://localhost/CDROM/CPAN
+.Ve
+.PP
+\&\s-1CPAN\s0.pm will then fetch the index files from one of the \s-1CPAN\s0 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.
+.PP
+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.
+.Sh "Maintaining the urllist parameter"
+.IX Subsection "Maintaining the urllist parameter"
+If you have \s-1YAML\s0.pm (or some other \s-1YAML\s0 module configured in
+\&\f(CW\*(C`yaml_module\*(C'\fR) installed, \s-1CPAN\s0.pm collects a few statistical data
+about recent downloads. You can view the statistics with the \f(CW\*(C`hosts\*(C'\fR
+command or inspect them directly by looking into the \f(CW\*(C`FTPstats.yml\*(C'\fR
+file in your \f(CW\*(C`cpan_home\*(C'\fR directory.
+.PP
+To get some interesting statistics, it is recommended that
+\&\f(CW\*(C`randomize_urllist\*(C'\fR be set; this introduces some amount of
+randomness into the \s-1URL\s0 selection.
+.ie n .Sh "The ""requires""\fP and \f(CW""build_requires"" dependency declarations"
+.el .Sh "The \f(CWrequires\fP and \f(CWbuild_requires\fP dependency declarations"
+.IX Subsection "The requires and build_requires dependency declarations"
+Since \s-1CPAN\s0.pm version 1.88_51 modules declared as \f(CW\*(C`build_requires\*(C'\fR by
+a distribution are treated differently depending on the config
+variable \f(CW\*(C`build_requires_install_policy\*(C'\fR. By setting
+\&\f(CW\*(C`build_requires_install_policy\*(C'\fR to \f(CW\*(C`no\*(C'\fR, 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
+\&\f(CW\*(C`blib/arch\*(C'\fR and \f(CW\*(C`blib/lib\*(C'\fR directories in the environment variable
+\&\s-1PERL5LIB\s0. If \f(CW\*(C`build_requires_install_policy\*(C'\fR is set ti \f(CW\*(C`yes\*(C'\fR, then
+both modules declared as \f(CW\*(C`requires\*(C'\fR and those declared as
+\&\f(CW\*(C`build_requires\*(C'\fR are treated alike. By setting to \f(CW\*(C`ask/yes\*(C'\fR or
+\&\f(CW\*(C`ask/no\*(C'\fR, \s-1CPAN\s0.pm asks the user and sets the default accordingly.
+.Sh "Configuration for individual distributions (\fIDistroprefs\fP)"
+.IX Subsection "Configuration for individual distributions (Distroprefs)"
+(\fBNote:\fR This feature has been introduced in \s-1CPAN\s0.pm 1.8854 and is
+still considered beta quality)
+.PP
+Distributions on \s-1CPAN\s0 usually behave according to what we call the
+\&\s-1CPAN\s0 mantra. Or since the advent of Module::Build we should talk about
+two mantras:
+.PP
+.Vb 4
+\& perl Makefile.PL perl Build.PL
+\& make ./Build
+\& make test ./Build test
+\& make install ./Build install
+.Ve
+.PP
+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.
+.PP
+The distroprefs system of \f(CW\*(C`CPAN.pm\*(C'\fR addresses this problem by
+allowing the user to specify extra informations and recipes in \s-1YAML\s0
+files to either
+.IP "\(bu" 4
+pass additional arguments to one of the four commands,
+.IP "\(bu" 4
+set environment variables
+.IP "\(bu" 4
+instantiate an Expect object that reads from the console, waits for
+some regular expressions and enters some answers
+.IP "\(bu" 4
+temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables
+.IP "\(bu" 4
+specify dependencies the original maintainer forgot
+.IP "\(bu" 4
+disable the installation of an object altogether
+.PP
+See the \s-1YAML\s0 and Data::Dumper files that come with the \f(CW\*(C`CPAN.pm\*(C'\fR
+distribution in the \f(CW\*(C`distroprefs/\*(C'\fR directory for examples.
+.Sh "Filenames"
+.IX Subsection "Filenames"
+The \s-1YAML\s0 files themselves must have the \f(CW\*(C`.yml\*(C'\fR extension; all other
+files are ignored (for two exceptions see \fIFallback Data::Dumper and
+Storable\fR below). The containing directory can be specified in
+\&\f(CW\*(C`CPAN.pm\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR config variable. Try \f(CW\*(C`o conf init
+prefs_dir\*(C'\fR in the \s-1CPAN\s0 shell to set and activate the distroprefs
+system.
+.PP
+Every \s-1YAML\s0 file may contain arbitrary documents according to the \s-1YAML\s0
+specification, and every document is treated as an entity that
+can specify the treatment of a single distribution.
+.PP
+Filenames can be picked arbitrarily; \f(CW\*(C`CPAN.pm\*(C'\fR always reads
+all files (in alphabetical order) and takes the key \f(CW\*(C`match\*(C'\fR (see
+below in \fILanguage Specs\fR) as a hashref containing match criteria
+that determine if the current distribution matches the \s-1YAML\s0 document
+or not.
+.Sh "Fallback Data::Dumper and Storable"
+.IX Subsection "Fallback Data::Dumper and Storable"
+If neither your configured \f(CW\*(C`yaml_module\*(C'\fR nor \s-1YAML\s0.pm is installed,
+\&\s-1CPAN\s0.pm falls back to using Data::Dumper and Storable and looks for
+files with the extensions \f(CW\*(C`.dd\*(C'\fR or \f(CW\*(C`.st\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR
+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 \f(CW$VAR1\fR, \f(CW$VAR2\fR, etc. The \s-1YAML\s0 shell would produce these
+with the command
+.PP
+.Vb 1
+\& ysh < somefile.yml > somefile.dd
+.Ve
+.PP
+For Storable files the rule is that they must be constructed such that
+\&\f(CW\*(C`Storable::retrieve(file)\*(C'\fR returns an array reference and the array
+elements represent one distropref object each. The conversion from
+\&\s-1YAML\s0 would look like so:
+.PP
+.Vb 3
+\& perl \-MYAML=LoadFile \-MStorable=nstore \-e '
+\& @y=LoadFile(shift);
+\& nstore(\e@y, shift)' somefile.yml somefile.st
+.Ve
+.PP
+In bootstrapping situations it is usually sufficient to translate only
+a few \s-1YAML\s0 files to Data::Dumper for crucial modules like
+\&\f(CW\*(C`YAML::Syck\*(C'\fR, \f(CW\*(C`YAML.pm\*(C'\fR and \f(CW\*(C`Expect.pm\*(C'\fR. 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.
+.Sh "Blueprint"
+.IX Subsection "Blueprint"
+The following example contains all supported keywords and structures
+with the exception of \f(CW\*(C`eexpect\*(C'\fR which can be used instead of
+\&\f(CW\*(C`expect\*(C'\fR.
+.PP
+.Vb 18
+\& \-\-\-
+\& comment: "Demo"
+\& match:
+\& module: "Dancing::Queen"
+\& distribution: "^CHACHACHA/Dancing\-"
+\& not_distribution: "\e.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"
+.Ve
+.PP
+.Vb 1
+\& env: {}
+.Ve
+.PP
+.Vb 3
+\& expect:
+\& \- "Which is your favorite fruit"
+\& \- "apple\en"
+.Ve
+.PP
+.Vb 4
+\& make:
+\& args:
+\& \- all
+\& \- extra\-all
+.Ve
+.PP
+.Vb 1
+\& env: {}
+.Ve
+.PP
+.Vb 1
+\& expect: []
+.Ve
+.PP
+.Vb 1
+\& commendline: "echo SKIPPING make"
+.Ve
+.PP
+.Vb 2
+\& test:
+\& args: []
+.Ve
+.PP
+.Vb 1
+\& env: {}
+.Ve
+.PP
+.Vb 1
+\& expect: []
+.Ve
+.PP
+.Vb 2
+\& install:
+\& args: []
+.Ve
+.PP
+.Vb 2
+\& env:
+\& WANT_TO_INSTALL: YES
+.Ve
+.PP
+.Vb 3
+\& expect:
+\& \- "Do you really want to install"
+\& \- "y\en"
+.Ve
+.PP
+.Vb 2
+\& patches:
+\& \- "ABCDE/Fedcba\-3.14\-ABCDE\-01.patch"
+.Ve
+.PP
+.Vb 7
+\& depends:
+\& configure_requires:
+\& LWP: 5.8
+\& build_requires:
+\& Test::Exception: 0.25
+\& requires:
+\& Spiffy: 0.30
+.Ve
+.Sh "Language Specs"
+.IX Subsection "Language Specs"
+Every \s-1YAML\s0 document represents a single hash reference. The valid keys
+in this hash are as follows:
+.IP "comment [scalar]" 4
+.IX Item "comment [scalar]"
+A comment
+.IP "cpanconfig [hash]" 4
+.IX Item "cpanconfig [hash]"
+Temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables.
+.Sp
+Supported are: \f(CW\*(C`build_requires_install_policy\*(C'\fR, \f(CW\*(C`check_sigs\*(C'\fR,
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_install_make_command\*(C'\fR, \f(CW\*(C`prefer_installer\*(C'\fR,
+\&\f(CW\*(C`test_report\*(C'\fR. Please report as a bug when you need another one
+supported.
+.IP "depends [hash] *** \s-1EXPERIMENTAL\s0 \s-1FEATURE\s0 ***" 4
+.IX Item "depends [hash] *** EXPERIMENTAL FEATURE ***"
+All three types, namely \f(CW\*(C`configure_requires\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and
+\&\f(CW\*(C`requires\*(C'\fR are supported in the way specified in the \s-1META\s0.yml
+specification. The current implementation \fImerges\fR the specified
+dependencies with those declared by the package maintainer. In a
+future implementation this may be changed to override the original
+declaration.
+.IP "disabled [boolean]" 4
+.IX Item "disabled [boolean]"
+Specifies that this distribution shall not be processed at all.
+.IP "features [array] *** \s-1EXPERIMENTAL\s0 \s-1FEATURE\s0 ***" 4
+.IX Item "features [array] *** EXPERIMENTAL FEATURE ***"
+Experimental implementation to deal with optional_features from
+\&\s-1META\s0.yml. Still needs coordination with installer software and
+currently works only for \s-1META\s0.yml declaring \f(CW\*(C`dynamic_config=0\*(C'\fR. Use
+with caution.
+.IP "goto [string]" 4
+.IX Item "goto [string]"
+The canonical name of a delegate distribution to install
+instead. Useful when a new version, although it tests \s-1OK\s0 itself,
+breaks something else or a developer release or a fork is already
+uploaded that is better than the last released version.
+.IP "install [hash]" 4
+.IX Item "install [hash]"
+Processing instructions for the \f(CW\*(C`make install\*(C'\fR or \f(CW\*(C`./Build install\*(C'\fR
+phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
+.IP "make [hash]" 4
+.IX Item "make [hash]"
+Processing instructions for the \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`./Build\*(C'\fR phase of the
+\&\s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
+.IP "match [hash]" 4
+.IX Item "match [hash]"
+A hashref with one or more of the keys \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`modules\*(C'\fR,
+\&\f(CW\*(C`perl\*(C'\fR, \f(CW\*(C`perlconfig\*(C'\fR, and \f(CW\*(C`env\*(C'\fR that specify whether a document is
+targeted at a specific \s-1CPAN\s0 distribution or installation.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+The corresponding values are interpreted as regular expressions. The
+\&\f(CW\*(C`distribution\*(C'\fR related one will be matched against the canonical
+distribution name, e.g. \*(L"AUTHOR/Foo\-Bar\-3.14.tar.gz\*(R".
+.Sp
+The \f(CW\*(C`module\*(C'\fR related one will be matched against \fIall\fR modules
+contained in the distribution until one module matches.
+.Sp
+The \f(CW\*(C`perl\*(C'\fR related one will be matched against \f(CW$^X\fR (but with the
+absolute path).
+.Sp
+The value associated with \f(CW\*(C`perlconfig\*(C'\fR is itself a hashref that is
+matched against corresponding values in the \f(CW%Config::Config\fR hash
+living in the \f(CW\*(C`Config.pm\*(C'\fR module.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+The value associated with \f(CW\*(C`env\*(C'\fR is itself a hashref that is
+matched against corresponding values in the \f(CW%ENV\fR hash.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+If more than one restriction of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, etc. is
+specified, the results of the separately computed match values must
+all match. If so, the hashref represented by the
+\&\s-1YAML\s0 document is returned as the preference structure for the current
+distribution.
+.IP "patches [array]" 4
+.IX Item "patches [array]"
+An array of patches on \s-1CPAN\s0 or on the local disk to be applied in
+order via an external patch program. If the value for the \f(CW\*(C`\-p\*(C'\fR
+parameter is \f(CW0\fR or \f(CW1\fR 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
+\&\f(CW\*(C`patches_dir\*(C'\fR configuration variable or in the format of a canonical
+distroname. For examples please consult the distroprefs/ directory in
+the \s-1CPAN\s0.pm distribution (these examples are not installed by
+default).
+.Sp
+Note: if the \f(CW\*(C`applypatch\*(C'\fR program is installed and \f(CW\*(C`CPAN::Config\*(C'\fR
+knows about it \fBand\fR a patch is written by the \f(CW\*(C`makepatch\*(C'\fR program,
+then \f(CW\*(C`CPAN.pm\*(C'\fR lets \f(CW\*(C`applypatch\*(C'\fR apply the patch. Both \f(CW\*(C`makepatch\*(C'\fR
+and \f(CW\*(C`applypatch\*(C'\fR are available from \s-1CPAN\s0 in the \f(CW\*(C`JV/makepatch\-*\*(C'\fR
+distribution.
+.IP "pl [hash]" 4
+.IX Item "pl [hash]"
+Processing instructions for the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
+Build.PL\*(C'\fR phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing
+Instructions\fR.
+.IP "test [hash]" 4
+.IX Item "test [hash]"
+Processing instructions for the \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR phase
+of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
+.Sh "Processing Instructions"
+.IX Subsection "Processing Instructions"
+.IP "args [array]" 4
+.IX Item "args [array]"
+Arguments to be added to the command line
+.IP "commandline" 4
+.IX Item "commandline"
+A full commandline to run via \f(CW\*(C`system()\*(C'\fR.
+During execution, the environment variable \s-1PERL\s0 is set
+to $^X (but with an absolute path). If \f(CW\*(C`commandline\*(C'\fR is specified,
+\&\f(CW\*(C`args\*(C'\fR is not used.
+.IP "eexpect [hash]" 4
+.IX Item "eexpect [hash]"
+Extended \f(CW\*(C`expect\*(C'\fR. This is a hash reference with four allowed keys,
+\&\f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`reuse\*(C'\fR, and \f(CW\*(C`talk\*(C'\fR.
+.Sp
+\&\f(CW\*(C`mode\*(C'\fR may have the values \f(CW\*(C`deterministic\*(C'\fR for the case where all
+questions come in the order written down and \f(CW\*(C`anyorder\*(C'\fR for the case
+where the questions may come in any order. The default mode is
+\&\f(CW\*(C`deterministic\*(C'\fR.
+.Sp
+\&\f(CW\*(C`timeout\*(C'\fR denotes a timeout in seconds. Floating-point timeouts are
+\&\s-1OK\s0. With \f(CW\*(C`mode=deterministic\*(C'\fR, the timeout denotes the
+timeout per question; with \f(CW\*(C`mode=anyorder\*(C'\fR it denotes the
+timeout per byte received from the stream or questions.
+.Sp
+\&\f(CW\*(C`talk\*(C'\fR 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 (\f(CW\*(C`perl Makefile.PL\*(C'\fR, \f(CW\*(C`perl
+Build.PL\*(C'\fR, \f(CW\*(C`make\*(C'\fR, etc.).
+.Sp
+For \f(CW\*(C`mode=deterministic\*(C'\fR, the \s-1CPAN\s0.pm injects the
+corresponding answer as soon as the stream matches the regular expression.
+.Sp
+For \f(CW\*(C`mode=anyorder\*(C'\fR \s-1CPAN\s0.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 \f(CW\*(C`reuse\*(C'\fR 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 \f(CW\*(C`Do you really want to do that\*(C'\fR 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 \f(CW\*(C`reuse\*(C'\fR to 1 makes this repetition
+unnecessary.
+.IP "env [hash]" 4
+.IX Item "env [hash]"
+Environment variables to be set during the command
+.IP "expect [array]" 4
+.IX Item "expect [array]"
+\&\f(CW\*(C`expect: <array>\*(C'\fR is a short notation for
+.Sp
+eexpect:
+ mode: deterministic
+ timeout: 15
+ talk: <array>
+.ie n .Sh "Schema verification with ""Kwalify"""
+.el .Sh "Schema verification with \f(CWKwalify\fP"
+.IX Subsection "Schema verification with Kwalify"
+If you have the \f(CW\*(C`Kwalify\*(C'\fR module installed (which is part of the
+Bundle::CPANxxl), then all your distroprefs files are checked for
+syntactic correctness.
+.Sh "Example Distroprefs Files"
+.IX Subsection "Example Distroprefs Files"
+\&\f(CW\*(C`CPAN.pm\*(C'\fR comes with a collection of example \s-1YAML\s0 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:\-)
+.SH "PROGRAMMER'S INTERFACE"
+.IX Header "PROGRAMMER'S INTERFACE"
+If you do not enter the shell, shell commands are
+available both as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as
+functions in the calling package (\f(CW\*(C`install(...)\*(C'\fR). Before calling low-level
+commands, it makes sense to initialize components of \s-1CPAN\s0 you need, e.g.:
+.PP
+.Vb 3
+\& CPAN::HandleConfig\->load;
+\& CPAN::Shell::setup_output;
+\& CPAN::Index\->reload;
+.Ve
+.PP
+High-level commands do such initializations automatically.
+.PP
+There's currently only one class that has a stable interface \-
+CPAN::Shell. All commands that are available in the \s-1CPAN\s0 shell are
+methods of the class CPAN::Shell. Each of the commands that produce
+listings of modules (\f(CW\*(C`r\*(C'\fR, \f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of
+the IDs of all modules within the list.
+.IP "expand($type,@things)" 2
+.IX Item "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
+\&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a
+list of CPAN::Module objects according to the \f(CW@things\fR arguments
+given. In scalar context, it returns only the first element of the
+list.
+.IP "expandany(@things)" 2
+.IX Item "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.
+.IP "Programming Examples" 2
+.IX Item "Programming Examples"
+This enables the programmer to do operations that combine
+functionalities that are available in the shell.
+.Sp
+.Vb 2
+\& # install everything that is outdated on my disk:
+\& perl \-MCPAN \-e 'CPAN::Shell\->install(CPAN::Shell\->r)'
+.Ve
+.Sp
+.Vb 4
+\& # install my favorite programs if necessary:
+\& for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
+\& CPAN::Shell\->install($mod);
+\& }
+.Ve
+.Sp
+.Vb 7
+\& # list all modules on my disk that have no VERSION number
+\& for $mod (CPAN::Shell\->expand("Module","/./")) {
+\& next unless $mod\->inst_file;
+\& # MakeMaker convention for undefined $VERSION:
+\& next unless $mod\->inst_version eq "undef";
+\& print "No VERSION in ", $mod\->id, "\en";
+\& }
+.Ve
+.Sp
+.Vb 2
+\& # find out which distribution on CPAN contains a module:
+\& print CPAN::Shell\->expand("Module","Apache::Constants")\->cpan_file
+.Ve
+.Sp
+Or if you want to schedule a \fIcron\fR job to watch \s-1CPAN\s0, you could list
+all modules that need updating. First a quick and dirty way:
+.Sp
+.Vb 1
+\& perl \-e 'use CPAN; CPAN::Shell\->r;'
+.Ve
+.Sp
+If you don't want any output should all modules be
+up to date, parse the output of above command for the regular
+expression \f(CW\*(C`/modules are up to date/\*(C'\fR and decide to mail the output
+only if it doesn't match.
+.Sp
+If you prefer to do it more in a programmerish style in one single
+process, something like this may better suit you:
+.Sp
+.Vb 7
+\& # list all modules on my disk that have newer versions on CPAN
+\& for $mod (CPAN::Shell\->expand("Module","/./")) {
+\& next unless $mod\->inst_file;
+\& next if $mod\->uptodate;
+\& printf "Module %s is installed as %s, could be updated to %s from CPAN\en",
+\& $mod\->id, $mod\->inst_version, $mod\->cpan_version;
+\& }
+.Ve
+.Sp
+If that gives too much output every day, you may want to
+watch only for three modules. You can write
+.Sp
+.Vb 1
+\& for $mod (CPAN::Shell\->expand("Module","/Apache|LWP|CGI/")) {
+.Ve
+.Sp
+as the first line instead. Or you can combine some of the above
+tricks:
+.Sp
+.Vb 5
+\& # watch only for a new mod_perl module
+\& $mod = CPAN::Shell\->expand("Module","mod_perl");
+\& exit if $mod\->uptodate;
+\& # new mod_perl arrived, let me know all update recommendations
+\& CPAN::Shell\->r;
+.Ve
+.Sh "Methods in the other Classes"
+.IX Subsection "Methods in the other Classes"
+.IP "\fICPAN::Author::as_glimpse()\fR" 4
+.IX Item "CPAN::Author::as_glimpse()"
+Returns a one-line description of the author
+.IP "\fICPAN::Author::as_string()\fR" 4
+.IX Item "CPAN::Author::as_string()"
+Returns a multi-line description of the author
+.IP "\fICPAN::Author::email()\fR" 4
+.IX Item "CPAN::Author::email()"
+Returns the author's email address
+.IP "\fICPAN::Author::fullname()\fR" 4
+.IX Item "CPAN::Author::fullname()"
+Returns the author's name
+.IP "\fICPAN::Author::name()\fR" 4
+.IX Item "CPAN::Author::name()"
+An alias for fullname
+.IP "\fICPAN::Bundle::as_glimpse()\fR" 4
+.IX Item "CPAN::Bundle::as_glimpse()"
+Returns a one-line description of the bundle
+.IP "\fICPAN::Bundle::as_string()\fR" 4
+.IX Item "CPAN::Bundle::as_string()"
+Returns a multi-line description of the bundle
+.IP "\fICPAN::Bundle::clean()\fR" 4
+.IX Item "CPAN::Bundle::clean()"
+Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle.
+.IP "\fICPAN::Bundle::contains()\fR" 4
+.IX Item "CPAN::Bundle::contains()"
+Returns a list of objects' IDs contained in a bundle. The associated
+objects may be bundles, modules or distributions.
+.IP "CPAN::Bundle::force($method,@args)" 4
+.IX Item "CPAN::Bundle::force($method,@args)"
+Forces \s-1CPAN\s0 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 \s-1CPAN\s0.pm
+does not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively
+to all contained objects. See also the section above on the \f(CW\*(C`force\*(C'\fR
+and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.IP "\fICPAN::Bundle::get()\fR" 4
+.IX Item "CPAN::Bundle::get()"
+Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle
+.IP "\fICPAN::Bundle::inst_file()\fR" 4
+.IX Item "CPAN::Bundle::inst_file()"
+Returns the highest installed version of the bundle in either \f(CW@INC\fR or
+\&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{cpan_home}>. Note that this is different from
+CPAN::Module::inst_file.
+.IP "\fICPAN::Bundle::inst_version()\fR" 4
+.IX Item "CPAN::Bundle::inst_version()"
+Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR
+.IP "\fICPAN::Bundle::uptodate()\fR" 4
+.IX Item "CPAN::Bundle::uptodate()"
+Returns 1 if the bundle itself and all its members are uptodate.
+.IP "\fICPAN::Bundle::install()\fR" 4
+.IX Item "CPAN::Bundle::install()"
+Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle
+.IP "\fICPAN::Bundle::make()\fR" 4
+.IX Item "CPAN::Bundle::make()"
+Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle
+.IP "\fICPAN::Bundle::readme()\fR" 4
+.IX Item "CPAN::Bundle::readme()"
+Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle
+.IP "\fICPAN::Bundle::test()\fR" 4
+.IX Item "CPAN::Bundle::test()"
+Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle
+.IP "\fICPAN::Distribution::as_glimpse()\fR" 4
+.IX Item "CPAN::Distribution::as_glimpse()"
+Returns a one-line description of the distribution
+.IP "\fICPAN::Distribution::as_string()\fR" 4
+.IX Item "CPAN::Distribution::as_string()"
+Returns a multi-line description of the distribution
+.IP "CPAN::Distribution::author" 4
+.IX Item "CPAN::Distribution::author"
+Returns the CPAN::Author object of the maintainer who uploaded this
+distribution
+.IP "\fICPAN::Distribution::pretty_id()\fR" 4
+.IX Item "CPAN::Distribution::pretty_id()"
+Returns a string of the form \*(L"\s-1AUTHORID/TARBALL\s0\*(R", where \s-1AUTHORID\s0 is the
+author's \s-1PAUSE\s0 \s-1ID\s0 and \s-1TARBALL\s0 is the distribution filename.
+.IP "\fICPAN::Distribution::base_id()\fR" 4
+.IX Item "CPAN::Distribution::base_id()"
+Returns the distribution filename without any archive suffix. E.g
+\&\*(L"Foo\-Bar\-0.01\*(R"
+.IP "\fICPAN::Distribution::clean()\fR" 4
+.IX Item "CPAN::Distribution::clean()"
+Changes to the directory where the distribution has been unpacked and
+runs \f(CW\*(C`make clean\*(C'\fR there.
+.IP "\fICPAN::Distribution::containsmods()\fR" 4
+.IX Item "CPAN::Distribution::containsmods()"
+Returns a list of IDs of modules contained in a distribution file.
+Works only for distributions listed in the 02packages.details.txt.gz
+file. This typically means that just most recent version of a
+distribution is covered.
+.IP "\fICPAN::Distribution::cvs_import()\fR" 4
+.IX Item "CPAN::Distribution::cvs_import()"
+Changes to the directory where the distribution has been unpacked and
+runs something like
+.Sp
+.Vb 1
+\& cvs \-d $cvs_root import \-m $cvs_log $cvs_dir $userid v$version
+.Ve
+.Sp
+there.
+.IP "\fICPAN::Distribution::dir()\fR" 4
+.IX Item "CPAN::Distribution::dir()"
+Returns the directory into which this distribution has been unpacked.
+.IP "CPAN::Distribution::force($method,@args)" 4
+.IX Item "CPAN::Distribution::force($method,@args)"
+Forces \s-1CPAN\s0 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 \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::Distribution::get()\fR" 4
+.IX Item "CPAN::Distribution::get()"
+Downloads the distribution from \s-1CPAN\s0 and unpacks it. Does nothing if
+the distribution has already been downloaded and unpacked within the
+current session.
+.IP "\fICPAN::Distribution::install()\fR" 4
+.IX Item "CPAN::Distribution::install()"
+Changes to the directory where the distribution has been unpacked and
+runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not
+yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR is issued in
+any case and if this fails, the install is cancelled. The
+cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for
+you.
+.Sp
+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.
+.Sp
+Note that \fIinstall()\fR gives no meaningful return value. See \fIuptodate()\fR.
+.IP "\fICPAN::Distribution::install_tested()\fR" 4
+.IX Item "CPAN::Distribution::install_tested()"
+Install all distributions that have tested sucessfully but
+not yet installed. See also \f(CW\*(C`is_tested\*(C'\fR.
+.IP "\fICPAN::Distribution::isa_perl()\fR" 4
+.IX Item "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
+\&\s-1CPAN\s0 can contain a hint to achieve a return value of true for other
+filenames too.
+.IP "\fICPAN::Distribution::look()\fR" 4
+.IX Item "CPAN::Distribution::look()"
+Changes to the directory where the distribution has been unpacked and
+opens a subshell there. Exiting the subshell returns.
+.IP "\fICPAN::Distribution::make()\fR" 4
+.IX Item "CPAN::Distribution::make()"
+First runs the \f(CW\*(C`get\*(C'\fR 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 \f(CW\*(C`perl
+Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there.
+.IP "\fICPAN::Distribution::perldoc()\fR" 4
+.IX Item "CPAN::Distribution::perldoc()"
+Downloads the pod documentation of the file associated with a
+distribution (in \s-1HTML\s0 format) and runs it through the external
+command \fIlynx\fR specified in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{lynx}>. If \fIlynx\fR
+isn't available, it converts it to plain text with the external
+command \fIhtml2text\fR and runs it through the pager specified
+in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{pager}>
+.IP "\fICPAN::Distribution::prefs()\fR" 4
+.IX Item "CPAN::Distribution::prefs()"
+Returns the hash reference from the first matching \s-1YAML\s0 file that the
+user has deposited in the \f(CW\*(C`prefs_dir/\*(C'\fR directory. The first
+succeeding match wins. The files in the \f(CW\*(C`prefs_dir/\*(C'\fR are processed
+alphabetically, and the canonical distroname (e.g.
+AUTHOR/Foo\-Bar\-3.14.tar.gz) is matched against the regular expressions
+stored in the \f(CW$root\fR\->{match}{distribution} attribute value.
+Additionally all module names contained in a distribution are matched
+against the regular expressions in the \f(CW$root\fR\->{match}{module} attribute
+value. The two match values are ANDed together. Each of the two
+attributes are optional.
+.IP "\fICPAN::Distribution::prereq_pm()\fR" 4
+.IX Item "CPAN::Distribution::prereq_pm()"
+Returns the hash reference that has been announced by a distribution
+as the \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`build_requires\*(C'\fR elements. These can be
+declared either by the \f(CW\*(C`META.yml\*(C'\fR (if authoritative) or can be
+deposited after the run of \f(CW\*(C`Build.PL\*(C'\fR in the file \f(CW\*(C`./_build/prereqs\*(C'\fR
+or after the run of \f(CW\*(C`Makfile.PL\*(C'\fR written as the \f(CW\*(C`PREREQ_PM\*(C'\fR hash in
+a comment in the produced \f(CW\*(C`Makefile\*(C'\fR. \fINote\fR: this method only works
+after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns
+undef otherwise.
+.IP "\fICPAN::Distribution::readme()\fR" 4
+.IX Item "CPAN::Distribution::readme()"
+Downloads the \s-1README\s0 file associated with a distribution and runs it
+through the pager specified in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{pager}>.
+.IP "\fICPAN::Distribution::reports()\fR" 4
+.IX Item "CPAN::Distribution::reports()"
+Downloads report data for this distribution from www.cpantesters.org
+and displays a subset of them.
+.IP "\fICPAN::Distribution::read_yaml()\fR" 4
+.IX Item "CPAN::Distribution::read_yaml()"
+Returns the content of the \s-1META\s0.yml of this distro as a hashref. Note:
+works only after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution.
+Returns undef otherwise. Also returns undef if the content of \s-1META\s0.yml
+is not authoritative. (The rules about what exactly makes the content
+authoritative are still in flux.)
+.IP "\fICPAN::Distribution::test()\fR" 4
+.IX Item "CPAN::Distribution::test()"
+Changes to the directory where the distribution has been unpacked and
+runs \f(CW\*(C`make test\*(C'\fR there.
+.IP "\fICPAN::Distribution::uptodate()\fR" 4
+.IX Item "CPAN::Distribution::uptodate()"
+Returns 1 if all the modules contained in the distribution are
+uptodate. Relies on containsmods.
+.IP "\fICPAN::Index::force_reload()\fR" 4
+.IX Item "CPAN::Index::force_reload()"
+Forces a reload of all indices.
+.IP "\fICPAN::Index::reload()\fR" 4
+.IX Item "CPAN::Index::reload()"
+Reloads all indices if they have not been read for more than
+\&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{index_expire}> days.
+.IP "\fICPAN::InfoObj::dump()\fR" 4
+.IX Item "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.
+.IP "\fICPAN::Module::as_glimpse()\fR" 4
+.IX Item "CPAN::Module::as_glimpse()"
+Returns a one-line description of the module in four columns: The
+first column contains the word \f(CW\*(C`Module\*(C'\fR, the second column consists
+of one character: an equals sign if this module is already installed
+and uptodate, a less-than sign if this module is installed but can be
+upgraded, and a space if the module is not installed. The third column
+is the name of the module and the fourth column gives maintainer or
+distribution information.
+.IP "\fICPAN::Module::as_string()\fR" 4
+.IX Item "CPAN::Module::as_string()"
+Returns a multi-line description of the module
+.IP "\fICPAN::Module::clean()\fR" 4
+.IX Item "CPAN::Module::clean()"
+Runs a clean on the distribution associated with this module.
+.IP "\fICPAN::Module::cpan_file()\fR" 4
+.IX Item "CPAN::Module::cpan_file()"
+Returns the filename on \s-1CPAN\s0 that is associated with the module.
+.IP "\fICPAN::Module::cpan_version()\fR" 4
+.IX Item "CPAN::Module::cpan_version()"
+Returns the latest version of this module available on \s-1CPAN\s0.
+.IP "\fICPAN::Module::cvs_import()\fR" 4
+.IX Item "CPAN::Module::cvs_import()"
+Runs a cvs_import on the distribution associated with this module.
+.IP "\fICPAN::Module::description()\fR" 4
+.IX Item "CPAN::Module::description()"
+Returns a 44 character description of this module. Only available for
+modules listed in The Module List (CPAN/modules/00modlist.long.html
+or 00modlist.long.txt.gz)
+.IP "\fICPAN::Module::distribution()\fR" 4
+.IX Item "CPAN::Module::distribution()"
+Returns the CPAN::Distribution object that contains the current
+version of this module.
+.IP "\fICPAN::Module::dslip_status()\fR" 4
+.IX Item "CPAN::Module::dslip_status()"
+Returns a hash reference. The keys of the hash are the letters \f(CW\*(C`D\*(C'\fR,
+\&\f(CW\*(C`S\*(C'\fR, \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`I\*(C'\fR, and <P>, 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
+.Ve
+.Sp
+.Vb 6
+\& 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 maintainance
+.Ve
+.Sp
+.Vb 6
+\& 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++
+.Ve
+.Sp
+.Vb 6
+\& 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
+.Ve
+.Sp
+.Vb 12
+\& 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: appoved by www.opensource.org
+\& d \- allows distribution without restrictions
+\& r \- restricted distribtion
+\& 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.
+.Sh "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.
+.Sh "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, ie. \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"
+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"
+.Sh "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
+\& 'print MM\->parse_version(shift)' 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).
+.Sh "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 "debug package..."
+sets debug mode for packages.
+.IP "o debug \-package..." 2
+.IX Item "debug -package..."
+unsets debug mode for packages.
+.IP "o debug all" 2
+.IX Item "debug all"
+turns debugging on for all packages.
+.IP "o debug number" 2
+.IX Item "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.
+.Sh "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.
+.Sh "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 "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.
+.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:
+.Sh "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
+keyservers, 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 cofeee after a few minutes and leave \s-1CPAN\s0.pm
+to churn away untended.
+.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.
+.Sh "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.
+.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
+.Sh "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
+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
+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
+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
+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
+I am not root, how can I install a module in a personal directory?
+.Sp
+First of all, you will want to use your own configuration, not the one
+that your root user installed. If you do not have permission to write
+in the cpan directory that root has configured, you will be asked if
+you want to create your own config. Answering \*(L"yes\*(R" will bring you into
+\&\s-1CPAN\s0's configuration stage, using the system config for all defaults except
+things that have to do with \s-1CPAN\s0's work directory, saving your choices to
+your MyConfig.pm file.
+.Sp
+You can also manually initiate this process with the following command:
+.Sp
+.Vb 1
+\& % perl \-MCPAN \-e 'mkmyconfig'
+.Ve
+.Sp
+or by running
+.Sp
+.Vb 1
+\& mkmyconfig
+.Ve
+.Sp
+from the \s-1CPAN\s0 shell.
+.Sp
+You will most probably also want to configure something like this:
+.Sp
+.Vb 5
+\& o conf makepl_arg "LIB=~/myperl/lib \e
+\& INSTALLMAN1DIR=~/myperl/man/man1 \e
+\& INSTALLMAN3DIR=~/myperl/man/man3 \e
+\& INSTALLSCRIPT=~/myperl/bin \e
+\& INSTALLBIN=~/myperl/bin"
+.Ve
+.Sp
+and then the equivalent command for Module::Build, which is
+.Sp
+.Vb 5
+\& o conf mbuildpl_arg "\-\-lib=~/myperl/lib \e
+\& \-\-installman1dir=~/myperl/man/man1 \e
+\& \-\-installman3dir=~/myperl/man/man3 \e
+\& \-\-installscript=~/myperl/bin \e
+\& \-\-installbin=~/myperl/bin"
+.Ve
+.Sp
+You can make this setting permanent like all \f(CW\*(C`o conf\*(C'\fR settings with
+\&\f(CW\*(C`o conf commit\*(C'\fR or by setting \f(CW\*(C`auto_commit\*(C'\fR beforehand.
+.Sp
+You will have to add ~/myperl/man to the \s-1MANPATH\s0 environment variable
+and also tell your perl programs to look into ~/myperl/lib, e.g. by
+including
+.Sp
+.Vb 1
+\& use lib "$ENV{HOME}/myperl/lib";
+.Ve
+.Sp
+or setting the \s-1PERL5LIB\s0 environment variable.
+.Sp
+While we're speaking about \f(CW$ENV\fR{\s-1HOME\s0}, it might be worth mentioning,
+that for Windows we use the File::HomeDir module that provides an
+equivalent to the concept of the home directory on Unix.
+.Sp
+Another thing you should bear in mind is that the \s-1UNINST\s0 parameter can
+be dangerous when you are installing into a private area because you
+might accidentally remove modules that other people depend on that are
+not using the private area.
+.IP "6)" 4
+How to get a package, unwrap it, and make a change before building it?
+.Sp
+Have a look at the \f(CW\*(C`look\*(C'\fR (!) command.
+.IP "7)" 4
+I installed a Bundle and had a couple of fails. When I
+retried, everything resolved nicely. Can this be fixed to work
+on first try?
+.Sp
+The reason for this is that \s-1CPAN\s0 does not know the dependencies of all
+modules when it starts out. To decide about the additional items to
+install, it just uses data found in the \s-1META\s0.yml file or the generated
+Makefile. An undetected missing piece breaks the process. But it may
+well be that your Bundle installs some prerequisite later than some
+depending item and thus your second try is able to resolve everything.
+Please note, \s-1CPAN\s0.pm does not know the dependency tree in advance and
+cannot sort the queue of things to install in a topologically correct
+order. It resolves perfectly well \fBif\fR all modules declare the
+prerequisites correctly with the \s-1PREREQ_PM\s0 attribute to MakeMaker or
+the \f(CW\*(C`requires\*(C'\fR stanza of Module::Build. For bundles which fail and
+you need to install often, it is recommended to sort the Bundle
+definition file manually.
+.IP "8)" 4
+In our intranet, we have many modules for internal use. How
+can I integrate these modules with \s-1CPAN\s0.pm but without uploading
+the modules to \s-1CPAN\s0?
+.Sp
+Have a look at the CPAN::Site module.
+.IP "9)" 4
+When I run \s-1CPAN\s0's shell, I get an error message about things in my
+\&\f(CW\*(C`/etc/inputrc\*(C'\fR (or \f(CW\*(C`~/.inputrc\*(C'\fR) file.
+.Sp
+These are readline issues and can only be fixed by studying readline
+configuration on your architecture and adjusting the referenced file
+accordingly. Please make a backup of the \f(CW\*(C`/etc/inputrc\*(C'\fR or \f(CW\*(C`~/.inputrc\*(C'\fR
+and edit them. Quite often harmless changes like uppercasing or
+lowercasing some arguments solves the problem.
+.IP "10)" 4
+.IX Item "10)"
+Some authors have strange characters in their names.
+.Sp
+Internally \s-1CPAN\s0.pm uses the \s-1UTF\-8\s0 charset. If your terminal is
+expecting \s-1ISO\-8859\-1\s0 charset, a converter can be activated by setting
+term_is_latin to a true value in your config file. One way of doing so
+would be
+.Sp
+.Vb 1
+\& cpan> o conf term_is_latin 1
+.Ve
+.Sp
+If other charset support is needed, please file a bugreport against
+\&\s-1CPAN\s0.pm at rt.cpan.org and describe your needs. Maybe we can extend
+the support or maybe \s-1UTF\-8\s0 terminals become widely available.
+.Sp
+Note: this config variable is deprecated and will be removed in a
+future version of \s-1CPAN\s0.pm. It will be replaced with the conventions
+around the family of \f(CW$LANG\fR and \f(CW$LC_\fR* environment variables.
+.IP "11)" 4
+.IX Item "11)"
+When an install fails for some reason and then I correct the error
+condition and retry, \s-1CPAN\s0.pm refuses to install the module, saying
+\&\f(CW\*(C`Already tried without success\*(C'\fR.
+.Sp
+Use the force pragma like so
+.Sp
+.Vb 1
+\& force install Foo::Bar
+.Ve
+.Sp
+Or you can use
+.Sp
+.Vb 1
+\& look Foo::Bar
+.Ve
+.Sp
+and then \f(CW\*(C`make install\*(C'\fR directly in the subshell.
+.IP "12)" 4
+.IX Item "12)"
+How do I install a \*(L"\s-1DEVELOPER\s0 \s-1RELEASE\s0\*(R" of a module?
+.Sp
+By default, \s-1CPAN\s0 will install the latest non-developer release of a
+module. If you want to install a dev release, you have to specify the
+partial path starting with the author id to the tarball you wish to
+install, like so:
+.Sp
+.Vb 1
+\& cpan> install KWILLIAMS/Module\-Build\-0.27_07.tar.gz
+.Ve
+.Sp
+Note that you can use the \f(CW\*(C`ls\*(C'\fR command to get this path listed.
+.IP "13)" 4
+.IX Item "13)"
+How do I install a module and all its dependencies from the commandline,
+without being prompted for anything, despite my \s-1CPAN\s0 configuration
+(or lack thereof)?
+.Sp
+\&\s-1CPAN\s0 uses ExtUtils::MakeMaker's \fIprompt()\fR function to ask its questions, so
+if you set the \s-1PERL_MM_USE_DEFAULT\s0 environment variable, you shouldn't be
+asked any questions at all (assuming the modules you are installing are
+nice about obeying that variable as well):
+.Sp
+.Vb 1
+\& % PERL_MM_USE_DEFAULT=1 perl \-MCPAN \-e 'install My::Module'
+.Ve
+.IP "14)" 4
+.IX Item "14)"
+How do I create a Module::Build based Build.PL derived from an
+ExtUtils::MakeMaker focused Makefile.PL?
+.Sp
+http://search.cpan.org/search?query=Module::Build::Convert
+.Sp
+http://www.refcnt.org/papers/module\-build\-convert
+.IP "15)" 4
+.IX Item "15)"
+I'm frequently irritated with the \s-1CPAN\s0 shell's inability to help me
+select a good mirror.
+.Sp
+The urllist config parameter is yours. You can add and remove sites at
+will. You should find out which sites have the best uptodateness,
+bandwidth, reliability, etc. and are topologically close to you. Some
+people prefer fast downloads, others uptodateness, others reliability.
+You decide which to try in which order.
+.Sp
+Henk P. Penning maintains a site that collects data about \s-1CPAN\s0 sites:
+.Sp
+.Vb 1
+\& http://www.cs.uu.nl/people/henkp/mirmon/cpan.html
+.Ve
+.Sp
+Also, feel free to play with experimental features. Run
+.Sp
+.Vb 1
+\& o conf init randomize_urllist ftpstats_period ftpstats_size
+.Ve
+.Sp
+and choose your favorite parameters. After a few downloads running the
+\&\f(CW\*(C`hosts\*(C'\fR command will probably assist you in choosing the best mirror
+sites.
+.IP "16)" 4
+.IX Item "16)"
+Why do I get asked the same questions every time I start the shell?
+.Sp
+You can make your configuration changes permanent by calling the
+command \f(CW\*(C`o conf commit\*(C'\fR. Alternatively set the \f(CW\*(C`auto_commit\*(C'\fR
+variable to true by running \f(CW\*(C`o conf init auto_commit\*(C'\fR and answering
+the following question with yes.
+.IP "17)" 4
+.IX Item "17)"
+Older versions of \s-1CPAN\s0.pm had the original root directory of all
+tarballs in the build directory. Now there are always random
+characters appended to these directory names. Why was this done?
+.Sp
+The random characters are provided by File::Temp and ensure that each
+module's individual build directory is unique. This makes running
+\&\s-1CPAN\s0.pm in concurrent processes simultaneously safe.
+.IP "18)" 4
+.IX Item "18)"
+Speaking of the build directory. Do I have to clean it up myself?
+.Sp
+You have the choice to set the config variable \f(CW\*(C`scan_cache\*(C'\fR to
+\&\f(CW\*(C`never\*(C'\fR. Then you must clean it up yourself. The other possible
+value, \f(CW\*(C`atstart\*(C'\fR only cleans up the build directory when you start
+the \s-1CPAN\s0 shell. If you never start up the \s-1CPAN\s0 shell, you probably
+also have to clean up the build directory yourself.
+.SH "COMPATIBILITY"
+.IX Header "COMPATIBILITY"
+.Sh "\s-1OLD\s0 \s-1PERL\s0 \s-1VERSIONS\s0"
+.IX Subsection "OLD PERL VERSIONS"
+\&\s-1CPAN\s0.pm is regularly tested to run under 5.004, 5.005, and assorted
+newer versions. It is getting more and more difficult to get the
+minimal prerequisites working on older perls. It is close to
+impossible to get the whole Bundle::CPAN working there. If you're in
+the position to have only these old versions, be advised that \s-1CPAN\s0 is
+designed to work fine without the Bundle::CPAN installed.
+.PP
+To get things going, note that GBARR/Scalar\-List\-Utils\-1.18.tar.gz is
+compatible with ancient perls and that File::Temp is listed as a
+prerequisite but \s-1CPAN\s0 has reasonable workarounds if it is missing.
+.Sh "\s-1CPANPLUS\s0"
+.IX Subsection "CPANPLUS"
+This module and its competitor, the \s-1CPANPLUS\s0 module, are both much
+cooler than the other. \s-1CPAN\s0.pm is older. \s-1CPANPLUS\s0 was designed to be
+more modular, but it was never intended to be compatible with \s-1CPAN\s0.pm.
+.SH "SECURITY ADVICE"
+.IX Header "SECURITY ADVICE"
+This software enables you to upgrade software on your computer and so
+is inherently dangerous because the newly installed software may
+contain bugs and may alter the way your computer works or even make it
+unusable. Please consider backing up your data before every upgrade.
+.SH "BUGS"
+.IX Header "BUGS"
+Please report bugs via <http://rt.cpan.org/>
+.PP
+Before submitting a bug, please make sure that the traditional method
+of building a Perl module package from a shell by following the
+installation instructions of that package still works in your
+environment.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andreas Koenig \f(CW\*(C`<andk@cpan.org>\*(C'\fR
+.SH "LICENSE"
+.IX Header "LICENSE"
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See <http://www.perl.com/perl/misc/Artistic.html>
+.SH "TRANSLATIONS"
+.IX Header "TRANSLATIONS"
+Kawai,Takanori provides a Japanese translation of this manpage at
+<http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+cpan, CPAN::Nox, CPAN::Version
projects / catagits/Gitalist.git / blobdiff