1CPAN(3pm) Perl Programmers Reference Guide CPAN(3pm)
2
6 CPAN - query, download and build perl modules from CPAN sites
7
9 Interactive mode:
10 perl -MCPAN -e shell
12 --or--
14 cpan
16 Basic commands:
18 # Modules:
20 cpan> install Acme::Meta # in the shell
22 CPAN::Shell->install("Acme::Meta"); # in perl
24 # Distributions:
26 cpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell
28 CPAN::Shell->
30 install("NWCLARK/Acme-Meta-0.02.tar.gz"); # in perl
31 # module objects:
33 $mo = CPAN::Shell->expandany($mod);
35 $mo = CPAN::Shell->expand("Module",$mod); # same thing
36 # distribution objects:
38 $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
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 These are fetched from one or more mirrored CPAN (Comprehensive Perl
51 Archive Network) sites and unpacked in a dedicated directory.
52 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 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 All methods provided are accessible in a programmer style and in an
64 interactive shell style.
65 CPAN::shell([$prompt, $command]) Starting Interactive Mode
67 Enter interactive mode by running
68 perl -MCPAN -e shell
70 or
72 cpan
74 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 Once at the command line, type "h" for one-page help screen; the rest
80 should be self-explanatory.
81 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 The most common uses of the interactive modes are
87 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 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 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 Examples:
107 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 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 "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 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 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 Example:
165 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 "get" downloads a distribution file and untars or unzips it, "make"
171 builds it, "test" runs the test suite, and "install" installs it.
172 Any "make" or "test" is run unconditionally. An
174 install <distribution_file>
176 is also run unconditionally. But for
178 install <module>
180 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 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 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 The "notest" pragma skips the test part in the build process.
195 Example:
197 cpan> notest install Tk
199 A "clean" command results in a
201 make clean
203 being executed within the distribution file's working directory.
205 "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 "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 CHECKUMS files distributed on CPAN.
217 The listing recurses into subdirectories.
218 The second form limits or expands the output with shell globbing as
220 in the following examples:
221 ls JV/make*
223 ls GSAR/*make*
224 ls */*make*
225 The last example is very slow and outputs extra progress indicators
227 that break the alignment of the result.
228 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 "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 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 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 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 In all these cases, the user can override this stubborn behaviour by
261 prepending the command with the word force, for example:
262 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 Each forced command is executed with the corresponding part of its
269 memory erased.
270 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 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 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 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 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 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 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 Return value: path to the written file.
315 hosts
317 Note: this feature is still in alpha state and may change in future
318 versions of CPAN.pm
319 This commands provides a statistical overview over recent download
321 activities. The data for this is collected in the YAML file
322 "FTPstats.yml" in your "cpan_home" directory. If no YAML module is
323 configured or YAML not installed, no stats are provided.
324 mkmyconfig
326 mkmyconfig() writes your own CPAN::MyConfig file into your "~/.cpan/"
327 directory so that you can save your own preferences instead of the
328 system-wide ones.
329 r [Module|/Regexp/]...
331 scans current perl installation for modules that have a newer version
332 available on CPAN and provides a list of them. If called without
333 argument, all potential upgrades are listed; if called with arguments
334 the list is filtered to the modules and regexps given as arguments.
335 The listing looks something like this:
337 Package namespace installed latest in CPAN file
339 CPAN 1.94_64 1.9600 ANDK/CPAN-1.9600.tar.gz
340 CPAN::Reporter 1.1801 1.1902 DAGOLDEN/CPAN-Reporter-1.1902.tar.gz
341 YAML 0.70 0.73 INGY/YAML-0.73.tar.gz
342 YAML::Syck 1.14 1.17 AVAR/YAML-Syck-1.17.tar.gz
343 YAML::Tiny 1.44 1.50 ADAMK/YAML-Tiny-1.50.tar.gz
344 CGI 3.43 3.55 MARKSTOS/CGI.pm-3.55.tar.gz
345 Module::Build::YAML 1.40 1.41 DAGOLDEN/Module-Build-0.3800.tar.gz
346 TAP::Parser::Result::YAML 3.22 3.23 ANDYA/Test-Harness-3.23.tar.gz
347 YAML::XS 0.34 0.35 INGY/YAML-LibYAML-0.35.tar.gz
348 It suppresses duplicates in the column "in CPAN file" such that
350 distributions with many upgradeable modules are listed only once.
351 Note that the list is not sorted.
353 recent ***EXPERIMENTAL COMMAND***
355 The "recent" command downloads a list of recent uploads to CPAN and
356 displays them slowly. While the command is running, a $SIG{INT} exits
357 the loop after displaying the current item.
358 Note: This command requires XML::LibXML installed.
360 Note: This whole command currently is just a hack and will probably
362 change in future versions of CPAN.pm, but the general approach will
363 likely remain.
364 Note: See also smoke
366 recompile
368 recompile() is a special command that takes no argument and runs the
369 make/test/install cycle with brute force over all installed dynamically
370 loadable extensions (a.k.a. XS modules) with 'force' in effect. The
371 primary purpose of this command is to finish a network installation.
372 Imagine you have a common source tree for two different architectures.
373 You decide to do a completely independent fresh installation. You start
374 on one architecture with the help of a Bundle file produced earlier.
375 CPAN installs the whole Bundle for you, but when you try to repeat the
376 job on the second architecture, CPAN responds with a "Foo up to date"
377 message for all modules. So you invoke CPAN's recompile on the second
378 architecture and you're done.
379 Another popular use for "recompile" is to act as a rescue in case your
381 perl breaks binary compatibility. If one of the modules that CPAN uses
382 is in turn depending on binary compatibility (so you cannot run CPAN
383 commands), then you should try the CPAN::Nox module for recovery.
384 report Bundle|Distribution|Module
386 The "report" command temporarily turns on the "test_report" config
387 variable, then runs the "force test" command with the given arguments.
388 The "force" pragma reruns the tests and repeats every step that might
389 have failed before.
390 smoke ***EXPERIMENTAL COMMAND***
392 *** WARNING: this command downloads and executes software from CPAN to
393 your computer of completely unknown status. You should never do this
394 with your normal account and better have a dedicated well separated and
395 secured machine to do this. ***
396 The "smoke" command takes the list of recent uploads to CPAN as
398 provided by the "recent" command and tests them all. While the command
399 is running $SIG{INT} is defined to mean that the current item shall be
400 skipped.
401 Note: This whole command currently is just a hack and will probably
403 change in future versions of CPAN.pm, but the general approach will
404 likely remain.
405 Note: See also recent
407 upgrade [Module|/Regexp/]...
409 The "upgrade" command first runs an "r" command with the given
410 arguments and then installs the newest versions of all modules that
411 were listed by that.
412 The four "CPAN::*" Classes: Author, Bundle, Module, Distribution
414 Although it may be considered internal, the class hierarchy does matter
415 for both users and programmer. CPAN.pm deals with the four classes
416 mentioned above, and those classes all share a set of methods.
417 Classical single polymorphism is in effect. A metaclass object
418 registers all objects of all kinds and indexes them with a string. The
419 strings referencing objects have a separated namespace (well, not
420 completely separated):
421 Namespace Class
423 words containing a "/" (slash) Distribution
425 words starting with Bundle:: Bundle
426 everything else Module or Author
427 Modules know their associated Distribution objects. They always refer
429 to the most recent official release. Developers may mark their releases
430 as unstable development versions (by inserting an underbar into the
431 module version number which will also be reflected in the distribution
432 name when you run 'make dist'), so the really hottest and newest
433 distribution is not always the default. If a module Foo circulates on
434 CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient way
435 to install version 1.23 by saying
436 install Foo
438 This would install the complete distribution file (say
440 BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
441 like to install version 1.23_90, you need to know where the
442 distribution file resides on CPAN relative to the authors/id/
443 directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
444 so you would have to say
445 install BAR/Foo-1.23_90.tar.gz
447 The first example will be driven by an object of the class
449 CPAN::Module, the second by an object of class CPAN::Distribution.
450 Integrating local directories
452 Note: this feature is still in alpha state and may change in future
453 versions of CPAN.pm
454 Distribution objects are normally distributions from the CPAN, but
456 there is a slightly degenerate case for Distribution objects, too, of
457 projects held on the local disk. These distribution objects have the
458 same name as the local directory and end with a dot. A dot by itself is
459 also allowed for the current directory at the time CPAN.pm was used.
460 All actions such as "make", "test", and "install" are applied directly
461 to that directory. This gives the command "cpan ." an interesting
462 touch: while the normal mantra of installing a CPAN module without
463 CPAN.pm is one of
464 perl Makefile.PL perl Build.PL
466 ( go and get prerequisites )
467 make ./Build
468 make test ./Build test
469 make install ./Build install
470 the command "cpan ." does all of this at once. It figures out which of
472 the two mantras is appropriate, fetches and installs all prerequisites,
473 takes care of them recursively, and finally finishes the installation
474 of the module in the current directory, be it a CPAN module or not.
475 The typical usage case is for private modules or working copies of
477 projects from remote repositories on the local disk.
478 Redirection
480 The usual shell redirection symbols " | " and ">" are recognized by the
481 cpan shell only when surrounded by whitespace. So piping to pager or
482 redirecting output into a file works somewhat as in a normal shell,
483 with the stipulation that you must type extra spaces.
484
486 When the CPAN module is used for the first time, a configuration
487 dialogue tries to determine a couple of site specific options. The
488 result of the dialog is stored in a hash reference $CPAN::Config in a
489 file CPAN/Config.pm.
490 Default values defined in the CPAN/Config.pm file can be overridden in
492 a user specific file: CPAN/MyConfig.pm. Such a file is best placed in
493 "$HOME/.cpan/CPAN/MyConfig.pm", because "$HOME/.cpan" is added to the
494 search path of the CPAN module before the use() or require()
495 statements. The mkmyconfig command writes this file for you.
496 The "o conf" command has various bells and whistles:
498 completion support
500 If you have a ReadLine module installed, you can hit TAB at any
501 point of the commandline and "o conf" will offer you completion for
502 the built-in subcommands and/or config variable names.
503 displaying some help: o conf help
505 Displays a short help
506 displaying current values: o conf [KEY]
508 Displays the current value(s) for this config variable. Without
509 KEY, displays all subcommands and config variables.
510 Example:
512 o conf shell
514 If KEY starts and ends with a slash, the string in between is
516 treated as a regular expression and only keys matching this regexp
517 are displayed
518 Example:
520 o conf /color/
522 changing of scalar values: o conf KEY VALUE
524 Sets the config variable KEY to VALUE. The empty string can be
525 specified as usual in shells, with '' or ""
526 Example:
528 o conf wget /usr/bin/wget
530 changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
532 If a config variable name ends with "list", it is a list. "o conf
533 KEY shift" removes the first element of the list, "o conf KEY pop"
534 removes the last element of the list. "o conf KEYS unshift LIST"
535 prepends a list of values to the list, "o conf KEYS push LIST"
536 appends a list of valued to the list.
537 Likewise, "o conf KEY splice LIST" passes the LIST to the
539 corresponding splice command.
540 Finally, any other list of arguments is taken as a new list value
542 for the KEY variable discarding the previous value.
543 Examples:
545 o conf urllist unshift http://cpan.dev.local/CPAN
547 o conf urllist splice 3 1
548 o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
549 reverting to saved: o conf defaults
551 Reverts all config variables to the state in the saved config file.
552 saving the config: o conf commit
554 Saves all config variables to the current config file
555 (CPAN/Config.pm or CPAN/MyConfig.pm that was loaded at start).
556 The configuration dialog can be started any time later again by issuing
558 the command " o conf init " in the CPAN shell. A subset of the
559 configuration dialog can be run by issuing "o conf init WORD" where
560 WORD is any valid config variable or a regular expression.
561 Config Variables
563 The following keys in the hash reference $CPAN::Config are currently
564 defined:
565 applypatch path to external prg
567 auto_commit commit all changes to config variables to disk
568 build_cache size of cache for directories to build modules
569 build_dir locally accessible directory to build modules
570 build_dir_reuse boolean if distros in build_dir are persistent
571 build_requires_install_policy
572 to install or not to install when a module is
573 only needed for building. yes|no|ask/yes|ask/no
574 bzip2 path to external prg
575 cache_metadata use serializer to cache metadata
576 check_sigs if signatures should be verified
577 colorize_debug Term::ANSIColor attributes for debugging output
578 colorize_output boolean if Term::ANSIColor should colorize output
579 colorize_print Term::ANSIColor attributes for normal output
580 colorize_warn Term::ANSIColor attributes for warnings
581 commandnumber_in_prompt
582 boolean if you want to see current command number
583 commands_quote preferred character to use for quoting external
584 commands when running them. Defaults to double
585 quote on Windows, single tick everywhere else;
586 can be set to space to disable quoting
587 connect_to_internet_ok
588 whether to ask if opening a connection is ok before
589 urllist is specified
590 cpan_home local directory reserved for this package
591 curl path to external prg
592 dontload_hash DEPRECATED
593 dontload_list arrayref: modules in the list will not be
594 loaded by the CPAN::has_inst() routine
595 ftp path to external prg
596 ftp_passive if set, the environment variable FTP_PASSIVE is set
597 for downloads
598 ftp_proxy proxy host for ftp requests
599 ftpstats_period max number of days to keep download statistics
600 ftpstats_size max number of items to keep in the download statistics
601 getcwd see below
602 gpg path to external prg
603 gzip location of external program gzip
604 halt_on_failure stop processing after the first failure of queued
605 items or dependencies
606 histfile file to maintain history between sessions
607 histsize maximum number of lines to keep in histfile
608 http_proxy proxy host for http requests
609 inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
610 after this many seconds inactivity. Set to 0 to
611 disable timeouts.
612 index_expire refetch index files after this many days
613 inhibit_startup_message
614 if true, suppress the startup message
615 keep_source_where directory in which to keep the source (if we do)
616 load_module_verbosity
617 report loading of optional modules used by CPAN.pm
618 lynx path to external prg
619 make location of external make program
620 make_arg arguments that should always be passed to 'make'
621 make_install_make_command
622 the make command for running 'make install', for
623 example 'sudo make'
624 make_install_arg same as make_arg for 'make install'
625 makepl_arg arguments passed to 'perl Makefile.PL'
626 mbuild_arg arguments passed to './Build'
627 mbuild_install_arg arguments passed to './Build install'
628 mbuild_install_build_command
629 command to use instead of './Build' when we are
630 in the install stage, for example 'sudo ./Build'
631 mbuildpl_arg arguments passed to 'perl Build.PL'
632 ncftp path to external prg
633 ncftpget path to external prg
634 no_proxy don't proxy to these hosts/domains (comma separated list)
635 pager location of external program more (or any pager)
636 password your password if you CPAN server wants one
637 patch path to external prg
638 patches_dir local directory containing patch files
639 perl5lib_verbosity verbosity level for PERL5LIB additions
640 prefer_external_tar
641 per default all untar operations are done with
642 Archive::Tar; by setting this variable to true
643 the external tar command is used if available
644 prefer_installer legal values are MB and EUMM: if a module comes
645 with both a Makefile.PL and a Build.PL, use the
646 former (EUMM) or the latter (MB); if the module
647 comes with only one of the two, that one will be
648 used no matter the setting
649 prerequisites_policy
650 what to do if you are missing module prerequisites
651 ('follow' automatically, 'ask' me, or 'ignore')
652 For 'follow', also sets PERL_AUTOINSTALL and
653 PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if
654 not already set
655 prefs_dir local directory to store per-distro build options
656 proxy_user username for accessing an authenticating proxy
657 proxy_pass password for accessing an authenticating proxy
658 randomize_urllist add some randomness to the sequence of the urllist
659 scan_cache controls scanning of cache ('atstart', 'atexit' or 'never')
660 shell your favorite shell
661 show_unparsable_versions
662 boolean if r command tells which modules are versionless
663 show_upload_date boolean if commands should try to determine upload date
664 show_zero_versions boolean if r command tells for which modules $version==0
665 tar location of external program tar
666 tar_verbosity verbosity level for the tar command
667 term_is_latin deprecated: if true Unicode is translated to ISO-8859-1
668 (and nonsense for characters outside latin range)
669 term_ornaments boolean to turn ReadLine ornamenting on/off
670 test_report email test reports (if CPAN::Reporter is installed)
671 trust_test_report_history
672 skip testing when previously tested ok (according to
673 CPAN::Reporter history)
674 unzip location of external program unzip
675 urllist arrayref to nearby CPAN sites (or equivalent locations)
676 use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
677 username your username if you CPAN server wants one
678 version_timeout stops version parsing after this many seconds.
679 Default is 15 secs. Set to 0 to disable.
680 wait_list arrayref to a wait server to try (See CPAN::WAIT)
681 wget path to external prg
682 yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
683 yaml_module which module to use to read/write YAML files
684 You can set and query each of these options interactively in the cpan
686 shell with the "o conf" or the "o conf init" command as specified
687 below.
688 "o conf <scalar option>"
690 prints the current value of the scalar option
691 "o conf <scalar option> <value>"
693 Sets the value of the scalar option to value
694 "o conf <list option>"
696 prints the current value of the list option in MakeMaker's neatvalue
697 format.
698 "o conf <list option> [shift|pop]"
700 shifts or pops the array in the list option variable
701 "o conf <list option> [unshift|push|splice] <list>"
703 works like the corresponding perl commands.
704 interactive editing: o conf init [MATCH|LIST]
706 Runs an interactive configuration dialog for matching variables.
707 Without argument runs the dialog over all supported config variables.
708 To specify a MATCH the argument must be enclosed by slashes.
709 Examples:
711 o conf init ftp_passive ftp_proxy
713 o conf init /color/
714 Note: this method of setting config variables often provides more
716 explanation about the functioning of a variable than the manpage.
717 CPAN::anycwd($path): Note on config variable getcwd
719 CPAN.pm changes the current working directory often and needs to
720 determine its own current working directory. By default it uses
721 Cwd::cwd, but if for some reason this doesn't work on your system,
722 configure alternatives according to the following table:
723 cwd Calls Cwd::cwd
725 getcwd
727 Calls Cwd::getcwd
728 fastcwd
730 Calls Cwd::fastcwd
731 backtickcwd
733 Calls the external command cwd.
734 Note on the format of the urllist parameter
736 urllist parameters are URLs according to RFC 1738. We do a little
737 guessing if your URL is not compliant, but if you have problems with
738 "file" URLs, please try the correct format. Either:
739 file://localhost/whatever/ftp/pub/CPAN/
741 or
743 file:///home/ftp/pub/CPAN/
745 The urllist parameter has CD-ROM support
747 The "urllist" parameter of the configuration table contains a list of
748 URLs used for downloading. If the list contains any "file" URLs, CPAN
749 always tries there first. This feature is disabled for index files. So
750 the recommendation for the owner of a CD-ROM with CPAN contents is:
751 include your local, possibly outdated CD-ROM as a "file" URL at the end
752 of urllist, e.g.
753 o conf urllist push file://localhost/CDROM/CPAN
755 CPAN.pm will then fetch the index files from one of the CPAN sites that
757 come at the beginning of urllist. It will later check for each module
758 to see whether there is a local copy of the most recent version.
759 Another peculiarity of urllist is that the site that we could
761 successfully fetch the last file from automatically gets a preference
762 token and is tried as the first site for the next request. So if you
763 add a new site at runtime it may happen that the previously preferred
764 site will be tried another time. This means that if you want to
765 disallow a site for the next transfer, it must be explicitly removed
766 from urllist.
767 Maintaining the urllist parameter
769 If you have YAML.pm (or some other YAML module configured in
770 "yaml_module") installed, CPAN.pm collects a few statistical data about
771 recent downloads. You can view the statistics with the "hosts" command
772 or inspect them directly by looking into the "FTPstats.yml" file in
773 your "cpan_home" directory.
774 To get some interesting statistics, it is recommended that
776 "randomize_urllist" be set; this introduces some amount of randomness
777 into the URL selection.
778 The "requires" and "build_requires" dependency declarations
780 Since CPAN.pm version 1.88_51 modules declared as "build_requires" by a
781 distribution are treated differently depending on the config variable
782 "build_requires_install_policy". By setting
783 "build_requires_install_policy" to "no", such a module is not
784 installed. It is only built and tested, and then kept in the list of
785 tested but uninstalled modules. As such, it is available during the
786 build of the dependent module by integrating the path to the
787 "blib/arch" and "blib/lib" directories in the environment variable
788 PERL5LIB. If "build_requires_install_policy" is set ti "yes", then both
789 modules declared as "requires" and those declared as "build_requires"
790 are treated alike. By setting to "ask/yes" or "ask/no", CPAN.pm asks
791 the user and sets the default accordingly.
792 Configuration for individual distributions (Distroprefs)
794 (Note: This feature has been introduced in CPAN.pm 1.8854 and is still
795 considered beta quality)
796 Distributions on CPAN usually behave according to what we call the CPAN
798 mantra. Or since the advent of Module::Build we should talk about two
799 mantras:
800 perl Makefile.PL perl Build.PL
802 make ./Build
803 make test ./Build test
804 make install ./Build install
805 But some modules cannot be built with this mantra. They try to get some
807 extra data from the user via the environment, extra arguments, or
808 interactively--thus disturbing the installation of large bundles like
809 Phalanx100 or modules with many dependencies like Plagger.
810 The distroprefs system of "CPAN.pm" addresses this problem by allowing
812 the user to specify extra informations and recipes in YAML files to
813 either
814 · pass additional arguments to one of the four commands,
816 · set environment variables
818 · instantiate an Expect object that reads from the console, waits for
820 some regular expressions and enters some answers
821 · temporarily override assorted "CPAN.pm" configuration variables
823 · specify dependencies the original maintainer forgot
825 · disable the installation of an object altogether
827 See the YAML and Data::Dumper files that come with the "CPAN.pm"
829 distribution in the "distroprefs/" directory for examples.
830 Filenames
832 The YAML files themselves must have the ".yml" extension; all other
833 files are ignored (for two exceptions see Fallback Data::Dumper and
834 Storable below). The containing directory can be specified in "CPAN.pm"
835 in the "prefs_dir" config variable. Try "o conf init prefs_dir" in the
836 CPAN shell to set and activate the distroprefs system.
837 Every YAML file may contain arbitrary documents according to the YAML
839 specification, and every document is treated as an entity that can
840 specify the treatment of a single distribution.
841 Filenames can be picked arbitrarily; "CPAN.pm" always reads all files
843 (in alphabetical order) and takes the key "match" (see below in
844 Language Specs) as a hashref containing match criteria that determine
845 if the current distribution matches the YAML document or not.
846 Fallback Data::Dumper and Storable
848 If neither your configured "yaml_module" nor YAML.pm is installed,
849 CPAN.pm falls back to using Data::Dumper and Storable and looks for
850 files with the extensions ".dd" or ".st" in the "prefs_dir" directory.
851 These files are expected to contain one or more hashrefs. For
852 Data::Dumper generated files, this is expected to be done with by
853 defining $VAR1, $VAR2, etc. The YAML shell would produce these with the
854 command
855 ysh < somefile.yml > somefile.dd
857 For Storable files the rule is that they must be constructed such that
859 "Storable::retrieve(file)" returns an array reference and the array
860 elements represent one distropref object each. The conversion from YAML
861 would look like so:
862 perl -MYAML=LoadFile -MStorable=nstore -e '
864 @y=LoadFile(shift);
865 nstore(\@y, shift)' somefile.yml somefile.st
866 In bootstrapping situations it is usually sufficient to translate only
868 a few YAML files to Data::Dumper for crucial modules like "YAML::Syck",
869 "YAML.pm" and "Expect.pm". If you prefer Storable over Data::Dumper,
870 remember to pull out a Storable version that writes an older format
871 than all the other Storable versions that will need to read them.
872 Blueprint
874 The following example contains all supported keywords and structures
875 with the exception of "eexpect" which can be used instead of "expect".
876 ---
878 comment: "Demo"
879 match:
880 module: "Dancing::Queen"
881 distribution: "^CHACHACHA/Dancing-"
882 not_distribution: "\.zip$"
883 perl: "/usr/local/cariba-perl/bin/perl"
884 perlconfig:
885 archname: "freebsd"
886 not_cc: "gcc"
887 env:
888 DANCING_FLOOR: "Shubiduh"
889 disabled: 1
890 cpanconfig:
891 make: gmake
892 pl:
893 args:
894 - "--somearg=specialcase"
895 env: {}
897 expect:
899 - "Which is your favorite fruit"
900 - "apple\n"
901 make:
903 args:
904 - all
905 - extra-all
906 env: {}
908 expect: []
910 commandline: "echo SKIPPING make"
912 test:
914 args: []
915 env: {}
917 expect: []
919 install:
921 args: []
922 env:
924 WANT_TO_INSTALL: YES
925 expect:
927 - "Do you really want to install"
928 - "y\n"
929 patches:
931 - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
932 depends:
934 configure_requires:
935 LWP: 5.8
936 build_requires:
937 Test::Exception: 0.25
938 requires:
939 Spiffy: 0.30
940 Language Specs
942 Every YAML document represents a single hash reference. The valid keys
943 in this hash are as follows:
944 comment [scalar]
946 A comment
947 cpanconfig [hash]
949 Temporarily override assorted "CPAN.pm" configuration variables.
950 Supported are: "build_requires_install_policy", "check_sigs",
952 "make", "make_install_make_command", "prefer_installer",
953 "test_report". Please report as a bug when you need another one
954 supported.
955 depends [hash] *** EXPERIMENTAL FEATURE ***
957 All three types, namely "configure_requires", "build_requires", and
958 "requires" are supported in the way specified in the META.yml
959 specification. The current implementation merges the specified
960 dependencies with those declared by the package maintainer. In a
961 future implementation this may be changed to override the original
962 declaration.
963 disabled [boolean]
965 Specifies that this distribution shall not be processed at all.
966 features [array] *** EXPERIMENTAL FEATURE ***
968 Experimental implementation to deal with optional_features from
969 META.yml. Still needs coordination with installer software and
970 currently works only for META.yml declaring "dynamic_config=0". Use
971 with caution.
972 goto [string]
974 The canonical name of a delegate distribution to install instead.
975 Useful when a new version, although it tests OK itself, breaks
976 something else or a developer release or a fork is already uploaded
977 that is better than the last released version.
978 install [hash]
980 Processing instructions for the "make install" or "./Build install"
981 phase of the CPAN mantra. See below under Processing Instructions.
982 make [hash]
984 Processing instructions for the "make" or "./Build" phase of the
985 CPAN mantra. See below under Processing Instructions.
986 match [hash]
988 A hashref with one or more of the keys "distribution", "modules",
989 "perl", "perlconfig", and "env" that specify whether a document is
990 targeted at a specific CPAN distribution or installation. Keys
991 prefixed with "not_" negates the corresponding match.
992 The corresponding values are interpreted as regular expressions.
994 The "distribution" related one will be matched against the
995 canonical distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
996 The "module" related one will be matched against all modules
998 contained in the distribution until one module matches.
999 The "perl" related one will be matched against $^X (but with the
1001 absolute path).
1002 The value associated with "perlconfig" is itself a hashref that is
1004 matched against corresponding values in the %Config::Config hash
1005 living in the "Config.pm" module. Keys prefixed with "not_"
1006 negates the corresponding match.
1007 The value associated with "env" is itself a hashref that is matched
1009 against corresponding values in the %ENV hash. Keys prefixed with
1010 "not_" negates the corresponding match.
1011 If more than one restriction of "module", "distribution", etc. is
1013 specified, the results of the separately computed match values must
1014 all match. If so, the hashref represented by the YAML document is
1015 returned as the preference structure for the current distribution.
1016 patches [array]
1018 An array of patches on CPAN or on the local disk to be applied in
1019 order via an external patch program. If the value for the "-p"
1020 parameter is 0 or 1 is determined by reading the patch beforehand.
1021 The path to each patch is either an absolute path on the local
1022 filesystem or relative to a patch directory specified in the
1023 "patches_dir" configuration variable or in the format of a
1024 canonical distro name. For examples please consult the distroprefs/
1025 directory in the CPAN.pm distribution (these examples are not
1026 installed by default).
1027 Note: if the "applypatch" program is installed and "CPAN::Config"
1029 knows about it and a patch is written by the "makepatch" program,
1030 then "CPAN.pm" lets "applypatch" apply the patch. Both "makepatch"
1031 and "applypatch" are available from CPAN in the "JV/makepatch-*"
1032 distribution.
1033 pl [hash]
1035 Processing instructions for the "perl Makefile.PL" or "perl
1036 Build.PL" phase of the CPAN mantra. See below under Processing
1037 Instructions.
1038 test [hash]
1040 Processing instructions for the "make test" or "./Build test" phase
1041 of the CPAN mantra. See below under Processing Instructions.
1042 Processing Instructions
1044 args [array]
1045 Arguments to be added to the command line
1046 commandline
1048 A full commandline to run via "system()". During execution, the
1049 environment variable PERL is set to $^X (but with an absolute
1050 path). If "commandline" is specified, "args" is not used.
1051 eexpect [hash]
1053 Extended "expect". This is a hash reference with four allowed keys,
1054 "mode", "timeout", "reuse", and "talk".
1055 You must install the "Expect" module to use "eexpect". CPAN.pm does
1057 not install it for you.
1058 "mode" may have the values "deterministic" for the case where all
1060 questions come in the order written down and "anyorder" for the
1061 case where the questions may come in any order. The default mode is
1062 "deterministic".
1063 "timeout" denotes a timeout in seconds. Floating-point timeouts are
1065 OK. With "mode=deterministic", the timeout denotes the timeout per
1066 question; with "mode=anyorder" it denotes the timeout per byte
1067 received from the stream or questions.
1068 "talk" is a reference to an array that contains alternating
1070 questions and answers. Questions are regular expressions and
1071 answers are literal strings. The Expect module watches the stream
1072 from the execution of the external program ("perl Makefile.PL",
1073 "perl Build.PL", "make", etc.).
1074 For "mode=deterministic", the CPAN.pm injects the corresponding
1076 answer as soon as the stream matches the regular expression.
1077 For "mode=anyorder" CPAN.pm answers a question as soon as the
1079 timeout is reached for the next byte in the input stream. In this
1080 mode you can use the "reuse" parameter to decide what will happen
1081 with a question-answer pair after it has been used. In the default
1082 case (reuse=0) it is removed from the array, avoiding being used
1083 again accidentally. If you want to answer the question "Do you
1084 really want to do that" several times, then it must be included in
1085 the array at least as often as you want this answer to be given.
1086 Setting the parameter "reuse" to 1 makes this repetition
1087 unnecessary.
1088 env [hash]
1090 Environment variables to be set during the command
1091 expect [array]
1093 You must install the "Expect" module to use "expect". CPAN.pm does
1094 not install it for you.
1095 "expect: <array>" is a short notation for this "eexpect":
1097 eexpect:
1099 mode: deterministic
1100 timeout: 15
1101 talk: <array>
1102 Schema verification with "Kwalify"
1104 If you have the "Kwalify" module installed (which is part of the
1105 Bundle::CPANxxl), then all your distroprefs files are checked for
1106 syntactic correctness.
1107 Example Distroprefs Files
1109 "CPAN.pm" comes with a collection of example YAML files. Note that
1110 these are really just examples and should not be used without care
1111 because they cannot fit everybody's purpose. After all, the authors of
1112 the packages that ask questions had a need to ask, so you should watch
1113 their questions and adjust the examples to your environment and your
1114 needs. You have been warned:-)
1115
1117 If you do not enter the shell, shell commands are available both as
1118 methods ("CPAN::Shell->install(...)") and as functions in the calling
1119 package ("install(...)"). Before calling low-level commands, it makes
1120 sense to initialize components of CPAN you need, e.g.:
1121 CPAN::HandleConfig->load;
1123 CPAN::Shell::setup_output;
1124 CPAN::Index->reload;
1125 High-level commands do such initializations automatically.
1127 There's currently only one class that has a stable interface -
1129 CPAN::Shell. All commands that are available in the CPAN shell are
1130 methods of the class CPAN::Shell. The arguments on the commandline are
1131 passed as arguments to the method.
1132 So if you take for example the shell command
1134 notest install A B C
1136 the actually executed command is
1138 CPAN::Shell->notest("install","A","B","C");
1140 Each of the commands that produce listings of modules ("r",
1142 "autobundle", "u") also return a list of the IDs of all modules within
1143 the list.
1144 expand($type,@things)
1146 The IDs of all objects available within a program are strings that
1147 can be expanded to the corresponding real objects with the
1148 "CPAN::Shell->expand("Module",@things)" method. Expand returns a list
1149 of CPAN::Module objects according to the @things arguments given. In
1150 scalar context, it returns only the first element of the list.
1151 expandany(@things)
1153 Like expand, but returns objects of the appropriate type, i.e.
1154 CPAN::Bundle objects for bundles, CPAN::Module objects for modules,
1155 and CPAN::Distribution objects for distributions. Note: it does not
1156 expand to CPAN::Author objects.
1157 Programming Examples
1159 This enables the programmer to do operations that combine
1160 functionalities that are available in the shell.
1161 # install everything that is outdated on my disk:
1163 perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
1164 # install my favorite programs if necessary:
1166 for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
1167 CPAN::Shell->install($mod);
1168 }
1169 # list all modules on my disk that have no VERSION number
1171 for $mod (CPAN::Shell->expand("Module","/./")) {
1172 next unless $mod->inst_file;
1173 # MakeMaker convention for undefined $VERSION:
1174 next unless $mod->inst_version eq "undef";
1175 print "No VERSION in ", $mod->id, "\n";
1176 }
1177 # find out which distribution on CPAN contains a module:
1179 print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
1180 Or if you want to schedule a cron job to watch CPAN, you could list
1182 all modules that need updating. First a quick and dirty way:
1183 perl -e 'use CPAN; CPAN::Shell->r;'
1185 If you don't want any output should all modules be up to date, parse
1187 the output of above command for the regular expression "/modules are
1188 up to date/" and decide to mail the output only if it doesn't match.
1189 If you prefer to do it more in a programmerish style in one single
1191 process, something like this may better suit you:
1192 # list all modules on my disk that have newer versions on CPAN
1194 for $mod (CPAN::Shell->expand("Module","/./")) {
1195 next unless $mod->inst_file;
1196 next if $mod->uptodate;
1197 printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
1198 $mod->id, $mod->inst_version, $mod->cpan_version;
1199 }
1200 If that gives too much output every day, you may want to watch only
1202 for three modules. You can write
1203 for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {
1205 as the first line instead. Or you can combine some of the above
1207 tricks:
1208 # watch only for a new mod_perl module
1210 $mod = CPAN::Shell->expand("Module","mod_perl");
1211 exit if $mod->uptodate;
1212 # new mod_perl arrived, let me know all update recommendations
1213 CPAN::Shell->r;
1214 Methods in the other Classes
1216 CPAN::Author::as_glimpse()
1217 Returns a one-line description of the author
1218 CPAN::Author::as_string()
1220 Returns a multi-line description of the author
1221 CPAN::Author::email()
1223 Returns the author's email address
1224 CPAN::Author::fullname()
1226 Returns the author's name
1227 CPAN::Author::name()
1229 An alias for fullname
1230 CPAN::Bundle::as_glimpse()
1232 Returns a one-line description of the bundle
1233 CPAN::Bundle::as_string()
1235 Returns a multi-line description of the bundle
1236 CPAN::Bundle::clean()
1238 Recursively runs the "clean" method on all items contained in the
1239 bundle.
1240 CPAN::Bundle::contains()
1242 Returns a list of objects' IDs contained in a bundle. The
1243 associated objects may be bundles, modules or distributions.
1244 CPAN::Bundle::force($method,@args)
1246 Forces CPAN to perform a task that it normally would have refused
1247 to do. Force takes as arguments a method name to be called and any
1248 number of additional arguments that should be passed to the called
1249 method. The internals of the object get the needed changes so that
1250 CPAN.pm does not refuse to take the action. The "force" is passed
1251 recursively to all contained objects. See also the section above on
1252 the "force" and the "fforce" pragma.
1253 CPAN::Bundle::get()
1255 Recursively runs the "get" method on all items contained in the
1256 bundle
1257 CPAN::Bundle::inst_file()
1259 Returns the highest installed version of the bundle in either @INC
1260 or "$CPAN::Config->{cpan_home}". Note that this is different from
1261 CPAN::Module::inst_file.
1262 CPAN::Bundle::inst_version()
1264 Like CPAN::Bundle::inst_file, but returns the $VERSION
1265 CPAN::Bundle::uptodate()
1267 Returns 1 if the bundle itself and all its members are up-to-date.
1268 CPAN::Bundle::install()
1270 Recursively runs the "install" method on all items contained in the
1271 bundle
1272 CPAN::Bundle::make()
1274 Recursively runs the "make" method on all items contained in the
1275 bundle
1276 CPAN::Bundle::readme()
1278 Recursively runs the "readme" method on all items contained in the
1279 bundle
1280 CPAN::Bundle::test()
1282 Recursively runs the "test" method on all items contained in the
1283 bundle
1284 CPAN::Distribution::as_glimpse()
1286 Returns a one-line description of the distribution
1287 CPAN::Distribution::as_string()
1289 Returns a multi-line description of the distribution
1290 CPAN::Distribution::author
1292 Returns the CPAN::Author object of the maintainer who uploaded this
1293 distribution
1294 CPAN::Distribution::pretty_id()
1296 Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is
1297 the author's PAUSE ID and TARBALL is the distribution filename.
1298 CPAN::Distribution::base_id()
1300 Returns the distribution filename without any archive suffix. E.g
1301 "Foo-Bar-0.01"
1302 CPAN::Distribution::clean()
1304 Changes to the directory where the distribution has been unpacked
1305 and runs "make clean" there.
1306 CPAN::Distribution::containsmods()
1308 Returns a list of IDs of modules contained in a distribution file.
1309 Works only for distributions listed in the
1310 02packages.details.txt.gz file. This typically means that just most
1311 recent version of a distribution is covered.
1312 CPAN::Distribution::cvs_import()
1314 Changes to the directory where the distribution has been unpacked
1315 and runs something like
1316 cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
1318 there.
1320 CPAN::Distribution::dir()
1322 Returns the directory into which this distribution has been
1323 unpacked.
1324 CPAN::Distribution::force($method,@args)
1326 Forces CPAN to perform a task that it normally would have refused
1327 to do. Force takes as arguments a method name to be called and any
1328 number of additional arguments that should be passed to the called
1329 method. The internals of the object get the needed changes so that
1330 CPAN.pm does not refuse to take the action. See also the section
1331 above on the "force" and the "fforce" pragma.
1332 CPAN::Distribution::get()
1334 Downloads the distribution from CPAN and unpacks it. Does nothing
1335 if the distribution has already been downloaded and unpacked within
1336 the current session.
1337 CPAN::Distribution::install()
1339 Changes to the directory where the distribution has been unpacked
1340 and runs the external command "make install" there. If "make" has
1341 not yet been run, it will be run first. A "make test" is issued in
1342 any case and if this fails, the install is cancelled. The
1343 cancellation can be avoided by letting "force" run the "install"
1344 for you.
1345 This install method only has the power to install the distribution
1347 if there are no dependencies in the way. To install an object along
1348 with all its dependencies, use CPAN::Shell->install.
1349 Note that install() gives no meaningful return value. See
1351 uptodate().
1352 CPAN::Distribution::install_tested()
1354 Install all distributions that have tested successfully but not yet
1355 installed. See also "is_tested".
1356 CPAN::Distribution::isa_perl()
1358 Returns 1 if this distribution file seems to be a perl
1359 distribution. Normally this is derived from the file name only,
1360 but the index from CPAN can contain a hint to achieve a return
1361 value of true for other filenames too.
1362 CPAN::Distribution::look()
1364 Changes to the directory where the distribution has been unpacked
1365 and opens a subshell there. Exiting the subshell returns.
1366 CPAN::Distribution::make()
1368 First runs the "get" method to make sure the distribution is
1369 downloaded and unpacked. Changes to the directory where the
1370 distribution has been unpacked and runs the external commands "perl
1371 Makefile.PL" or "perl Build.PL" and "make" there.
1372 CPAN::Distribution::perldoc()
1374 Downloads the pod documentation of the file associated with a
1375 distribution (in HTML format) and runs it through the external
1376 command lynx specified in "$CPAN::Config->{lynx}". If lynx isn't
1377 available, it converts it to plain text with the external command
1378 html2text and runs it through the pager specified in
1379 "$CPAN::Config->{pager}".
1380 CPAN::Distribution::prefs()
1382 Returns the hash reference from the first matching YAML file that
1383 the user has deposited in the "prefs_dir/" directory. The first
1384 succeeding match wins. The files in the "prefs_dir/" are processed
1385 alphabetically, and the canonical distro name (e.g.
1386 AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular
1387 expressions stored in the $root->{match}{distribution} attribute
1388 value. Additionally all module names contained in a distribution
1389 are matched against the regular expressions in the
1390 $root->{match}{module} attribute value. The two match values are
1391 ANDed together. Each of the two attributes are optional.
1392 CPAN::Distribution::prereq_pm()
1394 Returns the hash reference that has been announced by a
1395 distribution as the "requires" and "build_requires" elements. These
1396 can be declared either by the "META.yml" (if authoritative) or can
1397 be deposited after the run of "Build.PL" in the file
1398 "./_build/prereqs" or after the run of "Makfile.PL" written as the
1399 "PREREQ_PM" hash in a comment in the produced "Makefile". Note:
1400 this method only works after an attempt has been made to "make" the
1401 distribution. Returns undef otherwise.
1402 CPAN::Distribution::readme()
1404 Downloads the README file associated with a distribution and runs
1405 it through the pager specified in "$CPAN::Config->{pager}".
1406 CPAN::Distribution::reports()
1408 Downloads report data for this distribution from
1409 www.cpantesters.org and displays a subset of them.
1410 CPAN::Distribution::read_yaml()
1412 Returns the content of the META.yml of this distro as a hashref.
1413 Note: works only after an attempt has been made to "make" the
1414 distribution. Returns undef otherwise. Also returns undef if the
1415 content of META.yml is not authoritative. (The rules about what
1416 exactly makes the content authoritative are still in flux.)
1417 CPAN::Distribution::test()
1419 Changes to the directory where the distribution has been unpacked
1420 and runs "make test" there.
1421 CPAN::Distribution::uptodate()
1423 Returns 1 if all the modules contained in the distribution are up-
1424 to-date. Relies on containsmods.
1425 CPAN::Index::force_reload()
1427 Forces a reload of all indices.
1428 CPAN::Index::reload()
1430 Reloads all indices if they have not been read for more than
1431 "$CPAN::Config->{index_expire}" days.
1432 CPAN::InfoObj::dump()
1434 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
1435 inherit this method. It prints the data structure associated with
1436 an object. Useful for debugging. Note: the data structure is
1437 considered internal and thus subject to change without notice.
1438 CPAN::Module::as_glimpse()
1440 Returns a one-line description of the module in four columns: The
1441 first column contains the word "Module", the second column consists
1442 of one character: an equals sign if this module is already
1443 installed and up-to-date, a less-than sign if this module is
1444 installed but can be upgraded, and a space if the module is not
1445 installed. The third column is the name of the module and the
1446 fourth column gives maintainer or distribution information.
1447 CPAN::Module::as_string()
1449 Returns a multi-line description of the module
1450 CPAN::Module::clean()
1452 Runs a clean on the distribution associated with this module.
1453 CPAN::Module::cpan_file()
1455 Returns the filename on CPAN that is associated with the module.
1456 CPAN::Module::cpan_version()
1458 Returns the latest version of this module available on CPAN.
1459 CPAN::Module::cvs_import()
1461 Runs a cvs_import on the distribution associated with this module.
1462 CPAN::Module::description()
1464 Returns a 44 character description of this module. Only available
1465 for modules listed in The Module List
1466 (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz)
1467 CPAN::Module::distribution()
1469 Returns the CPAN::Distribution object that contains the current
1470 version of this module.
1471 CPAN::Module::dslip_status()
1473 Returns a hash reference. The keys of the hash are the letters "D",
1474 "S", "L", "I", and <P>, for development status, support level,
1475 language, interface and public licence respectively. The data for
1476 the DSLIP status are collected by pause.perl.org when authors
1477 register their namespaces. The values of the 5 hash elements are
1478 one-character words whose meaning is described in the table below.
1479 There are also 5 hash elements "DV", "SV", "LV", "IV", and <PV>
1480 that carry a more verbose value of the 5 status variables.
1481 Where the 'DSLIP' characters have the following meanings:
1483 D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
1485 i - Idea, listed to gain consensus or as a placeholder
1486 c - under construction but pre-alpha (not yet released)
1487 a/b - Alpha/Beta testing
1488 R - Released
1489 M - Mature (no rigorous definition)
1490 S - Standard, supplied with Perl 5
1491 S - Support Level:
1493 m - Mailing-list
1494 d - Developer
1495 u - Usenet newsgroup comp.lang.perl.modules
1496 n - None known, try comp.lang.perl.modules
1497 a - abandoned; volunteers welcome to take over maintenance
1498 L - Language Used:
1500 p - Perl-only, no compiler needed, should be platform independent
1501 c - C and perl, a C compiler will be needed
1502 h - Hybrid, written in perl with optional C code, no compiler needed
1503 + - C++ and perl, a C++ compiler will be needed
1504 o - perl and another language other than C or C++
1505 I - Interface Style
1507 f - plain Functions, no references used
1508 h - hybrid, object and function interfaces available
1509 n - no interface at all (huh?)
1510 r - some use of unblessed References or ties
1511 O - Object oriented using blessed references and/or inheritance
1512 P - Public License
1514 p - Standard-Perl: user may choose between GPL and Artistic
1515 g - GPL: GNU General Public License
1516 l - LGPL: "GNU Lesser General Public License" (previously known as
1517 "GNU Library General Public License")
1518 b - BSD: The BSD License
1519 a - Artistic license alone
1520 2 - Artistic license 2.0 or later
1521 o - open source: approved by www.opensource.org
1522 d - allows distribution without restrictions
1523 r - restricted distribution
1524 n - no license at all
1525 CPAN::Module::force($method,@args)
1527 Forces CPAN to perform a task it would normally refuse to do. Force
1528 takes as arguments a method name to be invoked and any number of
1529 additional arguments to pass that method. The internals of the
1530 object get the needed changes so that CPAN.pm does not refuse to
1531 take the action. See also the section above on the "force" and the
1532 "fforce" pragma.
1533 CPAN::Module::get()
1535 Runs a get on the distribution associated with this module.
1536 CPAN::Module::inst_file()
1538 Returns the filename of the module found in @INC. The first file
1539 found is reported, just as perl itself stops searching @INC once it
1540 finds a module.
1541 CPAN::Module::available_file()
1543 Returns the filename of the module found in PERL5LIB or @INC. The
1544 first file found is reported. The advantage of this method over
1545 "inst_file" is that modules that have been tested but not yet
1546 installed are included because PERL5LIB keeps track of tested
1547 modules.
1548 CPAN::Module::inst_version()
1550 Returns the version number of the installed module in readable
1551 format.
1552 CPAN::Module::available_version()
1554 Returns the version number of the available module in readable
1555 format.
1556 CPAN::Module::install()
1558 Runs an "install" on the distribution associated with this module.
1559 CPAN::Module::look()
1561 Changes to the directory where the distribution associated with
1562 this module has been unpacked and opens a subshell there. Exiting
1563 the subshell returns.
1564 CPAN::Module::make()
1566 Runs a "make" on the distribution associated with this module.
1567 CPAN::Module::manpage_headline()
1569 If module is installed, peeks into the module's manpage, reads the
1570 headline, and returns it. Moreover, if the module has been
1571 downloaded within this session, does the equivalent on the
1572 downloaded module even if it hasn't been installed yet.
1573 CPAN::Module::perldoc()
1575 Runs a "perldoc" on this module.
1576 CPAN::Module::readme()
1578 Runs a "readme" on the distribution associated with this module.
1579 CPAN::Module::reports()
1581 Calls the reports() method on the associated distribution object.
1582 CPAN::Module::test()
1584 Runs a "test" on the distribution associated with this module.
1585 CPAN::Module::uptodate()
1587 Returns 1 if the module is installed and up-to-date.
1588 CPAN::Module::userid()
1590 Returns the author's ID of the module.
1591 Cache Manager
1593 Currently the cache manager only keeps track of the build directory
1594 ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
1595 deletes complete directories below "build_dir" as soon as the size of
1596 all directories there gets bigger than $CPAN::Config->{build_cache} (in
1597 MB). The contents of this cache may be used for later re-installations
1598 that you intend to do manually, but will never be trusted by CPAN
1599 itself. This is due to the fact that the user might use these
1600 directories for building modules on different architectures.
1601 There is another directory ($CPAN::Config->{keep_source_where}) where
1603 the original distribution files are kept. This directory is not covered
1604 by the cache manager and must be controlled by the user. If you choose
1605 to have the same directory as build_dir and as keep_source_where
1606 directory, then your sources will be deleted with the same fifo
1607 mechanism.
1608 Bundles
1610 A bundle is just a perl module in the namespace Bundle:: that does not
1611 define any functions or methods. It usually only contains
1612 documentation.
1613 It starts like a perl module with a package declaration and a $VERSION
1615 variable. After that the pod section looks like any other pod with the
1616 only difference being that one special pod section exists starting with
1617 (verbatim):
1618 =head1 CONTENTS
1620 In this pod section each line obeys the format
1622 Module_Name [Version_String] [- optional text]
1624 The only required part is the first field, the name of a module (e.g.
1626 Foo::Bar, i.e. not the name of the distribution file). The rest of the
1627 line is optional. The comment part is delimited by a dash just as in
1628 the man page header.
1629 The distribution of a bundle should follow the same convention as other
1631 distributions.
1632 Bundles are treated specially in the CPAN package. If you say 'install
1634 Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
1635 the modules in the CONTENTS section of the pod. You can install your
1636 own Bundles locally by placing a conformant Bundle file somewhere into
1637 your @INC path. The autobundle() command which is available in the
1638 shell interface does that for you by including all currently installed
1639 modules in a snapshot bundle file.
1640
1642 The CPAN program is trying to depend on as little as possible so the
1643 user can use it in hostile environment. It works better the more
1644 goodies the environment provides. For example if you try in the CPAN
1645 shell
1646 install Bundle::CPAN
1648 or
1650 install Bundle::CPANxxl
1652 you will find the shell more convenient than the bare shell before.
1654 If you have a local mirror of CPAN and can access all files with
1656 "file:" URLs, then you only need a perl later than perl5.003 to run
1657 this module. Otherwise Net::FTP is strongly recommended. LWP may be
1658 required for non-UNIX systems, or if your nearest CPAN site is
1659 associated with a URL that is not "ftp:".
1660 If you have neither Net::FTP nor LWP, there is a fallback mechanism
1662 implemented for an external ftp command or for an external lynx
1663 command.
1664
1666 Finding packages and VERSION
1667 This module presumes that all packages on CPAN
1668 · declare their $VERSION variable in an easy to parse manner. This
1670 prerequisite can hardly be relaxed because it consumes far too much
1671 memory to load all packages into the running program just to
1672 determine the $VERSION variable. Currently all programs that are
1673 dealing with version use something like this
1674 perl -MExtUtils::MakeMaker -le \
1676 'print MM->parse_version(shift)' filename
1677 If you are author of a package and wonder if your $VERSION can be
1679 parsed, please try the above method.
1680 · come as compressed or gzipped tarfiles or as zip files and contain a
1682 "Makefile.PL" or "Build.PL" (well, we try to handle a bit more, but
1683 with little enthusiasm).
1684 Debugging
1686 Debugging this module is more than a bit complex due to interference
1687 from the software producing the indices on CPAN, the mirroring process
1688 on CPAN, packaging, configuration, synchronicity, and even (gasp!) due
1689 to bugs within the CPAN.pm module itself.
1690 For debugging the code of CPAN.pm itself in interactive mode, some
1692 debugging aid can be turned on for most packages within CPAN.pm with
1693 one of
1694 o debug package...
1696 sets debug mode for packages.
1697 o debug -package...
1699 unsets debug mode for packages.
1700 o debug all
1702 turns debugging on for all packages.
1703 o debug number
1705 which sets the debugging packages directly. Note that "o debug 0" turns
1707 debugging off.
1708 What seems a successful strategy is the combination of "reload cpan"
1710 and the debugging switches. Add a new debug statement while running in
1711 the shell and then issue a "reload cpan" and see the new debugging
1712 messages immediately without losing the current context.
1713 "o debug" without an argument lists the valid package names and the
1715 current set of packages in debugging mode. "o debug" has built-in
1716 completion support.
1717 For debugging of CPAN data there is the "dump" command which takes the
1719 same arguments as make/test/install and outputs each object's
1720 Data::Dumper dump. If an argument looks like a perl variable and
1721 contains one of "$", "@" or "%", it is eval()ed and fed to Data::Dumper
1722 directly.
1723 Floppy, Zip, Offline Mode
1725 CPAN.pm works nicely without network access, too. If you maintain
1726 machines that are not networked at all, you should consider working
1727 with "file:" URLs. You'll have to collect your modules somewhere first.
1728 So you might use CPAN.pm to put together all you need on a networked
1729 machine. Then copy the $CPAN::Config->{keep_source_where} (but not
1730 $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
1731 of a personal CPAN. CPAN.pm on the non-networked machines works nicely
1732 with this floppy. See also below the paragraph about CD-ROM support.
1733 Basic Utilities for Programmers
1735 has_inst($module)
1736 Returns true if the module is installed. Used to load all modules
1737 into the running CPAN.pm that are considered optional. The config
1738 variable "dontload_list" intercepts the "has_inst()" call such that
1739 an optional module is not loaded despite being available. For
1740 example, the following command will prevent "YAML.pm" from being
1741 loaded:
1742 cpan> o conf dontload_list push YAML
1744 See the source for details.
1746 has_usable($module)
1748 Returns true if the module is installed and in a usable state. Only
1749 useful for a handful of modules that are used internally. See the
1750 source for details.
1751 instance($module)
1753 The constructor for all the singletons used to represent modules,
1754 distributions, authors, and bundles. If the object already exists,
1755 this method returns the object; otherwise, it calls the constructor.
1756
1758 There's no strong security layer in CPAN.pm. CPAN.pm helps you to
1759 install foreign, unmasked, unsigned code on your machine. We compare to
1760 a checksum that comes from the net just as the distribution file
1761 itself. But we try to make it easy to add security on demand:
1762 Cryptographically signed modules
1764 Since release 1.77, CPAN.pm has been able to verify cryptographically
1765 signed module distributions using Module::Signature. The CPAN modules
1766 can be signed by their authors, thus giving more security. The simple
1767 unsigned MD5 checksums that were used before by CPAN protect mainly
1768 against accidental file corruption.
1769 You will need to have Module::Signature installed, which in turn
1771 requires that you have at least one of Crypt::OpenPGP module or the
1772 command-line gpg tool installed.
1773 You will also need to be able to connect over the Internet to the
1775 public key servers, like pgp.mit.edu, and their port 11731 (the HKP
1776 protocol).
1777 The configuration parameter check_sigs is there to turn signature
1779 checking on or off.
1780
1782 Most functions in package CPAN are exported by default. The reason for
1783 this is that the primary use is intended for the cpan shell or for one-
1784 liners.
1785
1787 When the CPAN shell enters a subshell via the look command, it sets the
1788 environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
1789 already set.
1790 When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
1792 to the ID of the running process. It also sets
1793 PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
1794 happen with older versions of Module::Install.
1795 When running "perl Makefile.PL", the environment variable
1797 "PERL5_CPAN_IS_EXECUTING" is set to the full path of the "Makefile.PL"
1798 that is being executed. This prevents runaway processes with newer
1799 versions of Module::Install.
1800 When the config variable ftp_passive is set, all downloads will be run
1802 with the environment variable FTP_PASSIVE set to this value. This is in
1803 general a good idea as it influences both Net::FTP and LWP based
1804 connections. The same effect can be achieved by starting the cpan shell
1805 with this environment variable set. For Net::FTP alone, one can also
1806 always set passive mode by running libnetcfg.
1807
1809 Populating a freshly installed perl with one's favorite modules is
1810 pretty easy if you maintain a private bundle definition file. To get a
1811 useful blueprint of a bundle definition file, the command autobundle
1812 can be used on the CPAN shell command line. This command writes a
1813 bundle definition file for all modules installed for the current perl
1814 interpreter. It's recommended to run this command once only, and from
1815 then on maintain the file manually under a private name, say
1816 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
1817 cpan> install Bundle::my_bundle
1819 then answer a few questions and go out for coffee (possibly even in a
1821 different city).
1822 Maintaining a bundle definition file means keeping track of two things:
1824 dependencies and interactivity. CPAN.pm sometimes fails on calculating
1825 dependencies because not all modules define all MakeMaker attributes
1826 correctly, so a bundle definition file should specify prerequisites as
1827 early as possible. On the other hand, it's annoying that so many
1828 distributions need some interactive configuring. So what you can try to
1829 accomplish in your private bundle file is to have the packages that
1830 need to be configured early in the file and the gentle ones later, so
1831 you can go out for coffee after a few minutes and leave CPAN.pm to
1832 churn away untended.
1833
1835 Thanks to Graham Barr for contributing the following paragraphs about
1836 the interaction between perl, and various firewall configurations. For
1837 further information on firewalls, it is recommended to consult the
1838 documentation that comes with the ncftp program. If you are unable to
1839 go through the firewall with a simple Perl setup, it is likely that you
1840 can configure ncftp so that it works through your firewall.
1841 Three basic types of firewalls
1843 Firewalls can be categorized into three basic types.
1844 http firewall
1846 This is when the firewall machine runs a web server, and to access
1847 the outside world, you must do so via that web server. If you set
1848 environment variables like http_proxy or ftp_proxy to values
1849 beginning with http://, or in your web browser you've proxy
1850 information set, then you know you are running behind an http
1851 firewall.
1852 To access servers outside these types of firewalls with perl (even
1854 for ftp), you need LWP or HTTP::Tiny.
1855 ftp firewall
1857 This where the firewall machine runs an ftp server. This kind of
1858 firewall will only let you access ftp servers outside the firewall.
1859 This is usually done by connecting to the firewall with ftp, then
1860 entering a username like "user@outside.host.com".
1861 To access servers outside these type of firewalls with perl, you
1863 need Net::FTP.
1864 One-way visibility
1866 One-way visibility means these firewalls try to make themselves
1867 invisible to users inside the firewall. An FTP data connection is
1868 normally created by sending your IP address to the remote server
1869 and then listening for the return connection. But the remote server
1870 will not be able to connect to you because of the firewall. For
1871 these types of firewall, FTP connections need to be done in a
1872 passive mode.
1873 There are two that I can think off.
1875 SOCKS
1877 If you are using a SOCKS firewall, you will need to compile
1878 perl and link it with the SOCKS library. This is what is
1879 normally called a 'socksified' perl. With this executable you
1880 will be able to connect to servers outside the firewall as if
1881 it were not there.
1882 IP Masquerade
1884 This is when the firewall implemented in the kernel (via NAT,
1885 or networking address translation), it allows you to hide a
1886 complete network behind one IP address. With this firewall no
1887 special compiling is needed as you can access hosts directly.
1888 For accessing ftp servers behind such firewalls you usually
1890 need to set the environment variable "FTP_PASSIVE" or the
1891 config variable ftp_passive to a true value.
1892 Configuring lynx or ncftp for going through a firewall
1894 If you can go through your firewall with e.g. lynx, presumably with a
1895 command such as
1896 /usr/local/bin/lynx -pscott:tiger
1898 then you would configure CPAN.pm with the command
1900 o conf lynx "/usr/local/bin/lynx -pscott:tiger"
1902 That's all. Similarly for ncftp or ftp, you would configure something
1904 like
1905 o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"
1907 Your mileage may vary...
1909
1911 1) I installed a new version of module X but CPAN keeps saying, I have
1912 the old version installed
1913 Probably you do have the old version installed. This can happen if
1915 a module installs itself into a different directory in the @INC
1916 path than it was previously installed. This is not really a CPAN.pm
1917 problem, you would have the same problem when installing the module
1918 manually. The easiest way to prevent this behaviour is to add the
1919 argument "UNINST=1" to the "make install" call, and that is why
1920 many people add this argument permanently by configuring
1921 o conf make_install_arg UNINST=1
1923 2) So why is UNINST=1 not the default?
1925 Because there are people who have their precise expectations about
1927 who may install where in the @INC path and who uses which @INC
1928 array. In fine tuned environments "UNINST=1" can cause damage.
1929 3) I want to clean up my mess, and install a new perl along with all
1931 modules I have. How do I go about it?
1932 Run the autobundle command for your old perl and optionally rename
1934 the resulting bundle file (e.g. Bundle/mybundle.pm), install the
1935 new perl with the Configure option prefix, e.g.
1936 ./Configure -Dprefix=/usr/local/perl-5.6.78.9
1938 Install the bundle file you produced in the first step with
1940 something like
1941 cpan> install Bundle::mybundle
1943 and you're done.
1945 4) When I install bundles or multiple modules with one command there
1947 is too much output to keep track of.
1948 You may want to configure something like
1950 o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
1952 o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"
1953 so that STDOUT is captured in a file for later inspection.
1955 5) I am not root, how can I install a module in a personal directory?
1957 As of CPAN 1.9463, if you do not have permission to write the
1959 default perl library directories, CPAN's configuration process will
1960 ask you whether you want to bootstrap <local::lib>, which makes
1961 keeping a personal perl library directory easy.
1962 Another thing you should bear in mind is that the UNINST parameter
1964 can be dangerous when you are installing into a private area
1965 because you might accidentally remove modules that other people
1966 depend on that are not using the private area.
1967 6) How to get a package, unwrap it, and make a change before building
1969 it?
1970 Have a look at the "look" (!) command.
1972 7) I installed a Bundle and had a couple of fails. When I retried,
1974 everything resolved nicely. Can this be fixed to work on first try?
1975 The reason for this is that CPAN does not know the dependencies of
1977 all modules when it starts out. To decide about the additional
1978 items to install, it just uses data found in the META.yml file or
1979 the generated Makefile. An undetected missing piece breaks the
1980 process. But it may well be that your Bundle installs some
1981 prerequisite later than some depending item and thus your second
1982 try is able to resolve everything. Please note, CPAN.pm does not
1983 know the dependency tree in advance and cannot sort the queue of
1984 things to install in a topologically correct order. It resolves
1985 perfectly well if all modules declare the prerequisites correctly
1986 with the PREREQ_PM attribute to MakeMaker or the "requires" stanza
1987 of Module::Build. For bundles which fail and you need to install
1988 often, it is recommended to sort the Bundle definition file
1989 manually.
1990 8) In our intranet, we have many modules for internal use. How can I
1992 integrate these modules with CPAN.pm but without uploading the
1993 modules to CPAN?
1994 Have a look at the CPAN::Site module.
1996 9) When I run CPAN's shell, I get an error message about things in my
1998 "/etc/inputrc" (or "~/.inputrc") file.
1999 These are readline issues and can only be fixed by studying
2001 readline configuration on your architecture and adjusting the
2002 referenced file accordingly. Please make a backup of the
2003 "/etc/inputrc" or "~/.inputrc" and edit them. Quite often harmless
2004 changes like uppercasing or lowercasing some arguments solves the
2005 problem.
2006 10) Some authors have strange characters in their names.
2008 Internally CPAN.pm uses the UTF-8 charset. If your terminal is
2010 expecting ISO-8859-1 charset, a converter can be activated by
2011 setting term_is_latin to a true value in your config file. One way
2012 of doing so would be
2013 cpan> o conf term_is_latin 1
2015 If other charset support is needed, please file a bug report
2017 against CPAN.pm at rt.cpan.org and describe your needs. Maybe we
2018 can extend the support or maybe UTF-8 terminals become widely
2019 available.
2020 Note: this config variable is deprecated and will be removed in a
2022 future version of CPAN.pm. It will be replaced with the conventions
2023 around the family of $LANG and $LC_* environment variables.
2024 11) When an install fails for some reason and then I correct the error
2026 condition and retry, CPAN.pm refuses to install the module, saying
2027 "Already tried without success".
2028 Use the force pragma like so
2030 force install Foo::Bar
2032 Or you can use
2034 look Foo::Bar
2036 and then "make install" directly in the subshell.
2038 12) How do I install a "DEVELOPER RELEASE" of a module?
2040 By default, CPAN will install the latest non-developer release of a
2042 module. If you want to install a dev release, you have to specify
2043 the partial path starting with the author id to the tarball you
2044 wish to install, like so:
2045 cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
2047 Note that you can use the "ls" command to get this path listed.
2049 13) How do I install a module and all its dependencies from the
2051 commandline, without being prompted for anything, despite my CPAN
2052 configuration (or lack thereof)?
2053 CPAN uses ExtUtils::MakeMaker's prompt() function to ask its
2055 questions, so if you set the PERL_MM_USE_DEFAULT environment
2056 variable, you shouldn't be asked any questions at all (assuming the
2057 modules you are installing are nice about obeying that variable as
2058 well):
2059 % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'
2061 14) How do I create a Module::Build based Build.PL derived from an
2063 ExtUtils::MakeMaker focused Makefile.PL?
2064 http://search.cpan.org/dist/Module-Build-Convert/
2066 15) I'm frequently irritated with the CPAN shell's inability to help me
2068 select a good mirror.
2069 CPAN can now help you select a "good" mirror, based on which ones
2071 have the lowest 'ping' round-trip times. From the shell, use the
2072 command 'o conf init urllist' and allow CPAN to automatically
2073 select mirrors for you.
2074 Beyond that help, the urllist config parameter is yours. You can
2076 add and remove sites at will. You should find out which sites have
2077 the best up-to-dateness, bandwidth, reliability, etc. and are
2078 topologically close to you. Some people prefer fast downloads,
2079 others up-to-dateness, others reliability. You decide which to try
2080 in which order.
2081 Henk P. Penning maintains a site that collects data about CPAN
2083 sites:
2084 http://www.cs.uu.nl/people/henkp/mirmon/cpan.html
2086 Also, feel free to play with experimental features. Run
2088 o conf init randomize_urllist ftpstats_period ftpstats_size
2090 and choose your favorite parameters. After a few downloads running
2092 the "hosts" command will probably assist you in choosing the best
2093 mirror sites.
2094 16) Why do I get asked the same questions every time I start the shell?
2096 You can make your configuration changes permanent by calling the
2098 command "o conf commit". Alternatively set the "auto_commit"
2099 variable to true by running "o conf init auto_commit" and answering
2100 the following question with yes.
2101 17) Older versions of CPAN.pm had the original root directory of all
2103 tarballs in the build directory. Now there are always random
2104 characters appended to these directory names. Why was this done?
2105 The random characters are provided by File::Temp and ensure that
2107 each module's individual build directory is unique. This makes
2108 running CPAN.pm in concurrent processes simultaneously safe.
2109 18) Speaking of the build directory. Do I have to clean it up myself?
2111 You have the choice to set the config variable "scan_cache" to
2113 "never". Then you must clean it up yourself. The other possible
2114 values, "atstart" and "atexit" clean up the build directory when
2115 you start or exit the CPAN shell, respectively. If you never start
2116 up the CPAN shell, you probably also have to clean up the build
2117 directory yourself.
2118
2120 OLD PERL VERSIONS
2121 CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted
2122 newer versions. It is getting more and more difficult to get the
2123 minimal prerequisites working on older perls. It is close to impossible
2124 to get the whole Bundle::CPAN working there. If you're in the position
2125 to have only these old versions, be advised that CPAN is designed to
2126 work fine without the Bundle::CPAN installed.
2127 To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
2129 compatible with ancient perls and that File::Temp is listed as a
2130 prerequisite but CPAN has reasonable workarounds if it is missing.
2131 CPANPLUS
2133 This module and its competitor, the CPANPLUS module, are both much
2134 cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
2135 more modular, but it was never intended to be compatible with CPAN.pm.
2136 CPANMINUS
2138 In the year 2010 App::cpanminus was launched as a new approach to a
2139 cpan shell with a considerably smaller footprint. Very cool stuff.
2140
2142 This software enables you to upgrade software on your computer and so
2143 is inherently dangerous because the newly installed software may
2144 contain bugs and may alter the way your computer works or even make it
2145 unusable. Please consider backing up your data before every upgrade.
2146
2148 Please report bugs via <http://rt.cpan.org/>
2149 Before submitting a bug, please make sure that the traditional method
2151 of building a Perl module package from a shell by following the
2152 installation instructions of that package still works in your
2153 environment.
2154
2156 Andreas Koenig "<andk@cpan.org>"
2157
2159 This program is free software; you can redistribute it and/or modify it
2160 under the same terms as Perl itself.
2161 See <http://www.perl.com/perl/misc/Artistic.html>
2163
2165 Kawai,Takanori provides a Japanese translation of a very old version of
2166 this manpage at
2167 <http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
2168
2170 Many people enter the CPAN shell by running the cpan utility program
2171 which is installed in the same directory as perl itself. So if you have
2172 this directory in your PATH variable (or some equivalent in your
2173 operating system) then typing "cpan" in a console window will work for
2174 you as well. Above that the utility provides several commandline
2175 shortcuts.
2176perl v5.16.3 2013-03-04 CPAN(3pm)