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         randomize_urllist  add some randomness to the sequence of the urllist
719         recommends_policy  whether recommended prerequisites should be included
720         scan_cache         controls scanning of cache ('atstart', 'atexit' or 'never')
721         shell              your favorite shell
722         show_unparsable_versions
723                            boolean if r command tells which modules are versionless
724         show_upload_date   boolean if commands should try to determine upload date
725         show_zero_versions boolean if r command tells for which modules $version==0
726         suggests_policy    whether suggested prerequisites should be included
727         tar                location of external program tar
728         tar_verbosity      verbosity level for the tar command
729         term_is_latin      deprecated: if true Unicode is translated to ISO-8859-1
730                            (and nonsense for characters outside latin range)
731         term_ornaments     boolean to turn ReadLine ornamenting on/off
732         test_report        email test reports (if CPAN::Reporter is installed)
733         trust_test_report_history
734                            skip testing when previously tested ok (according to
735                            CPAN::Reporter history)
736         unzip              location of external program unzip
737         urllist            arrayref to nearby CPAN sites (or equivalent locations)
738         urllist_ping_external
739                            use external ping command when autoselecting mirrors
740         urllist_ping_verbose
741                            increase verbosity when autoselecting mirrors
742         use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
743         use_sqlite         use CPAN::SQLite for metadata storage (fast and lean)
744         username           your username if you CPAN server wants one
745         version_timeout    stops version parsing after this many seconds.
746                            Default is 15 secs. Set to 0 to disable.
747         wait_list          arrayref to a wait server to try (See CPAN::WAIT)
748         wget               path to external prg
749         yaml_load_code     enable YAML code deserialisation via CPAN::DeferredCode
750         yaml_module        which module to use to read/write YAML files
751
752       You can set and query each of these options interactively in the cpan
753       shell with the "o conf" or the "o conf init" command as specified
754       below.
755
756       "o conf <scalar option>"
757         prints the current value of the scalar option
758
759       "o conf <scalar option> <value>"
760         Sets the value of the scalar option to value
761
762       "o conf <list option>"
763         prints the current value of the list option in MakeMaker's neatvalue
764         format.
765
766       "o conf <list option> [shift|pop]"
767         shifts or pops the array in the list option variable
768
769       "o conf <list option> [unshift|push|splice] <list>"
770         works like the corresponding perl commands.
771
772       interactive editing: o conf init [MATCH|LIST]
773         Runs an interactive configuration dialog for matching variables.
774         Without argument runs the dialog over all supported config variables.
775         To specify a MATCH the argument must be enclosed by slashes.
776
777         Examples:
778
779           o conf init ftp_passive ftp_proxy
780           o conf init /color/
781
782         Note: this method of setting config variables often provides more
783         explanation about the functioning of a variable than the manpage.
784
785   CPAN::anycwd($path): Note on config variable getcwd
786       CPAN.pm changes the current working directory often and needs to
787       determine its own current working directory. By default it uses
788       Cwd::cwd, but if for some reason this doesn't work on your system,
789       configure alternatives according to the following table:
790
791       cwd Calls Cwd::cwd
792
793       getcwd
794           Calls Cwd::getcwd
795
796       fastcwd
797           Calls Cwd::fastcwd
798
799       getdcwd
800           Calls Cwd::getdcwd
801
802       backtickcwd
803           Calls the external command cwd.
804
805   Note on the format of the urllist parameter
806       urllist parameters are URLs according to RFC 1738. We do a little
807       guessing if your URL is not compliant, but if you have problems with
808       "file" URLs, please try the correct format. Either:
809
810           file://localhost/whatever/ftp/pub/CPAN/
811
812       or
813
814           file:///home/ftp/pub/CPAN/
815
816   The urllist parameter has CD-ROM support
817       The "urllist" parameter of the configuration table contains a list of
818       URLs used for downloading. If the list contains any "file" URLs, CPAN
819       always tries there first. This feature is disabled for index files. So
820       the recommendation for the owner of a CD-ROM with CPAN contents is:
821       include your local, possibly outdated CD-ROM as a "file" URL at the end
822       of urllist, e.g.
823
824         o conf urllist push file://localhost/CDROM/CPAN
825
826       CPAN.pm will then fetch the index files from one of the CPAN sites that
827       come at the beginning of urllist. It will later check for each module
828       to see whether there is a local copy of the most recent version.
829
830       Another peculiarity of urllist is that the site that we could
831       successfully fetch the last file from automatically gets a preference
832       token and is tried as the first site for the next request. So if you
833       add a new site at runtime it may happen that the previously preferred
834       site will be tried another time. This means that if you want to
835       disallow a site for the next transfer, it must be explicitly removed
836       from urllist.
837
838   Maintaining the urllist parameter
839       If you have YAML.pm (or some other YAML module configured in
840       "yaml_module") installed, CPAN.pm collects a few statistical data about
841       recent downloads. You can view the statistics with the "hosts" command
842       or inspect them directly by looking into the "FTPstats.yml" file in
843       your "cpan_home" directory.
844
845       To get some interesting statistics, it is recommended that
846       "randomize_urllist" be set; this introduces some amount of randomness
847       into the URL selection.
848
849   The "requires" and "build_requires" dependency declarations
850       Since CPAN.pm version 1.88_51 modules declared as "build_requires" by a
851       distribution are treated differently depending on the config variable
852       "build_requires_install_policy". By setting
853       "build_requires_install_policy" to "no", such a module is not
854       installed. It is only built and tested, and then kept in the list of
855       tested but uninstalled modules. As such, it is available during the
856       build of the dependent module by integrating the path to the
857       "blib/arch" and "blib/lib" directories in the environment variable
858       PERL5LIB. If "build_requires_install_policy" is set to "yes", then both
859       modules declared as "requires" and those declared as "build_requires"
860       are treated alike. By setting to "ask/yes" or "ask/no", CPAN.pm asks
861       the user and sets the default accordingly.
862
863   Configuration of the allow_installing_* parameters
864       The "allow_installing_*" parameters are evaluated during the "make"
865       phase. If set to "yes", they allow the testing and the installation of
866       the current distro and otherwise have no effect. If set to "no", they
867       may abort the build (preventing testing and installing), depending on
868       the contents of the "blib/" directory. The "blib/" directory is the
869       directory that holds all the files that would usually be installed in
870       the "install" phase.
871
872       "allow_installing_outdated_dists" compares the "blib/" directory with
873       the CPAN index.  If it finds something there that belongs, according to
874       the index, to a different dist, it aborts the current build.
875
876       "allow_installing_module_downgrades" compares the "blib/" directory
877       with already installed modules, actually their version numbers, as
878       determined by ExtUtils::MakeMaker or equivalent. If a to-be-installed
879       module would downgrade an already installed module, the current build
880       is aborted.
881
882       An interesting twist occurs when a distroprefs document demands the
883       installation of an outdated dist via goto while
884       "allow_installing_outdated_dists" forbids it. Without additional
885       provisions, this would let the "allow_installing_outdated_dists" win
886       and the distroprefs lose. So the proper arrangement in such a case is
887       to write a second distroprefs document for the distro that "goto"
888       points to and overrule the "cpanconfig" there. E.g.:
889
890         ---
891         match:
892           distribution: "^MAUKE/Keyword-Simple-0.04.tar.gz"
893         goto: "MAUKE/Keyword-Simple-0.03.tar.gz"
894         ---
895         match:
896           distribution: "^MAUKE/Keyword-Simple-0.03.tar.gz"
897         cpanconfig:
898           allow_installing_outdated_dists: yes
899
900   Configuration for individual distributions (Distroprefs)
901       (Note: This feature has been introduced in CPAN.pm 1.8854)
902
903       Distributions on CPAN usually behave according to what we call the CPAN
904       mantra. Or since the advent of Module::Build we should talk about two
905       mantras:
906
907           perl Makefile.PL     perl Build.PL
908           make                 ./Build
909           make test            ./Build test
910           make install         ./Build install
911
912       But some modules cannot be built with this mantra. They try to get some
913       extra data from the user via the environment, extra arguments, or
914       interactively--thus disturbing the installation of large bundles like
915       Phalanx100 or modules with many dependencies like Plagger.
916
917       The distroprefs system of "CPAN.pm" addresses this problem by allowing
918       the user to specify extra informations and recipes in YAML files to
919       either
920
921       •   pass additional arguments to one of the four commands,
922
923       •   set environment variables
924
925       •   instantiate an Expect object that reads from the console, waits for
926           some regular expressions and enters some answers
927
928       •   temporarily override assorted "CPAN.pm" configuration variables
929
930       •   specify dependencies the original maintainer forgot
931
932       •   disable the installation of an object altogether
933
934       See the YAML and Data::Dumper files that come with the "CPAN.pm"
935       distribution in the "distroprefs/" directory for examples.
936
937   Filenames
938       The YAML files themselves must have the ".yml" extension; all other
939       files are ignored (for two exceptions see Fallback Data::Dumper and
940       Storable below). The containing directory can be specified in "CPAN.pm"
941       in the "prefs_dir" config variable. Try "o conf init prefs_dir" in the
942       CPAN shell to set and activate the distroprefs system.
943
944       Every YAML file may contain arbitrary documents according to the YAML
945       specification, and every document is treated as an entity that can
946       specify the treatment of a single distribution.
947
948       Filenames can be picked arbitrarily; "CPAN.pm" always reads all files
949       (in alphabetical order) and takes the key "match" (see below in
950       Language Specs) as a hashref containing match criteria that determine
951       if the current distribution matches the YAML document or not.
952
953   Fallback Data::Dumper and Storable
954       If neither your configured "yaml_module" nor YAML.pm is installed,
955       CPAN.pm falls back to using Data::Dumper and Storable and looks for
956       files with the extensions ".dd" or ".st" in the "prefs_dir" directory.
957       These files are expected to contain one or more hashrefs.  For
958       Data::Dumper generated files, this is expected to be done with by
959       defining $VAR1, $VAR2, etc. The YAML shell would produce these with the
960       command
961
962           ysh < somefile.yml > somefile.dd
963
964       For Storable files the rule is that they must be constructed such that
965       "Storable::retrieve(file)" returns an array reference and the array
966       elements represent one distropref object each. The conversion from YAML
967       would look like so:
968
969           perl -MYAML=LoadFile -MStorable=nstore -e '
970               @y=LoadFile(shift);
971               nstore(\@y, shift)' somefile.yml somefile.st
972
973       In bootstrapping situations it is usually sufficient to translate only
974       a few YAML files to Data::Dumper for crucial modules like "YAML::Syck",
975       "YAML.pm" and "Expect.pm". If you prefer Storable over Data::Dumper,
976       remember to pull out a Storable version that writes an older format
977       than all the other Storable versions that will need to read them.
978
979   Blueprint
980       The following example contains all supported keywords and structures
981       with the exception of "eexpect" which can be used instead of "expect".
982
983         ---
984         comment: "Demo"
985         match:
986           module: "Dancing::Queen"
987           distribution: "^CHACHACHA/Dancing-"
988           not_distribution: "\.zip$"
989           perl: "/usr/local/cariba-perl/bin/perl"
990           perlconfig:
991             archname: "freebsd"
992             not_cc: "gcc"
993           env:
994             DANCING_FLOOR: "Shubiduh"
995         disabled: 1
996         cpanconfig:
997           make: gmake
998         pl:
999           args:
1000             - "--somearg=specialcase"
1001
1002           env: {}
1003
1004           expect:
1005             - "Which is your favorite fruit"
1006             - "apple\n"
1007
1008         make:
1009           args:
1010             - all
1011             - extra-all
1012
1013           env: {}
1014
1015           expect: []
1016
1017           commandline: "echo SKIPPING make"
1018
1019         test:
1020           args: []
1021
1022           env: {}
1023
1024           expect: []
1025
1026         install:
1027           args: []
1028
1029           env:
1030             WANT_TO_INSTALL: YES
1031
1032           expect:
1033             - "Do you really want to install"
1034             - "y\n"
1035
1036         patches:
1037           - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
1038
1039         depends:
1040           configure_requires:
1041             LWP: 5.8
1042           build_requires:
1043             Test::Exception: 0.25
1044           requires:
1045             Spiffy: 0.30
1046
1047   Language Specs
1048       Every YAML document represents a single hash reference. The valid keys
1049       in this hash are as follows:
1050
1051       comment [scalar]
1052           A comment
1053
1054       cpanconfig [hash]
1055           Temporarily override assorted "CPAN.pm" configuration variables.
1056
1057           Supported are: "build_requires_install_policy", "check_sigs",
1058           "make", "make_install_make_command", "prefer_installer",
1059           "test_report". Please report as a bug when you need another one
1060           supported.
1061
1062       depends [hash] *** EXPERIMENTAL FEATURE ***
1063           All three types, namely "configure_requires", "build_requires", and
1064           "requires" are supported in the way specified in the META.yml
1065           specification. The current implementation merges the specified
1066           dependencies with those declared by the package maintainer. In a
1067           future implementation this may be changed to override the original
1068           declaration.
1069
1070       disabled [boolean]
1071           Specifies that this distribution shall not be processed at all.
1072
1073       features [array] *** EXPERIMENTAL FEATURE ***
1074           Experimental implementation to deal with optional_features from
1075           META.yml. Still needs coordination with installer software and
1076           currently works only for META.yml declaring "dynamic_config=0". Use
1077           with caution.
1078
1079       goto [string]
1080           The canonical name of a delegate distribution to install instead.
1081           Useful when a new version, although it tests OK itself, breaks
1082           something else or a developer release or a fork is already uploaded
1083           that is better than the last released version.
1084
1085       install [hash]
1086           Processing instructions for the "make install" or "./Build install"
1087           phase of the CPAN mantra. See below under Processing Instructions.
1088
1089       make [hash]
1090           Processing instructions for the "make" or "./Build" phase of the
1091           CPAN mantra. See below under Processing Instructions.
1092
1093       match [hash]
1094           A hashref with one or more of the keys "distribution", "module",
1095           "perl", "perlconfig", and "env" that specify whether a document is
1096           targeted at a specific CPAN distribution or installation.  Keys
1097           prefixed with "not_" negates the corresponding match.
1098
1099           The corresponding values are interpreted as regular expressions.
1100           The "distribution" related one will be matched against the
1101           canonical distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
1102
1103           The "module" related one will be matched against all modules
1104           contained in the distribution until one module matches.
1105
1106           The "perl" related one will be matched against $^X (but with the
1107           absolute path).
1108
1109           The value associated with "perlconfig" is itself a hashref that is
1110           matched against corresponding values in the %Config::Config hash
1111           living in the "Config.pm" module.  Keys prefixed with "not_"
1112           negates the corresponding match.
1113
1114           The value associated with "env" is itself a hashref that is matched
1115           against corresponding values in the %ENV hash.  Keys prefixed with
1116           "not_" negates the corresponding match.
1117
1118           If more than one restriction of "module", "distribution", etc. is
1119           specified, the results of the separately computed match values must
1120           all match. If so, the hashref represented by the YAML document is
1121           returned as the preference structure for the current distribution.
1122
1123       patches [array]
1124           An array of patches on CPAN or on the local disk to be applied in
1125           order via an external patch program. If the value for the "-p"
1126           parameter is 0 or 1 is determined by reading the patch beforehand.
1127           The path to each patch is either an absolute path on the local
1128           filesystem or relative to a patch directory specified in the
1129           "patches_dir" configuration variable or in the format of a
1130           canonical distro name. For examples please consult the distroprefs/
1131           directory in the CPAN.pm distribution (these examples are not
1132           installed by default).
1133
1134           Note: if the "applypatch" program is installed and "CPAN::Config"
1135           knows about it and a patch is written by the "makepatch" program,
1136           then "CPAN.pm" lets "applypatch" apply the patch. Both "makepatch"
1137           and "applypatch" are available from CPAN in the "JV/makepatch-*"
1138           distribution.
1139
1140       pl [hash]
1141           Processing instructions for the "perl Makefile.PL" or "perl
1142           Build.PL" phase of the CPAN mantra. See below under Processing
1143           Instructions.
1144
1145       test [hash]
1146           Processing instructions for the "make test" or "./Build test" phase
1147           of the CPAN mantra. See below under Processing Instructions.
1148
1149   Processing Instructions
1150       args [array]
1151           Arguments to be added to the command line
1152
1153       commandline
1154           A full commandline to run via "system()".  During execution, the
1155           environment variable PERL is set to $^X (but with an absolute
1156           path). If "commandline" is specified, "args" is not used.
1157
1158       eexpect [hash]
1159           Extended "expect". This is a hash reference with four allowed keys,
1160           "mode", "timeout", "reuse", and "talk".
1161
1162           You must install the "Expect" module to use "eexpect". CPAN.pm does
1163           not install it for you.
1164
1165           "mode" may have the values "deterministic" for the case where all
1166           questions come in the order written down and "anyorder" for the
1167           case where the questions may come in any order. The default mode is
1168           "deterministic".
1169
1170           "timeout" denotes a timeout in seconds. Floating-point timeouts are
1171           OK. With "mode=deterministic", the timeout denotes the timeout per
1172           question; with "mode=anyorder" it denotes the timeout per byte
1173           received from the stream or questions.
1174
1175           "talk" is a reference to an array that contains alternating
1176           questions and answers. Questions are regular expressions and
1177           answers are literal strings. The Expect module watches the stream
1178           from the execution of the external program ("perl Makefile.PL",
1179           "perl Build.PL", "make", etc.).
1180
1181           For "mode=deterministic", the CPAN.pm injects the corresponding
1182           answer as soon as the stream matches the regular expression.
1183
1184           For "mode=anyorder" CPAN.pm answers a question as soon as the
1185           timeout is reached for the next byte in the input stream. In this
1186           mode you can use the "reuse" parameter to decide what will happen
1187           with a question-answer pair after it has been used. In the default
1188           case (reuse=0) it is removed from the array, avoiding being used
1189           again accidentally. If you want to answer the question "Do you
1190           really want to do that" several times, then it must be included in
1191           the array at least as often as you want this answer to be given.
1192           Setting the parameter "reuse" to 1 makes this repetition
1193           unnecessary.
1194
1195       env [hash]
1196           Environment variables to be set during the command
1197
1198       expect [array]
1199           You must install the "Expect" module to use "expect". CPAN.pm does
1200           not install it for you.
1201
1202           "expect: <array>" is a short notation for this "eexpect":
1203
1204                   eexpect:
1205                           mode: deterministic
1206                           timeout: 15
1207                           talk: <array>
1208
1209   Schema verification with "Kwalify"
1210       If you have the "Kwalify" module installed (which is part of the
1211       Bundle::CPANxxl), then all your distroprefs files are checked for
1212       syntactic correctness.
1213
1214   Example Distroprefs Files
1215       "CPAN.pm" comes with a collection of example YAML files. Note that
1216       these are really just examples and should not be used without care
1217       because they cannot fit everybody's purpose. After all, the authors of
1218       the packages that ask questions had a need to ask, so you should watch
1219       their questions and adjust the examples to your environment and your
1220       needs. You have been warned:-)
1221

PROGRAMMER'S INTERFACE

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

PREREQUISITES

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

UTILITIES

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

SECURITY

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

EXPORT

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

ENVIRONMENT

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

POPULATE AN INSTALLATION WITH LOTS OF MODULES

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

WORKING WITH CPAN.pm BEHIND FIREWALLS

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

FAQ

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

COMPATIBILITY

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

SECURITY ADVICE

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

BUGS

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

AUTHOR

2286       Andreas Koenig "<andk@cpan.org>"
2287

LICENSE

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

TRANSLATIONS

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

SEE ALSO

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