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 Net::FTP, LWP, and certain external
48 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. If the argument is a distribution
147 file name (recognized by embedded slashes), it is processed. If it is
148 a module, CPAN determines the distribution file in which this module
149 is included and processes that, following any dependencies named in
150 the module's META.yml or Makefile.PL (this behavior is controlled by
151 the configuration parameter "prerequisites_policy".)
152 "get" downloads a distribution file and untars or unzips it, "make"
154 builds it, "test" runs the test suite, and "install" installs it.
155 Any "make" or "test" is run unconditionally. An
157 install <distribution_file>
159 is also run unconditionally. But for
161 install <module>
163 CPAN checks whether an install is needed and prints module up to date
165 if the distribution file containing the module doesn't need updating.
166 CPAN also keeps track of what it has done within the current session
168 and doesn't try to build a package a second time regardless of
169 whether it succeeded or not. It does not repeat a test run if the
170 test has been run successfully before. Same for install runs.
171 The "force" pragma may precede another command (currently: "get",
173 "make", "test", or "install") to execute the command from scratch and
174 attempt to continue past certain errors. See the section below on the
175 "force" and the "fforce" pragma.
176 The "notest" pragma skips the test part in the build process.
178 Example:
180 cpan> notest install Tk
182 A "clean" command results in a
184 make clean
186 being executed within the distribution file's working directory.
188 "readme", "perldoc", "look" module or distribution
190 "readme" displays the README file of the associated distribution.
191 "Look" gets and untars (if not yet done) the distribution file,
192 changes to the appropriate directory and opens a subshell process in
193 that directory. "perldoc" displays the module's pod documentation in
194 html or plain text format.
195 "ls" author
197 "ls" globbing_expression
198 The first form lists all distribution files in and below an author's
199 CPAN directory as stored in the CHECKUMS files distributed on CPAN.
200 The listing recurses into subdirectories.
201 The second form limits or expands the output with shell globbing as
203 in the following examples:
204 ls JV/make*
206 ls GSAR/*make*
207 ls */*make*
208 The last example is very slow and outputs extra progress indicators
210 that break the alignment of the result.
211 Note that globbing only lists directories explicitly asked for, for
213 example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may
214 be regarded as a bug that may be changed in some future version.
215 "failed"
217 The "failed" command reports all distributions that failed on one of
218 "make", "test" or "install" for some reason in the currently running
219 shell session.
220 Persistence between sessions
222 If the "YAML" or the "YAML::Syck" module is installed a record of the
223 internal state of all modules is written to disk after each step.
224 The files contain a signature of the currently running perl version
225 for later perusal.
226 If the configurations variable "build_dir_reuse" is set to a true
228 value, then CPAN.pm reads the collected YAML files. If the stored
229 signature matches the currently running perl, the stored state is
230 loaded into memory such that persistence between sessions is
231 effectively established.
232 The "force" and the "fforce" pragma
234 To speed things up in complex installation scenarios, CPAN.pm keeps
235 track of what it has already done and refuses to do some things a
236 second time. A "get", a "make", and an "install" are not repeated. A
237 "test" is repeated only if the previous test was unsuccessful. The
238 diagnostic message when CPAN.pm refuses to do something a second time
239 is one of Has already been "unwrapped|made|tested successfully" or
240 something similar. Another situation where CPAN refuses to act is an
241 "install" if the corresponding "test" was not successful.
242 In all these cases, the user can override this stubborn behaviour by
244 prepending the command with the word force, for example:
245 cpan> force get Foo
247 cpan> force make AUTHOR/Bar-3.14.tar.gz
248 cpan> force test Baz
249 cpan> force install Acme::Meta
250 Each forced command is executed with the corresponding part of its
252 memory erased.
253 The "fforce" pragma is a variant that emulates a "force get" which
255 erases the entire memory followed by the action specified,
256 effectively restarting the whole get/make/test/install procedure from
257 scratch.
258 Lockfile
260 Interactive sessions maintain a lockfile, by default "~/.cpan/.lock".
261 Batch jobs can run without a lockfile and not disturb each other.
262 The shell offers to run in downgraded mode when another process is
264 holding the lockfile. This is an experimental feature that is not yet
265 tested very well. This second shell then does not write the history
266 file, does not use the metadata file, and has a different prompt.
267 Signals
269 CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you
270 are in the cpan-shell, it is intended that you can press "^C" anytime
271 and return to the cpan-shell prompt. A SIGTERM will cause the cpan-
272 shell to clean up and leave the shell loop. You can emulate the
273 effect of a SIGTERM by sending two consecutive SIGINTs, which usually
274 means by pressing "^C" twice.
275 CPAN.pm ignores SIGPIPE. If the user sets "inactivity_timeout", a
277 SIGALRM is used during the run of the "perl Makefile.PL" or "perl
278 Build.PL" subprocess.
279 CPAN::Shell
281 The commands available in the shell interface are methods in the
282 package CPAN::Shell. If you enter the shell command, your input is
283 split by the Text::ParseWords::shellwords() routine, which acts like
284 most shells do. The first word is interpreted as the method to be
285 invoked, and the rest of the words are treated as the method's
286 arguments. Continuation lines are supported by ending a line with a
287 literal backslash.
288 autobundle
290 "autobundle" writes a bundle file into the
291 "$CPAN::Config->{cpan_home}/Bundle" directory. The file contains a list
292 of all modules that are both available from CPAN and currently
293 installed within @INC. The name of the bundle file is based on the
294 current date and a counter.
295 hosts
297 Note: this feature is still in alpha state and may change in future
298 versions of CPAN.pm
299 This commands provides a statistical overview over recent download
301 activities. The data for this is collected in the YAML file
302 "FTPstats.yml" in your "cpan_home" directory. If no YAML module is
303 configured or YAML not installed, no stats are provided.
304 mkmyconfig
306 mkmyconfig() writes your own CPAN::MyConfig file into your "~/.cpan/"
307 directory so that you can save your own preferences instead of the
308 system-wide ones.
309 recent ***EXPERIMENTAL COMMAND***
311 The "recent" command downloads a list of recent uploads to CPAN and
312 displays them slowly. While the command is running, a $SIG{INT} exits
313 the loop after displaying the current item.
314 Note: This command requires XML::LibXML installed.
316 Note: This whole command currently is just a hack and will probably
318 change in future versions of CPAN.pm, but the general approach will
319 likely remain.
320 Note: See also smoke
322 recompile
324 recompile() is a special command that takes no argument and runs the
325 make/test/install cycle with brute force over all installed dynamically
326 loadable extensions (aka XS modules) with 'force' in effect. The
327 primary purpose of this command is to finish a network installation.
328 Imagine you have a common source tree for two different architectures.
329 You decide to do a completely independent fresh installation. You start
330 on one architecture with the help of a Bundle file produced earlier.
331 CPAN installs the whole Bundle for you, but when you try to repeat the
332 job on the second architecture, CPAN responds with a "Foo up to date"
333 message for all modules. So you invoke CPAN's recompile on the second
334 architecture and you're done.
335 Another popular use for "recompile" is to act as a rescue in case your
337 perl breaks binary compatibility. If one of the modules that CPAN uses
338 is in turn depending on binary compatibility (so you cannot run CPAN
339 commands), then you should try the CPAN::Nox module for recovery.
340 report Bundle|Distribution|Module
342 The "report" command temporarily turns on the "test_report" config
343 variable, then runs the "force test" command with the given arguments.
344 The "force" pragma reruns the tests and repeats every step that might
345 have failed before.
346 smoke ***EXPERIMENTAL COMMAND***
348 *** WARNING: this command downloads and executes software from CPAN to
349 your computer of completely unknown status. You should never do this
350 with your normal account and better have a dedicated well separated and
351 secured machine to do this. ***
352 The "smoke" command takes the list of recent uploads to CPAN as
354 provided by the "recent" command and tests them all. While the command
355 is running $SIG{INT} is defined to mean that the current item shall be
356 skipped.
357 Note: This whole command currently is just a hack and will probably
359 change in future versions of CPAN.pm, but the general approach will
360 likely remain.
361 Note: See also recent
363 upgrade [Module|/Regex/]...
365 The "upgrade" command first runs an "r" command with the given
366 arguments and then installs the newest versions of all modules that
367 were listed by that.
368 The four "CPAN::*" Classes: Author, Bundle, Module, Distribution
370 Although it may be considered internal, the class hierarchy does matter
371 for both users and programmer. CPAN.pm deals with the four classes
372 mentioned above, and those classes all share a set of methods.
373 Classical single polymorphism is in effect. A metaclass object
374 registers all objects of all kinds and indexes them with a string. The
375 strings referencing objects have a separated namespace (well, not
376 completely separated):
377 Namespace Class
379 words containing a "/" (slash) Distribution
381 words starting with Bundle:: Bundle
382 everything else Module or Author
383 Modules know their associated Distribution objects. They always refer
385 to the most recent official release. Developers may mark their releases
386 as unstable development versions (by inserting an underbar into the
387 module version number which will also be reflected in the distribution
388 name when you run 'make dist'), so the really hottest and newest
389 distribution is not always the default. If a module Foo circulates on
390 CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient way
391 to install version 1.23 by saying
392 install Foo
394 This would install the complete distribution file (say
396 BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
397 like to install version 1.23_90, you need to know where the
398 distribution file resides on CPAN relative to the authors/id/
399 directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
400 so you would have to say
401 install BAR/Foo-1.23_90.tar.gz
403 The first example will be driven by an object of the class
405 CPAN::Module, the second by an object of class CPAN::Distribution.
406 Integrating local directories
408 Note: this feature is still in alpha state and may change in future
409 versions of CPAN.pm
410 Distribution objects are normally distributions from the CPAN, but
412 there is a slightly degenerate case for Distribution objects, too, of
413 projects held on the local disk. These distribution objects have the
414 same name as the local directory and end with a dot. A dot by itself is
415 also allowed for the current directory at the time CPAN.pm was used.
416 All actions such as "make", "test", and "install" are applied directly
417 to that directory. This gives the command "cpan ." an interesting
418 touch: while the normal mantra of installing a CPAN module without
419 CPAN.pm is one of
420 perl Makefile.PL perl Build.PL
422 ( go and get prerequisites )
423 make ./Build
424 make test ./Build test
425 make install ./Build install
426 the command "cpan ." does all of this at once. It figures out which of
428 the two mantras is appropriate, fetches and installs all prerequisites,
429 takes care of them recursively, and finally finishes the installation
430 of the module in the current directory, be it a CPAN module or not.
431 The typical usage case is for private modules or working copies of
433 projects from remote repositories on the local disk.
434 Redirection
436 The usual shell redirection symbols " | " and ">" are recognized by the
437 cpan shell only when surrounded by whitespace. So piping to pager or
438 redirecting output into a file works somewhat as in a normal shell,
439 with the stipulation that you must type extra spaces.
440
442 When the CPAN module is used for the first time, a configuration
443 dialogue tries to determine a couple of site specific options. The
444 result of the dialog is stored in a hash reference $CPAN::Config in a
445 file CPAN/Config.pm.
446 Default values defined in the CPAN/Config.pm file can be overridden in
448 a user specific file: CPAN/MyConfig.pm. Such a file is best placed in
449 "$HOME/.cpan/CPAN/MyConfig.pm", because "$HOME/.cpan" is added to the
450 search path of the CPAN module before the use() or require()
451 statements. The mkmyconfig command writes this file for you.
452 The "o conf" command has various bells and whistles:
454 completion support
456 If you have a ReadLine module installed, you can hit TAB at any
457 point of the commandline and "o conf" will offer you completion for
458 the built-in subcommands and/or config variable names.
459 displaying some help: o conf help
461 Displays a short help
462 displaying current values: o conf [KEY]
464 Displays the current value(s) for this config variable. Without
465 KEY, displays all subcommands and config variables.
466 Example:
468 o conf shell
470 If KEY starts and ends with a slash, the string in between is
472 treated as a regular expression and only keys matching this regex
473 are displayed
474 Example:
476 o conf /color/
478 changing of scalar values: o conf KEY VALUE
480 Sets the config variable KEY to VALUE. The empty string can be
481 specified as usual in shells, with '' or ""
482 Example:
484 o conf wget /usr/bin/wget
486 changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
488 If a config variable name ends with "list", it is a list. "o conf
489 KEY shift" removes the first element of the list, "o conf KEY pop"
490 removes the last element of the list. "o conf KEYS unshift LIST"
491 prepends a list of values to the list, "o conf KEYS push LIST"
492 appends a list of valued to the list.
493 Likewise, "o conf KEY splice LIST" passes the LIST to the
495 corresponding splice command.
496 Finally, any other list of arguments is taken as a new list value
498 for the KEY variable discarding the previous value.
499 Examples:
501 o conf urllist unshift http://cpan.dev.local/CPAN
503 o conf urllist splice 3 1
504 o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
505 reverting to saved: o conf defaults
507 Reverts all config variables to the state in the saved config file.
508 saving the config: o conf commit
510 Saves all config variables to the current config file
511 (CPAN/Config.pm or CPAN/MyConfig.pm that was loaded at start).
512 The configuration dialog can be started any time later again by issuing
514 the command " o conf init " in the CPAN shell. A subset of the
515 configuration dialog can be run by issuing "o conf init WORD" where
516 WORD is any valid config variable or a regular expression.
517 Config Variables
519 The following keys in the hash reference $CPAN::Config are currently
520 defined:
521 applypatch path to external prg
523 auto_commit commit all changes to config variables to disk
524 build_cache size of cache for directories to build modules
525 build_dir locally accessible directory to build modules
526 build_dir_reuse boolean if distros in build_dir are persistent
527 build_requires_install_policy
528 to install or not to install when a module is
529 only needed for building. yes|no|ask/yes|ask/no
530 bzip2 path to external prg
531 cache_metadata use serializer to cache metadata
532 check_sigs if signatures should be verified
533 colorize_debug Term::ANSIColor attributes for debugging output
534 colorize_output boolean if Term::ANSIColor should colorize output
535 colorize_print Term::ANSIColor attributes for normal output
536 colorize_warn Term::ANSIColor attributes for warnings
537 commandnumber_in_prompt
538 boolean if you want to see current command number
539 commands_quote preferred character to use for quoting external
540 commands when running them. Defaults to double
541 quote on Windows, single tick everywhere else;
542 can be set to space to disable quoting
543 connect_to_internet_ok
544 whether to ask if opening a connection is ok before
545 urllist is specified
546 cpan_home local directory reserved for this package
547 curl path to external prg
548 dontload_hash DEPRECATED
549 dontload_list arrayref: modules in the list will not be
550 loaded by the CPAN::has_inst() routine
551 ftp path to external prg
552 ftp_passive if set, the envariable FTP_PASSIVE is set for downloads
553 ftp_proxy proxy host for ftp requests
554 ftpstats_period max number of days to keep download statistics
555 ftpstats_size max number of items to keep in the download statistics
556 getcwd see below
557 gpg path to external prg
558 gzip location of external program gzip
559 halt_on_failure stop processing after the first failure of queued
560 items or dependencies
561 histfile file to maintain history between sessions
562 histsize maximum number of lines to keep in histfile
563 http_proxy proxy host for http requests
564 inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
565 after this many seconds inactivity. Set to 0 to
566 disable timeouts.
567 index_expire refetch index files after this many days
568 inhibit_startup_message
569 if true, suppress the startup message
570 keep_source_where directory in which to keep the source (if we do)
571 load_module_verbosity
572 report loading of optional modules used by CPAN.pm
573 lynx path to external prg
574 make location of external make program
575 make_arg arguments that should always be passed to 'make'
576 make_install_make_command
577 the make command for running 'make install', for
578 example 'sudo make'
579 make_install_arg same as make_arg for 'make install'
580 makepl_arg arguments passed to 'perl Makefile.PL'
581 mbuild_arg arguments passed to './Build'
582 mbuild_install_arg arguments passed to './Build install'
583 mbuild_install_build_command
584 command to use instead of './Build' when we are
585 in the install stage, for example 'sudo ./Build'
586 mbuildpl_arg arguments passed to 'perl Build.PL'
587 ncftp path to external prg
588 ncftpget path to external prg
589 no_proxy don't proxy to these hosts/domains (comma separated list)
590 pager location of external program more (or any pager)
591 password your password if you CPAN server wants one
592 patch path to external prg
593 patches_dir local directory containing patch files
594 perl5lib_verbosity verbosity level for PERL5LIB additions
595 prefer_installer legal values are MB and EUMM: if a module comes
596 with both a Makefile.PL and a Build.PL, use the
597 former (EUMM) or the latter (MB); if the module
598 comes with only one of the two, that one will be
599 used no matter the setting
600 prerequisites_policy
601 what to do if you are missing module prerequisites
602 ('follow' automatically, 'ask' me, or 'ignore')
603 prefs_dir local directory to store per-distro build options
604 proxy_user username for accessing an authenticating proxy
605 proxy_pass password for accessing an authenticating proxy
606 randomize_urllist add some randomness to the sequence of the urllist
607 scan_cache controls scanning of cache ('atstart' or 'never')
608 shell your favorite shell
609 show_unparsable_versions
610 boolean if r command tells which modules are versionless
611 show_upload_date boolean if commands should try to determine upload date
612 show_zero_versions boolean if r command tells for which modules $version==0
613 tar location of external program tar
614 tar_verbosity verbosity level for the tar command
615 term_is_latin deprecated: if true Unicode is translated to ISO-8859-1
616 (and nonsense for characters outside latin range)
617 term_ornaments boolean to turn ReadLine ornamenting on/off
618 test_report email test reports (if CPAN::Reporter is installed)
619 trust_test_report_history
620 skip testing when previously tested ok (according to
621 CPAN::Reporter history)
622 unzip location of external program unzip
623 urllist arrayref to nearby CPAN sites (or equivalent locations)
624 use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
625 username your username if you CPAN server wants one
626 wait_list arrayref to a wait server to try (See CPAN::WAIT)
627 wget path to external prg
628 yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
629 yaml_module which module to use to read/write YAML files
630 You can set and query each of these options interactively in the cpan
632 shell with the "o conf" or the "o conf init" command as specified
633 below.
634 "o conf <scalar option>"
636 prints the current value of the scalar option
637 "o conf <scalar option> <value>"
639 Sets the value of the scalar option to value
640 "o conf <list option>"
642 prints the current value of the list option in MakeMaker's neatvalue
643 format.
644 "o conf <list option> [shift|pop]"
646 shifts or pops the array in the list option variable
647 "o conf <list option> [unshift|push|splice] <list>"
649 works like the corresponding perl commands.
650 interactive editing: o conf init [MATCH|LIST]
652 Runs an interactive configuration dialog for matching variables.
653 Without argument runs the dialog over all supported config variables.
654 To specify a MATCH the argument must be enclosed by slashes.
655 Examples:
657 o conf init ftp_passive ftp_proxy
659 o conf init /color/
660 Note: this method of setting config variables often provides more
662 explanation about the functioning of a variable than the manpage.
663 CPAN::anycwd($path): Note on config variable getcwd
665 CPAN.pm changes the current working directory often and needs to
666 determine its own current working directory. By default it uses
667 Cwd::cwd, but if for some reason this doesn't work on your system,
668 configure alternatives according to the following table:
669 cwd Calls Cwd::cwd
671 getcwd
673 Calls Cwd::getcwd
674 fastcwd
676 Calls Cwd::fastcwd
677 backtickcwd
679 Calls the external command cwd.
680 Note on the format of the urllist parameter
682 urllist parameters are URLs according to RFC 1738. We do a little
683 guessing if your URL is not compliant, but if you have problems with
684 "file" URLs, please try the correct format. Either:
685 file://localhost/whatever/ftp/pub/CPAN/
687 or
689 file:///home/ftp/pub/CPAN/
691 The urllist parameter has CD-ROM support
693 The "urllist" parameter of the configuration table contains a list of
694 URLs used for downloading. If the list contains any "file" URLs, CPAN
695 always tries there first. This feature is disabled for index files. So
696 the recommendation for the owner of a CD-ROM with CPAN contents is:
697 include your local, possibly outdated CD-ROM as a "file" URL at the end
698 of urllist, e.g.
699 o conf urllist push file://localhost/CDROM/CPAN
701 CPAN.pm will then fetch the index files from one of the CPAN sites that
703 come at the beginning of urllist. It will later check for each module
704 to see whether there is a local copy of the most recent version.
705 Another peculiarity of urllist is that the site that we could
707 successfully fetch the last file from automatically gets a preference
708 token and is tried as the first site for the next request. So if you
709 add a new site at runtime it may happen that the previously preferred
710 site will be tried another time. This means that if you want to
711 disallow a site for the next transfer, it must be explicitly removed
712 from urllist.
713 Maintaining the urllist parameter
715 If you have YAML.pm (or some other YAML module configured in
716 "yaml_module") installed, CPAN.pm collects a few statistical data about
717 recent downloads. You can view the statistics with the "hosts" command
718 or inspect them directly by looking into the "FTPstats.yml" file in
719 your "cpan_home" directory.
720 To get some interesting statistics, it is recommended that
722 "randomize_urllist" be set; this introduces some amount of randomness
723 into the URL selection.
724 The "requires" and "build_requires" dependency declarations
726 Since CPAN.pm version 1.88_51 modules declared as "build_requires" by a
727 distribution are treated differently depending on the config variable
728 "build_requires_install_policy". By setting
729 "build_requires_install_policy" to "no", such a module is not
730 installed. It is only built and tested, and then kept in the list of
731 tested but uninstalled modules. As such, it is available during the
732 build of the dependent module by integrating the path to the
733 "blib/arch" and "blib/lib" directories in the environment variable
734 PERL5LIB. If "build_requires_install_policy" is set ti "yes", then both
735 modules declared as "requires" and those declared as "build_requires"
736 are treated alike. By setting to "ask/yes" or "ask/no", CPAN.pm asks
737 the user and sets the default accordingly.
738 Configuration for individual distributions (Distroprefs)
740 (Note: This feature has been introduced in CPAN.pm 1.8854 and is still
741 considered beta quality)
742 Distributions on CPAN usually behave according to what we call the CPAN
744 mantra. Or since the advent of Module::Build we should talk about two
745 mantras:
746 perl Makefile.PL perl Build.PL
748 make ./Build
749 make test ./Build test
750 make install ./Build install
751 But some modules cannot be built with this mantra. They try to get some
753 extra data from the user via the environment, extra arguments, or
754 interactively--thus disturbing the installation of large bundles like
755 Phalanx100 or modules with many dependencies like Plagger.
756 The distroprefs system of "CPAN.pm" addresses this problem by allowing
758 the user to specify extra informations and recipes in YAML files to
759 either
760 · pass additional arguments to one of the four commands,
762 · set environment variables
764 · instantiate an Expect object that reads from the console, waits for
766 some regular expressions and enters some answers
767 · temporarily override assorted "CPAN.pm" configuration variables
769 · specify dependencies the original maintainer forgot
771 · disable the installation of an object altogether
773 See the YAML and Data::Dumper files that come with the "CPAN.pm"
775 distribution in the "distroprefs/" directory for examples.
776 Filenames
778 The YAML files themselves must have the ".yml" extension; all other
779 files are ignored (for two exceptions see Fallback Data::Dumper and
780 Storable below). The containing directory can be specified in "CPAN.pm"
781 in the "prefs_dir" config variable. Try "o conf init prefs_dir" in the
782 CPAN shell to set and activate the distroprefs system.
783 Every YAML file may contain arbitrary documents according to the YAML
785 specification, and every document is treated as an entity that can
786 specify the treatment of a single distribution.
787 Filenames can be picked arbitrarily; "CPAN.pm" always reads all files
789 (in alphabetical order) and takes the key "match" (see below in
790 Language Specs) as a hashref containing match criteria that determine
791 if the current distribution matches the YAML document or not.
792 Fallback Data::Dumper and Storable
794 If neither your configured "yaml_module" nor YAML.pm is installed,
795 CPAN.pm falls back to using Data::Dumper and Storable and looks for
796 files with the extensions ".dd" or ".st" in the "prefs_dir" directory.
797 These files are expected to contain one or more hashrefs. For
798 Data::Dumper generated files, this is expected to be done with by
799 defining $VAR1, $VAR2, etc. The YAML shell would produce these with the
800 command
801 ysh < somefile.yml > somefile.dd
803 For Storable files the rule is that they must be constructed such that
805 "Storable::retrieve(file)" returns an array reference and the array
806 elements represent one distropref object each. The conversion from YAML
807 would look like so:
808 perl -MYAML=LoadFile -MStorable=nstore -e '
810 @y=LoadFile(shift);
811 nstore(\@y, shift)' somefile.yml somefile.st
812 In bootstrapping situations it is usually sufficient to translate only
814 a few YAML files to Data::Dumper for crucial modules like "YAML::Syck",
815 "YAML.pm" and "Expect.pm". If you prefer Storable over Data::Dumper,
816 remember to pull out a Storable version that writes an older format
817 than all the other Storable versions that will need to read them.
818 Blueprint
820 The following example contains all supported keywords and structures
821 with the exception of "eexpect" which can be used instead of "expect".
822 ---
824 comment: "Demo"
825 match:
826 module: "Dancing::Queen"
827 distribution: "^CHACHACHA/Dancing-"
828 not_distribution: "\.zip$"
829 perl: "/usr/local/cariba-perl/bin/perl"
830 perlconfig:
831 archname: "freebsd"
832 not_cc: "gcc"
833 env:
834 DANCING_FLOOR: "Shubiduh"
835 disabled: 1
836 cpanconfig:
837 make: gmake
838 pl:
839 args:
840 - "--somearg=specialcase"
841 env: {}
843 expect:
845 - "Which is your favorite fruit"
846 - "apple\n"
847 make:
849 args:
850 - all
851 - extra-all
852 env: {}
854 expect: []
856 commendline: "echo SKIPPING make"
858 test:
860 args: []
861 env: {}
863 expect: []
865 install:
867 args: []
868 env:
870 WANT_TO_INSTALL: YES
871 expect:
873 - "Do you really want to install"
874 - "y\n"
875 patches:
877 - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
878 depends:
880 configure_requires:
881 LWP: 5.8
882 build_requires:
883 Test::Exception: 0.25
884 requires:
885 Spiffy: 0.30
886 Language Specs
888 Every YAML document represents a single hash reference. The valid keys
889 in this hash are as follows:
890 comment [scalar]
892 A comment
893 cpanconfig [hash]
895 Temporarily override assorted "CPAN.pm" configuration variables.
896 Supported are: "build_requires_install_policy", "check_sigs",
898 "make", "make_install_make_command", "prefer_installer",
899 "test_report". Please report as a bug when you need another one
900 supported.
901 depends [hash] *** EXPERIMENTAL FEATURE ***
903 All three types, namely "configure_requires", "build_requires", and
904 "requires" are supported in the way specified in the META.yml
905 specification. The current implementation merges the specified
906 dependencies with those declared by the package maintainer. In a
907 future implementation this may be changed to override the original
908 declaration.
909 disabled [boolean]
911 Specifies that this distribution shall not be processed at all.
912 features [array] *** EXPERIMENTAL FEATURE ***
914 Experimental implementation to deal with optional_features from
915 META.yml. Still needs coordination with installer software and
916 currently works only for META.yml declaring "dynamic_config=0". Use
917 with caution.
918 goto [string]
920 The canonical name of a delegate distribution to install instead.
921 Useful when a new version, although it tests OK itself, breaks
922 something else or a developer release or a fork is already uploaded
923 that is better than the last released version.
924 install [hash]
926 Processing instructions for the "make install" or "./Build install"
927 phase of the CPAN mantra. See below under Processing Instructions.
928 make [hash]
930 Processing instructions for the "make" or "./Build" phase of the
931 CPAN mantra. See below under Processing Instructions.
932 match [hash]
934 A hashref with one or more of the keys "distribution", "modules",
935 "perl", "perlconfig", and "env" that specify whether a document is
936 targeted at a specific CPAN distribution or installation. Keys
937 prefixed with "not_" negates the corresponding match.
938 The corresponding values are interpreted as regular expressions.
940 The "distribution" related one will be matched against the
941 canonical distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
942 The "module" related one will be matched against all modules
944 contained in the distribution until one module matches.
945 The "perl" related one will be matched against $^X (but with the
947 absolute path).
948 The value associated with "perlconfig" is itself a hashref that is
950 matched against corresponding values in the %Config::Config hash
951 living in the "Config.pm" module. Keys prefixed with "not_"
952 negates the corresponding match.
953 The value associated with "env" is itself a hashref that is matched
955 against corresponding values in the %ENV hash. Keys prefixed with
956 "not_" negates the corresponding match.
957 If more than one restriction of "module", "distribution", etc. is
959 specified, the results of the separately computed match values must
960 all match. If so, the hashref represented by the YAML document is
961 returned as the preference structure for the current distribution.
962 patches [array]
964 An array of patches on CPAN or on the local disk to be applied in
965 order via an external patch program. If the value for the "-p"
966 parameter is 0 or 1 is determined by reading the patch beforehand.
967 The path to each patch is either an absolute path on the local
968 filesystem or relative to a patch directory specified in the
969 "patches_dir" configuration variable or in the format of a
970 canonical distroname. For examples please consult the distroprefs/
971 directory in the CPAN.pm distribution (these examples are not
972 installed by default).
973 Note: if the "applypatch" program is installed and "CPAN::Config"
975 knows about it and a patch is written by the "makepatch" program,
976 then "CPAN.pm" lets "applypatch" apply the patch. Both "makepatch"
977 and "applypatch" are available from CPAN in the "JV/makepatch-*"
978 distribution.
979 pl [hash]
981 Processing instructions for the "perl Makefile.PL" or "perl
982 Build.PL" phase of the CPAN mantra. See below under Processing
983 Instructions.
984 test [hash]
986 Processing instructions for the "make test" or "./Build test" phase
987 of the CPAN mantra. See below under Processing Instructions.
988 Processing Instructions
990 args [array]
991 Arguments to be added to the command line
992 commandline
994 A full commandline to run via "system()". During execution, the
995 environment variable PERL is set to $^X (but with an absolute
996 path). If "commandline" is specified, "args" is not used.
997 eexpect [hash]
999 Extended "expect". This is a hash reference with four allowed keys,
1000 "mode", "timeout", "reuse", and "talk".
1001 "mode" may have the values "deterministic" for the case where all
1003 questions come in the order written down and "anyorder" for the
1004 case where the questions may come in any order. The default mode is
1005 "deterministic".
1006 "timeout" denotes a timeout in seconds. Floating-point timeouts are
1008 OK. With "mode=deterministic", the timeout denotes the timeout per
1009 question; with "mode=anyorder" it denotes the timeout per byte
1010 received from the stream or questions.
1011 "talk" is a reference to an array that contains alternating
1013 questions and answers. Questions are regular expressions and
1014 answers are literal strings. The Expect module watches the stream
1015 from the execution of the external program ("perl Makefile.PL",
1016 "perl Build.PL", "make", etc.).
1017 For "mode=deterministic", the CPAN.pm injects the corresponding
1019 answer as soon as the stream matches the regular expression.
1020 For "mode=anyorder" CPAN.pm answers a question as soon as the
1022 timeout is reached for the next byte in the input stream. In this
1023 mode you can use the "reuse" parameter to decide what will happen
1024 with a question-answer pair after it has been used. In the default
1025 case (reuse=0) it is removed from the array, avoiding being used
1026 again accidentally. If you want to answer the question "Do you
1027 really want to do that" several times, then it must be included in
1028 the array at least as often as you want this answer to be given.
1029 Setting the parameter "reuse" to 1 makes this repetition
1030 unnecessary.
1031 env [hash]
1033 Environment variables to be set during the command
1034 expect [array]
1036 "expect: <array>" is a short notation for
1037 eexpect:
1039 mode: deterministic
1040 timeout: 15
1041 talk: <array>
1042 Schema verification with "Kwalify"
1044 If you have the "Kwalify" module installed (which is part of the
1045 Bundle::CPANxxl), then all your distroprefs files are checked for
1046 syntactic correctness.
1047 Example Distroprefs Files
1049 "CPAN.pm" comes with a collection of example YAML files. Note that
1050 these are really just examples and should not be used without care
1051 because they cannot fit everybody's purpose. After all, the authors of
1052 the packages that ask questions had a need to ask, so you should watch
1053 their questions and adjust the examples to your environment and your
1054 needs. You have been warned:-)
1055
1057 If you do not enter the shell, shell commands are available both as
1058 methods ("CPAN::Shell->install(...)") and as functions in the calling
1059 package ("install(...)"). Before calling low-level commands, it makes
1060 sense to initialize components of CPAN you need, e.g.:
1061 CPAN::HandleConfig->load;
1063 CPAN::Shell::setup_output;
1064 CPAN::Index->reload;
1065 High-level commands do such initializations automatically.
1067 There's currently only one class that has a stable interface -
1069 CPAN::Shell. All commands that are available in the CPAN shell are
1070 methods of the class CPAN::Shell. Each of the commands that produce
1071 listings of modules ("r", "autobundle", "u") also return a list of the
1072 IDs of all modules within the list.
1073 expand($type,@things)
1075 The IDs of all objects available within a program are strings that
1076 can be expanded to the corresponding real objects with the
1077 "CPAN::Shell->expand("Module",@things)" method. Expand returns a list
1078 of CPAN::Module objects according to the @things arguments given. In
1079 scalar context, it returns only the first element of the list.
1080 expandany(@things)
1082 Like expand, but returns objects of the appropriate type, i.e.
1083 CPAN::Bundle objects for bundles, CPAN::Module objects for modules,
1084 and CPAN::Distribution objects for distributions. Note: it does not
1085 expand to CPAN::Author objects.
1086 Programming Examples
1088 This enables the programmer to do operations that combine
1089 functionalities that are available in the shell.
1090 # install everything that is outdated on my disk:
1092 perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
1093 # install my favorite programs if necessary:
1095 for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
1096 CPAN::Shell->install($mod);
1097 }
1098 # list all modules on my disk that have no VERSION number
1100 for $mod (CPAN::Shell->expand("Module","/./")) {
1101 next unless $mod->inst_file;
1102 # MakeMaker convention for undefined $VERSION:
1103 next unless $mod->inst_version eq "undef";
1104 print "No VERSION in ", $mod->id, "\n";
1105 }
1106 # find out which distribution on CPAN contains a module:
1108 print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
1109 Or if you want to schedule a cron job to watch CPAN, you could list
1111 all modules that need updating. First a quick and dirty way:
1112 perl -e 'use CPAN; CPAN::Shell->r;'
1114 If you don't want any output should all modules be up to date, parse
1116 the output of above command for the regular expression "/modules are
1117 up to date/" and decide to mail the output only if it doesn't match.
1118 If you prefer to do it more in a programmerish style in one single
1120 process, something like this may better suit you:
1121 # list all modules on my disk that have newer versions on CPAN
1123 for $mod (CPAN::Shell->expand("Module","/./")) {
1124 next unless $mod->inst_file;
1125 next if $mod->uptodate;
1126 printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
1127 $mod->id, $mod->inst_version, $mod->cpan_version;
1128 }
1129 If that gives too much output every day, you may want to watch only
1131 for three modules. You can write
1132 for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {
1134 as the first line instead. Or you can combine some of the above
1136 tricks:
1137 # watch only for a new mod_perl module
1139 $mod = CPAN::Shell->expand("Module","mod_perl");
1140 exit if $mod->uptodate;
1141 # new mod_perl arrived, let me know all update recommendations
1142 CPAN::Shell->r;
1143 Methods in the other Classes
1145 CPAN::Author::as_glimpse()
1146 Returns a one-line description of the author
1147 CPAN::Author::as_string()
1149 Returns a multi-line description of the author
1150 CPAN::Author::email()
1152 Returns the author's email address
1153 CPAN::Author::fullname()
1155 Returns the author's name
1156 CPAN::Author::name()
1158 An alias for fullname
1159 CPAN::Bundle::as_glimpse()
1161 Returns a one-line description of the bundle
1162 CPAN::Bundle::as_string()
1164 Returns a multi-line description of the bundle
1165 CPAN::Bundle::clean()
1167 Recursively runs the "clean" method on all items contained in the
1168 bundle.
1169 CPAN::Bundle::contains()
1171 Returns a list of objects' IDs contained in a bundle. The
1172 associated objects may be bundles, modules or distributions.
1173 CPAN::Bundle::force($method,@args)
1175 Forces CPAN to perform a task that it normally would have refused
1176 to do. Force takes as arguments a method name to be called and any
1177 number of additional arguments that should be passed to the called
1178 method. The internals of the object get the needed changes so that
1179 CPAN.pm does not refuse to take the action. The "force" is passed
1180 recursively to all contained objects. See also the section above on
1181 the "force" and the "fforce" pragma.
1182 CPAN::Bundle::get()
1184 Recursively runs the "get" method on all items contained in the
1185 bundle
1186 CPAN::Bundle::inst_file()
1188 Returns the highest installed version of the bundle in either @INC
1189 or "$CPAN::Config-"{cpan_home}>. Note that this is different from
1190 CPAN::Module::inst_file.
1191 CPAN::Bundle::inst_version()
1193 Like CPAN::Bundle::inst_file, but returns the $VERSION
1194 CPAN::Bundle::uptodate()
1196 Returns 1 if the bundle itself and all its members are uptodate.
1197 CPAN::Bundle::install()
1199 Recursively runs the "install" method on all items contained in the
1200 bundle
1201 CPAN::Bundle::make()
1203 Recursively runs the "make" method on all items contained in the
1204 bundle
1205 CPAN::Bundle::readme()
1207 Recursively runs the "readme" method on all items contained in the
1208 bundle
1209 CPAN::Bundle::test()
1211 Recursively runs the "test" method on all items contained in the
1212 bundle
1213 CPAN::Distribution::as_glimpse()
1215 Returns a one-line description of the distribution
1216 CPAN::Distribution::as_string()
1218 Returns a multi-line description of the distribution
1219 CPAN::Distribution::author
1221 Returns the CPAN::Author object of the maintainer who uploaded this
1222 distribution
1223 CPAN::Distribution::pretty_id()
1225 Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is
1226 the author's PAUSE ID and TARBALL is the distribution filename.
1227 CPAN::Distribution::base_id()
1229 Returns the distribution filename without any archive suffix. E.g
1230 "Foo-Bar-0.01"
1231 CPAN::Distribution::clean()
1233 Changes to the directory where the distribution has been unpacked
1234 and runs "make clean" there.
1235 CPAN::Distribution::containsmods()
1237 Returns a list of IDs of modules contained in a distribution file.
1238 Works only for distributions listed in the
1239 02packages.details.txt.gz file. This typically means that just most
1240 recent version of a distribution is covered.
1241 CPAN::Distribution::cvs_import()
1243 Changes to the directory where the distribution has been unpacked
1244 and runs something like
1245 cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
1247 there.
1249 CPAN::Distribution::dir()
1251 Returns the directory into which this distribution has been
1252 unpacked.
1253 CPAN::Distribution::force($method,@args)
1255 Forces CPAN to perform a task that it normally would have refused
1256 to do. Force takes as arguments a method name to be called and any
1257 number of additional arguments that should be passed to the called
1258 method. The internals of the object get the needed changes so that
1259 CPAN.pm does not refuse to take the action. See also the section
1260 above on the "force" and the "fforce" pragma.
1261 CPAN::Distribution::get()
1263 Downloads the distribution from CPAN and unpacks it. Does nothing
1264 if the distribution has already been downloaded and unpacked within
1265 the current session.
1266 CPAN::Distribution::install()
1268 Changes to the directory where the distribution has been unpacked
1269 and runs the external command "make install" there. If "make" has
1270 not yet been run, it will be run first. A "make test" is issued in
1271 any case and if this fails, the install is cancelled. The
1272 cancellation can be avoided by letting "force" run the "install"
1273 for you.
1274 This install method only has the power to install the distribution
1276 if there are no dependencies in the way. To install an object along
1277 with all its dependencies, use CPAN::Shell->install.
1278 Note that install() gives no meaningful return value. See
1280 uptodate().
1281 CPAN::Distribution::install_tested()
1283 Install all distributions that have tested sucessfully but not yet
1284 installed. See also "is_tested".
1285 CPAN::Distribution::isa_perl()
1287 Returns 1 if this distribution file seems to be a perl
1288 distribution. Normally this is derived from the file name only,
1289 but the index from CPAN can contain a hint to achieve a return
1290 value of true for other filenames too.
1291 CPAN::Distribution::look()
1293 Changes to the directory where the distribution has been unpacked
1294 and opens a subshell there. Exiting the subshell returns.
1295 CPAN::Distribution::make()
1297 First runs the "get" method to make sure the distribution is
1298 downloaded and unpacked. Changes to the directory where the
1299 distribution has been unpacked and runs the external commands "perl
1300 Makefile.PL" or "perl Build.PL" and "make" there.
1301 CPAN::Distribution::perldoc()
1303 Downloads the pod documentation of the file associated with a
1304 distribution (in HTML format) and runs it through the external
1305 command lynx specified in "$CPAN::Config-"{lynx}>. If lynx isn't
1306 available, it converts it to plain text with the external command
1307 html2text and runs it through the pager specified in
1308 "$CPAN::Config-"{pager}>
1309 CPAN::Distribution::prefs()
1311 Returns the hash reference from the first matching YAML file that
1312 the user has deposited in the "prefs_dir/" directory. The first
1313 succeeding match wins. The files in the "prefs_dir/" are processed
1314 alphabetically, and the canonical distroname (e.g.
1315 AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular
1316 expressions stored in the $root->{match}{distribution} attribute
1317 value. Additionally all module names contained in a distribution
1318 are matched against the regular expressions in the
1319 $root->{match}{module} attribute value. The two match values are
1320 ANDed together. Each of the two attributes are optional.
1321 CPAN::Distribution::prereq_pm()
1323 Returns the hash reference that has been announced by a
1324 distribution as the "requires" and "build_requires" elements. These
1325 can be declared either by the "META.yml" (if authoritative) or can
1326 be deposited after the run of "Build.PL" in the file
1327 "./_build/prereqs" or after the run of "Makfile.PL" written as the
1328 "PREREQ_PM" hash in a comment in the produced "Makefile". Note:
1329 this method only works after an attempt has been made to "make" the
1330 distribution. Returns undef otherwise.
1331 CPAN::Distribution::readme()
1333 Downloads the README file associated with a distribution and runs
1334 it through the pager specified in "$CPAN::Config-"{pager}>.
1335 CPAN::Distribution::reports()
1337 Downloads report data for this distribution from
1338 www.cpantesters.org and displays a subset of them.
1339 CPAN::Distribution::read_yaml()
1341 Returns the content of the META.yml of this distro as a hashref.
1342 Note: works only after an attempt has been made to "make" the
1343 distribution. Returns undef otherwise. Also returns undef if the
1344 content of META.yml is not authoritative. (The rules about what
1345 exactly makes the content authoritative are still in flux.)
1346 CPAN::Distribution::test()
1348 Changes to the directory where the distribution has been unpacked
1349 and runs "make test" there.
1350 CPAN::Distribution::uptodate()
1352 Returns 1 if all the modules contained in the distribution are
1353 uptodate. Relies on containsmods.
1354 CPAN::Index::force_reload()
1356 Forces a reload of all indices.
1357 CPAN::Index::reload()
1359 Reloads all indices if they have not been read for more than
1360 "$CPAN::Config-"{index_expire}> days.
1361 CPAN::InfoObj::dump()
1363 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
1364 inherit this method. It prints the data structure associated with
1365 an object. Useful for debugging. Note: the data structure is
1366 considered internal and thus subject to change without notice.
1367 CPAN::Module::as_glimpse()
1369 Returns a one-line description of the module in four columns: The
1370 first column contains the word "Module", the second column consists
1371 of one character: an equals sign if this module is already
1372 installed and uptodate, a less-than sign if this module is
1373 installed but can be upgraded, and a space if the module is not
1374 installed. The third column is the name of the module and the
1375 fourth column gives maintainer or distribution information.
1376 CPAN::Module::as_string()
1378 Returns a multi-line description of the module
1379 CPAN::Module::clean()
1381 Runs a clean on the distribution associated with this module.
1382 CPAN::Module::cpan_file()
1384 Returns the filename on CPAN that is associated with the module.
1385 CPAN::Module::cpan_version()
1387 Returns the latest version of this module available on CPAN.
1388 CPAN::Module::cvs_import()
1390 Runs a cvs_import on the distribution associated with this module.
1391 CPAN::Module::description()
1393 Returns a 44 character description of this module. Only available
1394 for modules listed in The Module List
1395 (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz)
1396 CPAN::Module::distribution()
1398 Returns the CPAN::Distribution object that contains the current
1399 version of this module.
1400 CPAN::Module::dslip_status()
1402 Returns a hash reference. The keys of the hash are the letters "D",
1403 "S", "L", "I", and <P>, for development status, support level,
1404 language, interface and public licence respectively. The data for
1405 the DSLIP status are collected by pause.perl.org when authors
1406 register their namespaces. The values of the 5 hash elements are
1407 one-character words whose meaning is described in the table below.
1408 There are also 5 hash elements "DV", "SV", "LV", "IV", and <PV>
1409 that carry a more verbose value of the 5 status variables.
1410 Where the 'DSLIP' characters have the following meanings:
1412 D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
1414 i - Idea, listed to gain consensus or as a placeholder
1415 c - under construction but pre-alpha (not yet released)
1416 a/b - Alpha/Beta testing
1417 R - Released
1418 M - Mature (no rigorous definition)
1419 S - Standard, supplied with Perl 5
1420 S - Support Level:
1422 m - Mailing-list
1423 d - Developer
1424 u - Usenet newsgroup comp.lang.perl.modules
1425 n - None known, try comp.lang.perl.modules
1426 a - abandoned; volunteers welcome to take over maintainance
1427 L - Language Used:
1429 p - Perl-only, no compiler needed, should be platform independent
1430 c - C and perl, a C compiler will be needed
1431 h - Hybrid, written in perl with optional C code, no compiler needed
1432 + - C++ and perl, a C++ compiler will be needed
1433 o - perl and another language other than C or C++
1434 I - Interface Style
1436 f - plain Functions, no references used
1437 h - hybrid, object and function interfaces available
1438 n - no interface at all (huh?)
1439 r - some use of unblessed References or ties
1440 O - Object oriented using blessed references and/or inheritance
1441 P - Public License
1443 p - Standard-Perl: user may choose between GPL and Artistic
1444 g - GPL: GNU General Public License
1445 l - LGPL: "GNU Lesser General Public License" (previously known as
1446 "GNU Library General Public License")
1447 b - BSD: The BSD License
1448 a - Artistic license alone
1449 2 - Artistic license 2.0 or later
1450 o - open source: appoved by www.opensource.org
1451 d - allows distribution without restrictions
1452 r - restricted distribtion
1453 n - no license at all
1454 CPAN::Module::force($method,@args)
1456 Forces CPAN to perform a task it would normally refuse to do. Force
1457 takes as arguments a method name to be invoked and any number of
1458 additional arguments to pass that method. The internals of the
1459 object get the needed changes so that CPAN.pm does not refuse to
1460 take the action. See also the section above on the "force" and the
1461 "fforce" pragma.
1462 CPAN::Module::get()
1464 Runs a get on the distribution associated with this module.
1465 CPAN::Module::inst_file()
1467 Returns the filename of the module found in @INC. The first file
1468 found is reported, just as perl itself stops searching @INC once it
1469 finds a module.
1470 CPAN::Module::available_file()
1472 Returns the filename of the module found in PERL5LIB or @INC. The
1473 first file found is reported. The advantage of this method over
1474 "inst_file" is that modules that have been tested but not yet
1475 installed are included because PERL5LIB keeps track of tested
1476 modules.
1477 CPAN::Module::inst_version()
1479 Returns the version number of the installed module in readable
1480 format.
1481 CPAN::Module::available_version()
1483 Returns the version number of the available module in readable
1484 format.
1485 CPAN::Module::install()
1487 Runs an "install" on the distribution associated with this module.
1488 CPAN::Module::look()
1490 Changes to the directory where the distribution associated with
1491 this module has been unpacked and opens a subshell there. Exiting
1492 the subshell returns.
1493 CPAN::Module::make()
1495 Runs a "make" on the distribution associated with this module.
1496 CPAN::Module::manpage_headline()
1498 If module is installed, peeks into the module's manpage, reads the
1499 headline, and returns it. Moreover, if the module has been
1500 downloaded within this session, does the equivalent on the
1501 downloaded module even if it hasn't been installed yet.
1502 CPAN::Module::perldoc()
1504 Runs a "perldoc" on this module.
1505 CPAN::Module::readme()
1507 Runs a "readme" on the distribution associated with this module.
1508 CPAN::Module::reports()
1510 Calls the reports() method on the associated distribution object.
1511 CPAN::Module::test()
1513 Runs a "test" on the distribution associated with this module.
1514 CPAN::Module::uptodate()
1516 Returns 1 if the module is installed and up-to-date.
1517 CPAN::Module::userid()
1519 Returns the author's ID of the module.
1520 Cache Manager
1522 Currently the cache manager only keeps track of the build directory
1523 ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
1524 deletes complete directories below "build_dir" as soon as the size of
1525 all directories there gets bigger than $CPAN::Config->{build_cache} (in
1526 MB). The contents of this cache may be used for later re-installations
1527 that you intend to do manually, but will never be trusted by CPAN
1528 itself. This is due to the fact that the user might use these
1529 directories for building modules on different architectures.
1530 There is another directory ($CPAN::Config->{keep_source_where}) where
1532 the original distribution files are kept. This directory is not covered
1533 by the cache manager and must be controlled by the user. If you choose
1534 to have the same directory as build_dir and as keep_source_where
1535 directory, then your sources will be deleted with the same fifo
1536 mechanism.
1537 Bundles
1539 A bundle is just a perl module in the namespace Bundle:: that does not
1540 define any functions or methods. It usually only contains
1541 documentation.
1542 It starts like a perl module with a package declaration and a $VERSION
1544 variable. After that the pod section looks like any other pod with the
1545 only difference being that one special pod section exists starting with
1546 (verbatim):
1547 =head1 CONTENTS
1549 In this pod section each line obeys the format
1551 Module_Name [Version_String] [- optional text]
1553 The only required part is the first field, the name of a module (e.g.
1555 Foo::Bar, ie. not the name of the distribution file). The rest of the
1556 line is optional. The comment part is delimited by a dash just as in
1557 the man page header.
1558 The distribution of a bundle should follow the same convention as other
1560 distributions.
1561 Bundles are treated specially in the CPAN package. If you say 'install
1563 Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
1564 the modules in the CONTENTS section of the pod. You can install your
1565 own Bundles locally by placing a conformant Bundle file somewhere into
1566 your @INC path. The autobundle() command which is available in the
1567 shell interface does that for you by including all currently installed
1568 modules in a snapshot bundle file.
1569
1571 If you have a local mirror of CPAN and can access all files with
1572 "file:" URLs, then you only need a perl later than perl5.003 to run
1573 this module. Otherwise Net::FTP is strongly recommended. LWP may be
1574 required for non-UNIX systems, or if your nearest CPAN site is
1575 associated with a URL that is not "ftp:".
1576 If you have neither Net::FTP nor LWP, there is a fallback mechanism
1578 implemented for an external ftp command or for an external lynx
1579 command.
1580
1582 Finding packages and VERSION
1583 This module presumes that all packages on CPAN
1584 · declare their $VERSION variable in an easy to parse manner. This
1586 prerequisite can hardly be relaxed because it consumes far too much
1587 memory to load all packages into the running program just to
1588 determine the $VERSION variable. Currently all programs that are
1589 dealing with version use something like this
1590 perl -MExtUtils::MakeMaker -le \
1592 'print MM->parse_version(shift)' filename
1593 If you are author of a package and wonder if your $VERSION can be
1595 parsed, please try the above method.
1596 · come as compressed or gzipped tarfiles or as zip files and contain a
1598 "Makefile.PL" or "Build.PL" (well, we try to handle a bit more, but
1599 with little enthusiasm).
1600 Debugging
1602 Debugging this module is more than a bit complex due to interference
1603 from the software producing the indices on CPAN, the mirroring process
1604 on CPAN, packaging, configuration, synchronicity, and even (gasp!) due
1605 to bugs within the CPAN.pm module itself.
1606 For debugging the code of CPAN.pm itself in interactive mode, some
1608 debugging aid can be turned on for most packages within CPAN.pm with
1609 one of
1610 o debug package...
1612 sets debug mode for packages.
1613 o debug -package...
1615 unsets debug mode for packages.
1616 o debug all
1618 turns debugging on for all packages.
1619 o debug number
1621 which sets the debugging packages directly. Note that "o debug 0" turns
1623 debugging off.
1624 What seems a successful strategy is the combination of "reload cpan"
1626 and the debugging switches. Add a new debug statement while running in
1627 the shell and then issue a "reload cpan" and see the new debugging
1628 messages immediately without losing the current context.
1629 "o debug" without an argument lists the valid package names and the
1631 current set of packages in debugging mode. "o debug" has built-in
1632 completion support.
1633 For debugging of CPAN data there is the "dump" command which takes the
1635 same arguments as make/test/install and outputs each object's
1636 Data::Dumper dump. If an argument looks like a perl variable and
1637 contains one of "$", "@" or "%", it is eval()ed and fed to Data::Dumper
1638 directly.
1639 Floppy, Zip, Offline Mode
1641 CPAN.pm works nicely without network access, too. If you maintain
1642 machines that are not networked at all, you should consider working
1643 with "file:" URLs. You'll have to collect your modules somewhere first.
1644 So you might use CPAN.pm to put together all you need on a networked
1645 machine. Then copy the $CPAN::Config->{keep_source_where} (but not
1646 $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
1647 of a personal CPAN. CPAN.pm on the non-networked machines works nicely
1648 with this floppy. See also below the paragraph about CD-ROM support.
1649 Basic Utilities for Programmers
1651 has_inst($module)
1652 Returns true if the module is installed. Used to load all modules
1653 into the running CPAN.pm that are considered optional. The config
1654 variable "dontload_list" intercepts the "has_inst()" call such that
1655 an optional module is not loaded despite being available. For
1656 example, the following command will prevent "YAML.pm" from being
1657 loaded:
1658 cpan> o conf dontload_list push YAML
1660 See the source for details.
1662 has_usable($module)
1664 Returns true if the module is installed and in a usable state. Only
1665 useful for a handful of modules that are used internally. See the
1666 source for details.
1667 instance($module)
1669 The constructor for all the singletons used to represent modules,
1670 distributions, authors, and bundles. If the object already exists,
1671 this method returns the object; otherwise, it calls the constructor.
1672
1674 There's no strong security layer in CPAN.pm. CPAN.pm helps you to
1675 install foreign, unmasked, unsigned code on your machine. We compare to
1676 a checksum that comes from the net just as the distribution file
1677 itself. But we try to make it easy to add security on demand:
1678 Cryptographically signed modules
1680 Since release 1.77, CPAN.pm has been able to verify cryptographically
1681 signed module distributions using Module::Signature. The CPAN modules
1682 can be signed by their authors, thus giving more security. The simple
1683 unsigned MD5 checksums that were used before by CPAN protect mainly
1684 against accidental file corruption.
1685 You will need to have Module::Signature installed, which in turn
1687 requires that you have at least one of Crypt::OpenPGP module or the
1688 command-line gpg tool installed.
1689 You will also need to be able to connect over the Internet to the
1691 public keyservers, like pgp.mit.edu, and their port 11731 (the HKP
1692 protocol).
1693 The configuration parameter check_sigs is there to turn signature
1695 checking on or off.
1696
1698 Most functions in package CPAN are exported by default. The reason for
1699 this is that the primary use is intended for the cpan shell or for one-
1700 liners.
1701
1703 When the CPAN shell enters a subshell via the look command, it sets the
1704 environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
1705 already set.
1706 When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
1708 to the ID of the running process. It also sets
1709 PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
1710 happen with older versions of Module::Install.
1711 When running "perl Makefile.PL", the environment variable
1713 "PERL5_CPAN_IS_EXECUTING" is set to the full path of the "Makefile.PL"
1714 that is being executed. This prevents runaway processes with newer
1715 versions of Module::Install.
1716 When the config variable ftp_passive is set, all downloads will be run
1718 with the environment variable FTP_PASSIVE set to this value. This is in
1719 general a good idea as it influences both Net::FTP and LWP based
1720 connections. The same effect can be achieved by starting the cpan shell
1721 with this environment variable set. For Net::FTP alone, one can also
1722 always set passive mode by running libnetcfg.
1723
1725 Populating a freshly installed perl with one's favorite modules is
1726 pretty easy if you maintain a private bundle definition file. To get a
1727 useful blueprint of a bundle definition file, the command autobundle
1728 can be used on the CPAN shell command line. This command writes a
1729 bundle definition file for all modules installed for the current perl
1730 interpreter. It's recommended to run this command once only, and from
1731 then on maintain the file manually under a private name, say
1732 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
1733 cpan> install Bundle::my_bundle
1735 then answer a few questions and go out for coffee (possibly even in a
1737 different city).
1738 Maintaining a bundle definition file means keeping track of two things:
1740 dependencies and interactivity. CPAN.pm sometimes fails on calculating
1741 dependencies because not all modules define all MakeMaker attributes
1742 correctly, so a bundle definition file should specify prerequisites as
1743 early as possible. On the other hand, it's annoying that so many
1744 distributions need some interactive configuring. So what you can try to
1745 accomplish in your private bundle file is to have the packages that
1746 need to be configured early in the file and the gentle ones later, so
1747 you can go out for cofeee after a few minutes and leave CPAN.pm to
1748 churn away untended.
1749
1751 Thanks to Graham Barr for contributing the following paragraphs about
1752 the interaction between perl, and various firewall configurations. For
1753 further information on firewalls, it is recommended to consult the
1754 documentation that comes with the ncftp program. If you are unable to
1755 go through the firewall with a simple Perl setup, it is likely that you
1756 can configure ncftp so that it works through your firewall.
1757 Three basic types of firewalls
1759 Firewalls can be categorized into three basic types.
1760 http firewall
1762 This is when the firewall machine runs a web server, and to access
1763 the outside world, you must do so via that web server. If you set
1764 environment variables like http_proxy or ftp_proxy to values
1765 beginning with http://, or in your web browser you've proxy
1766 information set, then you know you are running behind an http
1767 firewall.
1768 To access servers outside these types of firewalls with perl (even
1770 for ftp), you need LWP.
1771 ftp firewall
1773 This where the firewall machine runs an ftp server. This kind of
1774 firewall will only let you access ftp servers outside the firewall.
1775 This is usually done by connecting to the firewall with ftp, then
1776 entering a username like "user@outside.host.com".
1777 To access servers outside these type of firewalls with perl, you
1779 need Net::FTP.
1780 One-way visibility
1782 One-way visibility means these firewalls try to make themselves
1783 invisible to users inside the firewall. An FTP data connection is
1784 normally created by sending your IP address to the remote server
1785 and then listening for the return connection. But the remote server
1786 will not be able to connect to you because of the firewall. For
1787 these types of firewall, FTP connections need to be done in a
1788 passive mode.
1789 There are two that I can think off.
1791 SOCKS
1793 If you are using a SOCKS firewall, you will need to compile
1794 perl and link it with the SOCKS library. This is what is
1795 normally called a 'socksified' perl. With this executable you
1796 will be able to connect to servers outside the firewall as if
1797 it were not there.
1798 IP Masquerade
1800 This is when the firewall implemented in the kernel (via NAT,
1801 or networking address translation), it allows you to hide a
1802 complete network behind one IP address. With this firewall no
1803 special compiling is needed as you can access hosts directly.
1804 For accessing ftp servers behind such firewalls you usually
1806 need to set the environment variable "FTP_PASSIVE" or the
1807 config variable ftp_passive to a true value.
1808 Configuring lynx or ncftp for going through a firewall
1810 If you can go through your firewall with e.g. lynx, presumably with a
1811 command such as
1812 /usr/local/bin/lynx -pscott:tiger
1814 then you would configure CPAN.pm with the command
1816 o conf lynx "/usr/local/bin/lynx -pscott:tiger"
1818 That's all. Similarly for ncftp or ftp, you would configure something
1820 like
1821 o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"
1823 Your mileage may vary...
1825
1827 1) I installed a new version of module X but CPAN keeps saying, I have
1828 the old version installed
1829 Probably you do have the old version installed. This can happen if
1831 a module installs itself into a different directory in the @INC
1832 path than it was previously installed. This is not really a CPAN.pm
1833 problem, you would have the same problem when installing the module
1834 manually. The easiest way to prevent this behaviour is to add the
1835 argument "UNINST=1" to the "make install" call, and that is why
1836 many people add this argument permanently by configuring
1837 o conf make_install_arg UNINST=1
1839 2) So why is UNINST=1 not the default?
1841 Because there are people who have their precise expectations about
1843 who may install where in the @INC path and who uses which @INC
1844 array. In fine tuned environments "UNINST=1" can cause damage.
1845 3) I want to clean up my mess, and install a new perl along with all
1847 modules I have. How do I go about it?
1848 Run the autobundle command for your old perl and optionally rename
1850 the resulting bundle file (e.g. Bundle/mybundle.pm), install the
1851 new perl with the Configure option prefix, e.g.
1852 ./Configure -Dprefix=/usr/local/perl-5.6.78.9
1854 Install the bundle file you produced in the first step with
1856 something like
1857 cpan> install Bundle::mybundle
1859 and you're done.
1861 4) When I install bundles or multiple modules with one command there
1863 is too much output to keep track of.
1864 You may want to configure something like
1866 o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
1868 o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"
1869 so that STDOUT is captured in a file for later inspection.
1871 5) I am not root, how can I install a module in a personal directory?
1873 First of all, you will want to use your own configuration, not the
1875 one that your root user installed. If you do not have permission to
1876 write in the cpan directory that root has configured, you will be
1877 asked if you want to create your own config. Answering "yes" will
1878 bring you into CPAN's configuration stage, using the system config
1879 for all defaults except things that have to do with CPAN's work
1880 directory, saving your choices to your MyConfig.pm file.
1881 You can also manually initiate this process with the following
1883 command:
1884 % perl -MCPAN -e 'mkmyconfig'
1886 or by running
1888 mkmyconfig
1890 from the CPAN shell.
1892 You will most probably also want to configure something like this:
1894 o conf makepl_arg "LIB=~/myperl/lib \
1896 INSTALLMAN1DIR=~/myperl/man/man1 \
1897 INSTALLMAN3DIR=~/myperl/man/man3 \
1898 INSTALLSCRIPT=~/myperl/bin \
1899 INSTALLBIN=~/myperl/bin"
1900 and then the equivalent command for Module::Build, which is
1902 o conf mbuildpl_arg "--lib=~/myperl/lib \
1904 --installman1dir=~/myperl/man/man1 \
1905 --installman3dir=~/myperl/man/man3 \
1906 --installscript=~/myperl/bin \
1907 --installbin=~/myperl/bin"
1908 You can make this setting permanent like all "o conf" settings with
1910 "o conf commit" or by setting "auto_commit" beforehand.
1911 You will have to add ~/myperl/man to the MANPATH environment
1913 variable and also tell your perl programs to look into
1914 ~/myperl/lib, e.g. by including
1915 use lib "$ENV{HOME}/myperl/lib";
1917 or setting the PERL5LIB environment variable.
1919 While we're speaking about $ENV{HOME}, it might be worth
1921 mentioning, that for Windows we use the File::HomeDir module that
1922 provides an equivalent to the concept of the home directory on
1923 Unix.
1924 Another thing you should bear in mind is that the UNINST parameter
1926 can be dangerous when you are installing into a private area
1927 because you might accidentally remove modules that other people
1928 depend on that are not using the private area.
1929 6) How to get a package, unwrap it, and make a change before building
1931 it?
1932 Have a look at the "look" (!) command.
1934 7) I installed a Bundle and had a couple of fails. When I retried,
1936 everything resolved nicely. Can this be fixed to work on first try?
1937 The reason for this is that CPAN does not know the dependencies of
1939 all modules when it starts out. To decide about the additional
1940 items to install, it just uses data found in the META.yml file or
1941 the generated Makefile. An undetected missing piece breaks the
1942 process. But it may well be that your Bundle installs some
1943 prerequisite later than some depending item and thus your second
1944 try is able to resolve everything. Please note, CPAN.pm does not
1945 know the dependency tree in advance and cannot sort the queue of
1946 things to install in a topologically correct order. It resolves
1947 perfectly well if all modules declare the prerequisites correctly
1948 with the PREREQ_PM attribute to MakeMaker or the "requires" stanza
1949 of Module::Build. For bundles which fail and you need to install
1950 often, it is recommended to sort the Bundle definition file
1951 manually.
1952 8) In our intranet, we have many modules for internal use. How can I
1954 integrate these modules with CPAN.pm but without uploading the
1955 modules to CPAN?
1956 Have a look at the CPAN::Site module.
1958 9) When I run CPAN's shell, I get an error message about things in my
1960 "/etc/inputrc" (or "~/.inputrc") file.
1961 These are readline issues and can only be fixed by studying
1963 readline configuration on your architecture and adjusting the
1964 referenced file accordingly. Please make a backup of the
1965 "/etc/inputrc" or "~/.inputrc" and edit them. Quite often harmless
1966 changes like uppercasing or lowercasing some arguments solves the
1967 problem.
1968 10) Some authors have strange characters in their names.
1970 Internally CPAN.pm uses the UTF-8 charset. If your terminal is
1972 expecting ISO-8859-1 charset, a converter can be activated by
1973 setting term_is_latin to a true value in your config file. One way
1974 of doing so would be
1975 cpan> o conf term_is_latin 1
1977 If other charset support is needed, please file a bugreport against
1979 CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend
1980 the support or maybe UTF-8 terminals become widely available.
1981 Note: this config variable is deprecated and will be removed in a
1983 future version of CPAN.pm. It will be replaced with the conventions
1984 around the family of $LANG and $LC_* environment variables.
1985 11) When an install fails for some reason and then I correct the error
1987 condition and retry, CPAN.pm refuses to install the module, saying
1988 "Already tried without success".
1989 Use the force pragma like so
1991 force install Foo::Bar
1993 Or you can use
1995 look Foo::Bar
1997 and then "make install" directly in the subshell.
1999 12) How do I install a "DEVELOPER RELEASE" of a module?
2001 By default, CPAN will install the latest non-developer release of a
2003 module. If you want to install a dev release, you have to specify
2004 the partial path starting with the author id to the tarball you
2005 wish to install, like so:
2006 cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
2008 Note that you can use the "ls" command to get this path listed.
2010 13) How do I install a module and all its dependencies from the
2012 commandline, without being prompted for anything, despite my CPAN
2013 configuration (or lack thereof)?
2014 CPAN uses ExtUtils::MakeMaker's prompt() function to ask its
2016 questions, so if you set the PERL_MM_USE_DEFAULT environment
2017 variable, you shouldn't be asked any questions at all (assuming the
2018 modules you are installing are nice about obeying that variable as
2019 well):
2020 % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'
2022 14) How do I create a Module::Build based Build.PL derived from an
2024 ExtUtils::MakeMaker focused Makefile.PL?
2025 http://search.cpan.org/search?query=Module::Build::Convert
2027 http://www.refcnt.org/papers/module-build-convert
2029 15) I'm frequently irritated with the CPAN shell's inability to help me
2031 select a good mirror.
2032 The urllist config parameter is yours. You can add and remove sites
2034 at will. You should find out which sites have the best
2035 uptodateness, bandwidth, reliability, etc. and are topologically
2036 close to you. Some people prefer fast downloads, others
2037 uptodateness, others reliability. You decide which to try in which
2038 order.
2039 Henk P. Penning maintains a site that collects data about CPAN
2041 sites:
2042 http://www.cs.uu.nl/people/henkp/mirmon/cpan.html
2044 Also, feel free to play with experimental features. Run
2046 o conf init randomize_urllist ftpstats_period ftpstats_size
2048 and choose your favorite parameters. After a few downloads running
2050 the "hosts" command will probably assist you in choosing the best
2051 mirror sites.
2052 16) Why do I get asked the same questions every time I start the shell?
2054 You can make your configuration changes permanent by calling the
2056 command "o conf commit". Alternatively set the "auto_commit"
2057 variable to true by running "o conf init auto_commit" and answering
2058 the following question with yes.
2059 17) Older versions of CPAN.pm had the original root directory of all
2061 tarballs in the build directory. Now there are always random
2062 characters appended to these directory names. Why was this done?
2063 The random characters are provided by File::Temp and ensure that
2065 each module's individual build directory is unique. This makes
2066 running CPAN.pm in concurrent processes simultaneously safe.
2067 18) Speaking of the build directory. Do I have to clean it up myself?
2069 You have the choice to set the config variable "scan_cache" to
2071 "never". Then you must clean it up yourself. The other possible
2072 value, "atstart" only cleans up the build directory when you start
2073 the CPAN shell. If you never start up the CPAN shell, you probably
2074 also have to clean up the build directory yourself.
2075
2077 OLD PERL VERSIONS
2078 CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted
2079 newer versions. It is getting more and more difficult to get the
2080 minimal prerequisites working on older perls. It is close to impossible
2081 to get the whole Bundle::CPAN working there. If you're in the position
2082 to have only these old versions, be advised that CPAN is designed to
2083 work fine without the Bundle::CPAN installed.
2084 To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
2086 compatible with ancient perls and that File::Temp is listed as a
2087 prerequisite but CPAN has reasonable workarounds if it is missing.
2088 CPANPLUS
2090 This module and its competitor, the CPANPLUS module, are both much
2091 cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
2092 more modular, but it was never intended to be compatible with CPAN.pm.
2093
2095 This software enables you to upgrade software on your computer and so
2096 is inherently dangerous because the newly installed software may
2097 contain bugs and may alter the way your computer works or even make it
2098 unusable. Please consider backing up your data before every upgrade.
2099
2101 Please report bugs via <http://rt.cpan.org/>
2102 Before submitting a bug, please make sure that the traditional method
2104 of building a Perl module package from a shell by following the
2105 installation instructions of that package still works in your
2106 environment.
2107
2109 Andreas Koenig "<andk@cpan.org>"
2110
2112 This program is free software; you can redistribute it and/or modify it
2113 under the same terms as Perl itself.
2114 See <http://www.perl.com/perl/misc/Artistic.html>
2116
2118 Kawai,Takanori provides a Japanese translation of this manpage at
2119 <http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
2120
2122 cpan, CPAN::Nox, CPAN::Version
2123perl v5.10.1 2009-06-27 CPAN(3pm)