1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
132 .TH CPAN 3 "2009-06-27" "perl v5.8.7" "User Contributed Perl Documentation"
134 CPAN \- query, download and build perl modules from CPAN sites
136 .IX Header "SYNOPSIS"
140 \& perl \-MCPAN \-e shell
156 \& cpan> install Acme::Meta # in the shell
160 \& CPAN::Shell\->install("Acme::Meta"); # in perl
168 \& cpan> install NWCLARK/Acme\-Meta\-0.02.tar.gz # in the shell
173 \& install("NWCLARK/Acme\-Meta\-0.02.tar.gz"); # in perl
181 \& $mo = CPAN::Shell\->expandany($mod);
182 \& $mo = CPAN::Shell\->expand("Module",$mod); # same thing
186 \& # distribution objects:
190 \& $do = CPAN::Shell\->expand("Module",$mod)\->distribution;
191 \& $do = CPAN::Shell\->expandany($distro); # same thing
192 \& $do = CPAN::Shell\->expand("Distribution",
193 \& $distro); # same thing
196 .IX Header "DESCRIPTION"
197 The \s-1CPAN\s0 module automates or at least simplifies the make and install
198 of perl modules and extensions. It includes some primitive searching
199 capabilities and knows how to use Net::FTP, \s-1LWP\s0, and certain external
200 download clients to fetch distributions from the net.
202 These are fetched from one or more mirrored \s-1CPAN\s0 (Comprehensive
203 Perl Archive Network) sites and unpacked in a dedicated directory.
205 The \s-1CPAN\s0 module also supports named and versioned
206 \&\fIbundles\fR of modules. Bundles simplify handling of sets of
207 related modules. See Bundles below.
209 The package contains a session manager and a cache manager. The
210 session manager keeps track of what has been fetched, built, and
211 installed in the current session. The cache manager keeps track of the
212 disk space occupied by the make processes and deletes excess space
213 using a simple \s-1FIFO\s0 mechanism.
215 All methods provided are accessible in a programmer style and in an
216 interactive shell style.
217 .ie n .Sh "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
218 .el .Sh "CPAN::shell([$prompt, \f(CW$command\fP]) Starting Interactive Mode"
219 .IX Subsection "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
220 Enter interactive mode by running
223 \& perl \-MCPAN \-e shell
232 which puts you into a readline interface. If \f(CW\*(C`Term::ReadKey\*(C'\fR and
233 either of \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR or \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR are installed,
234 history and command completion are supported.
236 Once at the command line, type \f(CW\*(C`h\*(C'\fR for one-page help
237 screen; the rest should be self\-explanatory.
239 The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments: one the
240 prompt, the second the default initial command line (the latter
241 only works if a real ReadLine interface module is installed).
243 The most common uses of the interactive modes are
244 .IP "Searching for authors, bundles, distribution files and modules" 2
245 .IX Item "Searching for authors, bundles, distribution files and modules"
246 There are corresponding one-letter commands \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`d\*(C'\fR, and \f(CW\*(C`m\*(C'\fR
247 for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the
248 mentioned four. Each of the four entities is implemented as a class
249 with slightly differing methods for displaying an object.
251 Arguments to these commands are either strings exactly matching
252 the identification string of an object, or regular expressions
253 matched case-insensitively against various attributes of the
254 objects. The parser only recognizes a regular expression when you
255 enclose it with slashes.
257 The principle is that the number of objects found influences how an
258 item is displayed. If the search finds one item, the result is
259 displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if
260 more than one is found, each object is displayed with the terse method
261 \&\f(CW\*(C`as_glimpse\*(C'\fR.
266 \& cpan> m Acme::MetaSyntactic
267 \& Module id = Acme::MetaSyntactic
268 \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
270 \& CPAN_FILE B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
271 \& UPLOAD_DATE 2006\-11\-06
272 \& MANPAGE Acme::MetaSyntactic \- Themed metasyntactic variables names
273 \& INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
278 \& FULLNAME Philippe Bruhat (BooK)
279 \& cpan> d BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
280 \& Distribution id = B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
281 \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
282 \& CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
283 \& UPLOAD_DATE 2006\-11\-06
285 \& Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme\-MetaSyntactic\-0.99.tar.gz)
286 \& Module Text::Lorem (ADEOLA/Text\-Lorem\-0.3.tar.gz)
287 \& Module Text::Lorem::More (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
288 \& Module Text::Lorem::More::Source (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
290 \& Distribution BEATNIK/Filter\-NumberLines\-0.02.tar.gz
291 \& Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime\-TimeZone\-0.7904.tar.gz)
292 \& Module Filter::NumberLines (BEATNIK/Filter\-NumberLines\-0.02.tar.gz)
296 The examples illustrate several aspects: the first three queries
297 target modules, authors, or distros directly and yield exactly one
298 result. The last two use regular expressions and yield several
299 results. The last one targets all of bundles, modules, authors, and
300 distros simultaneously. When more than one result is available, they
301 are printed in one-line format.
302 .ie n .IP """get""\fR, \f(CW""make""\fR, \f(CW""test""\fR, \f(CW""install""\fR, \f(CW""clean"" modules or distributions" 2
303 .el .IP "\f(CWget\fR, \f(CWmake\fR, \f(CWtest\fR, \f(CWinstall\fR, \f(CWclean\fR modules or distributions" 2
304 .IX Item "get, make, test, install, clean modules or distributions"
305 These commands take any number of arguments and investigate what is
306 necessary to perform the action. If the argument is a distribution
307 file name (recognized by embedded slashes), it is processed. If it is
308 a module, \s-1CPAN\s0 determines the distribution file in which this module
309 is included and processes that, following any dependencies named in
310 the module's \s-1META\s0.yml or Makefile.PL (this behavior is controlled by
311 the configuration parameter \f(CW\*(C`prerequisites_policy\*(C'\fR.)
313 \&\f(CW\*(C`get\*(C'\fR downloads a distribution file and untars or unzips it, \f(CW\*(C`make\*(C'\fR
314 builds it, \f(CW\*(C`test\*(C'\fR runs the test suite, and \f(CW\*(C`install\*(C'\fR installs it.
316 Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR is run unconditionally. An
319 \& install <distribution_file>
322 is also run unconditionally. But for
328 \&\s-1CPAN\s0 checks whether an install is needed and prints
329 \&\fImodule up to date\fR if the distribution file containing
330 the module doesn't need updating.
332 \&\s-1CPAN\s0 also keeps track of what it has done within the current session
333 and doesn't try to build a package a second time regardless of whether it
334 succeeded or not. It does not repeat a test run if the test
335 has been run successfully before. Same for install runs.
337 The \f(CW\*(C`force\*(C'\fR pragma may precede another command (currently: \f(CW\*(C`get\*(C'\fR,
338 \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, or \f(CW\*(C`install\*(C'\fR) to execute the command from scratch
339 and attempt to continue past certain errors. See the section below on
340 the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
342 The \f(CW\*(C`notest\*(C'\fR pragma skips the test part in the build
348 \& cpan> notest install Tk
351 A \f(CW\*(C`clean\*(C'\fR command results in a
357 being executed within the distribution file's working directory.
358 .ie n .IP """readme""\fR, \f(CW""perldoc""\fR, \f(CW""look"" module or distribution" 2
359 .el .IP "\f(CWreadme\fR, \f(CWperldoc\fR, \f(CWlook\fR module or distribution" 2
360 .IX Item "readme, perldoc, look module or distribution"
361 \&\f(CW\*(C`readme\*(C'\fR displays the \s-1README\s0 file of the associated distribution.
362 \&\f(CW\*(C`Look\*(C'\fR gets and untars (if not yet done) the distribution file,
363 changes to the appropriate directory and opens a subshell process in
364 that directory. \f(CW\*(C`perldoc\*(C'\fR displays the module's pod documentation
365 in html or plain text format.
366 .ie n .IP """ls"" author" 2
367 .el .IP "\f(CWls\fR author" 2
370 .ie n .IP """ls"" globbing_expression" 2
371 .el .IP "\f(CWls\fR globbing_expression" 2
372 .IX Item "ls globbing_expression"
374 The first form lists all distribution files in and below an author's
375 \&\s-1CPAN\s0 directory as stored in the \s-1CHECKUMS\s0 files distributed on
376 \&\s-1CPAN\s0. The listing recurses into subdirectories.
378 The second form limits or expands the output with shell
379 globbing as in the following examples:
387 The last example is very slow and outputs extra progress indicators
388 that break the alignment of the result.
390 Note that globbing only lists directories explicitly asked for, for
391 example FOO/* will not list FOO/bar/Acme\-Sthg\-n.nn.tar.gz. This may be
392 regarded as a bug that may be changed in some future version.
393 .ie n .IP """failed""" 2
394 .el .IP "\f(CWfailed\fR" 2
396 The \f(CW\*(C`failed\*(C'\fR command reports all distributions that failed on one of
397 \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR or \f(CW\*(C`install\*(C'\fR for some reason in the currently
398 running shell session.
399 .IP "Persistence between sessions" 2
400 .IX Item "Persistence between sessions"
401 If the \f(CW\*(C`YAML\*(C'\fR or the \f(CW\*(C`YAML::Syck\*(C'\fR module is installed a record of
402 the internal state of all modules is written to disk after each step.
403 The files contain a signature of the currently running perl version
406 If the configurations variable \f(CW\*(C`build_dir_reuse\*(C'\fR is set to a true
407 value, then \s-1CPAN\s0.pm reads the collected \s-1YAML\s0 files. If the stored
408 signature matches the currently running perl, the stored state is
409 loaded into memory such that persistence between sessions
410 is effectively established.
411 .ie n .IP "The ""force""\fR and the \f(CW""fforce"" pragma" 2
412 .el .IP "The \f(CWforce\fR and the \f(CWfforce\fR pragma" 2
413 .IX Item "The force and the fforce pragma"
414 To speed things up in complex installation scenarios, \s-1CPAN\s0.pm keeps
415 track of what it has already done and refuses to do some things a
416 second time. A \f(CW\*(C`get\*(C'\fR, a \f(CW\*(C`make\*(C'\fR, and an \f(CW\*(C`install\*(C'\fR are not repeated.
417 A \f(CW\*(C`test\*(C'\fR is repeated only if the previous test was unsuccessful. The
418 diagnostic message when \s-1CPAN\s0.pm refuses to do something a second time
419 is one of \fIHas already been \fR\f(CW\*(C`unwrapped|made|tested successfully\*(C'\fR or
420 something similar. Another situation where \s-1CPAN\s0 refuses to act is an
421 \&\f(CW\*(C`install\*(C'\fR if the corresponding \f(CW\*(C`test\*(C'\fR was not successful.
423 In all these cases, the user can override this stubborn behaviour by
424 prepending the command with the word force, for example:
427 \& cpan> force get Foo
428 \& cpan> force make AUTHOR/Bar\-3.14.tar.gz
429 \& cpan> force test Baz
430 \& cpan> force install Acme::Meta
433 Each \fIforced\fR command is executed with the corresponding part of its
436 The \f(CW\*(C`fforce\*(C'\fR pragma is a variant that emulates a \f(CW\*(C`force get\*(C'\fR which
437 erases the entire memory followed by the action specified, effectively
438 restarting the whole get/make/test/install procedure from scratch.
441 Interactive sessions maintain a lockfile, by default \f(CW\*(C`~/.cpan/.lock\*(C'\fR.
442 Batch jobs can run without a lockfile and not disturb each other.
444 The shell offers to run in \fIdowngraded mode\fR when another process is
445 holding the lockfile. This is an experimental feature that is not yet
446 tested very well. This second shell then does not write the history
447 file, does not use the metadata file, and has a different prompt.
450 \&\s-1CPAN\s0.pm installs signal handlers for \s-1SIGINT\s0 and \s-1SIGTERM\s0. While you are
451 in the cpan\-shell, it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and
452 return to the cpan-shell prompt. A \s-1SIGTERM\s0 will cause the cpan-shell
453 to clean up and leave the shell loop. You can emulate the effect of a
454 \&\s-1SIGTERM\s0 by sending two consecutive SIGINTs, which usually means by
455 pressing \f(CW\*(C`^C\*(C'\fR twice.
457 \&\s-1CPAN\s0.pm ignores \s-1SIGPIPE\s0. If the user sets \f(CW\*(C`inactivity_timeout\*(C'\fR, a
458 \&\s-1SIGALRM\s0 is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
459 Build.PL\*(C'\fR subprocess.
461 .IX Subsection "CPAN::Shell"
462 The commands available in the shell interface are methods in
463 the package CPAN::Shell. If you enter the shell command, your
464 input is split by the \fIText::ParseWords::shellwords()\fR routine, which
465 acts like most shells do. The first word is interpreted as the
466 method to be invoked, and the rest of the words are treated as the method's arguments.
467 Continuation lines are supported by ending a line with a
470 .IX Subsection "autobundle"
471 \&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the
472 \&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains
473 a list of all modules that are both available from \s-1CPAN\s0 and currently
474 installed within \f(CW@INC\fR. The name of the bundle file is based on the
475 current date and a counter.
477 .IX Subsection "hosts"
478 Note: this feature is still in alpha state and may change in future
479 versions of \s-1CPAN\s0.pm
481 This commands provides a statistical overview over recent download
482 activities. The data for this is collected in the \s-1YAML\s0 file
483 \&\f(CW\*(C`FTPstats.yml\*(C'\fR in your \f(CW\*(C`cpan_home\*(C'\fR directory. If no \s-1YAML\s0 module is
484 configured or \s-1YAML\s0 not installed, no stats are provided.
486 .IX Subsection "mkmyconfig"
487 \&\fImkmyconfig()\fR writes your own CPAN::MyConfig file into your \f(CW\*(C`~/.cpan/\*(C'\fR
488 directory so that you can save your own preferences instead of the
490 .Sh "recent ***EXPERIMENTAL COMMAND***"
491 .IX Subsection "recent ***EXPERIMENTAL COMMAND***"
492 The \f(CW\*(C`recent\*(C'\fR command downloads a list of recent uploads to \s-1CPAN\s0 and
493 displays them \fIslowly\fR. While the command is running, a \f(CW$SIG\fR{\s-1INT\s0}
494 exits the loop after displaying the current item.
496 \&\fBNote\fR: This command requires XML::LibXML installed.
498 \&\fBNote\fR: This whole command currently is just a hack and will
499 probably change in future versions of \s-1CPAN\s0.pm, but the general
500 approach will likely remain.
502 \&\fBNote\fR: See also smoke
504 .IX Subsection "recompile"
505 \&\fIrecompile()\fR is a special command that takes no argument and
506 runs the make/test/install cycle with brute force over all installed
507 dynamically loadable extensions (aka \s-1XS\s0 modules) with 'force' in
508 effect. The primary purpose of this command is to finish a network
509 installation. Imagine you have a common source tree for two different
510 architectures. You decide to do a completely independent fresh
511 installation. You start on one architecture with the help of a Bundle
512 file produced earlier. \s-1CPAN\s0 installs the whole Bundle for you, but
513 when you try to repeat the job on the second architecture, \s-1CPAN\s0
514 responds with a \f(CW"Foo up to date"\fR message for all modules. So you
515 invoke \s-1CPAN\s0's recompile on the second architecture and you're done.
517 Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your
518 perl breaks binary compatibility. If one of the modules that \s-1CPAN\s0 uses
519 is in turn depending on binary compatibility (so you cannot run \s-1CPAN\s0
520 commands), then you should try the CPAN::Nox module for recovery.
521 .Sh "report Bundle|Distribution|Module"
522 .IX Subsection "report Bundle|Distribution|Module"
523 The \f(CW\*(C`report\*(C'\fR command temporarily turns on the \f(CW\*(C`test_report\*(C'\fR config
524 variable, then runs the \f(CW\*(C`force test\*(C'\fR command with the given
525 arguments. The \f(CW\*(C`force\*(C'\fR pragma reruns the tests and repeats
526 every step that might have failed before.
527 .Sh "smoke ***EXPERIMENTAL COMMAND***"
528 .IX Subsection "smoke ***EXPERIMENTAL COMMAND***"
529 \&\fB*** \s-1WARNING:\s0 this command downloads and executes software from \s-1CPAN\s0 to
530 your computer of completely unknown status. You should never do
531 this with your normal account and better have a dedicated well
532 separated and secured machine to do this. ***\fR
534 The \f(CW\*(C`smoke\*(C'\fR command takes the list of recent uploads to \s-1CPAN\s0 as
535 provided by the \f(CW\*(C`recent\*(C'\fR command and tests them all. While the
536 command is running \f(CW$SIG\fR{\s-1INT\s0} is defined to mean that the current item
539 \&\fBNote\fR: This whole command currently is just a hack and will
540 probably change in future versions of \s-1CPAN\s0.pm, but the general
541 approach will likely remain.
543 \&\fBNote\fR: See also recent
544 .Sh "upgrade [Module|/Regex/]..."
545 .IX Subsection "upgrade [Module|/Regex/]..."
546 The \f(CW\*(C`upgrade\*(C'\fR command first runs an \f(CW\*(C`r\*(C'\fR command with the given
547 arguments and then installs the newest versions of all modules that
549 .ie n .Sh "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution"
550 .el .Sh "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution"
551 .IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution"
552 Although it may be considered internal, the class hierarchy does matter
553 for both users and programmer. \s-1CPAN\s0.pm deals with the four
554 classes mentioned above, and those classes all share a set of methods. Classical
555 single polymorphism is in effect. A metaclass object registers all
556 objects of all kinds and indexes them with a string. The strings
557 referencing objects have a separated namespace (well, not completely
565 \& words containing a "/" (slash) Distribution
566 \& words starting with Bundle:: Bundle
567 \& everything else Module or Author
570 Modules know their associated Distribution objects. They always refer
571 to the most recent official release. Developers may mark their releases
572 as unstable development versions (by inserting an underbar into the
573 module version number which will also be reflected in the distribution
574 name when you run 'make dist'), so the really hottest and newest
575 distribution is not always the default. If a module Foo circulates
576 on \s-1CPAN\s0 in both version 1.23 and 1.23_90, \s-1CPAN\s0.pm offers a convenient
577 way to install version 1.23 by saying
583 This would install the complete distribution file (say
584 BAR/Foo\-1.23.tar.gz) with all accompanying material. But if you would
585 like to install version 1.23_90, you need to know where the
586 distribution file resides on \s-1CPAN\s0 relative to the authors/id/
587 directory. If the author is \s-1BAR\s0, this might be BAR/Foo\-1.23_90.tar.gz;
588 so you would have to say
591 \& install BAR/Foo\-1.23_90.tar.gz
594 The first example will be driven by an object of the class
595 CPAN::Module, the second by an object of class CPAN::Distribution.
596 .Sh "Integrating local directories"
597 .IX Subsection "Integrating local directories"
598 Note: this feature is still in alpha state and may change in future
599 versions of \s-1CPAN\s0.pm
601 Distribution objects are normally distributions from the \s-1CPAN\s0, but
602 there is a slightly degenerate case for Distribution objects, too, of
603 projects held on the local disk. These distribution objects have the
604 same name as the local directory and end with a dot. A dot by itself
605 is also allowed for the current directory at the time \s-1CPAN\s0.pm was
606 used. All actions such as \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`install\*(C'\fR are applied
607 directly to that directory. This gives the command \f(CW\*(C`cpan .\*(C'\fR an
608 interesting touch: while the normal mantra of installing a \s-1CPAN\s0 module
609 without \s-1CPAN\s0.pm is one of
612 \& perl Makefile.PL perl Build.PL
613 \& ( go and get prerequisites )
615 \& make test ./Build test
616 \& make install ./Build install
619 the command \f(CW\*(C`cpan .\*(C'\fR does all of this at once. It figures out which
620 of the two mantras is appropriate, fetches and installs all
621 prerequisites, takes care of them recursively, and finally finishes the
622 installation of the module in the current directory, be it a \s-1CPAN\s0
625 The typical usage case is for private modules or working copies of
626 projects from remote repositories on the local disk.
628 .IX Subsection "Redirection"
629 The usual shell redirection symbols \f(CW\*(C` | \*(C'\fR and \f(CW\*(C`>\*(C'\fR are recognized
630 by the cpan shell \fBonly when surrounded by whitespace\fR. So piping to
631 pager or redirecting output into a file works somewhat as in a normal
632 shell, with the stipulation that you must type extra spaces.
634 .IX Header "CONFIGURATION"
635 When the \s-1CPAN\s0 module is used for the first time, a configuration
636 dialogue tries to determine a couple of site specific options. The
637 result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR
638 in a file CPAN/Config.pm.
640 Default values defined in the CPAN/Config.pm file can be
641 overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
642 best placed in \f(CW\*(C`$HOME/.cpan/CPAN/MyConfig.pm\*(C'\fR, because \f(CW\*(C`$HOME/.cpan\*(C'\fR is
643 added to the search path of the \s-1CPAN\s0 module before the \fIuse()\fR or
644 \&\fIrequire()\fR statements. The mkmyconfig command writes this file for you.
646 The \f(CW\*(C`o conf\*(C'\fR command has various bells and whistles:
647 .IP "completion support" 4
648 .IX Item "completion support"
649 If you have a ReadLine module installed, you can hit \s-1TAB\s0 at any point
650 of the commandline and \f(CW\*(C`o conf\*(C'\fR will offer you completion for the
651 built-in subcommands and/or config variable names.
652 .IP "displaying some help: o conf help" 4
653 .IX Item "displaying some help: o conf help"
654 Displays a short help
655 .IP "displaying current values: o conf [\s-1KEY\s0]" 4
656 .IX Item "displaying current values: o conf [KEY]"
657 Displays the current value(s) for this config variable. Without \s-1KEY\s0,
658 displays all subcommands and config variables.
666 If \s-1KEY\s0 starts and ends with a slash, the string in between is
667 treated as a regular expression and only keys matching this regex
675 .IP "changing of scalar values: o conf \s-1KEY\s0 \s-1VALUE\s0" 4
676 .IX Item "changing of scalar values: o conf KEY VALUE"
677 Sets the config variable \s-1KEY\s0 to \s-1VALUE\s0. The empty string can be
678 specified as usual in shells, with \f(CW''\fR or \f(CW""\fR
683 \& o conf wget /usr/bin/wget
685 .IP "changing of list values: o conf \s-1KEY\s0 SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" 4
686 .IX Item "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST"
687 If a config variable name ends with \f(CW\*(C`list\*(C'\fR, it is a list. \f(CW\*(C`o conf
688 KEY shift\*(C'\fR removes the first element of the list, \f(CW\*(C`o conf KEY pop\*(C'\fR
689 removes the last element of the list. \f(CW\*(C`o conf KEYS unshift LIST\*(C'\fR
690 prepends a list of values to the list, \f(CW\*(C`o conf KEYS push LIST\*(C'\fR
691 appends a list of valued to the list.
693 Likewise, \f(CW\*(C`o conf KEY splice LIST\*(C'\fR passes the \s-1LIST\s0 to the corresponding
696 Finally, any other list of arguments is taken as a new list value for
697 the \s-1KEY\s0 variable discarding the previous value.
702 \& o conf urllist unshift http://cpan.dev.local/CPAN
703 \& o conf urllist splice 3 1
704 \& o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
706 .IP "reverting to saved: o conf defaults" 4
707 .IX Item "reverting to saved: o conf defaults"
708 Reverts all config variables to the state in the saved config file.
709 .IP "saving the config: o conf commit" 4
710 .IX Item "saving the config: o conf commit"
711 Saves all config variables to the current config file (CPAN/Config.pm
712 or CPAN/MyConfig.pm that was loaded at start).
714 The configuration dialog can be started any time later again by
715 issuing the command \f(CW\*(C` o conf init \*(C'\fR in the \s-1CPAN\s0 shell. A subset of
716 the configuration dialog can be run by issuing \f(CW\*(C`o conf init WORD\*(C'\fR
717 where \s-1WORD\s0 is any valid config variable or a regular expression.
718 .Sh "Config Variables"
719 .IX Subsection "Config Variables"
720 The following keys in the hash reference \f(CW$CPAN::Config\fR are
724 \& applypatch path to external prg
725 \& auto_commit commit all changes to config variables to disk
726 \& build_cache size of cache for directories to build modules
727 \& build_dir locally accessible directory to build modules
728 \& build_dir_reuse boolean if distros in build_dir are persistent
729 \& build_requires_install_policy
730 \& to install or not to install when a module is
731 \& only needed for building. yes|no|ask/yes|ask/no
732 \& bzip2 path to external prg
733 \& cache_metadata use serializer to cache metadata
734 \& check_sigs if signatures should be verified
735 \& colorize_debug Term::ANSIColor attributes for debugging output
736 \& colorize_output boolean if Term::ANSIColor should colorize output
737 \& colorize_print Term::ANSIColor attributes for normal output
738 \& colorize_warn Term::ANSIColor attributes for warnings
739 \& commandnumber_in_prompt
740 \& boolean if you want to see current command number
741 \& commands_quote preferred character to use for quoting external
742 \& commands when running them. Defaults to double
743 \& quote on Windows, single tick everywhere else;
744 \& can be set to space to disable quoting
745 \& connect_to_internet_ok
746 \& whether to ask if opening a connection is ok before
747 \& urllist is specified
748 \& cpan_home local directory reserved for this package
749 \& curl path to external prg
750 \& dontload_hash DEPRECATED
751 \& dontload_list arrayref: modules in the list will not be
752 \& loaded by the CPAN::has_inst() routine
753 \& ftp path to external prg
754 \& ftp_passive if set, the envariable FTP_PASSIVE is set for downloads
755 \& ftp_proxy proxy host for ftp requests
756 \& ftpstats_period max number of days to keep download statistics
757 \& ftpstats_size max number of items to keep in the download statistics
759 \& gpg path to external prg
760 \& gzip location of external program gzip
761 \& halt_on_failure stop processing after the first failure of queued
762 \& items or dependencies
763 \& histfile file to maintain history between sessions
764 \& histsize maximum number of lines to keep in histfile
765 \& http_proxy proxy host for http requests
766 \& inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
767 \& after this many seconds inactivity. Set to 0 to
769 \& index_expire refetch index files after this many days
770 \& inhibit_startup_message
771 \& if true, suppress the startup message
772 \& keep_source_where directory in which to keep the source (if we do)
773 \& load_module_verbosity
774 \& report loading of optional modules used by CPAN.pm
775 \& lynx path to external prg
776 \& make location of external make program
777 \& make_arg arguments that should always be passed to 'make'
778 \& make_install_make_command
779 \& the make command for running 'make install', for
780 \& example 'sudo make'
781 \& make_install_arg same as make_arg for 'make install'
782 \& makepl_arg arguments passed to 'perl Makefile.PL'
783 \& mbuild_arg arguments passed to './Build'
784 \& mbuild_install_arg arguments passed to './Build install'
785 \& mbuild_install_build_command
786 \& command to use instead of './Build' when we are
787 \& in the install stage, for example 'sudo ./Build'
788 \& mbuildpl_arg arguments passed to 'perl Build.PL'
789 \& ncftp path to external prg
790 \& ncftpget path to external prg
791 \& no_proxy don't proxy to these hosts/domains (comma separated list)
792 \& pager location of external program more (or any pager)
793 \& password your password if you CPAN server wants one
794 \& patch path to external prg
795 \& patches_dir local directory containing patch files
796 \& perl5lib_verbosity verbosity level for PERL5LIB additions
797 \& prefer_installer legal values are MB and EUMM: if a module comes
798 \& with both a Makefile.PL and a Build.PL, use the
799 \& former (EUMM) or the latter (MB); if the module
800 \& comes with only one of the two, that one will be
801 \& used no matter the setting
802 \& prerequisites_policy
803 \& what to do if you are missing module prerequisites
804 \& ('follow' automatically, 'ask' me, or 'ignore')
805 \& prefs_dir local directory to store per\-distro build options
806 \& proxy_user username for accessing an authenticating proxy
807 \& proxy_pass password for accessing an authenticating proxy
808 \& randomize_urllist add some randomness to the sequence of the urllist
809 \& scan_cache controls scanning of cache ('atstart' or 'never')
810 \& shell your favorite shell
811 \& show_unparsable_versions
812 \& boolean if r command tells which modules are versionless
813 \& show_upload_date boolean if commands should try to determine upload date
814 \& show_zero_versions boolean if r command tells for which modules $version==0
815 \& tar location of external program tar
816 \& tar_verbosity verbosity level for the tar command
817 \& term_is_latin deprecated: if true Unicode is translated to ISO\-8859\-1
818 \& (and nonsense for characters outside latin range)
819 \& term_ornaments boolean to turn ReadLine ornamenting on/off
820 \& test_report email test reports (if CPAN::Reporter is installed)
821 \& trust_test_report_history
822 \& skip testing when previously tested ok (according to
823 \& CPAN::Reporter history)
824 \& unzip location of external program unzip
825 \& urllist arrayref to nearby CPAN sites (or equivalent locations)
826 \& use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
827 \& username your username if you CPAN server wants one
828 \& wait_list arrayref to a wait server to try (See CPAN::WAIT)
829 \& wget path to external prg
830 \& yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
831 \& yaml_module which module to use to read/write YAML files
834 You can set and query each of these options interactively in the cpan
835 shell with the \f(CW\*(C`o conf\*(C'\fR or the \f(CW\*(C`o conf init\*(C'\fR command as specified below.
836 .ie n .IP """o conf <scalar option>""" 2
837 .el .IP "\f(CWo conf <scalar option>\fR" 2
838 .IX Item "o conf <scalar option>"
839 prints the current value of the \fIscalar option\fR
840 .ie n .IP """o conf <scalar option> <value>""" 2
841 .el .IP "\f(CWo conf <scalar option> <value>\fR" 2
842 .IX Item "o conf <scalar option> <value>"
843 Sets the value of the \fIscalar option\fR to \fIvalue\fR
844 .ie n .IP """o conf <list option>""" 2
845 .el .IP "\f(CWo conf <list option>\fR" 2
846 .IX Item "o conf <list option>"
847 prints the current value of the \fIlist option\fR in MakeMaker's
849 .ie n .IP """o conf <list option> [shift|pop]""" 2
850 .el .IP "\f(CWo conf <list option> [shift|pop]\fR" 2
851 .IX Item "o conf <list option> [shift|pop]"
852 shifts or pops the array in the \fIlist option\fR variable
853 .ie n .IP """o conf <list option> [unshift|push|splice] <list>""" 2
854 .el .IP "\f(CWo conf <list option> [unshift|push|splice] <list>\fR" 2
855 .IX Item "o conf <list option> [unshift|push|splice] <list>"
856 works like the corresponding perl commands.
857 .IP "interactive editing: o conf init [MATCH|LIST]" 2
858 .IX Item "interactive editing: o conf init [MATCH|LIST]"
859 Runs an interactive configuration dialog for matching variables.
860 Without argument runs the dialog over all supported config variables.
861 To specify a \s-1MATCH\s0 the argument must be enclosed by slashes.
866 \& o conf init ftp_passive ftp_proxy
867 \& o conf init /color/
870 Note: this method of setting config variables often provides more
871 explanation about the functioning of a variable than the manpage.
872 .Sh "CPAN::anycwd($path): Note on config variable getcwd"
873 .IX Subsection "CPAN::anycwd($path): Note on config variable getcwd"
874 \&\s-1CPAN\s0.pm changes the current working directory often and needs to
875 determine its own current working directory. By default it uses
876 Cwd::cwd, but if for some reason this doesn't work on your system,
877 configure alternatives according to the following table:
888 .IX Item "backtickcwd"
889 Calls the external command cwd.
890 .Sh "Note on the format of the urllist parameter"
891 .IX Subsection "Note on the format of the urllist parameter"
892 urllist parameters are URLs according to \s-1RFC\s0 1738. We do a little
893 guessing if your \s-1URL\s0 is not compliant, but if you have problems with
894 \&\f(CW\*(C`file\*(C'\fR URLs, please try the correct format. Either:
897 \& file://localhost/whatever/ftp/pub/CPAN/
903 \& file:///home/ftp/pub/CPAN/
905 .Sh "The urllist parameter has CD-ROM support"
906 .IX Subsection "The urllist parameter has CD-ROM support"
907 The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of
908 URLs used for downloading. If the list contains any
909 \&\f(CW\*(C`file\*(C'\fR URLs, \s-1CPAN\s0 always tries there first. This
910 feature is disabled for index files. So the recommendation for the
911 owner of a CD-ROM with \s-1CPAN\s0 contents is: include your local, possibly
912 outdated CD-ROM as a \f(CW\*(C`file\*(C'\fR \s-1URL\s0 at the end of urllist, e.g.
915 \& o conf urllist push file://localhost/CDROM/CPAN
918 \&\s-1CPAN\s0.pm will then fetch the index files from one of the \s-1CPAN\s0 sites
919 that come at the beginning of urllist. It will later check for each
920 module to see whether there is a local copy of the most recent version.
922 Another peculiarity of urllist is that the site that we could
923 successfully fetch the last file from automatically gets a preference
924 token and is tried as the first site for the next request. So if you
925 add a new site at runtime it may happen that the previously preferred
926 site will be tried another time. This means that if you want to disallow
927 a site for the next transfer, it must be explicitly removed from
929 .Sh "Maintaining the urllist parameter"
930 .IX Subsection "Maintaining the urllist parameter"
931 If you have \s-1YAML\s0.pm (or some other \s-1YAML\s0 module configured in
932 \&\f(CW\*(C`yaml_module\*(C'\fR) installed, \s-1CPAN\s0.pm collects a few statistical data
933 about recent downloads. You can view the statistics with the \f(CW\*(C`hosts\*(C'\fR
934 command or inspect them directly by looking into the \f(CW\*(C`FTPstats.yml\*(C'\fR
935 file in your \f(CW\*(C`cpan_home\*(C'\fR directory.
937 To get some interesting statistics, it is recommended that
938 \&\f(CW\*(C`randomize_urllist\*(C'\fR be set; this introduces some amount of
939 randomness into the \s-1URL\s0 selection.
940 .ie n .Sh "The ""requires""\fP and \f(CW""build_requires"" dependency declarations"
941 .el .Sh "The \f(CWrequires\fP and \f(CWbuild_requires\fP dependency declarations"
942 .IX Subsection "The requires and build_requires dependency declarations"
943 Since \s-1CPAN\s0.pm version 1.88_51 modules declared as \f(CW\*(C`build_requires\*(C'\fR by
944 a distribution are treated differently depending on the config
945 variable \f(CW\*(C`build_requires_install_policy\*(C'\fR. By setting
946 \&\f(CW\*(C`build_requires_install_policy\*(C'\fR to \f(CW\*(C`no\*(C'\fR, such a module is not
947 installed. It is only built and tested, and then kept in the list of
948 tested but uninstalled modules. As such, it is available during the
949 build of the dependent module by integrating the path to the
950 \&\f(CW\*(C`blib/arch\*(C'\fR and \f(CW\*(C`blib/lib\*(C'\fR directories in the environment variable
951 \&\s-1PERL5LIB\s0. If \f(CW\*(C`build_requires_install_policy\*(C'\fR is set ti \f(CW\*(C`yes\*(C'\fR, then
952 both modules declared as \f(CW\*(C`requires\*(C'\fR and those declared as
953 \&\f(CW\*(C`build_requires\*(C'\fR are treated alike. By setting to \f(CW\*(C`ask/yes\*(C'\fR or
954 \&\f(CW\*(C`ask/no\*(C'\fR, \s-1CPAN\s0.pm asks the user and sets the default accordingly.
955 .Sh "Configuration for individual distributions (\fIDistroprefs\fP)"
956 .IX Subsection "Configuration for individual distributions (Distroprefs)"
957 (\fBNote:\fR This feature has been introduced in \s-1CPAN\s0.pm 1.8854 and is
958 still considered beta quality)
960 Distributions on \s-1CPAN\s0 usually behave according to what we call the
961 \&\s-1CPAN\s0 mantra. Or since the advent of Module::Build we should talk about
965 \& perl Makefile.PL perl Build.PL
967 \& make test ./Build test
968 \& make install ./Build install
971 But some modules cannot be built with this mantra. They try to get
972 some extra data from the user via the environment, extra arguments, or
973 interactively\*(--thus disturbing the installation of large bundles like
974 Phalanx100 or modules with many dependencies like Plagger.
976 The distroprefs system of \f(CW\*(C`CPAN.pm\*(C'\fR addresses this problem by
977 allowing the user to specify extra informations and recipes in \s-1YAML\s0
980 pass additional arguments to one of the four commands,
982 set environment variables
984 instantiate an Expect object that reads from the console, waits for
985 some regular expressions and enters some answers
987 temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables
989 specify dependencies the original maintainer forgot
991 disable the installation of an object altogether
993 See the \s-1YAML\s0 and Data::Dumper files that come with the \f(CW\*(C`CPAN.pm\*(C'\fR
994 distribution in the \f(CW\*(C`distroprefs/\*(C'\fR directory for examples.
996 .IX Subsection "Filenames"
997 The \s-1YAML\s0 files themselves must have the \f(CW\*(C`.yml\*(C'\fR extension; all other
998 files are ignored (for two exceptions see \fIFallback Data::Dumper and
999 Storable\fR below). The containing directory can be specified in
1000 \&\f(CW\*(C`CPAN.pm\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR config variable. Try \f(CW\*(C`o conf init
1001 prefs_dir\*(C'\fR in the \s-1CPAN\s0 shell to set and activate the distroprefs
1004 Every \s-1YAML\s0 file may contain arbitrary documents according to the \s-1YAML\s0
1005 specification, and every document is treated as an entity that
1006 can specify the treatment of a single distribution.
1008 Filenames can be picked arbitrarily; \f(CW\*(C`CPAN.pm\*(C'\fR always reads
1009 all files (in alphabetical order) and takes the key \f(CW\*(C`match\*(C'\fR (see
1010 below in \fILanguage Specs\fR) as a hashref containing match criteria
1011 that determine if the current distribution matches the \s-1YAML\s0 document
1013 .Sh "Fallback Data::Dumper and Storable"
1014 .IX Subsection "Fallback Data::Dumper and Storable"
1015 If neither your configured \f(CW\*(C`yaml_module\*(C'\fR nor \s-1YAML\s0.pm is installed,
1016 \&\s-1CPAN\s0.pm falls back to using Data::Dumper and Storable and looks for
1017 files with the extensions \f(CW\*(C`.dd\*(C'\fR or \f(CW\*(C`.st\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR
1018 directory. These files are expected to contain one or more hashrefs.
1019 For Data::Dumper generated files, this is expected to be done with by
1020 defining \f(CW$VAR1\fR, \f(CW$VAR2\fR, etc. The \s-1YAML\s0 shell would produce these
1024 \& ysh < somefile.yml > somefile.dd
1027 For Storable files the rule is that they must be constructed such that
1028 \&\f(CW\*(C`Storable::retrieve(file)\*(C'\fR returns an array reference and the array
1029 elements represent one distropref object each. The conversion from
1030 \&\s-1YAML\s0 would look like so:
1033 \& perl \-MYAML=LoadFile \-MStorable=nstore \-e '
1034 \& @y=LoadFile(shift);
1035 \& nstore(\e@y, shift)' somefile.yml somefile.st
1038 In bootstrapping situations it is usually sufficient to translate only
1039 a few \s-1YAML\s0 files to Data::Dumper for crucial modules like
1040 \&\f(CW\*(C`YAML::Syck\*(C'\fR, \f(CW\*(C`YAML.pm\*(C'\fR and \f(CW\*(C`Expect.pm\*(C'\fR. If you prefer Storable
1041 over Data::Dumper, remember to pull out a Storable version that writes
1042 an older format than all the other Storable versions that will need to
1045 .IX Subsection "Blueprint"
1046 The following example contains all supported keywords and structures
1047 with the exception of \f(CW\*(C`eexpect\*(C'\fR which can be used instead of
1048 \&\f(CW\*(C`expect\*(C'\fR.
1054 \& module: "Dancing::Queen"
1055 \& distribution: "^CHACHACHA/Dancing\-"
1056 \& not_distribution: "\e.zip$"
1057 \& perl: "/usr/local/cariba\-perl/bin/perl"
1059 \& archname: "freebsd"
1062 \& DANCING_FLOOR: "Shubiduh"
1068 \& \- "\-\-somearg=specialcase"
1077 \& \- "Which is your favorite fruit"
1097 \& commendline: "echo SKIPPING make"
1120 \& WANT_TO_INSTALL: YES
1125 \& \- "Do you really want to install"
1131 \& \- "ABCDE/Fedcba\-3.14\-ABCDE\-01.patch"
1136 \& configure_requires:
1139 \& Test::Exception: 0.25
1143 .Sh "Language Specs"
1144 .IX Subsection "Language Specs"
1145 Every \s-1YAML\s0 document represents a single hash reference. The valid keys
1146 in this hash are as follows:
1147 .IP "comment [scalar]" 4
1148 .IX Item "comment [scalar]"
1150 .IP "cpanconfig [hash]" 4
1151 .IX Item "cpanconfig [hash]"
1152 Temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables.
1154 Supported are: \f(CW\*(C`build_requires_install_policy\*(C'\fR, \f(CW\*(C`check_sigs\*(C'\fR,
1155 \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_install_make_command\*(C'\fR, \f(CW\*(C`prefer_installer\*(C'\fR,
1156 \&\f(CW\*(C`test_report\*(C'\fR. Please report as a bug when you need another one
1158 .IP "depends [hash] *** \s-1EXPERIMENTAL\s0 \s-1FEATURE\s0 ***" 4
1159 .IX Item "depends [hash] *** EXPERIMENTAL FEATURE ***"
1160 All three types, namely \f(CW\*(C`configure_requires\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and
1161 \&\f(CW\*(C`requires\*(C'\fR are supported in the way specified in the \s-1META\s0.yml
1162 specification. The current implementation \fImerges\fR the specified
1163 dependencies with those declared by the package maintainer. In a
1164 future implementation this may be changed to override the original
1166 .IP "disabled [boolean]" 4
1167 .IX Item "disabled [boolean]"
1168 Specifies that this distribution shall not be processed at all.
1169 .IP "features [array] *** \s-1EXPERIMENTAL\s0 \s-1FEATURE\s0 ***" 4
1170 .IX Item "features [array] *** EXPERIMENTAL FEATURE ***"
1171 Experimental implementation to deal with optional_features from
1172 \&\s-1META\s0.yml. Still needs coordination with installer software and
1173 currently works only for \s-1META\s0.yml declaring \f(CW\*(C`dynamic_config=0\*(C'\fR. Use
1175 .IP "goto [string]" 4
1176 .IX Item "goto [string]"
1177 The canonical name of a delegate distribution to install
1178 instead. Useful when a new version, although it tests \s-1OK\s0 itself,
1179 breaks something else or a developer release or a fork is already
1180 uploaded that is better than the last released version.
1181 .IP "install [hash]" 4
1182 .IX Item "install [hash]"
1183 Processing instructions for the \f(CW\*(C`make install\*(C'\fR or \f(CW\*(C`./Build install\*(C'\fR
1184 phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
1186 .IX Item "make [hash]"
1187 Processing instructions for the \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`./Build\*(C'\fR phase of the
1188 \&\s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
1189 .IP "match [hash]" 4
1190 .IX Item "match [hash]"
1191 A hashref with one or more of the keys \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`modules\*(C'\fR,
1192 \&\f(CW\*(C`perl\*(C'\fR, \f(CW\*(C`perlconfig\*(C'\fR, and \f(CW\*(C`env\*(C'\fR that specify whether a document is
1193 targeted at a specific \s-1CPAN\s0 distribution or installation.
1194 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1196 The corresponding values are interpreted as regular expressions. The
1197 \&\f(CW\*(C`distribution\*(C'\fR related one will be matched against the canonical
1198 distribution name, e.g. \*(L"AUTHOR/Foo\-Bar\-3.14.tar.gz\*(R".
1200 The \f(CW\*(C`module\*(C'\fR related one will be matched against \fIall\fR modules
1201 contained in the distribution until one module matches.
1203 The \f(CW\*(C`perl\*(C'\fR related one will be matched against \f(CW$^X\fR (but with the
1206 The value associated with \f(CW\*(C`perlconfig\*(C'\fR is itself a hashref that is
1207 matched against corresponding values in the \f(CW%Config::Config\fR hash
1208 living in the \f(CW\*(C`Config.pm\*(C'\fR module.
1209 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1211 The value associated with \f(CW\*(C`env\*(C'\fR is itself a hashref that is
1212 matched against corresponding values in the \f(CW%ENV\fR hash.
1213 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1215 If more than one restriction of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, etc. is
1216 specified, the results of the separately computed match values must
1217 all match. If so, the hashref represented by the
1218 \&\s-1YAML\s0 document is returned as the preference structure for the current
1220 .IP "patches [array]" 4
1221 .IX Item "patches [array]"
1222 An array of patches on \s-1CPAN\s0 or on the local disk to be applied in
1223 order via an external patch program. If the value for the \f(CW\*(C`\-p\*(C'\fR
1224 parameter is \f(CW0\fR or \f(CW1\fR is determined by reading the patch
1225 beforehand. The path to each patch is either an absolute path on the
1226 local filesystem or relative to a patch directory specified in the
1227 \&\f(CW\*(C`patches_dir\*(C'\fR configuration variable or in the format of a canonical
1228 distroname. For examples please consult the distroprefs/ directory in
1229 the \s-1CPAN\s0.pm distribution (these examples are not installed by
1232 Note: if the \f(CW\*(C`applypatch\*(C'\fR program is installed and \f(CW\*(C`CPAN::Config\*(C'\fR
1233 knows about it \fBand\fR a patch is written by the \f(CW\*(C`makepatch\*(C'\fR program,
1234 then \f(CW\*(C`CPAN.pm\*(C'\fR lets \f(CW\*(C`applypatch\*(C'\fR apply the patch. Both \f(CW\*(C`makepatch\*(C'\fR
1235 and \f(CW\*(C`applypatch\*(C'\fR are available from \s-1CPAN\s0 in the \f(CW\*(C`JV/makepatch\-*\*(C'\fR
1238 .IX Item "pl [hash]"
1239 Processing instructions for the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
1240 Build.PL\*(C'\fR phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing
1243 .IX Item "test [hash]"
1244 Processing instructions for the \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR phase
1245 of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR.
1246 .Sh "Processing Instructions"
1247 .IX Subsection "Processing Instructions"
1248 .IP "args [array]" 4
1249 .IX Item "args [array]"
1250 Arguments to be added to the command line
1252 .IX Item "commandline"
1253 A full commandline to run via \f(CW\*(C`system()\*(C'\fR.
1254 During execution, the environment variable \s-1PERL\s0 is set
1255 to $^X (but with an absolute path). If \f(CW\*(C`commandline\*(C'\fR is specified,
1256 \&\f(CW\*(C`args\*(C'\fR is not used.
1257 .IP "eexpect [hash]" 4
1258 .IX Item "eexpect [hash]"
1259 Extended \f(CW\*(C`expect\*(C'\fR. This is a hash reference with four allowed keys,
1260 \&\f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`reuse\*(C'\fR, and \f(CW\*(C`talk\*(C'\fR.
1262 \&\f(CW\*(C`mode\*(C'\fR may have the values \f(CW\*(C`deterministic\*(C'\fR for the case where all
1263 questions come in the order written down and \f(CW\*(C`anyorder\*(C'\fR for the case
1264 where the questions may come in any order. The default mode is
1265 \&\f(CW\*(C`deterministic\*(C'\fR.
1267 \&\f(CW\*(C`timeout\*(C'\fR denotes a timeout in seconds. Floating-point timeouts are
1268 \&\s-1OK\s0. With \f(CW\*(C`mode=deterministic\*(C'\fR, the timeout denotes the
1269 timeout per question; with \f(CW\*(C`mode=anyorder\*(C'\fR it denotes the
1270 timeout per byte received from the stream or questions.
1272 \&\f(CW\*(C`talk\*(C'\fR is a reference to an array that contains alternating questions
1273 and answers. Questions are regular expressions and answers are literal
1274 strings. The Expect module watches the stream from the
1275 execution of the external program (\f(CW\*(C`perl Makefile.PL\*(C'\fR, \f(CW\*(C`perl
1276 Build.PL\*(C'\fR, \f(CW\*(C`make\*(C'\fR, etc.).
1278 For \f(CW\*(C`mode=deterministic\*(C'\fR, the \s-1CPAN\s0.pm injects the
1279 corresponding answer as soon as the stream matches the regular expression.
1281 For \f(CW\*(C`mode=anyorder\*(C'\fR \s-1CPAN\s0.pm answers a question as soon
1282 as the timeout is reached for the next byte in the input stream. In
1283 this mode you can use the \f(CW\*(C`reuse\*(C'\fR parameter to decide what will
1284 happen with a question-answer pair after it has been used. In the
1285 default case (reuse=0) it is removed from the array, avoiding being
1286 used again accidentally. If you want to answer the
1287 question \f(CW\*(C`Do you really want to do that\*(C'\fR several times, then it must
1288 be included in the array at least as often as you want this answer to
1289 be given. Setting the parameter \f(CW\*(C`reuse\*(C'\fR to 1 makes this repetition
1292 .IX Item "env [hash]"
1293 Environment variables to be set during the command
1294 .IP "expect [array]" 4
1295 .IX Item "expect [array]"
1296 \&\f(CW\*(C`expect: <array>\*(C'\fR is a short notation for
1302 .ie n .Sh "Schema verification with ""Kwalify"""
1303 .el .Sh "Schema verification with \f(CWKwalify\fP"
1304 .IX Subsection "Schema verification with Kwalify"
1305 If you have the \f(CW\*(C`Kwalify\*(C'\fR module installed (which is part of the
1306 Bundle::CPANxxl), then all your distroprefs files are checked for
1307 syntactic correctness.
1308 .Sh "Example Distroprefs Files"
1309 .IX Subsection "Example Distroprefs Files"
1310 \&\f(CW\*(C`CPAN.pm\*(C'\fR comes with a collection of example \s-1YAML\s0 files. Note that these
1311 are really just examples and should not be used without care because
1312 they cannot fit everybody's purpose. After all, the authors of the
1313 packages that ask questions had a need to ask, so you should watch
1314 their questions and adjust the examples to your environment and your
1315 needs. You have been warned:\-)
1316 .SH "PROGRAMMER'S INTERFACE"
1317 .IX Header "PROGRAMMER'S INTERFACE"
1318 If you do not enter the shell, shell commands are
1319 available both as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as
1320 functions in the calling package (\f(CW\*(C`install(...)\*(C'\fR). Before calling low-level
1321 commands, it makes sense to initialize components of \s-1CPAN\s0 you need, e.g.:
1324 \& CPAN::HandleConfig\->load;
1325 \& CPAN::Shell::setup_output;
1326 \& CPAN::Index\->reload;
1329 High-level commands do such initializations automatically.
1331 There's currently only one class that has a stable interface \-
1332 CPAN::Shell. All commands that are available in the \s-1CPAN\s0 shell are
1333 methods of the class CPAN::Shell. Each of the commands that produce
1334 listings of modules (\f(CW\*(C`r\*(C'\fR, \f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of
1335 the IDs of all modules within the list.
1336 .IP "expand($type,@things)" 2
1337 .IX Item "expand($type,@things)"
1338 The IDs of all objects available within a program are strings that can
1339 be expanded to the corresponding real objects with the
1340 \&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a
1341 list of CPAN::Module objects according to the \f(CW@things\fR arguments
1342 given. In scalar context, it returns only the first element of the
1344 .IP "expandany(@things)" 2
1345 .IX Item "expandany(@things)"
1346 Like expand, but returns objects of the appropriate type, i.e.
1347 CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and
1348 CPAN::Distribution objects for distributions. Note: it does not expand
1349 to CPAN::Author objects.
1350 .IP "Programming Examples" 2
1351 .IX Item "Programming Examples"
1352 This enables the programmer to do operations that combine
1353 functionalities that are available in the shell.
1356 \& # install everything that is outdated on my disk:
1357 \& perl \-MCPAN \-e 'CPAN::Shell\->install(CPAN::Shell\->r)'
1361 \& # install my favorite programs if necessary:
1362 \& for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
1363 \& CPAN::Shell\->install($mod);
1368 \& # list all modules on my disk that have no VERSION number
1369 \& for $mod (CPAN::Shell\->expand("Module","/./")) {
1370 \& next unless $mod\->inst_file;
1371 \& # MakeMaker convention for undefined $VERSION:
1372 \& next unless $mod\->inst_version eq "undef";
1373 \& print "No VERSION in ", $mod\->id, "\en";
1378 \& # find out which distribution on CPAN contains a module:
1379 \& print CPAN::Shell\->expand("Module","Apache::Constants")\->cpan_file
1382 Or if you want to schedule a \fIcron\fR job to watch \s-1CPAN\s0, you could list
1383 all modules that need updating. First a quick and dirty way:
1386 \& perl \-e 'use CPAN; CPAN::Shell\->r;'
1389 If you don't want any output should all modules be
1390 up to date, parse the output of above command for the regular
1391 expression \f(CW\*(C`/modules are up to date/\*(C'\fR and decide to mail the output
1392 only if it doesn't match.
1394 If you prefer to do it more in a programmerish style in one single
1395 process, something like this may better suit you:
1398 \& # list all modules on my disk that have newer versions on CPAN
1399 \& for $mod (CPAN::Shell\->expand("Module","/./")) {
1400 \& next unless $mod\->inst_file;
1401 \& next if $mod\->uptodate;
1402 \& printf "Module %s is installed as %s, could be updated to %s from CPAN\en",
1403 \& $mod\->id, $mod\->inst_version, $mod\->cpan_version;
1407 If that gives too much output every day, you may want to
1408 watch only for three modules. You can write
1411 \& for $mod (CPAN::Shell\->expand("Module","/Apache|LWP|CGI/")) {
1414 as the first line instead. Or you can combine some of the above
1418 \& # watch only for a new mod_perl module
1419 \& $mod = CPAN::Shell\->expand("Module","mod_perl");
1420 \& exit if $mod\->uptodate;
1421 \& # new mod_perl arrived, let me know all update recommendations
1424 .Sh "Methods in the other Classes"
1425 .IX Subsection "Methods in the other Classes"
1426 .IP "\fICPAN::Author::as_glimpse()\fR" 4
1427 .IX Item "CPAN::Author::as_glimpse()"
1428 Returns a one-line description of the author
1429 .IP "\fICPAN::Author::as_string()\fR" 4
1430 .IX Item "CPAN::Author::as_string()"
1431 Returns a multi-line description of the author
1432 .IP "\fICPAN::Author::email()\fR" 4
1433 .IX Item "CPAN::Author::email()"
1434 Returns the author's email address
1435 .IP "\fICPAN::Author::fullname()\fR" 4
1436 .IX Item "CPAN::Author::fullname()"
1437 Returns the author's name
1438 .IP "\fICPAN::Author::name()\fR" 4
1439 .IX Item "CPAN::Author::name()"
1440 An alias for fullname
1441 .IP "\fICPAN::Bundle::as_glimpse()\fR" 4
1442 .IX Item "CPAN::Bundle::as_glimpse()"
1443 Returns a one-line description of the bundle
1444 .IP "\fICPAN::Bundle::as_string()\fR" 4
1445 .IX Item "CPAN::Bundle::as_string()"
1446 Returns a multi-line description of the bundle
1447 .IP "\fICPAN::Bundle::clean()\fR" 4
1448 .IX Item "CPAN::Bundle::clean()"
1449 Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle.
1450 .IP "\fICPAN::Bundle::contains()\fR" 4
1451 .IX Item "CPAN::Bundle::contains()"
1452 Returns a list of objects' IDs contained in a bundle. The associated
1453 objects may be bundles, modules or distributions.
1454 .IP "CPAN::Bundle::force($method,@args)" 4
1455 .IX Item "CPAN::Bundle::force($method,@args)"
1456 Forces \s-1CPAN\s0 to perform a task that it normally would have refused to
1457 do. Force takes as arguments a method name to be called and any number
1458 of additional arguments that should be passed to the called method.
1459 The internals of the object get the needed changes so that \s-1CPAN\s0.pm
1460 does not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively
1461 to all contained objects. See also the section above on the \f(CW\*(C`force\*(C'\fR
1462 and the \f(CW\*(C`fforce\*(C'\fR pragma.
1463 .IP "\fICPAN::Bundle::get()\fR" 4
1464 .IX Item "CPAN::Bundle::get()"
1465 Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle
1466 .IP "\fICPAN::Bundle::inst_file()\fR" 4
1467 .IX Item "CPAN::Bundle::inst_file()"
1468 Returns the highest installed version of the bundle in either \f(CW@INC\fR or
1469 \&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{cpan_home}>. Note that this is different from
1470 CPAN::Module::inst_file.
1471 .IP "\fICPAN::Bundle::inst_version()\fR" 4
1472 .IX Item "CPAN::Bundle::inst_version()"
1473 Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR
1474 .IP "\fICPAN::Bundle::uptodate()\fR" 4
1475 .IX Item "CPAN::Bundle::uptodate()"
1476 Returns 1 if the bundle itself and all its members are uptodate.
1477 .IP "\fICPAN::Bundle::install()\fR" 4
1478 .IX Item "CPAN::Bundle::install()"
1479 Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle
1480 .IP "\fICPAN::Bundle::make()\fR" 4
1481 .IX Item "CPAN::Bundle::make()"
1482 Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle
1483 .IP "\fICPAN::Bundle::readme()\fR" 4
1484 .IX Item "CPAN::Bundle::readme()"
1485 Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle
1486 .IP "\fICPAN::Bundle::test()\fR" 4
1487 .IX Item "CPAN::Bundle::test()"
1488 Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle
1489 .IP "\fICPAN::Distribution::as_glimpse()\fR" 4
1490 .IX Item "CPAN::Distribution::as_glimpse()"
1491 Returns a one-line description of the distribution
1492 .IP "\fICPAN::Distribution::as_string()\fR" 4
1493 .IX Item "CPAN::Distribution::as_string()"
1494 Returns a multi-line description of the distribution
1495 .IP "CPAN::Distribution::author" 4
1496 .IX Item "CPAN::Distribution::author"
1497 Returns the CPAN::Author object of the maintainer who uploaded this
1499 .IP "\fICPAN::Distribution::pretty_id()\fR" 4
1500 .IX Item "CPAN::Distribution::pretty_id()"
1501 Returns a string of the form \*(L"\s-1AUTHORID/TARBALL\s0\*(R", where \s-1AUTHORID\s0 is the
1502 author's \s-1PAUSE\s0 \s-1ID\s0 and \s-1TARBALL\s0 is the distribution filename.
1503 .IP "\fICPAN::Distribution::base_id()\fR" 4
1504 .IX Item "CPAN::Distribution::base_id()"
1505 Returns the distribution filename without any archive suffix. E.g
1506 \&\*(L"Foo\-Bar\-0.01\*(R"
1507 .IP "\fICPAN::Distribution::clean()\fR" 4
1508 .IX Item "CPAN::Distribution::clean()"
1509 Changes to the directory where the distribution has been unpacked and
1510 runs \f(CW\*(C`make clean\*(C'\fR there.
1511 .IP "\fICPAN::Distribution::containsmods()\fR" 4
1512 .IX Item "CPAN::Distribution::containsmods()"
1513 Returns a list of IDs of modules contained in a distribution file.
1514 Works only for distributions listed in the 02packages.details.txt.gz
1515 file. This typically means that just most recent version of a
1516 distribution is covered.
1517 .IP "\fICPAN::Distribution::cvs_import()\fR" 4
1518 .IX Item "CPAN::Distribution::cvs_import()"
1519 Changes to the directory where the distribution has been unpacked and
1523 \& cvs \-d $cvs_root import \-m $cvs_log $cvs_dir $userid v$version
1527 .IP "\fICPAN::Distribution::dir()\fR" 4
1528 .IX Item "CPAN::Distribution::dir()"
1529 Returns the directory into which this distribution has been unpacked.
1530 .IP "CPAN::Distribution::force($method,@args)" 4
1531 .IX Item "CPAN::Distribution::force($method,@args)"
1532 Forces \s-1CPAN\s0 to perform a task that it normally would have refused to
1533 do. Force takes as arguments a method name to be called and any number
1534 of additional arguments that should be passed to the called method.
1535 The internals of the object get the needed changes so that \s-1CPAN\s0.pm
1536 does not refuse to take the action. See also the section above on the
1537 \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
1538 .IP "\fICPAN::Distribution::get()\fR" 4
1539 .IX Item "CPAN::Distribution::get()"
1540 Downloads the distribution from \s-1CPAN\s0 and unpacks it. Does nothing if
1541 the distribution has already been downloaded and unpacked within the
1543 .IP "\fICPAN::Distribution::install()\fR" 4
1544 .IX Item "CPAN::Distribution::install()"
1545 Changes to the directory where the distribution has been unpacked and
1546 runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not
1547 yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR is issued in
1548 any case and if this fails, the install is cancelled. The
1549 cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for
1552 This install method only has the power to install the distribution if
1553 there are no dependencies in the way. To install an object along with all
1554 its dependencies, use CPAN::Shell\->install.
1556 Note that \fIinstall()\fR gives no meaningful return value. See \fIuptodate()\fR.
1557 .IP "\fICPAN::Distribution::install_tested()\fR" 4
1558 .IX Item "CPAN::Distribution::install_tested()"
1559 Install all distributions that have tested sucessfully but
1560 not yet installed. See also \f(CW\*(C`is_tested\*(C'\fR.
1561 .IP "\fICPAN::Distribution::isa_perl()\fR" 4
1562 .IX Item "CPAN::Distribution::isa_perl()"
1563 Returns 1 if this distribution file seems to be a perl distribution.
1564 Normally this is derived from the file name only, but the index from
1565 \&\s-1CPAN\s0 can contain a hint to achieve a return value of true for other
1567 .IP "\fICPAN::Distribution::look()\fR" 4
1568 .IX Item "CPAN::Distribution::look()"
1569 Changes to the directory where the distribution has been unpacked and
1570 opens a subshell there. Exiting the subshell returns.
1571 .IP "\fICPAN::Distribution::make()\fR" 4
1572 .IX Item "CPAN::Distribution::make()"
1573 First runs the \f(CW\*(C`get\*(C'\fR method to make sure the distribution is
1574 downloaded and unpacked. Changes to the directory where the
1575 distribution has been unpacked and runs the external commands \f(CW\*(C`perl
1576 Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there.
1577 .IP "\fICPAN::Distribution::perldoc()\fR" 4
1578 .IX Item "CPAN::Distribution::perldoc()"
1579 Downloads the pod documentation of the file associated with a
1580 distribution (in \s-1HTML\s0 format) and runs it through the external
1581 command \fIlynx\fR specified in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{lynx}>. If \fIlynx\fR
1582 isn't available, it converts it to plain text with the external
1583 command \fIhtml2text\fR and runs it through the pager specified
1584 in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{pager}>
1585 .IP "\fICPAN::Distribution::prefs()\fR" 4
1586 .IX Item "CPAN::Distribution::prefs()"
1587 Returns the hash reference from the first matching \s-1YAML\s0 file that the
1588 user has deposited in the \f(CW\*(C`prefs_dir/\*(C'\fR directory. The first
1589 succeeding match wins. The files in the \f(CW\*(C`prefs_dir/\*(C'\fR are processed
1590 alphabetically, and the canonical distroname (e.g.
1591 AUTHOR/Foo\-Bar\-3.14.tar.gz) is matched against the regular expressions
1592 stored in the \f(CW$root\fR\->{match}{distribution} attribute value.
1593 Additionally all module names contained in a distribution are matched
1594 against the regular expressions in the \f(CW$root\fR\->{match}{module} attribute
1595 value. The two match values are ANDed together. Each of the two
1596 attributes are optional.
1597 .IP "\fICPAN::Distribution::prereq_pm()\fR" 4
1598 .IX Item "CPAN::Distribution::prereq_pm()"
1599 Returns the hash reference that has been announced by a distribution
1600 as the \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`build_requires\*(C'\fR elements. These can be
1601 declared either by the \f(CW\*(C`META.yml\*(C'\fR (if authoritative) or can be
1602 deposited after the run of \f(CW\*(C`Build.PL\*(C'\fR in the file \f(CW\*(C`./_build/prereqs\*(C'\fR
1603 or after the run of \f(CW\*(C`Makfile.PL\*(C'\fR written as the \f(CW\*(C`PREREQ_PM\*(C'\fR hash in
1604 a comment in the produced \f(CW\*(C`Makefile\*(C'\fR. \fINote\fR: this method only works
1605 after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns
1607 .IP "\fICPAN::Distribution::readme()\fR" 4
1608 .IX Item "CPAN::Distribution::readme()"
1609 Downloads the \s-1README\s0 file associated with a distribution and runs it
1610 through the pager specified in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{pager}>.
1611 .IP "\fICPAN::Distribution::reports()\fR" 4
1612 .IX Item "CPAN::Distribution::reports()"
1613 Downloads report data for this distribution from www.cpantesters.org
1614 and displays a subset of them.
1615 .IP "\fICPAN::Distribution::read_yaml()\fR" 4
1616 .IX Item "CPAN::Distribution::read_yaml()"
1617 Returns the content of the \s-1META\s0.yml of this distro as a hashref. Note:
1618 works only after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution.
1619 Returns undef otherwise. Also returns undef if the content of \s-1META\s0.yml
1620 is not authoritative. (The rules about what exactly makes the content
1621 authoritative are still in flux.)
1622 .IP "\fICPAN::Distribution::test()\fR" 4
1623 .IX Item "CPAN::Distribution::test()"
1624 Changes to the directory where the distribution has been unpacked and
1625 runs \f(CW\*(C`make test\*(C'\fR there.
1626 .IP "\fICPAN::Distribution::uptodate()\fR" 4
1627 .IX Item "CPAN::Distribution::uptodate()"
1628 Returns 1 if all the modules contained in the distribution are
1629 uptodate. Relies on containsmods.
1630 .IP "\fICPAN::Index::force_reload()\fR" 4
1631 .IX Item "CPAN::Index::force_reload()"
1632 Forces a reload of all indices.
1633 .IP "\fICPAN::Index::reload()\fR" 4
1634 .IX Item "CPAN::Index::reload()"
1635 Reloads all indices if they have not been read for more than
1636 \&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{index_expire}> days.
1637 .IP "\fICPAN::InfoObj::dump()\fR" 4
1638 .IX Item "CPAN::InfoObj::dump()"
1639 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
1640 inherit this method. It prints the data structure associated with an
1641 object. Useful for debugging. Note: the data structure is considered
1642 internal and thus subject to change without notice.
1643 .IP "\fICPAN::Module::as_glimpse()\fR" 4
1644 .IX Item "CPAN::Module::as_glimpse()"
1645 Returns a one-line description of the module in four columns: The
1646 first column contains the word \f(CW\*(C`Module\*(C'\fR, the second column consists
1647 of one character: an equals sign if this module is already installed
1648 and uptodate, a less-than sign if this module is installed but can be
1649 upgraded, and a space if the module is not installed. The third column
1650 is the name of the module and the fourth column gives maintainer or
1651 distribution information.
1652 .IP "\fICPAN::Module::as_string()\fR" 4
1653 .IX Item "CPAN::Module::as_string()"
1654 Returns a multi-line description of the module
1655 .IP "\fICPAN::Module::clean()\fR" 4
1656 .IX Item "CPAN::Module::clean()"
1657 Runs a clean on the distribution associated with this module.
1658 .IP "\fICPAN::Module::cpan_file()\fR" 4
1659 .IX Item "CPAN::Module::cpan_file()"
1660 Returns the filename on \s-1CPAN\s0 that is associated with the module.
1661 .IP "\fICPAN::Module::cpan_version()\fR" 4
1662 .IX Item "CPAN::Module::cpan_version()"
1663 Returns the latest version of this module available on \s-1CPAN\s0.
1664 .IP "\fICPAN::Module::cvs_import()\fR" 4
1665 .IX Item "CPAN::Module::cvs_import()"
1666 Runs a cvs_import on the distribution associated with this module.
1667 .IP "\fICPAN::Module::description()\fR" 4
1668 .IX Item "CPAN::Module::description()"
1669 Returns a 44 character description of this module. Only available for
1670 modules listed in The Module List (CPAN/modules/00modlist.long.html
1671 or 00modlist.long.txt.gz)
1672 .IP "\fICPAN::Module::distribution()\fR" 4
1673 .IX Item "CPAN::Module::distribution()"
1674 Returns the CPAN::Distribution object that contains the current
1675 version of this module.
1676 .IP "\fICPAN::Module::dslip_status()\fR" 4
1677 .IX Item "CPAN::Module::dslip_status()"
1678 Returns a hash reference. The keys of the hash are the letters \f(CW\*(C`D\*(C'\fR,
1679 \&\f(CW\*(C`S\*(C'\fR, \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`I\*(C'\fR, and <P>, for development status, support level,
1680 language, interface and public licence respectively. The data for the
1681 \&\s-1DSLIP\s0 status are collected by pause.perl.org when authors register
1682 their namespaces. The values of the 5 hash elements are one-character
1683 words whose meaning is described in the table below. There are also 5
1684 hash elements \f(CW\*(C`DV\*(C'\fR, \f(CW\*(C`SV\*(C'\fR, \f(CW\*(C`LV\*(C'\fR, \f(CW\*(C`IV\*(C'\fR, and <\s-1PV\s0> that carry a more
1685 verbose value of the 5 status variables.
1687 Where the '\s-1DSLIP\s0' characters have the following meanings:
1690 \& D \- Development Stage (Note: *NO IMPLIED TIMESCALES*):
1691 \& i \- Idea, listed to gain consensus or as a placeholder
1692 \& c \- under construction but pre\-alpha (not yet released)
1693 \& a/b \- Alpha/Beta testing
1695 \& M \- Mature (no rigorous definition)
1696 \& S \- Standard, supplied with Perl 5
1700 \& S \- Support Level:
1701 \& m \- Mailing\-list
1703 \& u \- Usenet newsgroup comp.lang.perl.modules
1704 \& n \- None known, try comp.lang.perl.modules
1705 \& a \- abandoned; volunteers welcome to take over maintainance
1709 \& L \- Language Used:
1710 \& p \- Perl\-only, no compiler needed, should be platform independent
1711 \& c \- C and perl, a C compiler will be needed
1712 \& h \- Hybrid, written in perl with optional C code, no compiler needed
1713 \& + \- C++ and perl, a C++ compiler will be needed
1714 \& o \- perl and another language other than C or C++
1718 \& I \- Interface Style
1719 \& f \- plain Functions, no references used
1720 \& h \- hybrid, object and function interfaces available
1721 \& n \- no interface at all (huh?)
1722 \& r \- some use of unblessed References or ties
1723 \& O \- Object oriented using blessed references and/or inheritance
1727 \& P \- Public License
1728 \& p \- Standard\-Perl: user may choose between GPL and Artistic
1729 \& g \- GPL: GNU General Public License
1730 \& l \- LGPL: "GNU Lesser General Public License" (previously known as
1731 \& "GNU Library General Public License")
1732 \& b \- BSD: The BSD License
1733 \& a \- Artistic license alone
1734 \& 2 \- Artistic license 2.0 or later
1735 \& o \- open source: appoved by www.opensource.org
1736 \& d \- allows distribution without restrictions
1737 \& r \- restricted distribtion
1738 \& n \- no license at all
1740 .IP "CPAN::Module::force($method,@args)" 4
1741 .IX Item "CPAN::Module::force($method,@args)"
1742 Forces \s-1CPAN\s0 to perform a task it would normally refuse to
1743 do. Force takes as arguments a method name to be invoked and any number
1744 of additional arguments to pass that method.
1745 The internals of the object get the needed changes so that \s-1CPAN\s0.pm
1746 does not refuse to take the action. See also the section above on the
1747 \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
1748 .IP "\fICPAN::Module::get()\fR" 4
1749 .IX Item "CPAN::Module::get()"
1750 Runs a get on the distribution associated with this module.
1751 .IP "\fICPAN::Module::inst_file()\fR" 4
1752 .IX Item "CPAN::Module::inst_file()"
1753 Returns the filename of the module found in \f(CW@INC\fR. The first file found
1754 is reported, just as perl itself stops searching \f(CW@INC\fR once it finds a
1756 .IP "\fICPAN::Module::available_file()\fR" 4
1757 .IX Item "CPAN::Module::available_file()"
1758 Returns the filename of the module found in \s-1PERL5LIB\s0 or \f(CW@INC\fR. The
1759 first file found is reported. The advantage of this method over
1760 \&\f(CW\*(C`inst_file\*(C'\fR is that modules that have been tested but not yet
1761 installed are included because \s-1PERL5LIB\s0 keeps track of tested modules.
1762 .IP "\fICPAN::Module::inst_version()\fR" 4
1763 .IX Item "CPAN::Module::inst_version()"
1764 Returns the version number of the installed module in readable format.
1765 .IP "\fICPAN::Module::available_version()\fR" 4
1766 .IX Item "CPAN::Module::available_version()"
1767 Returns the version number of the available module in readable format.
1768 .IP "\fICPAN::Module::install()\fR" 4
1769 .IX Item "CPAN::Module::install()"
1770 Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module.
1771 .IP "\fICPAN::Module::look()\fR" 4
1772 .IX Item "CPAN::Module::look()"
1773 Changes to the directory where the distribution associated with this
1774 module has been unpacked and opens a subshell there. Exiting the
1776 .IP "\fICPAN::Module::make()\fR" 4
1777 .IX Item "CPAN::Module::make()"
1778 Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module.
1779 .IP "\fICPAN::Module::manpage_headline()\fR" 4
1780 .IX Item "CPAN::Module::manpage_headline()"
1781 If module is installed, peeks into the module's manpage, reads the
1782 headline, and returns it. Moreover, if the module has been downloaded
1783 within this session, does the equivalent on the downloaded module even
1784 if it hasn't been installed yet.
1785 .IP "\fICPAN::Module::perldoc()\fR" 4
1786 .IX Item "CPAN::Module::perldoc()"
1787 Runs a \f(CW\*(C`perldoc\*(C'\fR on this module.
1788 .IP "\fICPAN::Module::readme()\fR" 4
1789 .IX Item "CPAN::Module::readme()"
1790 Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module.
1791 .IP "\fICPAN::Module::reports()\fR" 4
1792 .IX Item "CPAN::Module::reports()"
1793 Calls the \fIreports()\fR method on the associated distribution object.
1794 .IP "\fICPAN::Module::test()\fR" 4
1795 .IX Item "CPAN::Module::test()"
1796 Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module.
1797 .IP "\fICPAN::Module::uptodate()\fR" 4
1798 .IX Item "CPAN::Module::uptodate()"
1799 Returns 1 if the module is installed and up\-to\-date.
1800 .IP "\fICPAN::Module::userid()\fR" 4
1801 .IX Item "CPAN::Module::userid()"
1802 Returns the author's \s-1ID\s0 of the module.
1804 .IX Subsection "Cache Manager"
1805 Currently the cache manager only keeps track of the build directory
1806 ($CPAN::Config\->{build_dir}). It is a simple \s-1FIFO\s0 mechanism that
1807 deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of
1808 all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache}
1809 (in \s-1MB\s0). The contents of this cache may be used for later
1810 re-installations that you intend to do manually, but will never be
1811 trusted by \s-1CPAN\s0 itself. This is due to the fact that the user might
1812 use these directories for building modules on different architectures.
1814 There is another directory ($CPAN::Config\->{keep_source_where}) where
1815 the original distribution files are kept. This directory is not
1816 covered by the cache manager and must be controlled by the user. If
1817 you choose to have the same directory as build_dir and as
1818 keep_source_where directory, then your sources will be deleted with
1819 the same fifo mechanism.
1821 .IX Subsection "Bundles"
1822 A bundle is just a perl module in the namespace Bundle:: that does not
1823 define any functions or methods. It usually only contains documentation.
1825 It starts like a perl module with a package declaration and a \f(CW$VERSION\fR
1826 variable. After that the pod section looks like any other pod with the
1827 only difference being that \fIone special pod section\fR exists starting with
1834 In this pod section each line obeys the format
1837 \& Module_Name [Version_String] [\- optional text]
1840 The only required part is the first field, the name of a module
1841 (e.g. Foo::Bar, ie. \fInot\fR the name of the distribution file). The rest
1842 of the line is optional. The comment part is delimited by a dash just
1843 as in the man page header.
1845 The distribution of a bundle should follow the same convention as
1846 other distributions.
1848 Bundles are treated specially in the \s-1CPAN\s0 package. If you say 'install
1849 Bundle::Tkkit' (assuming such a bundle exists), \s-1CPAN\s0 will install all
1850 the modules in the \s-1CONTENTS\s0 section of the pod. You can install your
1851 own Bundles locally by placing a conformant Bundle file somewhere into
1852 your \f(CW@INC\fR path. The \fIautobundle()\fR command which is available in the
1853 shell interface does that for you by including all currently installed
1854 modules in a snapshot bundle file.
1856 .IX Header "PREREQUISITES"
1857 If you have a local mirror of \s-1CPAN\s0 and can access all files with
1858 \&\*(L"file:\*(R" URLs, then you only need a perl later than perl5.003 to run
1859 this module. Otherwise Net::FTP is strongly recommended. \s-1LWP\s0 may be
1860 required for non-UNIX systems, or if your nearest \s-1CPAN\s0 site is
1861 associated with a \s-1URL\s0 that is not \f(CW\*(C`ftp:\*(C'\fR.
1863 If you have neither Net::FTP nor \s-1LWP\s0, there is a fallback mechanism
1864 implemented for an external ftp command or for an external lynx
1867 .IX Header "UTILITIES"
1868 .Sh "Finding packages and \s-1VERSION\s0"
1869 .IX Subsection "Finding packages and VERSION"
1870 This module presumes that all packages on \s-1CPAN\s0
1872 declare their \f(CW$VERSION\fR variable in an easy to parse manner. This
1873 prerequisite can hardly be relaxed because it consumes far too much
1874 memory to load all packages into the running program just to determine
1875 the \f(CW$VERSION\fR variable. Currently all programs that are dealing with
1876 version use something like this
1879 \& perl \-MExtUtils::MakeMaker \-le \e
1880 \& 'print MM\->parse_version(shift)' filename
1883 If you are author of a package and wonder if your \f(CW$VERSION\fR can be
1884 parsed, please try the above method.
1886 come as compressed or gzipped tarfiles or as zip files and contain a
1887 \&\f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR (well, we try to handle a bit more, but
1888 with little enthusiasm).
1890 .IX Subsection "Debugging"
1891 Debugging this module is more than a bit complex due to interference from
1892 the software producing the indices on \s-1CPAN\s0, the mirroring process on \s-1CPAN\s0,
1893 packaging, configuration, synchronicity, and even (gasp!) due to bugs
1894 within the \s-1CPAN\s0.pm module itself.
1896 For debugging the code of \s-1CPAN\s0.pm itself in interactive mode, some
1897 debugging aid can be turned on for most packages within
1898 \&\s-1CPAN\s0.pm with one of
1899 .IP "o debug package..." 2
1900 .IX Item "debug package..."
1901 sets debug mode for packages.
1902 .IP "o debug \-package..." 2
1903 .IX Item "debug -package..."
1904 unsets debug mode for packages.
1906 .IX Item "debug all"
1907 turns debugging on for all packages.
1908 .IP "o debug number" 2
1909 .IX Item "debug number"
1911 which sets the debugging packages directly. Note that \f(CW\*(C`o debug 0\*(C'\fR
1912 turns debugging off.
1914 What seems a successful strategy is the combination of \f(CW\*(C`reload
1915 cpan\*(C'\fR and the debugging switches. Add a new debug statement while
1916 running in the shell and then issue a \f(CW\*(C`reload cpan\*(C'\fR and see the new
1917 debugging messages immediately without losing the current context.
1919 \&\f(CW\*(C`o debug\*(C'\fR without an argument lists the valid package names and the
1920 current set of packages in debugging mode. \f(CW\*(C`o debug\*(C'\fR has built-in
1923 For debugging of \s-1CPAN\s0 data there is the \f(CW\*(C`dump\*(C'\fR command which takes
1924 the same arguments as make/test/install and outputs each object's
1925 Data::Dumper dump. If an argument looks like a perl variable and
1926 contains one of \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, it is \fIeval()\fRed and fed to
1927 Data::Dumper directly.
1928 .Sh "Floppy, Zip, Offline Mode"
1929 .IX Subsection "Floppy, Zip, Offline Mode"
1930 \&\s-1CPAN\s0.pm works nicely without network access, too. If you maintain machines
1931 that are not networked at all, you should consider working with \f(CW\*(C`file:\*(C'\fR
1932 URLs. You'll have to collect your modules somewhere first. So
1933 you might use \s-1CPAN\s0.pm to put together all you need on a networked
1934 machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not
1935 \&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind
1936 of a personal \s-1CPAN\s0. \s-1CPAN\s0.pm on the non-networked machines works nicely
1937 with this floppy. See also below the paragraph about CD-ROM support.
1938 .Sh "Basic Utilities for Programmers"
1939 .IX Subsection "Basic Utilities for Programmers"
1940 .IP "has_inst($module)" 2
1941 .IX Item "has_inst($module)"
1942 Returns true if the module is installed. Used to load all modules into
1943 the running \s-1CPAN\s0.pm that are considered optional. The config variable
1944 \&\f(CW\*(C`dontload_list\*(C'\fR intercepts the \f(CW\*(C`has_inst()\*(C'\fR call such
1945 that an optional module is not loaded despite being available. For
1946 example, the following command will prevent \f(CW\*(C`YAML.pm\*(C'\fR from being
1950 \& cpan> o conf dontload_list push YAML
1953 See the source for details.
1954 .IP "has_usable($module)" 2
1955 .IX Item "has_usable($module)"
1956 Returns true if the module is installed and in a usable state. Only
1957 useful for a handful of modules that are used internally. See the
1959 .IP "instance($module)" 2
1960 .IX Item "instance($module)"
1961 The constructor for all the singletons used to represent modules,
1962 distributions, authors, and bundles. If the object already exists, this
1963 method returns the object; otherwise, it calls the constructor.
1965 .IX Header "SECURITY"
1966 There's no strong security layer in \s-1CPAN\s0.pm. \s-1CPAN\s0.pm helps you to
1967 install foreign, unmasked, unsigned code on your machine. We compare
1968 to a checksum that comes from the net just as the distribution file
1969 itself. But we try to make it easy to add security on demand:
1970 .Sh "Cryptographically signed modules"
1971 .IX Subsection "Cryptographically signed modules"
1972 Since release 1.77, \s-1CPAN\s0.pm has been able to verify cryptographically
1973 signed module distributions using Module::Signature. The \s-1CPAN\s0 modules
1974 can be signed by their authors, thus giving more security. The simple
1975 unsigned \s-1MD5\s0 checksums that were used before by \s-1CPAN\s0 protect mainly
1976 against accidental file corruption.
1978 You will need to have Module::Signature installed, which in turn
1979 requires that you have at least one of Crypt::OpenPGP module or the
1980 command-line \fIgpg\fR tool installed.
1982 You will also need to be able to connect over the Internet to the public
1983 keyservers, like pgp.mit.edu, and their port 11731 (the \s-1HKP\s0 protocol).
1985 The configuration parameter check_sigs is there to turn signature
1989 Most functions in package \s-1CPAN\s0 are exported by default. The reason
1990 for this is that the primary use is intended for the cpan shell or for
1993 .IX Header "ENVIRONMENT"
1994 When the \s-1CPAN\s0 shell enters a subshell via the look command, it sets
1995 the environment \s-1CPAN_SHELL_LEVEL\s0 to 1, or increments that variable if it is
1998 When \s-1CPAN\s0 runs, it sets the environment variable \s-1PERL5_CPAN_IS_RUNNING\s0
1999 to the \s-1ID\s0 of the running process. It also sets
2000 \&\s-1PERL5_CPANPLUS_IS_RUNNING\s0 to prevent runaway processes which could
2001 happen with older versions of Module::Install.
2003 When running \f(CW\*(C`perl Makefile.PL\*(C'\fR, the environment variable
2004 \&\f(CW\*(C`PERL5_CPAN_IS_EXECUTING\*(C'\fR is set to the full path of the
2005 \&\f(CW\*(C`Makefile.PL\*(C'\fR that is being executed. This prevents runaway processes
2006 with newer versions of Module::Install.
2008 When the config variable ftp_passive is set, all downloads will be run
2009 with the environment variable \s-1FTP_PASSIVE\s0 set to this value. This is
2010 in general a good idea as it influences both Net::FTP and \s-1LWP\s0 based
2011 connections. The same effect can be achieved by starting the cpan
2012 shell with this environment variable set. For Net::FTP alone, one can
2013 also always set passive mode by running libnetcfg.
2014 .SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
2015 .IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
2016 Populating a freshly installed perl with one's favorite modules is pretty
2017 easy if you maintain a private bundle definition file. To get a useful
2018 blueprint of a bundle definition file, the command autobundle can be used
2019 on the \s-1CPAN\s0 shell command line. This command writes a bundle definition
2020 file for all modules installed for the current perl
2021 interpreter. It's recommended to run this command once only, and from then
2022 on maintain the file manually under a private name, say
2023 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
2026 \& cpan> install Bundle::my_bundle
2029 then answer a few questions and go out for coffee (possibly
2030 even in a different city).
2032 Maintaining a bundle definition file means keeping track of two
2033 things: dependencies and interactivity. \s-1CPAN\s0.pm sometimes fails on
2034 calculating dependencies because not all modules define all MakeMaker
2035 attributes correctly, so a bundle definition file should specify
2036 prerequisites as early as possible. On the other hand, it's
2037 annoying that so many distributions need some interactive configuring. So
2038 what you can try to accomplish in your private bundle file is to have the
2039 packages that need to be configured early in the file and the gentle
2040 ones later, so you can go out for cofeee after a few minutes and leave \s-1CPAN\s0.pm
2041 to churn away untended.
2042 .SH "WORKING WITH CPAN.pm BEHIND FIREWALLS"
2043 .IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS"
2044 Thanks to Graham Barr for contributing the following paragraphs about
2045 the interaction between perl, and various firewall configurations. For
2046 further information on firewalls, it is recommended to consult the
2047 documentation that comes with the \fIncftp\fR program. If you are unable to
2048 go through the firewall with a simple Perl setup, it is likely
2049 that you can configure \fIncftp\fR so that it works through your firewall.
2050 .Sh "Three basic types of firewalls"
2051 .IX Subsection "Three basic types of firewalls"
2052 Firewalls can be categorized into three basic types.
2053 .IP "http firewall" 4
2054 .IX Item "http firewall"
2055 This is when the firewall machine runs a web server, and to access the
2056 outside world, you must do so via that web server. If you set environment
2057 variables like http_proxy or ftp_proxy to values beginning with http://,
2058 or in your web browser you've proxy information set, then you know
2059 you are running behind an http firewall.
2061 To access servers outside these types of firewalls with perl (even for
2062 ftp), you need \s-1LWP\s0.
2063 .IP "ftp firewall" 4
2064 .IX Item "ftp firewall"
2065 This where the firewall machine runs an ftp server. This kind of
2066 firewall will only let you access ftp servers outside the firewall.
2067 This is usually done by connecting to the firewall with ftp, then
2068 entering a username like \*(L"user@outside.host.com\*(R".
2070 To access servers outside these type of firewalls with perl, you
2072 .IP "One-way visibility" 4
2073 .IX Item "One-way visibility"
2074 One-way visibility means these firewalls try to make themselves
2075 invisible to users inside the firewall. An \s-1FTP\s0 data connection is
2076 normally created by sending your \s-1IP\s0 address to the remote server and then
2077 listening for the return connection. But the remote server will not be able to
2078 connect to you because of the firewall. For these types of firewall,
2079 \&\s-1FTP\s0 connections need to be done in a passive mode.
2081 There are two that I can think off.
2083 .IP "\s-1SOCKS\s0" 4
2085 If you are using a \s-1SOCKS\s0 firewall, you will need to compile perl and link
2086 it with the \s-1SOCKS\s0 library. This is what is normally called a 'socksified'
2087 perl. With this executable you will be able to connect to servers outside
2088 the firewall as if it were not there.
2089 .IP "\s-1IP\s0 Masquerade" 4
2090 .IX Item "IP Masquerade"
2091 This is when the firewall implemented in the kernel (via \s-1NAT\s0, or networking
2092 address translation), it allows you to hide a complete network behind one
2093 \&\s-1IP\s0 address. With this firewall no special compiling is needed as you can
2094 access hosts directly.
2096 For accessing ftp servers behind such firewalls you usually need to
2097 set the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR or the config variable
2098 ftp_passive to a true value.
2102 .Sh "Configuring lynx or ncftp for going through a firewall"
2103 .IX Subsection "Configuring lynx or ncftp for going through a firewall"
2104 If you can go through your firewall with e.g. lynx, presumably with a
2108 \& /usr/local/bin/lynx \-pscott:tiger
2111 then you would configure \s-1CPAN\s0.pm with the command
2114 \& o conf lynx "/usr/local/bin/lynx \-pscott:tiger"
2117 That's all. Similarly for ncftp or ftp, you would configure something
2121 \& o conf ncftp "/usr/bin/ncftp \-f /home/scott/ncftplogin.cfg"
2124 Your mileage may vary...
2128 I installed a new version of module X but \s-1CPAN\s0 keeps saying,
2129 I have the old version installed
2131 Probably you \fBdo\fR have the old version installed. This can
2132 happen if a module installs itself into a different directory in the
2133 \&\f(CW@INC\fR path than it was previously installed. This is not really a
2134 \&\s-1CPAN\s0.pm problem, you would have the same problem when installing the
2135 module manually. The easiest way to prevent this behaviour is to add
2136 the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why
2137 many people add this argument permanently by configuring
2140 \& o conf make_install_arg UNINST=1
2143 So why is UNINST=1 not the default?
2145 Because there are people who have their precise expectations about who
2146 may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In
2147 fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage.
2149 I want to clean up my mess, and install a new perl along with
2150 all modules I have. How do I go about it?
2152 Run the autobundle command for your old perl and optionally rename the
2153 resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
2154 with the Configure option prefix, e.g.
2157 \& ./Configure \-Dprefix=/usr/local/perl\-5.6.78.9
2160 Install the bundle file you produced in the first step with something like
2163 \& cpan> install Bundle::mybundle
2168 When I install bundles or multiple modules with one command
2169 there is too much output to keep track of.
2171 You may want to configure something like
2174 \& o conf make_arg "| tee \-ai /root/.cpan/logs/make.out"
2175 \& o conf make_install_arg "| tee \-ai /root/.cpan/logs/make_install.out"
2178 so that \s-1STDOUT\s0 is captured in a file for later inspection.
2180 I am not root, how can I install a module in a personal directory?
2182 First of all, you will want to use your own configuration, not the one
2183 that your root user installed. If you do not have permission to write
2184 in the cpan directory that root has configured, you will be asked if
2185 you want to create your own config. Answering \*(L"yes\*(R" will bring you into
2186 \&\s-1CPAN\s0's configuration stage, using the system config for all defaults except
2187 things that have to do with \s-1CPAN\s0's work directory, saving your choices to
2188 your MyConfig.pm file.
2190 You can also manually initiate this process with the following command:
2193 \& % perl \-MCPAN \-e 'mkmyconfig'
2202 from the \s-1CPAN\s0 shell.
2204 You will most probably also want to configure something like this:
2207 \& o conf makepl_arg "LIB=~/myperl/lib \e
2208 \& INSTALLMAN1DIR=~/myperl/man/man1 \e
2209 \& INSTALLMAN3DIR=~/myperl/man/man3 \e
2210 \& INSTALLSCRIPT=~/myperl/bin \e
2211 \& INSTALLBIN=~/myperl/bin"
2214 and then the equivalent command for Module::Build, which is
2217 \& o conf mbuildpl_arg "\-\-lib=~/myperl/lib \e
2218 \& \-\-installman1dir=~/myperl/man/man1 \e
2219 \& \-\-installman3dir=~/myperl/man/man3 \e
2220 \& \-\-installscript=~/myperl/bin \e
2221 \& \-\-installbin=~/myperl/bin"
2224 You can make this setting permanent like all \f(CW\*(C`o conf\*(C'\fR settings with
2225 \&\f(CW\*(C`o conf commit\*(C'\fR or by setting \f(CW\*(C`auto_commit\*(C'\fR beforehand.
2227 You will have to add ~/myperl/man to the \s-1MANPATH\s0 environment variable
2228 and also tell your perl programs to look into ~/myperl/lib, e.g. by
2232 \& use lib "$ENV{HOME}/myperl/lib";
2235 or setting the \s-1PERL5LIB\s0 environment variable.
2237 While we're speaking about \f(CW$ENV\fR{\s-1HOME\s0}, it might be worth mentioning,
2238 that for Windows we use the File::HomeDir module that provides an
2239 equivalent to the concept of the home directory on Unix.
2241 Another thing you should bear in mind is that the \s-1UNINST\s0 parameter can
2242 be dangerous when you are installing into a private area because you
2243 might accidentally remove modules that other people depend on that are
2244 not using the private area.
2246 How to get a package, unwrap it, and make a change before building it?
2248 Have a look at the \f(CW\*(C`look\*(C'\fR (!) command.
2250 I installed a Bundle and had a couple of fails. When I
2251 retried, everything resolved nicely. Can this be fixed to work
2254 The reason for this is that \s-1CPAN\s0 does not know the dependencies of all
2255 modules when it starts out. To decide about the additional items to
2256 install, it just uses data found in the \s-1META\s0.yml file or the generated
2257 Makefile. An undetected missing piece breaks the process. But it may
2258 well be that your Bundle installs some prerequisite later than some
2259 depending item and thus your second try is able to resolve everything.
2260 Please note, \s-1CPAN\s0.pm does not know the dependency tree in advance and
2261 cannot sort the queue of things to install in a topologically correct
2262 order. It resolves perfectly well \fBif\fR all modules declare the
2263 prerequisites correctly with the \s-1PREREQ_PM\s0 attribute to MakeMaker or
2264 the \f(CW\*(C`requires\*(C'\fR stanza of Module::Build. For bundles which fail and
2265 you need to install often, it is recommended to sort the Bundle
2266 definition file manually.
2268 In our intranet, we have many modules for internal use. How
2269 can I integrate these modules with \s-1CPAN\s0.pm but without uploading
2270 the modules to \s-1CPAN\s0?
2272 Have a look at the CPAN::Site module.
2274 When I run \s-1CPAN\s0's shell, I get an error message about things in my
2275 \&\f(CW\*(C`/etc/inputrc\*(C'\fR (or \f(CW\*(C`~/.inputrc\*(C'\fR) file.
2277 These are readline issues and can only be fixed by studying readline
2278 configuration on your architecture and adjusting the referenced file
2279 accordingly. Please make a backup of the \f(CW\*(C`/etc/inputrc\*(C'\fR or \f(CW\*(C`~/.inputrc\*(C'\fR
2280 and edit them. Quite often harmless changes like uppercasing or
2281 lowercasing some arguments solves the problem.
2284 Some authors have strange characters in their names.
2286 Internally \s-1CPAN\s0.pm uses the \s-1UTF\-8\s0 charset. If your terminal is
2287 expecting \s-1ISO\-8859\-1\s0 charset, a converter can be activated by setting
2288 term_is_latin to a true value in your config file. One way of doing so
2292 \& cpan> o conf term_is_latin 1
2295 If other charset support is needed, please file a bugreport against
2296 \&\s-1CPAN\s0.pm at rt.cpan.org and describe your needs. Maybe we can extend
2297 the support or maybe \s-1UTF\-8\s0 terminals become widely available.
2299 Note: this config variable is deprecated and will be removed in a
2300 future version of \s-1CPAN\s0.pm. It will be replaced with the conventions
2301 around the family of \f(CW$LANG\fR and \f(CW$LC_\fR* environment variables.
2304 When an install fails for some reason and then I correct the error
2305 condition and retry, \s-1CPAN\s0.pm refuses to install the module, saying
2306 \&\f(CW\*(C`Already tried without success\*(C'\fR.
2308 Use the force pragma like so
2311 \& force install Foo::Bar
2320 and then \f(CW\*(C`make install\*(C'\fR directly in the subshell.
2323 How do I install a \*(L"\s-1DEVELOPER\s0 \s-1RELEASE\s0\*(R" of a module?
2325 By default, \s-1CPAN\s0 will install the latest non-developer release of a
2326 module. If you want to install a dev release, you have to specify the
2327 partial path starting with the author id to the tarball you wish to
2331 \& cpan> install KWILLIAMS/Module\-Build\-0.27_07.tar.gz
2334 Note that you can use the \f(CW\*(C`ls\*(C'\fR command to get this path listed.
2337 How do I install a module and all its dependencies from the commandline,
2338 without being prompted for anything, despite my \s-1CPAN\s0 configuration
2341 \&\s-1CPAN\s0 uses ExtUtils::MakeMaker's \fIprompt()\fR function to ask its questions, so
2342 if you set the \s-1PERL_MM_USE_DEFAULT\s0 environment variable, you shouldn't be
2343 asked any questions at all (assuming the modules you are installing are
2344 nice about obeying that variable as well):
2347 \& % PERL_MM_USE_DEFAULT=1 perl \-MCPAN \-e 'install My::Module'
2351 How do I create a Module::Build based Build.PL derived from an
2352 ExtUtils::MakeMaker focused Makefile.PL?
2354 http://search.cpan.org/search?query=Module::Build::Convert
2356 http://www.refcnt.org/papers/module\-build\-convert
2359 I'm frequently irritated with the \s-1CPAN\s0 shell's inability to help me
2360 select a good mirror.
2362 The urllist config parameter is yours. You can add and remove sites at
2363 will. You should find out which sites have the best uptodateness,
2364 bandwidth, reliability, etc. and are topologically close to you. Some
2365 people prefer fast downloads, others uptodateness, others reliability.
2366 You decide which to try in which order.
2368 Henk P. Penning maintains a site that collects data about \s-1CPAN\s0 sites:
2371 \& http://www.cs.uu.nl/people/henkp/mirmon/cpan.html
2374 Also, feel free to play with experimental features. Run
2377 \& o conf init randomize_urllist ftpstats_period ftpstats_size
2380 and choose your favorite parameters. After a few downloads running the
2381 \&\f(CW\*(C`hosts\*(C'\fR command will probably assist you in choosing the best mirror
2385 Why do I get asked the same questions every time I start the shell?
2387 You can make your configuration changes permanent by calling the
2388 command \f(CW\*(C`o conf commit\*(C'\fR. Alternatively set the \f(CW\*(C`auto_commit\*(C'\fR
2389 variable to true by running \f(CW\*(C`o conf init auto_commit\*(C'\fR and answering
2390 the following question with yes.
2393 Older versions of \s-1CPAN\s0.pm had the original root directory of all
2394 tarballs in the build directory. Now there are always random
2395 characters appended to these directory names. Why was this done?
2397 The random characters are provided by File::Temp and ensure that each
2398 module's individual build directory is unique. This makes running
2399 \&\s-1CPAN\s0.pm in concurrent processes simultaneously safe.
2402 Speaking of the build directory. Do I have to clean it up myself?
2404 You have the choice to set the config variable \f(CW\*(C`scan_cache\*(C'\fR to
2405 \&\f(CW\*(C`never\*(C'\fR. Then you must clean it up yourself. The other possible
2406 value, \f(CW\*(C`atstart\*(C'\fR only cleans up the build directory when you start
2407 the \s-1CPAN\s0 shell. If you never start up the \s-1CPAN\s0 shell, you probably
2408 also have to clean up the build directory yourself.
2410 .IX Header "COMPATIBILITY"
2411 .Sh "\s-1OLD\s0 \s-1PERL\s0 \s-1VERSIONS\s0"
2412 .IX Subsection "OLD PERL VERSIONS"
2413 \&\s-1CPAN\s0.pm is regularly tested to run under 5.004, 5.005, and assorted
2414 newer versions. It is getting more and more difficult to get the
2415 minimal prerequisites working on older perls. It is close to
2416 impossible to get the whole Bundle::CPAN working there. If you're in
2417 the position to have only these old versions, be advised that \s-1CPAN\s0 is
2418 designed to work fine without the Bundle::CPAN installed.
2420 To get things going, note that GBARR/Scalar\-List\-Utils\-1.18.tar.gz is
2421 compatible with ancient perls and that File::Temp is listed as a
2422 prerequisite but \s-1CPAN\s0 has reasonable workarounds if it is missing.
2423 .Sh "\s-1CPANPLUS\s0"
2424 .IX Subsection "CPANPLUS"
2425 This module and its competitor, the \s-1CPANPLUS\s0 module, are both much
2426 cooler than the other. \s-1CPAN\s0.pm is older. \s-1CPANPLUS\s0 was designed to be
2427 more modular, but it was never intended to be compatible with \s-1CPAN\s0.pm.
2428 .SH "SECURITY ADVICE"
2429 .IX Header "SECURITY ADVICE"
2430 This software enables you to upgrade software on your computer and so
2431 is inherently dangerous because the newly installed software may
2432 contain bugs and may alter the way your computer works or even make it
2433 unusable. Please consider backing up your data before every upgrade.
2436 Please report bugs via <http://rt.cpan.org/>
2438 Before submitting a bug, please make sure that the traditional method
2439 of building a Perl module package from a shell by following the
2440 installation instructions of that package still works in your
2444 Andreas Koenig \f(CW\*(C`<andk@cpan.org>\*(C'\fR
2446 .IX Header "LICENSE"
2447 This program is free software; you can redistribute it and/or
2448 modify it under the same terms as Perl itself.
2450 See <http://www.perl.com/perl/misc/Artistic.html>
2452 .IX Header "TRANSLATIONS"
2453 Kawai,Takanori provides a Japanese translation of this manpage at
2454 <http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
2456 .IX Header "SEE ALSO"
2457 cpan, CPAN::Nox, CPAN::Version
projects / catagits/Gitalist.git / blob