1CPAN(3)               User Contributed Perl Documentation              CPAN(3)
2
3
4

NAME

6       CPAN - query, download and build perl modules from CPAN sites
7

SYNOPSIS

9       Interactive mode:
10
11         perl -MCPAN -e shell
12
13       --or--
14
15         cpan
16
17       Basic commands:
18
19         # Modules:
20
21         cpan> install Acme::Meta                       # in the shell
22
23         CPAN::Shell->install("Acme::Meta");            # in perl
24
25         # Distributions:
26
27         cpan> install NWCLARK/Acme-Meta-0.02.tar.gz    # in the shell
28
29         CPAN::Shell->
30           install("NWCLARK/Acme-Meta-0.02.tar.gz");    # in perl
31
32         # module objects:
33
34         $mo = CPAN::Shell->expandany($mod);
35         $mo = CPAN::Shell->expand("Module",$mod);      # same thing
36
37         # distribution objects:
38
39         $do = CPAN::Shell->expand("Module",$mod)->distribution;
40         $do = CPAN::Shell->expandany($distro);         # same thing
41         $do = CPAN::Shell->expand("Distribution",
42                                   $distro);            # same thing
43

DESCRIPTION

45       The CPAN module automates or at least simplifies the make and install
46       of perl modules and extensions. It includes some primitive searching
47       capabilities and knows how to use LWP, HTTP::Tiny, Net::FTP and certain
48       external download clients to fetch distributions from the net.
49
50       These are fetched from one or more mirrored CPAN (Comprehensive Perl
51       Archive Network) sites and unpacked in a dedicated directory.
52
53       The CPAN module also supports named and versioned bundles of modules.
54       Bundles simplify handling of sets of related modules. See Bundles
55       below.
56
57       The package contains a session manager and a cache manager. The session
58       manager keeps track of what has been fetched, built, and installed in
59       the current session. The cache manager keeps track of the disk space
60       occupied by the make processes and deletes excess space using a simple
61       FIFO mechanism.
62
63       All methods provided are accessible in a programmer style and in an
64       interactive shell style.
65
66   CPAN::shell([$prompt, $command]) Starting Interactive Mode
67       Enter interactive mode by running
68
69           perl -MCPAN -e shell
70
71       or
72
73           cpan
74
75       which puts you into a readline interface. If "Term::ReadKey" and either
76       of "Term::ReadLine::Perl" or "Term::ReadLine::Gnu" are installed,
77       history and command completion are supported.
78
79       Once at the command line, type "h" for one-page help screen; the rest
80       should be self-explanatory.
81
82       The function call "shell" takes two optional arguments: one the prompt,
83       the second the default initial command line (the latter only works if a
84       real ReadLine interface module is installed).
85
86       The most common uses of the interactive modes are
87
88       Searching for authors, bundles, distribution files and modules
89         There are corresponding one-letter commands "a", "b", "d", and "m"
90         for each of the four categories and another, "i" for any of the
91         mentioned four. Each of the four entities is implemented as a class
92         with slightly differing methods for displaying an object.
93
94         Arguments to these commands are either strings exactly matching the
95         identification string of an object, or regular expressions matched
96         case-insensitively against various attributes of the objects. The
97         parser only recognizes a regular expression when you enclose it with
98         slashes.
99
100         The principle is that the number of objects found influences how an
101         item is displayed. If the search finds one item, the result is
102         displayed with the rather verbose method "as_string", but if more
103         than one is found, each object is displayed with the terse method
104         "as_glimpse".
105
106         Examples:
107
108           cpan> m Acme::MetaSyntactic
109           Module id = Acme::MetaSyntactic
110               CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
111               CPAN_VERSION 0.99
112               CPAN_FILE    B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
113               UPLOAD_DATE  2006-11-06
114               MANPAGE      Acme::MetaSyntactic - Themed metasyntactic variables names
115               INST_FILE    /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
116               INST_VERSION 0.99
117           cpan> a BOOK
118           Author id = BOOK
119               EMAIL        [...]
120               FULLNAME     Philippe Bruhat (BooK)
121           cpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz
122           Distribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
123               CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
124               CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
125               UPLOAD_DATE  2006-11-06
126           cpan> m /lorem/
127           Module  = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz)
128           Module    Text::Lorem            (ADEOLA/Text-Lorem-0.3.tar.gz)
129           Module    Text::Lorem::More      (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
130           Module    Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
131           cpan> i /berlin/
132           Distribution    BEATNIK/Filter-NumberLines-0.02.tar.gz
133           Module  = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz)
134           Module    Filter::NumberLines    (BEATNIK/Filter-NumberLines-0.02.tar.gz)
135           Author          [...]
136
137         The examples illustrate several aspects: the first three queries
138         target modules, authors, or distros directly and yield exactly one
139         result. The last two use regular expressions and yield several
140         results. The last one targets all of bundles, modules, authors, and
141         distros simultaneously. When more than one result is available, they
142         are printed in one-line format.
143
144       "get", "make", "test", "install", "clean" modules or distributions
145         These commands take any number of arguments and investigate what is
146         necessary to perform the action. Argument processing is as follows:
147
148           known module name in format Foo/Bar.pm   module
149           other embedded slash                     distribution
150             - with trailing slash dot              directory
151           enclosing slashes                        regexp
152           known module name in format Foo::Bar     module
153
154         If the argument is a distribution file name (recognized by embedded
155         slashes), it is processed. If it is a module, CPAN determines the
156         distribution file in which this module is included and processes
157         that, following any dependencies named in the module's META.yml or
158         Makefile.PL (this behavior is controlled by the configuration
159         parameter "prerequisites_policy"). If an argument is enclosed in
160         slashes it is treated as a regular expression: it is expanded and if
161         the result is a single object (distribution, bundle or module), this
162         object is processed.
163
164         Example:
165
166             install Dummy::Perl                   # installs the module
167             install AUXXX/Dummy-Perl-3.14.tar.gz  # installs that distribution
168             install /Dummy-Perl-3.14/             # same if the regexp is unambiguous
169
170         "get" downloads a distribution file and untars or unzips it, "make"
171         builds it, "test" runs the test suite, and "install" installs it.
172
173         Any "make" or "test" is run unconditionally. An
174
175           install <distribution_file>
176
177         is also run unconditionally. But for
178
179           install <module>
180
181         CPAN checks whether an install is needed and prints module up to date
182         if the distribution file containing the module doesn't need updating.
183
184         CPAN also keeps track of what it has done within the current session
185         and doesn't try to build a package a second time regardless of
186         whether it succeeded or not. It does not repeat a test run if the
187         test has been run successfully before. Same for install runs.
188
189         The "force" pragma may precede another command (currently: "get",
190         "make", "test", or "install") to execute the command from scratch and
191         attempt to continue past certain errors. See the section below on the
192         "force" and the "fforce" pragma.
193
194         The "notest" pragma skips the test part in the build process.
195
196         Example:
197
198             cpan> notest install Tk
199
200         A "clean" command results in a
201
202           make clean
203
204         being executed within the distribution file's working directory.
205
206       "readme", "perldoc", "look" module or distribution
207         "readme" displays the README file of the associated distribution.
208         "Look" gets and untars (if not yet done) the distribution file,
209         changes to the appropriate directory and opens a subshell process in
210         that directory. "perldoc" displays the module's pod documentation in
211         html or plain text format.
212
213       "ls" author
214       "ls" globbing_expression
215         The first form lists all distribution files in and below an author's
216         CPAN directory as stored in the CHECKSUMS files distributed on CPAN.
217         The listing recurses into subdirectories.
218
219         The second form limits or expands the output with shell globbing as
220         in the following examples:
221
222               ls JV/make*
223               ls GSAR/*make*
224               ls */*make*
225
226         The last example is very slow and outputs extra progress indicators
227         that break the alignment of the result.
228
229         Note that globbing only lists directories explicitly asked for, for
230         example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may
231         be regarded as a bug that may be changed in some future version.
232
233       "failed"
234         The "failed" command reports all distributions that failed on one of
235         "make", "test" or "install" for some reason in the currently running
236         shell session.
237
238       Persistence between sessions
239         If the "YAML" or the "YAML::Syck" module is installed a record of the
240         internal state of all modules is written to disk after each step.
241         The files contain a signature of the currently running perl version
242         for later perusal.
243
244         If the configurations variable "build_dir_reuse" is set to a true
245         value, then CPAN.pm reads the collected YAML files. If the stored
246         signature matches the currently running perl, the stored state is
247         loaded into memory such that persistence between sessions is
248         effectively established.
249
250       The "force" and the "fforce" pragma
251         To speed things up in complex installation scenarios, CPAN.pm keeps
252         track of what it has already done and refuses to do some things a
253         second time. A "get", a "make", and an "install" are not repeated.  A
254         "test" is repeated only if the previous test was unsuccessful. The
255         diagnostic message when CPAN.pm refuses to do something a second time
256         is one of Has already been "unwrapped|made|tested successfully" or
257         something similar. Another situation where CPAN refuses to act is an
258         "install" if the corresponding "test" was not successful.
259
260         In all these cases, the user can override this stubborn behaviour by
261         prepending the command with the word force, for example:
262
263           cpan> force get Foo
264           cpan> force make AUTHOR/Bar-3.14.tar.gz
265           cpan> force test Baz
266           cpan> force install Acme::Meta
267
268         Each forced command is executed with the corresponding part of its
269         memory erased.
270
271         The "fforce" pragma is a variant that emulates a "force get" which
272         erases the entire memory followed by the action specified,
273         effectively restarting the whole get/make/test/install procedure from
274         scratch.
275
276       Lockfile
277         Interactive sessions maintain a lockfile, by default "~/.cpan/.lock".
278         Batch jobs can run without a lockfile and not disturb each other.
279
280         The shell offers to run in downgraded mode when another process is
281         holding the lockfile. This is an experimental feature that is not yet
282         tested very well. This second shell then does not write the history
283         file, does not use the metadata file, and has a different prompt.
284
285       Signals
286         CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you
287         are in the cpan-shell, it is intended that you can press "^C" anytime
288         and return to the cpan-shell prompt. A SIGTERM will cause the cpan-
289         shell to clean up and leave the shell loop. You can emulate the
290         effect of a SIGTERM by sending two consecutive SIGINTs, which usually
291         means by pressing "^C" twice.
292
293         CPAN.pm ignores SIGPIPE. If the user sets "inactivity_timeout", a
294         SIGALRM is used during the run of the "perl Makefile.PL" or "perl
295         Build.PL" subprocess. A SIGALRM is also used during module version
296         parsing, and is controlled by "version_timeout".
297
298   CPAN::Shell
299       The commands available in the shell interface are methods in the
300       package CPAN::Shell. If you enter the shell command, your input is
301       split by the Text::ParseWords::shellwords() routine, which acts like
302       most shells do. The first word is interpreted as the method to be
303       invoked, and the rest of the words are treated as the method's
304       arguments.  Continuation lines are supported by ending a line with a
305       literal backslash.
306
307   autobundle
308       "autobundle" writes a bundle file into the
309       "$CPAN::Config->{cpan_home}/Bundle" directory. The file contains a list
310       of all modules that are both available from CPAN and currently
311       installed within @INC. Duplicates of each distribution are suppressed.
312       The name of the bundle file is based on the current date and a counter,
313       e.g. Bundle/Snapshot_2012_05_21_00.pm. This is installed again by
314       running "cpan Bundle::Snapshot_2012_05_21_00", or installing
315       "Bundle::Snapshot_2012_05_21_00" from the CPAN shell.
316
317       Return value: path to the written file.
318
319   hosts
320       Note: this feature is still in alpha state and may change in future
321       versions of CPAN.pm
322
323       This commands provides a statistical overview over recent download
324       activities. The data for this is collected in the YAML file
325       "FTPstats.yml" in your "cpan_home" directory. If no YAML module is
326       configured or YAML not installed, no stats are provided.
327
328       install_tested
329           Install all distributions that have been tested successfully but
330           have not yet been installed. See also "is_tested".
331
332       is_tested
333           List all build directories of distributions that have been tested
334           successfully but have not yet been installed. See also
335           "install_tested".
336
337   mkmyconfig
338       mkmyconfig() writes your own CPAN::MyConfig file into your "~/.cpan/"
339       directory so that you can save your own preferences instead of the
340       system-wide ones.
341
342   r [Module|/Regexp/]...
343       scans current perl installation for modules that have a newer version
344       available on CPAN and provides a list of them. If called without
345       argument, all potential upgrades are listed; if called with arguments
346       the list is filtered to the modules and regexps given as arguments.
347
348       The listing looks something like this:
349
350         Package namespace         installed    latest  in CPAN file
351         CPAN                        1.94_64    1.9600  ANDK/CPAN-1.9600.tar.gz
352         CPAN::Reporter               1.1801    1.1902  DAGOLDEN/CPAN-Reporter-1.1902.tar.gz
353         YAML                           0.70      0.73  INGY/YAML-0.73.tar.gz
354         YAML::Syck                     1.14      1.17  AVAR/YAML-Syck-1.17.tar.gz
355         YAML::Tiny                     1.44      1.50  ADAMK/YAML-Tiny-1.50.tar.gz
356         CGI                            3.43      3.55  MARKSTOS/CGI.pm-3.55.tar.gz
357         Module::Build::YAML            1.40      1.41  DAGOLDEN/Module-Build-0.3800.tar.gz
358         TAP::Parser::Result::YAML      3.22      3.23  ANDYA/Test-Harness-3.23.tar.gz
359         YAML::XS                       0.34      0.35  INGY/YAML-LibYAML-0.35.tar.gz
360
361       It suppresses duplicates in the column "in CPAN file" such that
362       distributions with many upgradeable modules are listed only once.
363
364       Note that the list is not sorted.
365
366   recent ***EXPERIMENTAL COMMAND***
367       The "recent" command downloads a list of recent uploads to CPAN and
368       displays them slowly. While the command is running, a $SIG{INT} exits
369       the loop after displaying the current item.
370
371       Note: This command requires XML::LibXML installed.
372
373       Note: This whole command currently is just a hack and will probably
374       change in future versions of CPAN.pm, but the general approach will
375       likely remain.
376
377       Note: See also smoke
378
379   recompile
380       recompile() is a special command that takes no argument and runs the
381       make/test/install cycle with brute force over all installed dynamically
382       loadable extensions (a.k.a. XS modules) with 'force' in effect. The
383       primary purpose of this command is to finish a network installation.
384       Imagine you have a common source tree for two different architectures.
385       You decide to do a completely independent fresh installation. You start
386       on one architecture with the help of a Bundle file produced earlier.
387       CPAN installs the whole Bundle for you, but when you try to repeat the
388       job on the second architecture, CPAN responds with a "Foo up to date"
389       message for all modules. So you invoke CPAN's recompile on the second
390       architecture and you're done.
391
392       Another popular use for "recompile" is to act as a rescue in case your
393       perl breaks binary compatibility. If one of the modules that CPAN uses
394       is in turn depending on binary compatibility (so you cannot run CPAN
395       commands), then you should try the CPAN::Nox module for recovery.
396
397   report Bundle|Distribution|Module
398       The "report" command temporarily turns on the "test_report" config
399       variable, then runs the "force test" command with the given arguments.
400       The "force" pragma reruns the tests and repeats every step that might
401       have failed before.
402
403   smoke ***EXPERIMENTAL COMMAND***
404       *** WARNING: this command downloads and executes software from CPAN to
405       your computer of completely unknown status. You should never do this
406       with your normal account and better have a dedicated well separated and
407       secured machine to do this. ***
408
409       The "smoke" command takes the list of recent uploads to CPAN as
410       provided by the "recent" command and tests them all. While the command
411       is running $SIG{INT} is defined to mean that the current item shall be
412       skipped.
413
414       Note: This whole command currently is just a hack and will probably
415       change in future versions of CPAN.pm, but the general approach will
416       likely remain.
417
418       Note: See also recent
419
420   upgrade [Module|/Regexp/]...
421       The "upgrade" command first runs an "r" command with the given
422       arguments and then installs the newest versions of all modules that
423       were listed by that.
424
425   The four "CPAN::*" Classes: Author, Bundle, Module, Distribution
426       Although it may be considered internal, the class hierarchy does matter
427       for both users and programmer. CPAN.pm deals with the four classes
428       mentioned above, and those classes all share a set of methods.
429       Classical single polymorphism is in effect. A metaclass object
430       registers all objects of all kinds and indexes them with a string. The
431       strings referencing objects have a separated namespace (well, not
432       completely separated):
433
434                Namespace                         Class
435
436          words containing a "/" (slash)      Distribution
437           words starting with Bundle::          Bundle
438                 everything else            Module or Author
439
440       Modules know their associated Distribution objects. They always refer
441       to the most recent official release. Developers may mark their releases
442       as unstable development versions (by inserting an underscore into the
443       module version number which will also be reflected in the distribution
444       name when you run 'make dist'), so the really hottest and newest
445       distribution is not always the default.  If a module Foo circulates on
446       CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient way
447       to install version 1.23 by saying
448
449           install Foo
450
451       This would install the complete distribution file (say
452       BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
453       like to install version 1.23_90, you need to know where the
454       distribution file resides on CPAN relative to the authors/id/
455       directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
456       so you would have to say
457
458           install BAR/Foo-1.23_90.tar.gz
459
460       The first example will be driven by an object of the class
461       CPAN::Module, the second by an object of class CPAN::Distribution.
462
463   Integrating local directories
464       Note: this feature is still in alpha state and may change in future
465       versions of CPAN.pm
466
467       Distribution objects are normally distributions from the CPAN, but
468       there is a slightly degenerate case for Distribution objects, too, of
469       projects held on the local disk. These distribution objects have the
470       same name as the local directory and end with a dot. A dot by itself is
471       also allowed for the current directory at the time CPAN.pm was used.
472       All actions such as "make", "test", and "install" are applied directly
473       to that directory. This gives the command "cpan ." an interesting
474       touch: while the normal mantra of installing a CPAN module without
475       CPAN.pm is one of
476
477           perl Makefile.PL                 perl Build.PL
478                  ( go and get prerequisites )
479           make                             ./Build
480           make test                        ./Build test
481           make install                     ./Build install
482
483       the command "cpan ." does all of this at once. It figures out which of
484       the two mantras is appropriate, fetches and installs all prerequisites,
485       takes care of them recursively, and finally finishes the installation
486       of the module in the current directory, be it a CPAN module or not.
487
488       The typical usage case is for private modules or working copies of
489       projects from remote repositories on the local disk.
490
491   Redirection
492       The usual shell redirection symbols " | " and ">" are recognized by the
493       cpan shell only when surrounded by whitespace. So piping to pager or
494       redirecting output into a file works somewhat as in a normal shell,
495       with the stipulation that you must type extra spaces.
496
497   Plugin support ***EXPERIMENTAL***
498       Plugins are objects that implement any of currently eight methods:
499
500         pre_get
501         post_get
502         pre_make
503         post_make
504         pre_test
505         post_test
506         pre_install
507         post_install
508
509       The "plugin_list" configuration parameter holds a list of strings of
510       the form
511
512         Modulename=arg0,arg1,arg2,arg3,...
513
514       eg:
515
516         CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1
517
518       At run time, each listed plugin is instantiated as a singleton object
519       by running the equivalent of this pseudo code:
520
521         my $plugin = <string representation from config>;
522         <generate Modulename and arguments from $plugin>;
523         my $p = $instance{$plugin} ||= Modulename->new($arg0,$arg1,...);
524
525       The generated singletons are kept around from instantiation until the
526       end of the shell session. <plugin_list> can be reconfigured at any time
527       at run time. While the cpan shell is running, it checks all activated
528       plugins at each of the 8 reference points listed above and runs the
529       respective method if it is implemented for that object. The method is
530       called with the active CPAN::Distribution object passed in as an
531       argument.
532

CONFIGURATION

534       When the CPAN module is used for the first time, a configuration
535       dialogue tries to determine a couple of site specific options. The
536       result of the dialog is stored in a hash reference  $CPAN::Config in a
537       file CPAN/Config.pm.
538
539       Default values defined in the CPAN/Config.pm file can be overridden in
540       a user specific file: CPAN/MyConfig.pm. Such a file is best placed in
541       "$HOME/.cpan/CPAN/MyConfig.pm", because "$HOME/.cpan" is added to the
542       search path of the CPAN module before the use() or require()
543       statements. The mkmyconfig command writes this file for you.
544
545       The "o conf" command has various bells and whistles:
546
547       completion support
548           If you have a ReadLine module installed, you can hit TAB at any
549           point of the commandline and "o conf" will offer you completion for
550           the built-in subcommands and/or config variable names.
551
552       displaying some help: o conf help
553           Displays a short help
554
555       displaying current values: o conf [KEY]
556           Displays the current value(s) for this config variable. Without
557           KEY, displays all subcommands and config variables.
558
559           Example:
560
561             o conf shell
562
563           If KEY starts and ends with a slash, the string in between is
564           treated as a regular expression and only keys matching this regexp
565           are displayed
566
567           Example:
568
569             o conf /color/
570
571       changing of scalar values: o conf KEY VALUE
572           Sets the config variable KEY to VALUE. The empty string can be
573           specified as usual in shells, with '' or ""
574
575           Example:
576
577             o conf wget /usr/bin/wget
578
579       changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
580           If a config variable name ends with "list", it is a list. "o conf
581           KEY shift" removes the first element of the list, "o conf KEY pop"
582           removes the last element of the list. "o conf KEYS unshift LIST"
583           prepends a list of values to the list, "o conf KEYS push LIST"
584           appends a list of valued to the list.
585
586           Likewise, "o conf KEY splice LIST" passes the LIST to the
587           corresponding splice command.
588
589           Finally, any other list of arguments is taken as a new list value
590           for the KEY variable discarding the previous value.
591
592           Examples:
593
594             o conf urllist unshift http://cpan.dev.local/CPAN
595             o conf urllist splice 3 1
596             o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
597
598       reverting to saved: o conf defaults
599           Reverts all config variables to the state in the saved config file.
600
601       saving the config: o conf commit
602           Saves all config variables to the current config file
603           (CPAN/Config.pm or CPAN/MyConfig.pm that was loaded at start).
604
605       The configuration dialog can be started any time later again by issuing
606       the command " o conf init " in the CPAN shell. A subset of the
607       configuration dialog can be run by issuing "o conf init WORD" where
608       WORD is any valid config variable or a regular expression.
609
610   Config Variables
611       The following keys in the hash reference $CPAN::Config are currently
612       defined:
613
614         allow_installing_module_downgrades
615                            allow or disallow installing module downgrades
616         allow_installing_outdated_dists
617                            allow or disallow installing modules that are
618                            indexed in the cpan index pointing to a distro
619                            with a higher distro-version number
620         applypatch         path to external prg
621         auto_commit        commit all changes to config variables to disk
622         build_cache        size of cache for directories to build modules
623         build_dir          locally accessible directory to build modules
624         build_dir_reuse    boolean if distros in build_dir are persistent
625         build_requires_install_policy
626                            to install or not to install when a module is
627                            only needed for building. yes|no|ask/yes|ask/no
628         bzip2              path to external prg
629         cache_metadata     use serializer to cache metadata
630         check_sigs         if signatures should be verified
631         cleanup_after_install
632                            remove build directory immediately after a
633                            successful install and remember that for the
634                            duration of the session
635         colorize_debug     Term::ANSIColor attributes for debugging output
636         colorize_output    boolean if Term::ANSIColor should colorize output
637         colorize_print     Term::ANSIColor attributes for normal output
638         colorize_warn      Term::ANSIColor attributes for warnings
639         commandnumber_in_prompt
640                            boolean if you want to see current command number
641         commands_quote     preferred character to use for quoting external
642                            commands when running them. Defaults to double
643                            quote on Windows, single tick everywhere else;
644                            can be set to space to disable quoting
645         connect_to_internet_ok
646                            whether to ask if opening a connection is ok before
647                            urllist is specified
648         cpan_home          local directory reserved for this package
649         curl               path to external prg
650         dontload_hash      DEPRECATED
651         dontload_list      arrayref: modules in the list will not be
652                            loaded by the CPAN::has_inst() routine
653         ftp                path to external prg
654         ftp_passive        if set, the environment variable FTP_PASSIVE is set
655                            for downloads
656         ftp_proxy          proxy host for ftp requests
657         ftpstats_period    max number of days to keep download statistics
658         ftpstats_size      max number of items to keep in the download statistics
659         getcwd             see below
660         gpg                path to external prg
661         gzip               location of external program gzip
662         halt_on_failure    stop processing after the first failure of queued
663                            items or dependencies
664         histfile           file to maintain history between sessions
665         histsize           maximum number of lines to keep in histfile
666         http_proxy         proxy host for http requests
667         inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
668                            after this many seconds inactivity. Set to 0 to
669                            disable timeouts.
670         index_expire       refetch index files after this many days
671         inhibit_startup_message
672                            if true, suppress the startup message
673         keep_source_where  directory in which to keep the source (if we do)
674         load_module_verbosity
675                            report loading of optional modules used by CPAN.pm
676         lynx               path to external prg
677         make               location of external make program
678         make_arg           arguments that should always be passed to 'make'
679         make_install_make_command
680                            the make command for running 'make install', for
681                            example 'sudo make'
682         make_install_arg   same as make_arg for 'make install'
683         makepl_arg         arguments passed to 'perl Makefile.PL'
684         mbuild_arg         arguments passed to './Build'
685         mbuild_install_arg arguments passed to './Build install'
686         mbuild_install_build_command
687                            command to use instead of './Build' when we are
688                            in the install stage, for example 'sudo ./Build'
689         mbuildpl_arg       arguments passed to 'perl Build.PL'
690         ncftp              path to external prg
691         ncftpget           path to external prg
692         no_proxy           don't proxy to these hosts/domains (comma separated list)
693         pager              location of external program more (or any pager)
694         password           your password if you CPAN server wants one
695         patch              path to external prg
696         patches_dir        local directory containing patch files
697         perl5lib_verbosity verbosity level for PERL5LIB additions
698         plugin_list        list of active hooks (see Plugin support above
699                            and the CPAN::Plugin module)
700         prefer_external_tar
701                            per default all untar operations are done with
702                            Archive::Tar; by setting this variable to true
703                            the external tar command is used if available
704         prefer_installer   legal values are MB and EUMM: if a module comes
705                            with both a Makefile.PL and a Build.PL, use the
706                            former (EUMM) or the latter (MB); if the module
707                            comes with only one of the two, that one will be
708                            used no matter the setting
709         prerequisites_policy
710                            what to do if you are missing module prerequisites
711                            ('follow' automatically, 'ask' me, or 'ignore')
712                            For 'follow', also sets PERL_AUTOINSTALL and
713                            PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if
714                            not already set
715         prefs_dir          local directory to store per-distro build options
716         proxy_user         username for accessing an authenticating proxy
717         proxy_pass         password for accessing an authenticating proxy
718         pushy_https        use https to cpan.org when possible, otherwise use http
719                            to cpan.org and issue a warning
720         randomize_urllist  add some randomness to the sequence of the urllist
721         recommends_policy  whether recommended prerequisites should be included
722         scan_cache         controls scanning of cache ('atstart', 'atexit' or 'never')
723         shell              your favorite shell
724         show_unparsable_versions
725                            boolean if r command tells which modules are versionless
726         show_upload_date   boolean if commands should try to determine upload date
727         show_zero_versions boolean if r command tells for which modules $version==0
728         suggests_policy    whether suggested prerequisites should be included
729         tar                location of external program tar
730         tar_verbosity      verbosity level for the tar command
731         term_is_latin      deprecated: if true Unicode is translated to ISO-8859-1
732                            (and nonsense for characters outside latin range)
733         term_ornaments     boolean to turn ReadLine ornamenting on/off
734         test_report        email test reports (if CPAN::Reporter is installed)
735         trust_test_report_history
736                            skip testing when previously tested ok (according to
737                            CPAN::Reporter history)
738         unzip              location of external program unzip
739         urllist            arrayref to nearby CPAN sites (or equivalent locations)
740         urllist_ping_external
741                            use external ping command when autoselecting mirrors
742         urllist_ping_verbose
743                            increase verbosity when autoselecting mirrors
744         use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
745         use_sqlite         use CPAN::SQLite for metadata storage (fast and lean)
746         username           your username if you CPAN server wants one
747         version_timeout    stops version parsing after this many seconds.
748                            Default is 15 secs. Set to 0 to disable.
749         wait_list          arrayref to a wait server to try (See CPAN::WAIT)
750         wget               path to external prg
751         yaml_load_code     enable YAML code deserialisation via CPAN::DeferredCode
752         yaml_module        which module to use to read/write YAML files
753
754       You can set and query each of these options interactively in the cpan
755       shell with the "o conf" or the "o conf init" command as specified
756       below.
757
758       "o conf <scalar option>"
759         prints the current value of the scalar option
760
761       "o conf <scalar option> <value>"
762         Sets the value of the scalar option to value
763
764       "o conf <list option>"
765         prints the current value of the list option in MakeMaker's neatvalue
766         format.
767
768       "o conf <list option> [shift|pop]"
769         shifts or pops the array in the list option variable
770
771       "o conf <list option> [unshift|push|splice] <list>"
772         works like the corresponding perl commands.
773
774       interactive editing: o conf init [MATCH|LIST]
775         Runs an interactive configuration dialog for matching variables.
776         Without argument runs the dialog over all supported config variables.
777         To specify a MATCH the argument must be enclosed by slashes.
778
779         Examples:
780
781           o conf init ftp_passive ftp_proxy
782           o conf init /color/
783
784         Note: this method of setting config variables often provides more
785         explanation about the functioning of a variable than the manpage.
786
787   CPAN::anycwd($path): Note on config variable getcwd
788       CPAN.pm changes the current working directory often and needs to
789       determine its own current working directory. By default it uses
790       Cwd::cwd, but if for some reason this doesn't work on your system,
791       configure alternatives according to the following table:
792
793       cwd Calls Cwd::cwd
794
795       getcwd
796           Calls Cwd::getcwd
797
798       fastcwd
799           Calls Cwd::fastcwd
800
801       getdcwd
802           Calls Cwd::getdcwd
803
804       backtickcwd
805           Calls the external command cwd.
806
807   Note on the format of the urllist parameter
808       urllist parameters are URLs according to RFC 1738. We do a little
809       guessing if your URL is not compliant, but if you have problems with
810       "file" URLs, please try the correct format. Either:
811
812           file://localhost/whatever/ftp/pub/CPAN/
813
814       or
815
816           file:///home/ftp/pub/CPAN/
817
818   The urllist parameter has CD-ROM support
819       The "urllist" parameter of the configuration table contains a list of
820       URLs used for downloading. If the list contains any "file" URLs, CPAN
821       always tries there first. This feature is disabled for index files. So
822       the recommendation for the owner of a CD-ROM with CPAN contents is:
823       include your local, possibly outdated CD-ROM as a "file" URL at the end
824       of urllist, e.g.
825
826         o conf urllist push file://localhost/CDROM/CPAN
827
828       CPAN.pm will then fetch the index files from one of the CPAN sites that
829       come at the beginning of urllist. It will later check for each module
830       to see whether there is a local copy of the most recent version.
831
832       Another peculiarity of urllist is that the site that we could
833       successfully fetch the last file from automatically gets a preference
834       token and is tried as the first site for the next request. So if you
835       add a new site at runtime it may happen that the previously preferred
836       site will be tried another time. This means that if you want to
837       disallow a site for the next transfer, it must be explicitly removed
838       from urllist.
839
840   Maintaining the urllist parameter
841       If you have YAML.pm (or some other YAML module configured in
842       "yaml_module") installed, CPAN.pm collects a few statistical data about
843       recent downloads. You can view the statistics with the "hosts" command
844       or inspect them directly by looking into the "FTPstats.yml" file in
845       your "cpan_home" directory.
846
847       To get some interesting statistics, it is recommended that
848       "randomize_urllist" be set; this introduces some amount of randomness
849       into the URL selection.
850
851   The "requires" and "build_requires" dependency declarations
852       Since CPAN.pm version 1.88_51 modules declared as "build_requires" by a
853       distribution are treated differently depending on the config variable
854       "build_requires_install_policy". By setting
855       "build_requires_install_policy" to "no", such a module is not
856       installed. It is only built and tested, and then kept in the list of
857       tested but uninstalled modules. As such, it is available during the
858       build of the dependent module by integrating the path to the
859       "blib/arch" and "blib/lib" directories in the environment variable
860       PERL5LIB. If "build_requires_install_policy" is set to "yes", then both
861       modules declared as "requires" and those declared as "build_requires"
862       are treated alike. By setting to "ask/yes" or "ask/no", CPAN.pm asks
863       the user and sets the default accordingly.
864
865   Configuration of the allow_installing_* parameters
866       The "allow_installing_*" parameters are evaluated during the "make"
867       phase. If set to "yes", they allow the testing and the installation of
868       the current distro and otherwise have no effect. If set to "no", they
869       may abort the build (preventing testing and installing), depending on
870       the contents of the "blib/" directory. The "blib/" directory is the
871       directory that holds all the files that would usually be installed in
872       the "install" phase.
873
874       "allow_installing_outdated_dists" compares the "blib/" directory with
875       the CPAN index.  If it finds something there that belongs, according to
876       the index, to a different dist, it aborts the current build.
877
878       "allow_installing_module_downgrades" compares the "blib/" directory
879       with already installed modules, actually their version numbers, as
880       determined by ExtUtils::MakeMaker or equivalent. If a to-be-installed
881       module would downgrade an already installed module, the current build
882       is aborted.
883
884       An interesting twist occurs when a distroprefs document demands the
885       installation of an outdated dist via goto while
886       "allow_installing_outdated_dists" forbids it. Without additional
887       provisions, this would let the "allow_installing_outdated_dists" win
888       and the distroprefs lose. So the proper arrangement in such a case is
889       to write a second distroprefs document for the distro that "goto"
890       points to and overrule the "cpanconfig" there. E.g.:
891
892         ---
893         match:
894           distribution: "^MAUKE/Keyword-Simple-0.04.tar.gz"
895         goto: "MAUKE/Keyword-Simple-0.03.tar.gz"
896         ---
897         match:
898           distribution: "^MAUKE/Keyword-Simple-0.03.tar.gz"
899         cpanconfig:
900           allow_installing_outdated_dists: yes
901
902   Configuration for individual distributions (Distroprefs)
903       (Note: This feature has been introduced in CPAN.pm 1.8854)
904
905       Distributions on CPAN usually behave according to what we call the CPAN
906       mantra. Or since the advent of Module::Build we should talk about two
907       mantras:
908
909           perl Makefile.PL     perl Build.PL
910           make                 ./Build
911           make test            ./Build test
912           make install         ./Build install
913
914       But some modules cannot be built with this mantra. They try to get some
915       extra data from the user via the environment, extra arguments, or
916       interactively--thus disturbing the installation of large bundles like
917       Phalanx100 or modules with many dependencies like Plagger.
918
919       The distroprefs system of "CPAN.pm" addresses this problem by allowing
920       the user to specify extra informations and recipes in YAML files to
921       either
922
923       •   pass additional arguments to one of the four commands,
924
925       •   set environment variables
926
927       •   instantiate an Expect object that reads from the console, waits for
928           some regular expressions and enters some answers
929
930       •   temporarily override assorted "CPAN.pm" configuration variables
931
932       •   specify dependencies the original maintainer forgot
933
934       •   disable the installation of an object altogether
935
936       See the YAML and Data::Dumper files that come with the "CPAN.pm"
937       distribution in the "distroprefs/" directory for examples.
938
939   Filenames
940       The YAML files themselves must have the ".yml" extension; all other
941       files are ignored (for two exceptions see Fallback Data::Dumper and
942       Storable below). The containing directory can be specified in "CPAN.pm"
943       in the "prefs_dir" config variable. Try "o conf init prefs_dir" in the
944       CPAN shell to set and activate the distroprefs system.
945
946       Every YAML file may contain arbitrary documents according to the YAML
947       specification, and every document is treated as an entity that can
948       specify the treatment of a single distribution.
949
950       Filenames can be picked arbitrarily; "CPAN.pm" always reads all files
951       (in alphabetical order) and takes the key "match" (see below in
952       Language Specs) as a hashref containing match criteria that determine
953       if the current distribution matches the YAML document or not.
954
955   Fallback Data::Dumper and Storable
956       If neither your configured "yaml_module" nor YAML.pm is installed,
957       CPAN.pm falls back to using Data::Dumper and Storable and looks for
958       files with the extensions ".dd" or ".st" in the "prefs_dir" directory.
959       These files are expected to contain one or more hashrefs.  For
960       Data::Dumper generated files, this is expected to be done with by
961       defining $VAR1, $VAR2, etc. The YAML shell would produce these with the
962       command
963
964           ysh < somefile.yml > somefile.dd
965
966       For Storable files the rule is that they must be constructed such that
967       "Storable::retrieve(file)" returns an array reference and the array
968       elements represent one distropref object each. The conversion from YAML
969       would look like so:
970
971           perl -MYAML=LoadFile -MStorable=nstore -e '
972               @y=LoadFile(shift);
973               nstore(\@y, shift)' somefile.yml somefile.st
974
975       In bootstrapping situations it is usually sufficient to translate only
976       a few YAML files to Data::Dumper for crucial modules like "YAML::Syck",
977       "YAML.pm" and "Expect.pm". If you prefer Storable over Data::Dumper,
978       remember to pull out a Storable version that writes an older format
979       than all the other Storable versions that will need to read them.
980
981   Blueprint
982       The following example contains all supported keywords and structures
983       with the exception of "eexpect" which can be used instead of "expect".
984
985         ---
986         comment: "Demo"
987         match:
988           module: "Dancing::Queen"
989           distribution: "^CHACHACHA/Dancing-"
990           not_distribution: "\.zip$"
991           perl: "/usr/local/cariba-perl/bin/perl"
992           perlconfig:
993             archname: "freebsd"
994             not_cc: "gcc"
995           env:
996             DANCING_FLOOR: "Shubiduh"
997         disabled: 1
998         cpanconfig:
999           make: gmake
1000         pl:
1001           args:
1002             - "--somearg=specialcase"
1003
1004           env: {}
1005
1006           expect:
1007             - "Which is your favorite fruit"
1008             - "apple\n"
1009
1010         make:
1011           args:
1012             - all
1013             - extra-all
1014
1015           env: {}
1016
1017           expect: []
1018
1019           commandline: "echo SKIPPING make"
1020
1021         test:
1022           args: []
1023
1024           env: {}
1025
1026           expect: []
1027
1028         install:
1029           args: []
1030
1031           env:
1032             WANT_TO_INSTALL: YES
1033
1034           expect:
1035             - "Do you really want to install"
1036             - "y\n"
1037
1038         patches:
1039           - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
1040
1041         depends:
1042           configure_requires:
1043             LWP: 5.8
1044           build_requires:
1045             Test::Exception: 0.25
1046           requires:
1047             Spiffy: 0.30
1048
1049   Language Specs
1050       Every YAML document represents a single hash reference. The valid keys
1051       in this hash are as follows:
1052
1053       comment [scalar]
1054           A comment
1055
1056       cpanconfig [hash]
1057           Temporarily override assorted "CPAN.pm" configuration variables.
1058
1059           Supported are: "build_requires_install_policy", "check_sigs",
1060           "make", "make_install_make_command", "prefer_installer",
1061           "test_report". Please report as a bug when you need another one
1062           supported.
1063
1064       depends [hash] *** EXPERIMENTAL FEATURE ***
1065           All three types, namely "configure_requires", "build_requires", and
1066           "requires" are supported in the way specified in the META.yml
1067           specification. The current implementation merges the specified
1068           dependencies with those declared by the package maintainer. In a
1069           future implementation this may be changed to override the original
1070           declaration.
1071
1072       disabled [boolean]
1073           Specifies that this distribution shall not be processed at all.
1074
1075       features [array] *** EXPERIMENTAL FEATURE ***
1076           Experimental implementation to deal with optional_features from
1077           META.yml. Still needs coordination with installer software and
1078           currently works only for META.yml declaring "dynamic_config=0". Use
1079           with caution.
1080
1081       goto [string]
1082           The canonical name of a delegate distribution to install instead.
1083           Useful when a new version, although it tests OK itself, breaks
1084           something else or a developer release or a fork is already uploaded
1085           that is better than the last released version.
1086
1087       install [hash]
1088           Processing instructions for the "make install" or "./Build install"
1089           phase of the CPAN mantra. See below under Processing Instructions.
1090
1091       make [hash]
1092           Processing instructions for the "make" or "./Build" phase of the
1093           CPAN mantra. See below under Processing Instructions.
1094
1095       match [hash]
1096           A hashref with one or more of the keys "distribution", "module",
1097           "perl", "perlconfig", and "env" that specify whether a document is
1098           targeted at a specific CPAN distribution or installation.  Keys
1099           prefixed with "not_" negates the corresponding match.
1100
1101           The corresponding values are interpreted as regular expressions.
1102           The "distribution" related one will be matched against the
1103           canonical distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
1104
1105           The "module" related one will be matched against all modules
1106           contained in the distribution until one module matches.
1107
1108           The "perl" related one will be matched against $^X (but with the
1109           absolute path).
1110
1111           The value associated with "perlconfig" is itself a hashref that is
1112           matched against corresponding values in the %Config::Config hash
1113           living in the "Config.pm" module.  Keys prefixed with "not_"
1114           negates the corresponding match.
1115
1116           The value associated with "env" is itself a hashref that is matched
1117           against corresponding values in the %ENV hash.  Keys prefixed with
1118           "not_" negates the corresponding match.
1119
1120           If more than one restriction of "module", "distribution", etc. is
1121           specified, the results of the separately computed match values must
1122           all match. If so, the hashref represented by the YAML document is
1123           returned as the preference structure for the current distribution.
1124
1125       patches [array]
1126           An array of patches on CPAN or on the local disk to be applied in
1127           order via an external patch program. If the value for the "-p"
1128           parameter is 0 or 1 is determined by reading the patch beforehand.
1129           The path to each patch is either an absolute path on the local
1130           filesystem or relative to a patch directory specified in the
1131           "patches_dir" configuration variable or in the format of a
1132           canonical distro name. For examples please consult the distroprefs/
1133           directory in the CPAN.pm distribution (these examples are not
1134           installed by default).
1135
1136           Note: if the "applypatch" program is installed and "CPAN::Config"
1137           knows about it and a patch is written by the "makepatch" program,
1138           then "CPAN.pm" lets "applypatch" apply the patch. Both "makepatch"
1139           and "applypatch" are available from CPAN in the "JV/makepatch-*"
1140           distribution.
1141
1142       pl [hash]
1143           Processing instructions for the "perl Makefile.PL" or "perl
1144           Build.PL" phase of the CPAN mantra. See below under Processing
1145           Instructions.
1146
1147       test [hash]
1148           Processing instructions for the "make test" or "./Build test" phase
1149           of the CPAN mantra. See below under Processing Instructions.
1150
1151   Processing Instructions
1152       args [array]
1153           Arguments to be added to the command line
1154
1155       commandline
1156           A full commandline to run via "system()".  During execution, the
1157           environment variable PERL is set to $^X (but with an absolute
1158           path). If "commandline" is specified, "args" is not used.
1159
1160       eexpect [hash]
1161           Extended "expect". This is a hash reference with four allowed keys,
1162           "mode", "timeout", "reuse", and "talk".
1163
1164           You must install the "Expect" module to use "eexpect". CPAN.pm does
1165           not install it for you.
1166
1167           "mode" may have the values "deterministic" for the case where all
1168           questions come in the order written down and "anyorder" for the
1169           case where the questions may come in any order. The default mode is
1170           "deterministic".
1171
1172           "timeout" denotes a timeout in seconds. Floating-point timeouts are
1173           OK. With "mode=deterministic", the timeout denotes the timeout per
1174           question; with "mode=anyorder" it denotes the timeout per byte
1175           received from the stream or questions.
1176
1177           "talk" is a reference to an array that contains alternating
1178           questions and answers. Questions are regular expressions and
1179           answers are literal strings. The Expect module watches the stream
1180           from the execution of the external program ("perl Makefile.PL",
1181           "perl Build.PL", "make", etc.).
1182
1183           For "mode=deterministic", the CPAN.pm injects the corresponding
1184           answer as soon as the stream matches the regular expression.
1185
1186           For "mode=anyorder" CPAN.pm answers a question as soon as the
1187           timeout is reached for the next byte in the input stream. In this
1188           mode you can use the "reuse" parameter to decide what will happen
1189           with a question-answer pair after it has been used. In the default
1190           case (reuse=0) it is removed from the array, avoiding being used
1191           again accidentally. If you want to answer the question "Do you
1192           really want to do that" several times, then it must be included in
1193           the array at least as often as you want this answer to be given.
1194           Setting the parameter "reuse" to 1 makes this repetition
1195           unnecessary.
1196
1197       env [hash]
1198           Environment variables to be set during the command
1199
1200       expect [array]
1201           You must install the "Expect" module to use "expect". CPAN.pm does
1202           not install it for you.
1203
1204           "expect: <array>" is a short notation for this "eexpect":
1205
1206                   eexpect:
1207                           mode: deterministic
1208                           timeout: 15
1209                           talk: <array>
1210
1211   Schema verification with "Kwalify"
1212       If you have the "Kwalify" module installed (which is part of the
1213       Bundle::CPANxxl), then all your distroprefs files are checked for
1214       syntactic correctness.
1215
1216   Example Distroprefs Files
1217       "CPAN.pm" comes with a collection of example YAML files. Note that
1218       these are really just examples and should not be used without care
1219       because they cannot fit everybody's purpose. After all, the authors of
1220       the packages that ask questions had a need to ask, so you should watch
1221       their questions and adjust the examples to your environment and your
1222       needs. You have been warned:-)
1223

PROGRAMMER'S INTERFACE

1225       If you do not enter the shell, shell commands are available both as
1226       methods ("CPAN::Shell->install(...)") and as functions in the calling
1227       package ("install(...)").  Before calling low-level commands, it makes
1228       sense to initialize components of CPAN you need, e.g.:
1229
1230         CPAN::HandleConfig->load;
1231         CPAN::Shell::setup_output;
1232         CPAN::Index->reload;
1233
1234       High-level commands do such initializations automatically.
1235
1236       There's currently only one class that has a stable interface -
1237       CPAN::Shell. All commands that are available in the CPAN shell are
1238       methods of the class CPAN::Shell. The arguments on the commandline are
1239       passed as arguments to the method.
1240
1241       So if you take for example the shell command
1242
1243         notest install A B C
1244
1245       the actually executed command is
1246
1247         CPAN::Shell->notest("install","A","B","C");
1248
1249       Each of the commands that produce listings of modules ("r",
1250       "autobundle", "u") also return a list of the IDs of all modules within
1251       the list.
1252
1253       expand($type,@things)
1254         The IDs of all objects available within a program are strings that
1255         can be expanded to the corresponding real objects with the
1256         "CPAN::Shell->expand("Module",@things)" method. Expand returns a list
1257         of CPAN::Module objects according to the @things arguments given. In
1258         scalar context, it returns only the first element of the list.
1259
1260       expandany(@things)
1261         Like expand, but returns objects of the appropriate type, i.e.
1262         CPAN::Bundle objects for bundles, CPAN::Module objects for modules,
1263         and CPAN::Distribution objects for distributions. Note: it does not
1264         expand to CPAN::Author objects.
1265
1266       Programming Examples
1267         This enables the programmer to do operations that combine
1268         functionalities that are available in the shell.
1269
1270             # install everything that is outdated on my disk:
1271             perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
1272
1273             # install my favorite programs if necessary:
1274             for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
1275                 CPAN::Shell->install($mod);
1276             }
1277
1278             # list all modules on my disk that have no VERSION number
1279             for $mod (CPAN::Shell->expand("Module","/./")) {
1280                 next unless $mod->inst_file;
1281                 # MakeMaker convention for undefined $VERSION:
1282                 next unless $mod->inst_version eq "undef";
1283                 print "No VERSION in ", $mod->id, "\n";
1284             }
1285
1286             # find out which distribution on CPAN contains a module:
1287             print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
1288
1289         Or if you want to schedule a cron job to watch CPAN, you could list
1290         all modules that need updating. First a quick and dirty way:
1291
1292             perl -e 'use CPAN; CPAN::Shell->r;'
1293
1294         If you don't want any output should all modules be up to date, parse
1295         the output of above command for the regular expression "/modules are
1296         up to date/" and decide to mail the output only if it doesn't match.
1297
1298         If you prefer to do it more in a programmerish style in one single
1299         process, something like this may better suit you:
1300
1301           # list all modules on my disk that have newer versions on CPAN
1302           for $mod (CPAN::Shell->expand("Module","/./")) {
1303             next unless $mod->inst_file;
1304             next if $mod->uptodate;
1305             printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
1306                 $mod->id, $mod->inst_version, $mod->cpan_version;
1307           }
1308
1309         If that gives too much output every day, you may want to watch only
1310         for three modules. You can write
1311
1312           for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {
1313
1314         as the first line instead. Or you can combine some of the above
1315         tricks:
1316
1317           # watch only for a new mod_perl module
1318           $mod = CPAN::Shell->expand("Module","mod_perl");
1319           exit if $mod->uptodate;
1320           # new mod_perl arrived, let me know all update recommendations
1321           CPAN::Shell->r;
1322
1323   Methods in the other Classes
1324       CPAN::Author::as_glimpse()
1325           Returns a one-line description of the author
1326
1327       CPAN::Author::as_string()
1328           Returns a multi-line description of the author
1329
1330       CPAN::Author::email()
1331           Returns the author's email address
1332
1333       CPAN::Author::fullname()
1334           Returns the author's name
1335
1336       CPAN::Author::name()
1337           An alias for fullname
1338
1339       CPAN::Bundle::as_glimpse()
1340           Returns a one-line description of the bundle
1341
1342       CPAN::Bundle::as_string()
1343           Returns a multi-line description of the bundle
1344
1345       CPAN::Bundle::clean()
1346           Recursively runs the "clean" method on all items contained in the
1347           bundle.
1348
1349       CPAN::Bundle::contains()
1350           Returns a list of objects' IDs contained in a bundle. The
1351           associated objects may be bundles, modules or distributions.
1352
1353       CPAN::Bundle::force($method,@args)
1354           Forces CPAN to perform a task that it normally would have refused
1355           to do. Force takes as arguments a method name to be called and any
1356           number of additional arguments that should be passed to the called
1357           method.  The internals of the object get the needed changes so that
1358           CPAN.pm does not refuse to take the action. The "force" is passed
1359           recursively to all contained objects. See also the section above on
1360           the "force" and the "fforce" pragma.
1361
1362       CPAN::Bundle::get()
1363           Recursively runs the "get" method on all items contained in the
1364           bundle
1365
1366       CPAN::Bundle::inst_file()
1367           Returns the highest installed version of the bundle in either @INC
1368           or "$CPAN::Config->{cpan_home}". Note that this is different from
1369           CPAN::Module::inst_file.
1370
1371       CPAN::Bundle::inst_version()
1372           Like CPAN::Bundle::inst_file, but returns the $VERSION
1373
1374       CPAN::Bundle::uptodate()
1375           Returns 1 if the bundle itself and all its members are up-to-date.
1376
1377       CPAN::Bundle::install()
1378           Recursively runs the "install" method on all items contained in the
1379           bundle
1380
1381       CPAN::Bundle::make()
1382           Recursively runs the "make" method on all items contained in the
1383           bundle
1384
1385       CPAN::Bundle::readme()
1386           Recursively runs the "readme" method on all items contained in the
1387           bundle
1388
1389       CPAN::Bundle::test()
1390           Recursively runs the "test" method on all items contained in the
1391           bundle
1392
1393       CPAN::Distribution::as_glimpse()
1394           Returns a one-line description of the distribution
1395
1396       CPAN::Distribution::as_string()
1397           Returns a multi-line description of the distribution
1398
1399       CPAN::Distribution::author
1400           Returns the CPAN::Author object of the maintainer who uploaded this
1401           distribution
1402
1403       CPAN::Distribution::pretty_id()
1404           Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is
1405           the author's PAUSE ID and TARBALL is the distribution filename.
1406
1407       CPAN::Distribution::base_id()
1408           Returns the distribution filename without any archive suffix.  E.g
1409           "Foo-Bar-0.01"
1410
1411       CPAN::Distribution::clean()
1412           Changes to the directory where the distribution has been unpacked
1413           and runs "make clean" there.
1414
1415       CPAN::Distribution::containsmods()
1416           Returns a list of IDs of modules contained in a distribution file.
1417           Works only for distributions listed in the
1418           02packages.details.txt.gz file. This typically means that just most
1419           recent version of a distribution is covered.
1420
1421       CPAN::Distribution::cvs_import()
1422           Changes to the directory where the distribution has been unpacked
1423           and runs something like
1424
1425               cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
1426
1427           there.
1428
1429       CPAN::Distribution::dir()
1430           Returns the directory into which this distribution has been
1431           unpacked.
1432
1433       CPAN::Distribution::force($method,@args)
1434           Forces CPAN to perform a task that it normally would have refused
1435           to do. Force takes as arguments a method name to be called and any
1436           number of additional arguments that should be passed to the called
1437           method.  The internals of the object get the needed changes so that
1438           CPAN.pm does not refuse to take the action. See also the section
1439           above on the "force" and the "fforce" pragma.
1440
1441       CPAN::Distribution::get()
1442           Downloads the distribution from CPAN and unpacks it. Does nothing
1443           if the distribution has already been downloaded and unpacked within
1444           the current session.
1445
1446       CPAN::Distribution::install()
1447           Changes to the directory where the distribution has been unpacked
1448           and runs the external command "make install" there. If "make" has
1449           not yet been run, it will be run first. A "make test" is issued in
1450           any case and if this fails, the install is cancelled. The
1451           cancellation can be avoided by letting "force" run the "install"
1452           for you.
1453
1454           This install method only has the power to install the distribution
1455           if there are no dependencies in the way. To install an object along
1456           with all its dependencies, use CPAN::Shell->install.
1457
1458           Note that install() gives no meaningful return value. See
1459           uptodate().
1460
1461       CPAN::Distribution::isa_perl()
1462           Returns 1 if this distribution file seems to be a perl
1463           distribution.  Normally this is derived from the file name only,
1464           but the index from CPAN can contain a hint to achieve a return
1465           value of true for other filenames too.
1466
1467       CPAN::Distribution::look()
1468           Changes to the directory where the distribution has been unpacked
1469           and opens a subshell there. Exiting the subshell returns.
1470
1471       CPAN::Distribution::make()
1472           First runs the "get" method to make sure the distribution is
1473           downloaded and unpacked. Changes to the directory where the
1474           distribution has been unpacked and runs the external commands "perl
1475           Makefile.PL" or "perl Build.PL" and "make" there.
1476
1477       CPAN::Distribution::perldoc()
1478           Downloads the pod documentation of the file associated with a
1479           distribution (in HTML format) and runs it through the external
1480           command lynx specified in "$CPAN::Config->{lynx}". If lynx isn't
1481           available, it converts it to plain text with the external command
1482           html2text and runs it through the pager specified in
1483           "$CPAN::Config->{pager}".
1484
1485       CPAN::Distribution::prefs()
1486           Returns the hash reference from the first matching YAML file that
1487           the user has deposited in the "prefs_dir/" directory. The first
1488           succeeding match wins. The files in the "prefs_dir/" are processed
1489           alphabetically, and the canonical distro name (e.g.
1490           AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular
1491           expressions stored in the $root->{match}{distribution} attribute
1492           value.  Additionally all module names contained in a distribution
1493           are matched against the regular expressions in the
1494           $root->{match}{module} attribute value. The two match values are
1495           ANDed together. Each of the two attributes are optional.
1496
1497       CPAN::Distribution::prereq_pm()
1498           Returns the hash reference that has been announced by a
1499           distribution as the "requires" and "build_requires" elements. These
1500           can be declared either by the "META.yml" (if authoritative) or can
1501           be deposited after the run of "Build.PL" in the file
1502           "./_build/prereqs" or after the run of "Makfile.PL" written as the
1503           "PREREQ_PM" hash in a comment in the produced "Makefile". Note:
1504           this method only works after an attempt has been made to "make" the
1505           distribution. Returns undef otherwise.
1506
1507       CPAN::Distribution::readme()
1508           Downloads the README file associated with a distribution and runs
1509           it through the pager specified in "$CPAN::Config->{pager}".
1510
1511       CPAN::Distribution::reports()
1512           Downloads report data for this distribution from
1513           www.cpantesters.org and displays a subset of them.
1514
1515       CPAN::Distribution::read_yaml()
1516           Returns the content of the META.yml of this distro as a hashref.
1517           Note: works only after an attempt has been made to "make" the
1518           distribution.  Returns undef otherwise. Also returns undef if the
1519           content of META.yml is not authoritative. (The rules about what
1520           exactly makes the content authoritative are still in flux.)
1521
1522       CPAN::Distribution::test()
1523           Changes to the directory where the distribution has been unpacked
1524           and runs "make test" there.
1525
1526       CPAN::Distribution::uptodate()
1527           Returns 1 if all the modules contained in the distribution are up-
1528           to-date. Relies on containsmods.
1529
1530       CPAN::Index::force_reload()
1531           Forces a reload of all indices.
1532
1533       CPAN::Index::reload()
1534           Reloads all indices if they have not been read for more than
1535           "$CPAN::Config->{index_expire}" days.
1536
1537       CPAN::InfoObj::dump()
1538           CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
1539           inherit this method. It prints the data structure associated with
1540           an object. Useful for debugging. Note: the data structure is
1541           considered internal and thus subject to change without notice.
1542
1543       CPAN::Module::as_glimpse()
1544           Returns a one-line description of the module in four columns: The
1545           first column contains the word "Module", the second column consists
1546           of one character: an equals sign if this module is already
1547           installed and up-to-date, a less-than sign if this module is
1548           installed but can be upgraded, and a space if the module is not
1549           installed. The third column is the name of the module and the
1550           fourth column gives maintainer or distribution information.
1551
1552       CPAN::Module::as_string()
1553           Returns a multi-line description of the module
1554
1555       CPAN::Module::clean()
1556           Runs a clean on the distribution associated with this module.
1557
1558       CPAN::Module::cpan_file()
1559           Returns the filename on CPAN that is associated with the module.
1560
1561       CPAN::Module::cpan_version()
1562           Returns the latest version of this module available on CPAN.
1563
1564       CPAN::Module::cvs_import()
1565           Runs a cvs_import on the distribution associated with this module.
1566
1567       CPAN::Module::description()
1568           Returns a 44 character description of this module. Only available
1569           for modules listed in The Module List
1570           (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz)
1571
1572       CPAN::Module::distribution()
1573           Returns the CPAN::Distribution object that contains the current
1574           version of this module.
1575
1576       CPAN::Module::dslip_status()
1577           Returns a hash reference. The keys of the hash are the letters "D",
1578           "S", "L", "I", and <P>, for development status, support level,
1579           language, interface and public licence respectively. The data for
1580           the DSLIP status are collected by pause.perl.org when authors
1581           register their namespaces. The values of the 5 hash elements are
1582           one-character words whose meaning is described in the table below.
1583           There are also 5 hash elements "DV", "SV", "LV", "IV", and <PV>
1584           that carry a more verbose value of the 5 status variables.
1585
1586           Where the 'DSLIP' characters have the following meanings:
1587
1588             D - Development Stage  (Note: *NO IMPLIED TIMESCALES*):
1589               i   - Idea, listed to gain consensus or as a placeholder
1590               c   - under construction but pre-alpha (not yet released)
1591               a/b - Alpha/Beta testing
1592               R   - Released
1593               M   - Mature (no rigorous definition)
1594               S   - Standard, supplied with Perl 5
1595
1596             S - Support Level:
1597               m   - Mailing-list
1598               d   - Developer
1599               u   - Usenet newsgroup comp.lang.perl.modules
1600               n   - None known, try comp.lang.perl.modules
1601               a   - abandoned; volunteers welcome to take over maintenance
1602
1603             L - Language Used:
1604               p   - Perl-only, no compiler needed, should be platform independent
1605               c   - C and perl, a C compiler will be needed
1606               h   - Hybrid, written in perl with optional C code, no compiler needed
1607               +   - C++ and perl, a C++ compiler will be needed
1608               o   - perl and another language other than C or C++
1609
1610             I - Interface Style
1611               f   - plain Functions, no references used
1612               h   - hybrid, object and function interfaces available
1613               n   - no interface at all (huh?)
1614               r   - some use of unblessed References or ties
1615               O   - Object oriented using blessed references and/or inheritance
1616
1617             P - Public License
1618               p   - Standard-Perl: user may choose between GPL and Artistic
1619               g   - GPL: GNU General Public License
1620               l   - LGPL: "GNU Lesser General Public License" (previously known as
1621                     "GNU Library General Public License")
1622               b   - BSD: The BSD License
1623               a   - Artistic license alone
1624               2   - Artistic license 2.0 or later
1625               o   - open source: approved by www.opensource.org
1626               d   - allows distribution without restrictions
1627               r   - restricted distribution
1628               n   - no license at all
1629
1630       CPAN::Module::force($method,@args)
1631           Forces CPAN to perform a task it would normally refuse to do. Force
1632           takes as arguments a method name to be invoked and any number of
1633           additional arguments to pass that method.  The internals of the
1634           object get the needed changes so that CPAN.pm does not refuse to
1635           take the action. See also the section above on the "force" and the
1636           "fforce" pragma.
1637
1638       CPAN::Module::get()
1639           Runs a get on the distribution associated with this module.
1640
1641       CPAN::Module::inst_file()
1642           Returns the filename of the module found in @INC. The first file
1643           found is reported, just as perl itself stops searching @INC once it
1644           finds a module.
1645
1646       CPAN::Module::available_file()
1647           Returns the filename of the module found in PERL5LIB or @INC. The
1648           first file found is reported. The advantage of this method over
1649           "inst_file" is that modules that have been tested but not yet
1650           installed are included because PERL5LIB keeps track of tested
1651           modules.
1652
1653       CPAN::Module::inst_version()
1654           Returns the version number of the installed module in readable
1655           format.
1656
1657       CPAN::Module::available_version()
1658           Returns the version number of the available module in readable
1659           format.
1660
1661       CPAN::Module::install()
1662           Runs an "install" on the distribution associated with this module.
1663
1664       CPAN::Module::look()
1665           Changes to the directory where the distribution associated with
1666           this module has been unpacked and opens a subshell there. Exiting
1667           the subshell returns.
1668
1669       CPAN::Module::make()
1670           Runs a "make" on the distribution associated with this module.
1671
1672       CPAN::Module::manpage_headline()
1673           If module is installed, peeks into the module's manpage, reads the
1674           headline, and returns it. Moreover, if the module has been
1675           downloaded within this session, does the equivalent on the
1676           downloaded module even if it hasn't been installed yet.
1677
1678       CPAN::Module::perldoc()
1679           Runs a "perldoc" on this module.
1680
1681       CPAN::Module::readme()
1682           Runs a "readme" on the distribution associated with this module.
1683
1684       CPAN::Module::reports()
1685           Calls the reports() method on the associated distribution object.
1686
1687       CPAN::Module::test()
1688           Runs a "test" on the distribution associated with this module.
1689
1690       CPAN::Module::uptodate()
1691           Returns 1 if the module is installed and up-to-date.
1692
1693       CPAN::Module::userid()
1694           Returns the author's ID of the module.
1695
1696   Cache Manager
1697       Currently the cache manager only keeps track of the build directory
1698       ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
1699       deletes complete directories below "build_dir" as soon as the size of
1700       all directories there gets bigger than $CPAN::Config->{build_cache} (in
1701       MB). The contents of this cache may be used for later re-installations
1702       that you intend to do manually, but will never be trusted by CPAN
1703       itself. This is due to the fact that the user might use these
1704       directories for building modules on different architectures.
1705
1706       There is another directory ($CPAN::Config->{keep_source_where}) where
1707       the original distribution files are kept. This directory is not covered
1708       by the cache manager and must be controlled by the user. If you choose
1709       to have the same directory as build_dir and as keep_source_where
1710       directory, then your sources will be deleted with the same fifo
1711       mechanism.
1712
1713   Bundles
1714       A bundle is just a perl module in the namespace Bundle:: that does not
1715       define any functions or methods. It usually only contains
1716       documentation.
1717
1718       It starts like a perl module with a package declaration and a $VERSION
1719       variable. After that the pod section looks like any other pod with the
1720       only difference being that one special pod section exists starting with
1721       (verbatim):
1722
1723           =head1 CONTENTS
1724
1725       In this pod section each line obeys the format
1726
1727               Module_Name [Version_String] [- optional text]
1728
1729       The only required part is the first field, the name of a module (e.g.
1730       Foo::Bar, i.e. not the name of the distribution file). The rest of the
1731       line is optional. The comment part is delimited by a dash just as in
1732       the man page header.
1733
1734       The distribution of a bundle should follow the same convention as other
1735       distributions.
1736
1737       Bundles are treated specially in the CPAN package. If you say 'install
1738       Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
1739       the modules in the CONTENTS section of the pod. You can install your
1740       own Bundles locally by placing a conformant Bundle file somewhere into
1741       your @INC path. The autobundle() command which is available in the
1742       shell interface does that for you by including all currently installed
1743       modules in a snapshot bundle file.
1744

PREREQUISITES

1746       The CPAN program is trying to depend on as little as possible so the
1747       user can use it in hostile environment. It works better the more
1748       goodies the environment provides. For example if you try in the CPAN
1749       shell
1750
1751         install Bundle::CPAN
1752
1753       or
1754
1755         install Bundle::CPANxxl
1756
1757       you will find the shell more convenient than the bare shell before.
1758
1759       If you have a local mirror of CPAN and can access all files with
1760       "file:" URLs, then you only need a perl later than perl5.003 to run
1761       this module. Otherwise Net::FTP is strongly recommended. LWP may be
1762       required for non-UNIX systems, or if your nearest CPAN site is
1763       associated with a URL that is not "ftp:".
1764
1765       If you have neither Net::FTP nor LWP, there is a fallback mechanism
1766       implemented for an external ftp command or for an external lynx
1767       command.
1768

UTILITIES

1770   Finding packages and VERSION
1771       This module presumes that all packages on CPAN
1772
1773       • declare their $VERSION variable in an easy to parse manner. This
1774         prerequisite can hardly be relaxed because it consumes far too much
1775         memory to load all packages into the running program just to
1776         determine the $VERSION variable. Currently all programs that are
1777         dealing with version use something like this
1778
1779             perl -MExtUtils::MakeMaker -le \
1780                 'print MM->parse_version(shift)' filename
1781
1782         If you are author of a package and wonder if your $VERSION can be
1783         parsed, please try the above method.
1784
1785       • come as compressed or gzipped tarfiles or as zip files and contain a
1786         "Makefile.PL" or "Build.PL" (well, we try to handle a bit more, but
1787         with little enthusiasm).
1788
1789   Debugging
1790       Debugging this module is more than a bit complex due to interference
1791       from the software producing the indices on CPAN, the mirroring process
1792       on CPAN, packaging, configuration, synchronicity, and even (gasp!) due
1793       to bugs within the CPAN.pm module itself.
1794
1795       For debugging the code of CPAN.pm itself in interactive mode, some
1796       debugging aid can be turned on for most packages within CPAN.pm with
1797       one of
1798
1799       o debug package...
1800         sets debug mode for packages.
1801
1802       o debug -package...
1803         unsets debug mode for packages.
1804
1805       o debug all
1806         turns debugging on for all packages.
1807
1808       o debug number
1809
1810       which sets the debugging packages directly. Note that "o debug 0" turns
1811       debugging off.
1812
1813       What seems a successful strategy is the combination of "reload cpan"
1814       and the debugging switches. Add a new debug statement while running in
1815       the shell and then issue a "reload cpan" and see the new debugging
1816       messages immediately without losing the current context.
1817
1818       "o debug" without an argument lists the valid package names and the
1819       current set of packages in debugging mode. "o debug" has built-in
1820       completion support.
1821
1822       For debugging of CPAN data there is the "dump" command which takes the
1823       same arguments as make/test/install and outputs each object's
1824       Data::Dumper dump. If an argument looks like a perl variable and
1825       contains one of "$", "@" or "%", it is eval()ed and fed to Data::Dumper
1826       directly.
1827
1828   Floppy, Zip, Offline Mode
1829       CPAN.pm works nicely without network access, too. If you maintain
1830       machines that are not networked at all, you should consider working
1831       with "file:" URLs. You'll have to collect your modules somewhere first.
1832       So you might use CPAN.pm to put together all you need on a networked
1833       machine. Then copy the $CPAN::Config->{keep_source_where} (but not
1834       $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
1835       of a personal CPAN. CPAN.pm on the non-networked machines works nicely
1836       with this floppy. See also below the paragraph about CD-ROM support.
1837
1838   Basic Utilities for Programmers
1839       has_inst($module)
1840         Returns true if the module is installed. Used to load all modules
1841         into the running CPAN.pm that are considered optional. The config
1842         variable "dontload_list" intercepts the "has_inst()" call such that
1843         an optional module is not loaded despite being available. For
1844         example, the following command will prevent "YAML.pm" from being
1845         loaded:
1846
1847             cpan> o conf dontload_list push YAML
1848
1849         See the source for details.
1850
1851       use_inst($module)
1852         Similary to has_inst() tries to load optional library but also dies
1853         if library is not available
1854
1855       has_usable($module)
1856         Returns true if the module is installed and in a usable state. Only
1857         useful for a handful of modules that are used internally. See the
1858         source for details.
1859
1860       instance($module)
1861         The constructor for all the singletons used to represent modules,
1862         distributions, authors, and bundles. If the object already exists,
1863         this method returns the object; otherwise, it calls the constructor.
1864
1865       frontend()
1866       frontend($new_frontend)
1867         Getter/setter for frontend object. Method just allows to subclass
1868         CPAN.pm.
1869

SECURITY

1871       There's no strong security layer in CPAN.pm. CPAN.pm helps you to
1872       install foreign, unmasked, unsigned code on your machine. We compare to
1873       a checksum that comes from the net just as the distribution file
1874       itself. But we try to make it easy to add security on demand:
1875
1876   Cryptographically signed modules
1877       Since release 1.77, CPAN.pm has been able to verify cryptographically
1878       signed module distributions using Module::Signature.  The CPAN modules
1879       can be signed by their authors, thus giving more security.  The simple
1880       unsigned MD5 checksums that were used before by CPAN protect mainly
1881       against accidental file corruption.
1882
1883       You will need to have Module::Signature installed, which in turn
1884       requires that you have at least one of Crypt::OpenPGP module or the
1885       command-line gpg tool installed.
1886
1887       You will also need to be able to connect over the Internet to the
1888       public key servers, like pgp.mit.edu, and their port 11731 (the HKP
1889       protocol).
1890
1891       The configuration parameter check_sigs is there to turn signature
1892       checking on or off.
1893

EXPORT

1895       Most functions in package CPAN are exported by default. The reason for
1896       this is that the primary use is intended for the cpan shell or for one-
1897       liners.
1898

ENVIRONMENT

1900       When the CPAN shell enters a subshell via the look command, it sets the
1901       environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
1902       already set.
1903
1904       When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
1905       to the ID of the running process. It also sets
1906       PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
1907       happen with older versions of Module::Install.
1908
1909       When running "perl Makefile.PL", the environment variable
1910       "PERL5_CPAN_IS_EXECUTING" is set to the full path of the "Makefile.PL"
1911       that is being executed. This prevents runaway processes with newer
1912       versions of Module::Install.
1913
1914       When the config variable ftp_passive is set, all downloads will be run
1915       with the environment variable FTP_PASSIVE set to this value. This is in
1916       general a good idea as it influences both Net::FTP and LWP based
1917       connections. The same effect can be achieved by starting the cpan shell
1918       with this environment variable set. For Net::FTP alone, one can also
1919       always set passive mode by running libnetcfg.
1920

POPULATE AN INSTALLATION WITH LOTS OF MODULES

1922       Populating a freshly installed perl with one's favorite modules is
1923       pretty easy if you maintain a private bundle definition file. To get a
1924       useful blueprint of a bundle definition file, the command autobundle
1925       can be used on the CPAN shell command line. This command writes a
1926       bundle definition file for all modules installed for the current perl
1927       interpreter. It's recommended to run this command once only, and from
1928       then on maintain the file manually under a private name, say
1929       Bundle/my_bundle.pm. With a clever bundle file you can then simply say
1930
1931           cpan> install Bundle::my_bundle
1932
1933       then answer a few questions and go out for coffee (possibly even in a
1934       different city).
1935
1936       Maintaining a bundle definition file means keeping track of two things:
1937       dependencies and interactivity. CPAN.pm sometimes fails on calculating
1938       dependencies because not all modules define all MakeMaker attributes
1939       correctly, so a bundle definition file should specify prerequisites as
1940       early as possible. On the other hand, it's annoying that so many
1941       distributions need some interactive configuring. So what you can try to
1942       accomplish in your private bundle file is to have the packages that
1943       need to be configured early in the file and the gentle ones later, so
1944       you can go out for coffee after a few minutes and leave CPAN.pm to
1945       churn away unattended.
1946

WORKING WITH CPAN.pm BEHIND FIREWALLS

1948       Thanks to Graham Barr for contributing the following paragraphs about
1949       the interaction between perl, and various firewall configurations. For
1950       further information on firewalls, it is recommended to consult the
1951       documentation that comes with the ncftp program. If you are unable to
1952       go through the firewall with a simple Perl setup, it is likely that you
1953       can configure ncftp so that it works through your firewall.
1954
1955   Three basic types of firewalls
1956       Firewalls can be categorized into three basic types.
1957
1958       http firewall
1959           This is when the firewall machine runs a web server, and to access
1960           the outside world, you must do so via that web server. If you set
1961           environment variables like http_proxy or ftp_proxy to values
1962           beginning with http://, or in your web browser you've proxy
1963           information set, then you know you are running behind an http
1964           firewall.
1965
1966           To access servers outside these types of firewalls with perl (even
1967           for ftp), you need LWP or HTTP::Tiny.
1968
1969       ftp firewall
1970           This where the firewall machine runs an ftp server. This kind of
1971           firewall will only let you access ftp servers outside the firewall.
1972           This is usually done by connecting to the firewall with ftp, then
1973           entering a username like "user@outside.host.com".
1974
1975           To access servers outside these type of firewalls with perl, you
1976           need Net::FTP.
1977
1978       One-way visibility
1979           One-way visibility means these firewalls try to make themselves
1980           invisible to users inside the firewall. An FTP data connection is
1981           normally created by sending your IP address to the remote server
1982           and then listening for the return connection. But the remote server
1983           will not be able to connect to you because of the firewall. For
1984           these types of firewall, FTP connections need to be done in a
1985           passive mode.
1986
1987           There are two that I can think off.
1988
1989           SOCKS
1990               If you are using a SOCKS firewall, you will need to compile
1991               perl and link it with the SOCKS library.  This is what is
1992               normally called a 'socksified' perl. With this executable you
1993               will be able to connect to servers outside the firewall as if
1994               it were not there.
1995
1996           IP Masquerade
1997               This is when the firewall implemented in the kernel (via NAT,
1998               or networking address translation), it allows you to hide a
1999               complete network behind one IP address. With this firewall no
2000               special compiling is needed as you can access hosts directly.
2001
2002               For accessing ftp servers behind such firewalls you usually
2003               need to set the environment variable "FTP_PASSIVE" or the
2004               config variable ftp_passive to a true value.
2005
2006   Configuring lynx or ncftp for going through a firewall
2007       If you can go through your firewall with e.g. lynx, presumably with a
2008       command such as
2009
2010           /usr/local/bin/lynx -pscott:tiger
2011
2012       then you would configure CPAN.pm with the command
2013
2014           o conf lynx "/usr/local/bin/lynx -pscott:tiger"
2015
2016       That's all. Similarly for ncftp or ftp, you would configure something
2017       like
2018
2019           o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"
2020
2021       Your mileage may vary...
2022

FAQ

2024       1)  I installed a new version of module X but CPAN keeps saying, I have
2025           the old version installed
2026
2027           Probably you do have the old version installed. This can happen if
2028           a module installs itself into a different directory in the @INC
2029           path than it was previously installed. This is not really a CPAN.pm
2030           problem, you would have the same problem when installing the module
2031           manually. The easiest way to prevent this behaviour is to add the
2032           argument "UNINST=1" to the "make install" call, and that is why
2033           many people add this argument permanently by configuring
2034
2035             o conf make_install_arg UNINST=1
2036
2037       2)  So why is UNINST=1 not the default?
2038
2039           Because there are people who have their precise expectations about
2040           who may install where in the @INC path and who uses which @INC
2041           array. In fine tuned environments "UNINST=1" can cause damage.
2042
2043       3)  I want to clean up my mess, and install a new perl along with all
2044           modules I have. How do I go about it?
2045
2046           Run the autobundle command for your old perl and optionally rename
2047           the resulting bundle file (e.g. Bundle/mybundle.pm), install the
2048           new perl with the Configure option prefix, e.g.
2049
2050               ./Configure -Dprefix=/usr/local/perl-5.6.78.9
2051
2052           Install the bundle file you produced in the first step with
2053           something like
2054
2055               cpan> install Bundle::mybundle
2056
2057           and you're done.
2058
2059       4)  When I install bundles or multiple modules with one command there
2060           is too much output to keep track of.
2061
2062           You may want to configure something like
2063
2064             o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
2065             o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"
2066
2067           so that STDOUT is captured in a file for later inspection.
2068
2069       5)  I am not root, how can I install a module in a personal directory?
2070
2071           As of CPAN 1.9463, if you do not have permission to write the
2072           default perl library directories, CPAN's configuration process will
2073           ask you whether you want to bootstrap <local::lib>, which makes
2074           keeping a personal perl library directory easy.
2075
2076           Another thing you should bear in mind is that the UNINST parameter
2077           can be dangerous when you are installing into a private area
2078           because you might accidentally remove modules that other people
2079           depend on that are not using the private area.
2080
2081       6)  How to get a package, unwrap it, and make a change before building
2082           it?
2083
2084           Have a look at the "look" (!) command.
2085
2086       7)  I installed a Bundle and had a couple of fails. When I retried,
2087           everything resolved nicely. Can this be fixed to work on first try?
2088
2089           The reason for this is that CPAN does not know the dependencies of
2090           all modules when it starts out. To decide about the additional
2091           items to install, it just uses data found in the META.yml file or
2092           the generated Makefile. An undetected missing piece breaks the
2093           process. But it may well be that your Bundle installs some
2094           prerequisite later than some depending item and thus your second
2095           try is able to resolve everything.  Please note, CPAN.pm does not
2096           know the dependency tree in advance and cannot sort the queue of
2097           things to install in a topologically correct order. It resolves
2098           perfectly well if all modules declare the prerequisites correctly
2099           with the PREREQ_PM attribute to MakeMaker or the "requires" stanza
2100           of Module::Build. For bundles which fail and you need to install
2101           often, it is recommended to sort the Bundle definition file
2102           manually.
2103
2104       8)  In our intranet, we have many modules for internal use. How can I
2105           integrate these modules with CPAN.pm but without uploading the
2106           modules to CPAN?
2107
2108           Have a look at the CPAN::Site module.
2109
2110       9)  When I run CPAN's shell, I get an error message about things in my
2111           "/etc/inputrc" (or "~/.inputrc") file.
2112
2113           These are readline issues and can only be fixed by studying
2114           readline configuration on your architecture and adjusting the
2115           referenced file accordingly. Please make a backup of the
2116           "/etc/inputrc" or "~/.inputrc" and edit them. Quite often harmless
2117           changes like uppercasing or lowercasing some arguments solves the
2118           problem.
2119
2120       10) Some authors have strange characters in their names.
2121
2122           Internally CPAN.pm uses the UTF-8 charset. If your terminal is
2123           expecting ISO-8859-1 charset, a converter can be activated by
2124           setting term_is_latin to a true value in your config file. One way
2125           of doing so would be
2126
2127               cpan> o conf term_is_latin 1
2128
2129           If other charset support is needed, please file a bug report
2130           against CPAN.pm at rt.cpan.org and describe your needs. Maybe we
2131           can extend the support or maybe UTF-8 terminals become widely
2132           available.
2133
2134           Note: this config variable is deprecated and will be removed in a
2135           future version of CPAN.pm. It will be replaced with the conventions
2136           around the family of $LANG and $LC_* environment variables.
2137
2138       11) When an install fails for some reason and then I correct the error
2139           condition and retry, CPAN.pm refuses to install the module, saying
2140           "Already tried without success".
2141
2142           Use the force pragma like so
2143
2144             force install Foo::Bar
2145
2146           Or you can use
2147
2148             look Foo::Bar
2149
2150           and then "make install" directly in the subshell.
2151
2152       12) How do I install a "DEVELOPER RELEASE" of a module?
2153
2154           By default, CPAN will install the latest non-developer release of a
2155           module. If you want to install a dev release, you have to specify
2156           the partial path starting with the author id to the tarball you
2157           wish to install, like so:
2158
2159               cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
2160
2161           Note that you can use the "ls" command to get this path listed.
2162
2163       13) How do I install a module and all its dependencies from the
2164           commandline, without being prompted for anything, despite my CPAN
2165           configuration (or lack thereof)?
2166
2167           CPAN uses ExtUtils::MakeMaker's prompt() function to ask its
2168           questions, so if you set the PERL_MM_USE_DEFAULT environment
2169           variable, you shouldn't be asked any questions at all (assuming the
2170           modules you are installing are nice about obeying that variable as
2171           well):
2172
2173               % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'
2174
2175       14) How do I create a Module::Build based Build.PL derived from an
2176           ExtUtils::MakeMaker focused Makefile.PL?
2177
2178           http://search.cpan.org/dist/Module-Build-Convert/
2179
2180       15) I'm frequently irritated with the CPAN shell's inability to help me
2181           select a good mirror.
2182
2183           CPAN can now help you select a "good" mirror, based on which ones
2184           have the lowest 'ping' round-trip times.  From the shell, use the
2185           command 'o conf init urllist' and allow CPAN to automatically
2186           select mirrors for you.
2187
2188           Beyond that help, the urllist config parameter is yours. You can
2189           add and remove sites at will. You should find out which sites have
2190           the best up-to-dateness, bandwidth, reliability, etc. and are
2191           topologically close to you. Some people prefer fast downloads,
2192           others up-to-dateness, others reliability.  You decide which to try
2193           in which order.
2194
2195           Henk P. Penning maintains a site that collects data about CPAN
2196           sites:
2197
2198             http://mirrors.cpan.org/
2199
2200           Also, feel free to play with experimental features. Run
2201
2202             o conf init randomize_urllist ftpstats_period ftpstats_size
2203
2204           and choose your favorite parameters. After a few downloads running
2205           the "hosts" command will probably assist you in choosing the best
2206           mirror sites.
2207
2208       16) Why do I get asked the same questions every time I start the shell?
2209
2210           You can make your configuration changes permanent by calling the
2211           command "o conf commit". Alternatively set the "auto_commit"
2212           variable to true by running "o conf init auto_commit" and answering
2213           the following question with yes.
2214
2215       17) Older versions of CPAN.pm had the original root directory of all
2216           tarballs in the build directory. Now there are always random
2217           characters appended to these directory names. Why was this done?
2218
2219           The random characters are provided by File::Temp and ensure that
2220           each module's individual build directory is unique. This makes
2221           running CPAN.pm in concurrent processes simultaneously safe.
2222
2223       18) Speaking of the build directory. Do I have to clean it up myself?
2224
2225           You have the choice to set the config variable "scan_cache" to
2226           "never". Then you must clean it up yourself. The other possible
2227           values, "atstart" and "atexit" clean up the build directory when
2228           you start (or more precisely, after the first extraction into the
2229           build directory) or exit the CPAN shell, respectively. If you never
2230           start up the CPAN shell, you probably also have to clean up the
2231           build directory yourself.
2232
2233       19) How can I switch to sudo instead of local::lib?
2234
2235           The following 5 environment veriables need to be reset to the
2236           previous values: PATH, PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MB_OPT,
2237           PERL_MM_OPT; and these two CPAN.pm config variables must be
2238           reconfigured: make_install_make_command and
2239           mbuild_install_build_command. The five env variables have probably
2240           been overwritten in your $HOME/.bashrc or some equivalent. You
2241           either find them there and delete their traces and logout/login or
2242           you override them temporarily, depending on your exact desire. The
2243           two cpanpm config variables can be set with:
2244
2245             o conf init /install_.*_command/
2246
2247           probably followed by
2248
2249             o conf commit
2250

COMPATIBILITY

2252   OLD PERL VERSIONS
2253       CPAN.pm is regularly tested to run under 5.005 and assorted newer
2254       versions. It is getting more and more difficult to get the minimal
2255       prerequisites working on older perls. It is close to impossible to get
2256       the whole Bundle::CPAN working there. If you're in the position to have
2257       only these old versions, be advised that CPAN is designed to work fine
2258       without the Bundle::CPAN installed.
2259
2260       To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
2261       compatible with ancient perls and that File::Temp is listed as a
2262       prerequisite but CPAN has reasonable workarounds if it is missing.
2263
2264   CPANPLUS
2265       This module and its competitor, the CPANPLUS module, are both much
2266       cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
2267       more modular, but it was never intended to be compatible with CPAN.pm.
2268
2269   CPANMINUS
2270       In the year 2010 App::cpanminus was launched as a new approach to a
2271       cpan shell with a considerably smaller footprint. Very cool stuff.
2272

SECURITY ADVICE

2274       This software enables you to upgrade software on your computer and so
2275       is inherently dangerous because the newly installed software may
2276       contain bugs and may alter the way your computer works or even make it
2277       unusable. Please consider backing up your data before every upgrade.
2278

BUGS

2280       Please report bugs via <http://rt.cpan.org/>
2281
2282       Before submitting a bug, please make sure that the traditional method
2283       of building a Perl module package from a shell by following the
2284       installation instructions of that package still works in your
2285       environment.
2286

AUTHOR

2288       Andreas Koenig "<andk@cpan.org>"
2289

LICENSE

2291       This program is free software; you can redistribute it and/or modify it
2292       under the same terms as Perl itself.
2293
2294       See <http://www.perl.com/perl/misc/Artistic.html>
2295

TRANSLATIONS

2297       Kawai,Takanori provides a Japanese translation of a very old version of
2298       this manpage at
2299       <http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
2300

SEE ALSO

2302       Many people enter the CPAN shell by running the cpan utility program
2303       which is installed in the same directory as perl itself. So if you have
2304       this directory in your PATH variable (or some equivalent in your
2305       operating system) then typing "cpan" in a console window will work for
2306       you as well. Above that the utility provides several commandline
2307       shortcuts.
2308
2309       melezhik (Alexey) sent me a link where he published a chef recipe to
2310       work with CPAN.pm: http://community.opscode.com/cookbooks/cpan.
2311
2312
2313
2314perl v5.34.1                      2022-04-20                           CPAN(3)
Impressum