Debian Codegraph @

upstream/mageia-cauldron/man3pm/CPAN.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "CPAN 3pm"
61 .TH CPAN 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 CPAN \- query, download and build perl modules from CPAN sites
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 Interactive mode:
71 .PP
72 .Vb 1
73 \& perl \-MCPAN \-e shell
74 .Ve
75 .PP
76 \&\-\-or\-\-
77 .PP
78 .Vb 1
79 \& cpan
80 .Ve
81 .PP
82 Basic commands:
83 .PP
84 .Vb 1
85 \& # Modules:
86 \&
87 \& cpan> install Acme::Meta # in the shell
88 \&
89 \& CPAN::Shell\->install("Acme::Meta"); # in perl
90 \&
91 \& # Distributions:
92 \&
93 \& cpan> install NWCLARK/Acme\-Meta\-0.02.tar.gz # in the shell
94 \&
95 \& CPAN::Shell\->
96 \& install("NWCLARK/Acme\-Meta\-0.02.tar.gz"); # in perl
97 \&
98 \& # module objects:
99 \&
100 \& $mo = CPAN::Shell\->expandany($mod);
101 \& $mo = CPAN::Shell\->expand("Module",$mod); # same thing
102 \&
103 \& # distribution objects:
104 \&
105 \& $do = CPAN::Shell\->expand("Module",$mod)\->distribution;
106 \& $do = CPAN::Shell\->expandany($distro); # same thing
107 \& $do = CPAN::Shell\->expand("Distribution",
108 \& $distro); # same thing
109 .Ve
110 .SH DESCRIPTION
111 .IX Header "DESCRIPTION"
112 The CPAN module automates or at least simplifies the make and install
113 of perl modules and extensions. It includes some primitive searching
114 capabilities and knows how to use LWP, HTTP::Tiny, Net::FTP and certain
115 external download clients to fetch distributions from the net.
116 .PP
117 These are fetched from one or more mirrored CPAN (Comprehensive
118 Perl Archive Network) sites and unpacked in a dedicated directory.
119 .PP
120 The CPAN module also supports named and versioned
121 \&\fIbundles\fR of modules. Bundles simplify handling of sets of
122 related modules. See Bundles below.
123 .PP
124 The package contains a session manager and a cache manager. The
125 session manager keeps track of what has been fetched, built, and
126 installed in the current session. The cache manager keeps track of the
127 disk space occupied by the make processes and deletes excess space
128 using a simple FIFO mechanism.
129 .PP
130 All methods provided are accessible in a programmer style and in an
131 interactive shell style.
132 .ie n .SS "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
133 .el .SS "CPAN::shell([$prompt, \f(CW$command\fP]) Starting Interactive Mode"
134 .IX Subsection "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
135 Enter interactive mode by running
136 .PP
137 .Vb 1
138 \& perl \-MCPAN \-e shell
139 .Ve
140 .PP
141 or
142 .PP
143 .Vb 1
144 \& cpan
145 .Ve
146 .PP
147 which puts you into a readline interface. If \f(CW\*(C`Term::ReadKey\*(C'\fR and
148 either of \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR or \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR are installed,
149 history and command completion are supported.
150 .PP
151 Once at the command line, type \f(CW\*(C`h\*(C'\fR for one\-page help
152 screen; the rest should be self\-explanatory.
153 .PP
154 The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments: one the
155 prompt, the second the default initial command line (the latter
156 only works if a real ReadLine interface module is installed).
157 .PP
158 The most common uses of the interactive modes are
159 .IP "Searching for authors, bundles, distribution files and modules" 2
160 .IX Item "Searching for authors, bundles, distribution files and modules"
161 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
162 for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the
163 mentioned four. Each of the four entities is implemented as a class
164 with slightly differing methods for displaying an object.
165 .Sp
166 Arguments to these commands are either strings exactly matching
167 the identification string of an object, or regular expressions
168 matched case\-insensitively against various attributes of the
169 objects. The parser only recognizes a regular expression when you
170 enclose it with slashes.
171 .Sp
172 The principle is that the number of objects found influences how an
173 item is displayed. If the search finds one item, the result is
174 displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if
175 more than one is found, each object is displayed with the terse method
176 \&\f(CW\*(C`as_glimpse\*(C'\fR.
177 .Sp
178 Examples:
179 .Sp
180 .Vb 10
181 \& cpan> m Acme::MetaSyntactic
182 \& Module id = Acme::MetaSyntactic
183 \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
184 \& CPAN_VERSION 0.99
185 \& CPAN_FILE B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
186 \& UPLOAD_DATE 2006\-11\-06
187 \& MANPAGE Acme::MetaSyntactic \- Themed metasyntactic variables names
188 \& INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
189 \& INST_VERSION 0.99
190 \& cpan> a BOOK
191 \& Author id = BOOK
192 \& EMAIL [...]
193 \& FULLNAME Philippe Bruhat (BooK)
194 \& cpan> d BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
195 \& Distribution id = B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
196 \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
197 \& CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
198 \& UPLOAD_DATE 2006\-11\-06
199 \& cpan> m /lorem/
200 \& Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme\-MetaSyntactic\-0.99.tar.gz)
201 \& Module Text::Lorem (ADEOLA/Text\-Lorem\-0.3.tar.gz)
202 \& Module Text::Lorem::More (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
203 \& Module Text::Lorem::More::Source (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
204 \& cpan> i /berlin/
205 \& Distribution BEATNIK/Filter\-NumberLines\-0.02.tar.gz
206 \& Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime\-TimeZone\-0.7904.tar.gz)
207 \& Module Filter::NumberLines (BEATNIK/Filter\-NumberLines\-0.02.tar.gz)
208 \& Author [...]
209 .Ve
210 .Sp
211 The examples illustrate several aspects: the first three queries
212 target modules, authors, or distros directly and yield exactly one
213 result. The last two use regular expressions and yield several
214 results. The last one targets all of bundles, modules, authors, and
215 distros simultaneously. When more than one result is available, they
216 are printed in one\-line format.
217 .ie n .IP """get"", ""make"", ""test"", ""install"", ""clean"" modules or distributions" 2
218 .el .IP "\f(CWget\fR, \f(CWmake\fR, \f(CWtest\fR, \f(CWinstall\fR, \f(CWclean\fR modules or distributions" 2
219 .IX Item "get, make, test, install, clean modules or distributions"
220 These commands take any number of arguments and investigate what is
221 necessary to perform the action. Argument processing is as follows:
222 .Sp
223 .Vb 5
224 \& known module name in format Foo/Bar.pm module
225 \& other embedded slash distribution
226 \& \- with trailing slash dot directory
227 \& enclosing slashes regexp
228 \& known module name in format Foo::Bar module
229 .Ve
230 .Sp
231 If the argument is a distribution file name (recognized by embedded
232 slashes), it is processed. If it is a module, CPAN determines the
233 distribution file in which this module is included and processes that,
234 following any dependencies named in the module\*(Aqs META.yml or
235 Makefile.PL (this behavior is controlled by the configuration
236 parameter \f(CW\*(C`prerequisites_policy\*(C'\fR). If an argument is enclosed in
237 slashes it is treated as a regular expression: it is expanded and if
238 the result is a single object (distribution, bundle or module), this
239 object is processed.
240 .Sp
241 Example:
242 .Sp
243 .Vb 3
244 \& install Dummy::Perl # installs the module
245 \& install AUXXX/Dummy\-Perl\-3.14.tar.gz # installs that distribution
246 \& install /Dummy\-Perl\-3.14/ # same if the regexp is unambiguous
247 .Ve
248 .Sp
249 \&\f(CW\*(C`get\*(C'\fR downloads a distribution file and untars or unzips it, \f(CW\*(C`make\*(C'\fR
250 builds it, \f(CW\*(C`test\*(C'\fR runs the test suite, and \f(CW\*(C`install\*(C'\fR installs it.
251 .Sp
252 Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR is run unconditionally. An
253 .Sp
254 .Vb 1
255 \& install <distribution_file>
256 .Ve
257 .Sp
258 is also run unconditionally. But for
259 .Sp
260 .Vb 1
261 \& install <module>
262 .Ve
263 .Sp
264 CPAN checks whether an install is needed and prints
265 \&\fImodule up to date\fR if the distribution file containing
266 the module doesn\*(Aqt need updating.
267 .Sp
268 CPAN also keeps track of what it has done within the current session
269 and doesn\*(Aqt try to build a package a second time regardless of whether it
270 succeeded or not. It does not repeat a test run if the test
271 has been run successfully before. Same for install runs.
272 .Sp
273 The \f(CW\*(C`force\*(C'\fR pragma may precede another command (currently: \f(CW\*(C`get\*(C'\fR,
274 \&\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
275 and attempt to continue past certain errors. See the section below on
276 the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
277 .Sp
278 The \f(CW\*(C`notest\*(C'\fR pragma skips the test part in the build
279 process.
280 .Sp
281 Example:
282 .Sp
283 .Vb 1
284 \& cpan> notest install Tk
285 .Ve
286 .Sp
287 A \f(CW\*(C`clean\*(C'\fR command results in a
288 .Sp
289 .Vb 1
290 \& make clean
291 .Ve
292 .Sp
293 being executed within the distribution file\*(Aqs working directory.
294 .ie n .IP """readme"", ""perldoc"", ""look"" module or distribution" 2
295 .el .IP "\f(CWreadme\fR, \f(CWperldoc\fR, \f(CWlook\fR module or distribution" 2
296 .IX Item "readme, perldoc, look module or distribution"
297 \&\f(CW\*(C`readme\*(C'\fR displays the README file of the associated distribution.
298 \&\f(CW\*(C`Look\*(C'\fR gets and untars (if not yet done) the distribution file,
299 changes to the appropriate directory and opens a subshell process in
300 that directory. \f(CW\*(C`perldoc\*(C'\fR displays the module\*(Aqs pod documentation
301 in html or plain text format.
302 .ie n .IP """ls"" author" 2
303 .el .IP "\f(CWls\fR author" 2
304 .IX Item "ls author"
305 .PD 0
306 .ie n .IP """ls"" globbing_expression" 2
307 .el .IP "\f(CWls\fR globbing_expression" 2
308 .IX Item "ls globbing_expression"
309 .PD
310 The first form lists all distribution files in and below an author\*(Aqs
311 CPAN directory as stored in the CHECKSUMS files distributed on
312 CPAN. The listing recurses into subdirectories.
313 .Sp
314 The second form limits or expands the output with shell
315 globbing as in the following examples:
316 .Sp
317 .Vb 3
318 \& ls JV/make*
319 \& ls GSAR/*make*
320 \& ls */*make*
321 .Ve
322 .Sp
323 The last example is very slow and outputs extra progress indicators
324 that break the alignment of the result.
325 .Sp
326 Note that globbing only lists directories explicitly asked for, for
327 example FOO/* will not list FOO/bar/Acme\-Sthg\-n.nn.tar.gz. This may be
328 regarded as a bug that may be changed in some future version.
329 .ie n .IP """failed""" 2
330 .el .IP \f(CWfailed\fR 2
331 .IX Item "failed"
332 The \f(CW\*(C`failed\*(C'\fR command reports all distributions that failed on one of
333 \&\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
334 running shell session.
335 .IP "Persistence between sessions" 2
336 .IX Item "Persistence between sessions"
337 If the \f(CW\*(C`YAML\*(C'\fR or the \f(CW\*(C`YAML::Syck\*(C'\fR module is installed a record of
338 the internal state of all modules is written to disk after each step.
339 The files contain a signature of the currently running perl version
340 for later perusal.
341 .Sp
342 If the configurations variable \f(CW\*(C`build_dir_reuse\*(C'\fR is set to a true
343 value, then CPAN.pm reads the collected YAML files. If the stored
344 signature matches the currently running perl, the stored state is
345 loaded into memory such that persistence between sessions
346 is effectively established.
347 .ie n .IP "The ""force"" and the ""fforce"" pragma" 2
348 .el .IP "The \f(CWforce\fR and the \f(CWfforce\fR pragma" 2
349 .IX Item "The force and the fforce pragma"
350 To speed things up in complex installation scenarios, CPAN.pm keeps
351 track of what it has already done and refuses to do some things a
352 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.
353 A \f(CW\*(C`test\*(C'\fR is repeated only if the previous test was unsuccessful. The
354 diagnostic message when CPAN.pm refuses to do something a second time
355 is one of \fIHas already been \fR\f(CW\*(C`unwrapped|made|tested successfully\*(C'\fR or
356 something similar. Another situation where CPAN refuses to act is an
357 \&\f(CW\*(C`install\*(C'\fR if the corresponding \f(CW\*(C`test\*(C'\fR was not successful.
358 .Sp
359 In all these cases, the user can override this stubborn behaviour by
360 prepending the command with the word force, for example:
361 .Sp
362 .Vb 4
363 \& cpan> force get Foo
364 \& cpan> force make AUTHOR/Bar\-3.14.tar.gz
365 \& cpan> force test Baz
366 \& cpan> force install Acme::Meta
367 .Ve
368 .Sp
369 Each \fIforced\fR command is executed with the corresponding part of its
370 memory erased.
371 .Sp
372 The \f(CW\*(C`fforce\*(C'\fR pragma is a variant that emulates a \f(CW\*(C`force get\*(C'\fR which
373 erases the entire memory followed by the action specified, effectively
374 restarting the whole get/make/test/install procedure from scratch.
375 .IP Lockfile 2
376 .IX Item "Lockfile"
377 Interactive sessions maintain a lockfile, by default \f(CW\*(C`~/.cpan/.lock\*(C'\fR.
378 Batch jobs can run without a lockfile and not disturb each other.
379 .Sp
380 The shell offers to run in \fIdowngraded mode\fR when another process is
381 holding the lockfile. This is an experimental feature that is not yet
382 tested very well. This second shell then does not write the history
383 file, does not use the metadata file, and has a different prompt.
384 .IP Signals 2
385 .IX Item "Signals"
386 CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
387 in the cpan\-shell, it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and
388 return to the cpan\-shell prompt. A SIGTERM will cause the cpan\-shell
389 to clean up and leave the shell loop. You can emulate the effect of a
390 SIGTERM by sending two consecutive SIGINTs, which usually means by
391 pressing \f(CW\*(C`^C\*(C'\fR twice.
392 .Sp
393 CPAN.pm ignores SIGPIPE. If the user sets \f(CW\*(C`inactivity_timeout\*(C'\fR, a
394 SIGALRM is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
395 Build.PL\*(C'\fR subprocess. A SIGALRM is also used during module version
396 parsing, and is controlled by \f(CW\*(C`version_timeout\*(C'\fR.
397 .SS CPAN::Shell
398 .IX Subsection "CPAN::Shell"
399 The commands available in the shell interface are methods in
400 the package CPAN::Shell. If you enter the shell command, your
401 input is split by the \fBText::ParseWords::shellwords()\fR routine, which
402 acts like most shells do. The first word is interpreted as the
403 method to be invoked, and the rest of the words are treated as the method\*(Aqs arguments.
404 Continuation lines are supported by ending a line with a
405 literal backslash.
406 .SS autobundle
407 .IX Subsection "autobundle"
408 \&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the
409 \&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains
410 a list of all modules that are both available from CPAN and currently
411 installed within \f(CW@INC\fR. Duplicates of each distribution are suppressed.
412 The name of the bundle file is based on the current date and a
413 counter, e.g. \fIBundle/Snapshot_2012_05_21_00.pm\fR. This is installed
414 again by running \f(CW\*(C`cpan Bundle::Snapshot_2012_05_21_00\*(C'\fR, or installing
415 \&\f(CW\*(C`Bundle::Snapshot_2012_05_21_00\*(C'\fR from the CPAN shell.
416 .PP
417 Return value: path to the written file.
418 .SS hosts
419 .IX Subsection "hosts"
420 Note: this feature is still in alpha state and may change in future
421 versions of CPAN.pm
422 .PP
423 This commands provides a statistical overview over recent download
424 activities. The data for this is collected in the YAML file
425 \&\f(CW\*(C`FTPstats.yml\*(C'\fR in your \f(CW\*(C`cpan_home\*(C'\fR directory. If no YAML module is
426 configured or YAML not installed, or if \f(CW\*(C`ftpstats_size\*(C'\fR is set to a
427 value \f(CW\*(C`<=0\*(C'\fR, no stats are provided.
428 .SS install_tested
429 .IX Subsection "install_tested"
430 Install all distributions that have been tested successfully but have
431 not yet been installed. See also \f(CW\*(C`is_tested\*(C'\fR.
432 .SS is_tested
433 .IX Subsection "is_tested"
434 List all build directories of distributions that have been tested
435 successfully but have not yet been installed. See also
436 \&\f(CW\*(C`install_tested\*(C'\fR.
437 .SS mkmyconfig
438 .IX Subsection "mkmyconfig"
439 \&\fBmkmyconfig()\fR writes your own CPAN::MyConfig file into your \f(CW\*(C`~/.cpan/\*(C'\fR
440 directory so that you can save your own preferences instead of the
441 system\-wide ones.
442 .SS "r [Module|/Regexp/]..."
443 .IX Subsection "r [Module|/Regexp/]..."
444 scans current perl installation for modules that have a newer version
445 available on CPAN and provides a list of them. If called without
446 argument, all potential upgrades are listed; if called with arguments
447 the list is filtered to the modules and regexps given as arguments.
448 .PP
449 The listing looks something like this:
450 .PP
451 .Vb 10
452 \& Package namespace installed latest in CPAN file
453 \& CPAN 1.94_64 1.9600 ANDK/CPAN\-1.9600.tar.gz
454 \& CPAN::Reporter 1.1801 1.1902 DAGOLDEN/CPAN\-Reporter\-1.1902.tar.gz
455 \& YAML 0.70 0.73 INGY/YAML\-0.73.tar.gz
456 \& YAML::Syck 1.14 1.17 AVAR/YAML\-Syck\-1.17.tar.gz
457 \& YAML::Tiny 1.44 1.50 ADAMK/YAML\-Tiny\-1.50.tar.gz
458 \& CGI 3.43 3.55 MARKSTOS/CGI.pm\-3.55.tar.gz
459 \& Module::Build::YAML 1.40 1.41 DAGOLDEN/Module\-Build\-0.3800.tar.gz
460 \& TAP::Parser::Result::YAML 3.22 3.23 ANDYA/Test\-Harness\-3.23.tar.gz
461 \& YAML::XS 0.34 0.35 INGY/YAML\-LibYAML\-0.35.tar.gz
462 .Ve
463 .PP
464 It suppresses duplicates in the column \f(CW\*(C`in CPAN file\*(C'\fR such that
465 distributions with many upgradeable modules are listed only once.
466 .PP
467 Note that the list is not sorted.
468 .SS "recent ***EXPERIMENTAL COMMAND***"
469 .IX Subsection "recent ***EXPERIMENTAL COMMAND***"
470 The \f(CW\*(C`recent\*(C'\fR command downloads a list of recent uploads to CPAN and
471 displays them \fIslowly\fR. While the command is running, a \f(CW$SIG\fR{INT}
472 exits the loop after displaying the current item.
473 .PP
474 \&\fBNote\fR: This command requires XML::LibXML installed.
475 .PP
476 \&\fBNote\fR: This whole command currently is just a hack and will
477 probably change in future versions of CPAN.pm, but the general
478 approach will likely remain.
479 .PP
480 \&\fBNote\fR: See also smoke
481 .SS recompile
482 .IX Subsection "recompile"
483 \&\fBrecompile()\fR is a special command that takes no argument and
484 runs the make/test/install cycle with brute force over all installed
485 dynamically loadable extensions (a.k.a. XS modules) with \*(Aqforce\*(Aq in
486 effect. The primary purpose of this command is to finish a network
487 installation. Imagine you have a common source tree for two different
488 architectures. You decide to do a completely independent fresh
489 installation. You start on one architecture with the help of a Bundle
490 file produced earlier. CPAN installs the whole Bundle for you, but
491 when you try to repeat the job on the second architecture, CPAN
492 responds with a \f(CW"Foo up to date"\fR message for all modules. So you
493 invoke CPAN\*(Aqs recompile on the second architecture and you\*(Aqre done.
494 .PP
495 Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your
496 perl breaks binary compatibility. If one of the modules that CPAN uses
497 is in turn depending on binary compatibility (so you cannot run CPAN
498 commands), then you should try the CPAN::Nox module for recovery.
499 .SS "report Bundle|Distribution|Module"
500 .IX Subsection "report Bundle|Distribution|Module"
501 The \f(CW\*(C`report\*(C'\fR command temporarily turns on the \f(CW\*(C`test_report\*(C'\fR config
502 variable, then runs the \f(CW\*(C`force test\*(C'\fR command with the given
503 arguments. The \f(CW\*(C`force\*(C'\fR pragma reruns the tests and repeats
504 every step that might have failed before.
505 .SS "smoke ***EXPERIMENTAL COMMAND***"
506 .IX Subsection "smoke ***EXPERIMENTAL COMMAND***"
507 \&\fB*** WARNING: this command downloads and executes software from CPAN to
508 your computer of completely unknown status. You should never do
509 this with your normal account and better have a dedicated well
510 separated and secured machine to do this. ***\fR
511 .PP
512 The \f(CW\*(C`smoke\*(C'\fR command takes the list of recent uploads to CPAN as
513 provided by the \f(CW\*(C`recent\*(C'\fR command and tests them all. While the
514 command is running \f(CW$SIG\fR{INT} is defined to mean that the current item
515 shall be skipped.
516 .PP
517 \&\fBNote\fR: This whole command currently is just a hack and will
518 probably change in future versions of CPAN.pm, but the general
519 approach will likely remain.
520 .PP
521 \&\fBNote\fR: See also recent
522 .SS "upgrade [Module|/Regexp/]..."
523 .IX Subsection "upgrade [Module|/Regexp/]..."
524 The \f(CW\*(C`upgrade\*(C'\fR command first runs an \f(CW\*(C`r\*(C'\fR command with the given
525 arguments and then installs the newest versions of all modules that
526 were listed by that.
527 .ie n .SS "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution"
528 .el .SS "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution"
529 .IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution"
530 Although it may be considered internal, the class hierarchy does matter
531 for both users and programmer. CPAN.pm deals with the four
532 classes mentioned above, and those classes all share a set of methods. Classical
533 single polymorphism is in effect. A metaclass object registers all
534 objects of all kinds and indexes them with a string. The strings
535 referencing objects have a separated namespace (well, not completely
536 separated):
537 .PP
538 .Vb 1
539 \& Namespace Class
540 \&
541 \& words containing a "/" (slash) Distribution
542 \& words starting with Bundle:: Bundle
543 \& everything else Module or Author
544 .Ve
545 .PP
546 Modules know their associated Distribution objects. They always refer
547 to the most recent official release. Developers may mark their releases
548 as unstable development versions (by inserting an underscore into the
549 module version number which will also be reflected in the distribution
550 name when you run \*(Aqmake dist\*(Aq), so the really hottest and newest
551 distribution is not always the default. If a module Foo circulates
552 on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
553 way to install version 1.23 by saying
554 .PP
555 .Vb 1
556 \& install Foo
557 .Ve
558 .PP
559 This would install the complete distribution file (say
560 BAR/Foo\-1.23.tar.gz) with all accompanying material. But if you would
561 like to install version 1.23_90, you need to know where the
562 distribution file resides on CPAN relative to the authors/id/
563 directory. If the author is BAR, this might be BAR/Foo\-1.23_90.tar.gz;
564 so you would have to say
565 .PP
566 .Vb 1
567 \& install BAR/Foo\-1.23_90.tar.gz
568 .Ve
569 .PP
570 The first example will be driven by an object of the class
571 CPAN::Module, the second by an object of class CPAN::Distribution.
572 .SS "Integrating local directories"
573 .IX Subsection "Integrating local directories"
574 Note: this feature is still in alpha state and may change in future
575 versions of CPAN.pm
576 .PP
577 Distribution objects are normally distributions from the CPAN, but
578 there is a slightly degenerate case for Distribution objects, too, of
579 projects held on the local disk. These distribution objects have the
580 same name as the local directory and end with a dot. A dot by itself
581 is also allowed for the current directory at the time CPAN.pm was
582 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
583 directly to that directory. This gives the command \f(CW\*(C`cpan .\*(C'\fR an
584 interesting touch: while the normal mantra of installing a CPAN module
585 without CPAN.pm is one of
586 .PP
587 .Vb 5
588 \& perl Makefile.PL perl Build.PL
589 \& ( go and get prerequisites )
590 \& make ./Build
591 \& make test ./Build test
592 \& make install ./Build install
593 .Ve
594 .PP
595 the command \f(CW\*(C`cpan .\*(C'\fR does all of this at once. It figures out which
596 of the two mantras is appropriate, fetches and installs all
597 prerequisites, takes care of them recursively, and finally finishes the
598 installation of the module in the current directory, be it a CPAN
599 module or not.
600 .PP
601 The typical usage case is for private modules or working copies of
602 projects from remote repositories on the local disk.
603 .SS Redirection
604 .IX Subsection "Redirection"
605 The usual shell redirection symbols \f(CW\*(C` | \*(C'\fR and \f(CW\*(C`>\*(C'\fR are recognized
606 by the cpan shell \fBonly when surrounded by whitespace\fR. So piping to
607 pager or redirecting output into a file works somewhat as in a normal
608 shell, with the stipulation that you must type extra spaces.
609 .SS "Plugin support ***EXPERIMENTAL***"
610 .IX Subsection "Plugin support ***EXPERIMENTAL***"
611 Plugins are objects that implement any of currently eight methods:
612 .PP
613 .Vb 8
614 \& pre_get
615 \& post_get
616 \& pre_make
617 \& post_make
618 \& pre_test
619 \& post_test
620 \& pre_install
621 \& post_install
622 .Ve
623 .PP
624 The \f(CW\*(C`plugin_list\*(C'\fR configuration parameter holds a list of strings of
625 the form
626 .PP
627 .Vb 1
628 \& Modulename=arg0,arg1,arg2,arg3,...
629 .Ve
630 .PP
631 eg:
632 .PP
633 .Vb 1
634 \& CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1
635 .Ve
636 .PP
637 At run time, each listed plugin is instantiated as a singleton object
638 by running the equivalent of this pseudo code:
639 .PP
640 .Vb 3
641 \& my $plugin = <string representation from config>;
642 \& <generate Modulename and arguments from $plugin>;
643 \& my $p = $instance{$plugin} ||= Modulename\->new($arg0,$arg1,...);
644 .Ve
645 .PP
646 The generated singletons are kept around from instantiation until the
647 end of the shell session. <plugin_list> can be reconfigured at any
648 time at run time. While the cpan shell is running, it checks all
649 activated plugins at each of the 8 reference points listed above and
650 runs the respective method if it is implemented for that object. The
651 method is called with the active CPAN::Distribution object passed in
652 as an argument.
653 .SH CONFIGURATION
654 .IX Header "CONFIGURATION"
655 When the CPAN module is used for the first time, a configuration
656 dialogue tries to determine a couple of site specific options. The
657 result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR
658 in a file CPAN/Config.pm.
659 .PP
660 Default values defined in the CPAN/Config.pm file can be
661 overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
662 best placed in \f(CW\*(C`$HOME/.cpan/CPAN/MyConfig.pm\*(C'\fR, because \f(CW\*(C`$HOME/.cpan\*(C'\fR is
663 added to the search path of the CPAN module before the \fBuse()\fR or
664 \&\fBrequire()\fR statements. The mkmyconfig command writes this file for you.
665 .PP
666 If you want to keep your own CPAN/MyConfig.pm somewhere else, you
667 should load it before loading CPAN.pm, e.g.:
668 .PP
669 .Vb 1
670 \& perl \-I/tmp/somewhere \-MCPAN::MyConfig \-MCPAN \-eshell
671 \&
672 \& \-\-or\-\-
673 \&
674 \& perl \-I/tmp/somewhere \-MCPAN::MyConfig \-S cpan
675 .Ve
676 .PP
677 Once you are in the shell you can change your configuration as follows.
678 .PP
679 The \f(CW\*(C`o conf\*(C'\fR command has various bells and whistles:
680 .IP "completion support" 4
681 .IX Item "completion support"
682 If you have a ReadLine module installed, you can hit TAB at any point
683 of the commandline and \f(CW\*(C`o conf\*(C'\fR will offer you completion for the
684 built\-in subcommands and/or config variable names.
685 .IP "displaying some help: o conf help" 4
686 .IX Item "displaying some help: o conf help"
687 Displays a short help
688 .IP "displaying current values: o conf [KEY]" 4
689 .IX Item "displaying current values: o conf [KEY]"
690 Displays the current value(s) for this config variable. Without KEY,
691 displays all subcommands and config variables.
692 .Sp
693 Example:
694 .Sp
695 .Vb 1
696 \& o conf shell
697 .Ve
698 .Sp
699 If KEY starts and ends with a slash, the string in between is
700 treated as a regular expression and only keys matching this regexp
701 are displayed
702 .Sp
703 Example:
704 .Sp
705 .Vb 1
706 \& o conf /color/
707 .Ve
708 .IP "changing of scalar values: o conf KEY VALUE" 4
709 .IX Item "changing of scalar values: o conf KEY VALUE"
710 Sets the config variable KEY to VALUE. The empty string can be
711 specified as usual in shells, with \f(CW\*(Aq\*(Aq\fR or \f(CW""\fR
712 .Sp
713 Example:
714 .Sp
715 .Vb 1
716 \& o conf wget /usr/bin/wget
717 .Ve
718 .IP "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" 4
719 .IX Item "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST"
720 If a config variable name ends with \f(CW\*(C`list\*(C'\fR, it is a list. \f(CW\*(C`o conf
721 KEY shift\*(C'\fR removes the first element of the list, \f(CW\*(C`o conf KEY pop\*(C'\fR
722 removes the last element of the list. \f(CW\*(C`o conf KEYS unshift LIST\*(C'\fR
723 prepends a list of values to the list, \f(CW\*(C`o conf KEYS push LIST\*(C'\fR
724 appends a list of valued to the list.
725 .Sp
726 Likewise, \f(CW\*(C`o conf KEY splice LIST\*(C'\fR passes the LIST to the corresponding
727 splice command.
728 .Sp
729 Finally, any other list of arguments is taken as a new list value for
730 the KEY variable discarding the previous value.
731 .Sp
732 Examples:
733 .Sp
734 .Vb 3
735 \& o conf urllist unshift http://cpan.dev.local/CPAN
736 \& o conf urllist splice 3 1
737 \& o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
738 .Ve
739 .IP "reverting to saved: o conf defaults" 4
740 .IX Item "reverting to saved: o conf defaults"
741 Reverts all config variables to the state in the saved config file.
742 .IP "saving the config: o conf commit" 4
743 .IX Item "saving the config: o conf commit"
744 Saves all config variables to the current config file (CPAN/Config.pm
745 or CPAN/MyConfig.pm that was loaded at start).
746 .PP
747 The configuration dialog can be started any time later again by
748 issuing the command \f(CW\*(C` o conf init \*(C'\fR in the CPAN shell. A subset of
749 the configuration dialog can be run by issuing \f(CW\*(C`o conf init WORD\*(C'\fR
750 where WORD is any valid config variable or a regular expression.
751 .SS "Config Variables"
752 .IX Subsection "Config Variables"
753 The following keys in the hash reference \f(CW$CPAN::Config\fR are
754 currently defined:
755 .PP
756 .Vb 10
757 \& allow_installing_module_downgrades
758 \& allow or disallow installing module downgrades
759 \& allow_installing_outdated_dists
760 \& allow or disallow installing modules that are
761 \& indexed in the cpan index pointing to a distro
762 \& with a higher distro\-version number
763 \& applypatch path to external prg
764 \& auto_commit commit all changes to config variables to disk
765 \& build_cache size of cache for directories to build modules
766 \& build_dir locally accessible directory to build modules
767 \& build_dir_reuse boolean if distros in build_dir are persistent
768 \& build_requires_install_policy
769 \& to install or not to install when a module is
770 \& only needed for building. yes|no|ask/yes|ask/no
771 \& bzip2 path to external prg
772 \& cache_metadata use serializer to cache metadata
773 \& check_sigs if signatures should be verified
774 \& cleanup_after_install
775 \& remove build directory immediately after a
776 \& successful install and remember that for the
777 \& duration of the session
778 \& colorize_debug Term::ANSIColor attributes for debugging output
779 \& colorize_output boolean if Term::ANSIColor should colorize output
780 \& colorize_print Term::ANSIColor attributes for normal output
781 \& colorize_warn Term::ANSIColor attributes for warnings
782 \& commandnumber_in_prompt
783 \& boolean if you want to see current command number
784 \& commands_quote preferred character to use for quoting external
785 \& commands when running them. Defaults to double
786 \& quote on Windows, single tick everywhere else;
787 \& can be set to space to disable quoting
788 \& connect_to_internet_ok
789 \& whether to ask if opening a connection is ok before
790 \& urllist is specified
791 \& cpan_home local directory reserved for this package
792 \& curl path to external prg
793 \& dontload_hash DEPRECATED
794 \& dontload_list arrayref: modules in the list will not be
795 \& loaded by the CPAN::has_inst() routine
796 \& ftp path to external prg
797 \& ftp_passive if set, the environment variable FTP_PASSIVE is set
798 \& for downloads
799 \& ftp_proxy proxy host for ftp requests
800 \& ftpstats_period max number of days to keep download statistics
801 \& ftpstats_size max number of items to keep in the download statistics
802 \& getcwd see below
803 \& gpg path to external prg
804 \& gzip location of external program gzip
805 \& halt_on_failure stop processing after the first failure of queued
806 \& items or dependencies
807 \& histfile file to maintain history between sessions
808 \& histsize maximum number of lines to keep in histfile
809 \& http_proxy proxy host for http requests
810 \& inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
811 \& after this many seconds inactivity. Set to 0 to
812 \& disable timeouts.
813 \& index_expire refetch index files after this many days
814 \& inhibit_startup_message
815 \& if true, suppress the startup message
816 \& keep_source_where directory in which to keep the source (if we do)
817 \& load_module_verbosity
818 \& report loading of optional modules used by CPAN.pm
819 \& lynx path to external prg
820 \& make location of external make program
821 \& make_arg arguments that should always be passed to \*(Aqmake\*(Aq
822 \& make_install_make_command
823 \& the make command for running \*(Aqmake install\*(Aq, for
824 \& example \*(Aqsudo make\*(Aq
825 \& make_install_arg same as make_arg for \*(Aqmake install\*(Aq
826 \& makepl_arg arguments passed to \*(Aqperl Makefile.PL\*(Aq
827 \& mbuild_arg arguments passed to \*(Aq./Build\*(Aq
828 \& mbuild_install_arg arguments passed to \*(Aq./Build install\*(Aq
829 \& mbuild_install_build_command
830 \& command to use instead of \*(Aq./Build\*(Aq when we are
831 \& in the install stage, for example \*(Aqsudo ./Build\*(Aq
832 \& mbuildpl_arg arguments passed to \*(Aqperl Build.PL\*(Aq
833 \& ncftp path to external prg
834 \& ncftpget path to external prg
835 \& no_proxy don\*(Aqt proxy to these hosts/domains (comma separated list)
836 \& pager location of external program more (or any pager)
837 \& password your password if you CPAN server wants one
838 \& patch path to external prg
839 \& patches_dir local directory containing patch files
840 \& perl5lib_verbosity verbosity level for PERL5LIB additions
841 \& plugin_list list of active hooks (see Plugin support above
842 \& and the CPAN::Plugin module)
843 \& prefer_external_tar
844 \& per default all untar operations are done with
845 \& Archive::Tar; by setting this variable to true
846 \& the external tar command is used if available
847 \& prefer_installer legal values are MB and EUMM: if a module comes
848 \& with both a Makefile.PL and a Build.PL, use the
849 \& former (EUMM) or the latter (MB); if the module
850 \& comes with only one of the two, that one will be
851 \& used no matter the setting
852 \& prerequisites_policy
853 \& what to do if you are missing module prerequisites
854 \& (\*(Aqfollow\*(Aq automatically, \*(Aqask\*(Aq me, or \*(Aqignore\*(Aq)
855 \& For \*(Aqfollow\*(Aq, also sets PERL_AUTOINSTALL and
856 \& PERL_EXTUTILS_AUTOINSTALL for "\-\-defaultdeps" if
857 \& not already set
858 \& prefs_dir local directory to store per\-distro build options
859 \& proxy_user username for accessing an authenticating proxy
860 \& proxy_pass password for accessing an authenticating proxy
861 \& pushy_https use https to cpan.org when possible, otherwise use http
862 \& to cpan.org and issue a warning
863 \& randomize_urllist add some randomness to the sequence of the urllist
864 \& recommends_policy whether recommended prerequisites should be included
865 \& scan_cache controls scanning of cache (\*(Aqatstart\*(Aq, \*(Aqatexit\*(Aq or \*(Aqnever\*(Aq)
866 \& shell your favorite shell
867 \& show_unparsable_versions
868 \& boolean if r command tells which modules are versionless
869 \& show_upload_date boolean if commands should try to determine upload date
870 \& show_zero_versions boolean if r command tells for which modules $version==0
871 \& suggests_policy whether suggested prerequisites should be included
872 \& tar location of external program tar
873 \& tar_verbosity verbosity level for the tar command
874 \& term_is_latin deprecated: if true Unicode is translated to ISO\-8859\-1
875 \& (and nonsense for characters outside latin range)
876 \& term_ornaments boolean to turn ReadLine ornamenting on/off
877 \& test_report email test reports (if CPAN::Reporter is installed)
878 \& trust_test_report_history
879 \& skip testing when previously tested ok (according to
880 \& CPAN::Reporter history)
881 \& unzip location of external program unzip
882 \& urllist arrayref to nearby CPAN sites (or equivalent locations)
883 \& urllist_ping_external
884 \& use external ping command when autoselecting mirrors
885 \& urllist_ping_verbose
886 \& increase verbosity when autoselecting mirrors
887 \& use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
888 \& use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
889 \& username your username if you CPAN server wants one
890 \& version_timeout stops version parsing after this many seconds.
891 \& Default is 15 secs. Set to 0 to disable.
892 \& wait_list arrayref to a wait server to try (See CPAN::WAIT)
893 \& wget path to external prg
894 \& yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
895 \& yaml_module which module to use to read/write YAML files
896 .Ve
897 .PP
898 You can set and query each of these options interactively in the cpan
899 shell with the \f(CW\*(C`o conf\*(C'\fR or the \f(CW\*(C`o conf init\*(C'\fR command as specified below.
900 .ie n .IP """o conf <scalar option>""" 2
901 .el .IP "\f(CWo conf <scalar option>\fR" 2
902 .IX Item "o conf <scalar option>"
903 prints the current value of the \fIscalar option\fR
904 .ie n .IP """o conf <scalar option> <value>""" 2
905 .el .IP "\f(CWo conf <scalar option> <value>\fR" 2
906 .IX Item "o conf <scalar option> <value>"
907 Sets the value of the \fIscalar option\fR to \fIvalue\fR
908 .ie n .IP """o conf <list option>""" 2
909 .el .IP "\f(CWo conf <list option>\fR" 2
910 .IX Item "o conf <list option>"
911 prints the current value of the \fIlist option\fR in MakeMaker\*(Aqs
912 neatvalue format.
913 .ie n .IP """o conf <list option> [shift|pop]""" 2
914 .el .IP "\f(CWo conf <list option> [shift|pop]\fR" 2
915 .IX Item "o conf <list option> [shift|pop]"
916 shifts or pops the array in the \fIlist option\fR variable
917 .ie n .IP """o conf <list option> [unshift|push|splice] <list>""" 2
918 .el .IP "\f(CWo conf <list option> [unshift|push|splice] <list>\fR" 2
919 .IX Item "o conf <list option> [unshift|push|splice] <list>"
920 works like the corresponding perl commands.
921 .IP "interactive editing: o conf init [MATCH|LIST]" 2
922 .IX Item "interactive editing: o conf init [MATCH|LIST]"
923 Runs an interactive configuration dialog for matching variables.
924 Without argument runs the dialog over all supported config variables.
925 To specify a MATCH the argument must be enclosed by slashes.
926 .Sp
927 Examples:
928 .Sp
929 .Vb 2
930 \& o conf init ftp_passive ftp_proxy
931 \& o conf init /color/
932 .Ve
933 .Sp
934 Note: this method of setting config variables often provides more
935 explanation about the functioning of a variable than the manpage.
936 .SS "CPAN::anycwd($path): Note on config variable getcwd"
937 .IX Subsection "CPAN::anycwd($path): Note on config variable getcwd"
938 CPAN.pm changes the current working directory often and needs to
939 determine its own current working directory. By default it uses
940 Cwd::cwd, but if for some reason this doesn\*(Aqt work on your system,
941 configure alternatives according to the following table:
942 .IP cwd 4
943 .IX Item "cwd"
944 Calls Cwd::cwd
945 .IP getcwd 4
946 .IX Item "getcwd"
947 Calls Cwd::getcwd
948 .IP fastcwd 4
949 .IX Item "fastcwd"
950 Calls Cwd::fastcwd
951 .IP getdcwd 4
952 .IX Item "getdcwd"
953 Calls Cwd::getdcwd
954 .IP backtickcwd 4
955 .IX Item "backtickcwd"
956 Calls the external command cwd.
957 .SS "Note on the format of the urllist parameter"
958 .IX Subsection "Note on the format of the urllist parameter"
959 urllist parameters are URLs according to RFC 1738. We do a little
960 guessing if your URL is not compliant, but if you have problems with
961 \&\f(CW\*(C`file\*(C'\fR URLs, please try the correct format. Either:
962 .PP
963 .Vb 1
964 \& file://localhost/whatever/ftp/pub/CPAN/
965 .Ve
966 .PP
967 or
968 .PP
969 .Vb 1
970 \& file:///home/ftp/pub/CPAN/
971 .Ve
972 .SS "The urllist parameter has CD\-ROM support"
973 .IX Subsection "The urllist parameter has CD-ROM support"
974 The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of
975 URLs used for downloading. If the list contains any
976 \&\f(CW\*(C`file\*(C'\fR URLs, CPAN always tries there first. This
977 feature is disabled for index files. So the recommendation for the
978 owner of a CD\-ROM with CPAN contents is: include your local, possibly
979 outdated CD\-ROM as a \f(CW\*(C`file\*(C'\fR URL at the end of urllist, e.g.
980 .PP
981 .Vb 1
982 \& o conf urllist push file://localhost/CDROM/CPAN
983 .Ve
984 .PP
985 CPAN.pm will then fetch the index files from one of the CPAN sites
986 that come at the beginning of urllist. It will later check for each
987 module to see whether there is a local copy of the most recent version.
988 .PP
989 Another peculiarity of urllist is that the site that we could
990 successfully fetch the last file from automatically gets a preference
991 token and is tried as the first site for the next request. So if you
992 add a new site at runtime it may happen that the previously preferred
993 site will be tried another time. This means that if you want to disallow
994 a site for the next transfer, it must be explicitly removed from
995 urllist.
996 .SS "Maintaining the urllist parameter"
997 .IX Subsection "Maintaining the urllist parameter"
998 If you have YAML.pm (or some other YAML module configured in
999 \&\f(CW\*(C`yaml_module\*(C'\fR) installed, CPAN.pm collects a few statistical data
1000 about recent downloads. You can view the statistics with the \f(CW\*(C`hosts\*(C'\fR
1001 command or inspect them directly by looking into the \f(CW\*(C`FTPstats.yml\*(C'\fR
1002 file in your \f(CW\*(C`cpan_home\*(C'\fR directory.
1003 .PP
1004 To get some interesting statistics, it is recommended that
1005 \&\f(CW\*(C`randomize_urllist\*(C'\fR be set; this introduces some amount of
1006 randomness into the URL selection.
1007 .ie n .SS "The ""requires"" and ""build_requires"" dependency declarations"
1008 .el .SS "The \f(CWrequires\fP and \f(CWbuild_requires\fP dependency declarations"
1009 .IX Subsection "The requires and build_requires dependency declarations"
1010 Since CPAN.pm version 1.88_51 modules declared as \f(CW\*(C`build_requires\*(C'\fR by
1011 a distribution are treated differently depending on the config
1012 variable \f(CW\*(C`build_requires_install_policy\*(C'\fR. By setting
1013 \&\f(CW\*(C`build_requires_install_policy\*(C'\fR to \f(CW\*(C`no\*(C'\fR, such a module is not
1014 installed. It is only built and tested, and then kept in the list of
1015 tested but uninstalled modules. As such, it is available during the
1016 build of the dependent module by integrating the path to the
1017 \&\f(CW\*(C`blib/arch\*(C'\fR and \f(CW\*(C`blib/lib\*(C'\fR directories in the environment variable
1018 PERL5LIB. If \f(CW\*(C`build_requires_install_policy\*(C'\fR is set to \f(CW\*(C`yes\*(C'\fR, then
1019 both modules declared as \f(CW\*(C`requires\*(C'\fR and those declared as
1020 \&\f(CW\*(C`build_requires\*(C'\fR are treated alike. By setting to \f(CW\*(C`ask/yes\*(C'\fR or
1021 \&\f(CW\*(C`ask/no\*(C'\fR, CPAN.pm asks the user and sets the default accordingly.
1022 .SS "Configuration of the allow_installing_* parameters"
1023 .IX Subsection "Configuration of the allow_installing_* parameters"
1024 The \f(CW\*(C`allow_installing_*\*(C'\fR parameters are evaluated during
1025 the \f(CW\*(C`make\*(C'\fR phase. If set to \f(CW\*(C`yes\*(C'\fR, they allow the testing and the installation of
1026 the current distro and otherwise have no effect. If set to \f(CW\*(C`no\*(C'\fR, they
1027 may abort the build (preventing testing and installing), depending on the contents of the
1028 \&\f(CW\*(C`blib/\*(C'\fR directory. The \f(CW\*(C`blib/\*(C'\fR directory is the directory that holds
1029 all the files that would usually be installed in the \f(CW\*(C`install\*(C'\fR phase.
1030 .PP
1031 \&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory with the CPAN index.
1032 If it finds something there that belongs, according to the index, to a different
1033 dist, it aborts the current build.
1034 .PP
1035 \&\f(CW\*(C`allow_installing_module_downgrades\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory
1036 with already installed modules, actually their version numbers, as
1037 determined by ExtUtils::MakeMaker or equivalent. If a to\-be\-installed
1038 module would downgrade an already installed module, the current build
1039 is aborted.
1040 .PP
1041 An interesting twist occurs when a distroprefs document demands the
1042 installation of an outdated dist via goto while
1043 \&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR forbids it. Without additional
1044 provisions, this would let the \f(CW\*(C`allow_installing_outdated_dists\*(C'\fR
1045 win and the distroprefs lose. So the proper arrangement in such a case
1046 is to write a second distroprefs document for the distro that \f(CW\*(C`goto\*(C'\fR
1047 points to and overrule the \f(CW\*(C`cpanconfig\*(C'\fR there. E.g.:
1048 .PP
1049 .Vb 9
1050 \& \-\-\-
1051 \& match:
1052 \& distribution: "^MAUKE/Keyword\-Simple\-0.04.tar.gz"
1053 \& goto: "MAUKE/Keyword\-Simple\-0.03.tar.gz"
1054 \& \-\-\-
1055 \& match:
1056 \& distribution: "^MAUKE/Keyword\-Simple\-0.03.tar.gz"
1057 \& cpanconfig:
1058 \& allow_installing_outdated_dists: yes
1059 .Ve
1060 .SS "Configuration for individual distributions (\fIDistroprefs\fP)"
1061 .IX Subsection "Configuration for individual distributions (Distroprefs)"
1062 (\fBNote:\fR This feature has been introduced in CPAN.pm 1.8854)
1063 .PP
1064 Distributions on CPAN usually behave according to what we call the
1065 CPAN mantra. Or since the advent of Module::Build we should talk about
1066 two mantras:
1067 .PP
1068 .Vb 4
1069 \& perl Makefile.PL perl Build.PL
1070 \& make ./Build
1071 \& make test ./Build test
1072 \& make install ./Build install
1073 .Ve
1074 .PP
1075 But some modules cannot be built with this mantra. They try to get
1076 some extra data from the user via the environment, extra arguments, or
1077 interactively\-\-thus disturbing the installation of large bundles like
1078 Phalanx100 or modules with many dependencies like Plagger.
1079 .PP
1080 The distroprefs system of \f(CW\*(C`CPAN.pm\*(C'\fR addresses this problem by
1081 allowing the user to specify extra informations and recipes in YAML
1082 files to either
1083 .IP \(bu 4
1084 pass additional arguments to one of the four commands,
1085 .IP \(bu 4
1086 set environment variables
1087 .IP \(bu 4
1088 instantiate an Expect object that reads from the console, waits for
1089 some regular expressions and enters some answers
1090 .IP \(bu 4
1091 temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables
1092 .IP \(bu 4
1093 specify dependencies the original maintainer forgot
1094 .IP \(bu 4
1095 disable the installation of an object altogether
1096 .PP
1097 See the YAML and Data::Dumper files that come with the \f(CW\*(C`CPAN.pm\*(C'\fR
1098 distribution in the \f(CW\*(C`distroprefs/\*(C'\fR directory for examples.
1099 .SS Filenames
1100 .IX Subsection "Filenames"
1101 The YAML files themselves must have the \f(CW\*(C`.yml\*(C'\fR extension; all other
1102 files are ignored (for two exceptions see \fIFallback Data::Dumper and
1103 Storable\fR below). The containing directory can be specified in
1104 \&\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
1105 prefs_dir\*(C'\fR in the CPAN shell to set and activate the distroprefs
1106 system.
1107 .PP
1108 Every YAML file may contain arbitrary documents according to the YAML
1109 specification, and every document is treated as an entity that
1110 can specify the treatment of a single distribution.
1111 .PP
1112 Filenames can be picked arbitrarily; \f(CW\*(C`CPAN.pm\*(C'\fR always reads
1113 all files (in alphabetical order) and takes the key \f(CW\*(C`match\*(C'\fR (see
1114 below in \fILanguage Specs\fR) as a hashref containing match criteria
1115 that determine if the current distribution matches the YAML document
1116 or not.
1117 .SS "Fallback Data::Dumper and Storable"
1118 .IX Subsection "Fallback Data::Dumper and Storable"
1119 If neither your configured \f(CW\*(C`yaml_module\*(C'\fR nor YAML.pm is installed,
1120 CPAN.pm falls back to using Data::Dumper and Storable and looks for
1121 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
1122 directory. These files are expected to contain one or more hashrefs.
1123 For Data::Dumper generated files, this is expected to be done with by
1124 defining \f(CW$VAR1\fR, \f(CW$VAR2\fR, etc. The YAML shell would produce these
1125 with the command
1126 .PP
1127 .Vb 1
1128 \& ysh < somefile.yml > somefile.dd
1129 .Ve
1130 .PP
1131 For Storable files the rule is that they must be constructed such that
1132 \&\f(CWStorable::retrieve(file)\fR returns an array reference and the array
1133 elements represent one distropref object each. The conversion from
1134 YAML would look like so:
1135 .PP
1136 .Vb 3
1137 \& perl \-MYAML=LoadFile \-MStorable=nstore \-e \*(Aq
1138 \& @y=LoadFile(shift);
1139 \& nstore(\e@y, shift)\*(Aq somefile.yml somefile.st
1140 .Ve
1141 .PP
1142 In bootstrapping situations it is usually sufficient to translate only
1143 a few YAML files to Data::Dumper for crucial modules like
1144 \&\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
1145 over Data::Dumper, remember to pull out a Storable version that writes
1146 an older format than all the other Storable versions that will need to
1147 read them.
1148 .SS Blueprint
1149 .IX Subsection "Blueprint"
1150 The following example contains all supported keywords and structures
1151 with the exception of \f(CW\*(C`eexpect\*(C'\fR which can be used instead of
1152 \&\f(CW\*(C`expect\*(C'\fR.
1153 .PP
1154 .Vb 10
1155 \& \-\-\-
1156 \& comment: "Demo"
1157 \& match:
1158 \& module: "Dancing::Queen"
1159 \& distribution: "^CHACHACHA/Dancing\-"
1160 \& not_distribution: "\e.zip$"
1161 \& perl: "/usr/local/cariba\-perl/bin/perl"
1162 \& perlconfig:
1163 \& archname: "freebsd"
1164 \& not_cc: "gcc"
1165 \& env:
1166 \& DANCING_FLOOR: "Shubiduh"
1167 \& disabled: 1
1168 \& cpanconfig:
1169 \& make: gmake
1170 \& pl:
1171 \& args:
1172 \& \- "\-\-somearg=specialcase"
1173 \&
1174 \& env: {}
1175 \&
1176 \& expect:
1177 \& \- "Which is your favorite fruit"
1178 \& \- "apple\en"
1179 \&
1180 \& make:
1181 \& args:
1182 \& \- all
1183 \& \- extra\-all
1184 \&
1185 \& env: {}
1186 \&
1187 \& expect: []
1188 \&
1189 \& commandline: "echo SKIPPING make"
1190 \&
1191 \& test:
1192 \& args: []
1193 \&
1194 \& env: {}
1195 \&
1196 \& expect: []
1197 \&
1198 \& install:
1199 \& args: []
1200 \&
1201 \& env:
1202 \& WANT_TO_INSTALL: YES
1203 \&
1204 \& expect:
1205 \& \- "Do you really want to install"
1206 \& \- "y\en"
1207 \&
1208 \& patches:
1209 \& \- "ABCDE/Fedcba\-3.14\-ABCDE\-01.patch"
1210 \&
1211 \& depends:
1212 \& configure_requires:
1213 \& LWP: 5.8
1214 \& build_requires:
1215 \& Test::Exception: 0.25
1216 \& requires:
1217 \& Spiffy: 0.30
1218 .Ve
1219 .SS "Language Specs"
1220 .IX Subsection "Language Specs"
1221 Every YAML document represents a single hash reference. The valid keys
1222 in this hash are as follows:
1223 .IP "comment [scalar]" 4
1224 .IX Item "comment [scalar]"
1225 A comment
1226 .IP "cpanconfig [hash]" 4
1227 .IX Item "cpanconfig [hash]"
1228 Temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables.
1229 .Sp
1230 Supported are: \f(CW\*(C`build_requires_install_policy\*(C'\fR, \f(CW\*(C`check_sigs\*(C'\fR,
1231 \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_install_make_command\*(C'\fR, \f(CW\*(C`prefer_installer\*(C'\fR,
1232 \&\f(CW\*(C`test_report\*(C'\fR. Please report as a bug when you need another one
1233 supported.
1234 .IP "depends [hash] *** EXPERIMENTAL FEATURE ***" 4
1235 .IX Item "depends [hash] *** EXPERIMENTAL FEATURE ***"
1236 All three types, namely \f(CW\*(C`configure_requires\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and
1237 \&\f(CW\*(C`requires\*(C'\fR are supported in the way specified in the META.yml
1238 specification. The current implementation \fImerges\fR the specified
1239 dependencies with those declared by the package maintainer. In a
1240 future implementation this may be changed to override the original
1241 declaration.
1242 .IP "disabled [boolean]" 4
1243 .IX Item "disabled [boolean]"
1244 Specifies that this distribution shall not be processed at all.
1245 .IP "features [array] *** EXPERIMENTAL FEATURE ***" 4
1246 .IX Item "features [array] *** EXPERIMENTAL FEATURE ***"
1247 Experimental implementation to deal with optional_features from
1248 META.yml. Still needs coordination with installer software and
1249 currently works only for META.yml declaring \f(CW\*(C`dynamic_config=0\*(C'\fR. Use
1250 with caution.
1251 .IP "goto [string]" 4
1252 .IX Item "goto [string]"
1253 The canonical name of a delegate distribution to install
1254 instead. Useful when a new version, although it tests OK itself,
1255 breaks something else or a developer release or a fork is already
1256 uploaded that is better than the last released version.
1257 .IP "install [hash]" 4
1258 .IX Item "install [hash]"
1259 Processing instructions for the \f(CW\*(C`make install\*(C'\fR or \f(CW\*(C`./Build install\*(C'\fR
1260 phase of the CPAN mantra. See below under \fIProcessing Instructions\fR.
1261 .IP "make [hash]" 4
1262 .IX Item "make [hash]"
1263 Processing instructions for the \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`./Build\*(C'\fR phase of the
1264 CPAN mantra. See below under \fIProcessing Instructions\fR.
1265 .IP "match [hash]" 4
1266 .IX Item "match [hash]"
1267 A hashref with one or more of the keys \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`module\*(C'\fR,
1268 \&\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
1269 targeted at a specific CPAN distribution or installation.
1270 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1271 .Sp
1272 The corresponding values are interpreted as regular expressions. The
1273 \&\f(CW\*(C`distribution\*(C'\fR related one will be matched against the canonical
1274 distribution name, e.g. "AUTHOR/Foo\-Bar\-3.14.tar.gz".
1275 .Sp
1276 The \f(CW\*(C`module\*(C'\fR related one will be matched against \fIall\fR modules
1277 contained in the distribution until one module matches.
1278 .Sp
1279 The \f(CW\*(C`perl\*(C'\fR related one will be matched against \f(CW$^X\fR (but with the
1280 absolute path).
1281 .Sp
1282 The value associated with \f(CW\*(C`perlconfig\*(C'\fR is itself a hashref that is
1283 matched against corresponding values in the \f(CW%Config::Config\fR hash
1284 living in the \f(CW\*(C`Config.pm\*(C'\fR module.
1285 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1286 .Sp
1287 The value associated with \f(CW\*(C`env\*(C'\fR is itself a hashref that is
1288 matched against corresponding values in the \f(CW%ENV\fR hash.
1289 Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
1290 .Sp
1291 If more than one restriction of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, etc. is
1292 specified, the results of the separately computed match values must
1293 all match. If so, the hashref represented by the
1294 YAML document is returned as the preference structure for the current
1295 distribution.
1296 .IP "patches [array]" 4
1297 .IX Item "patches [array]"
1298 An array of patches on CPAN or on the local disk to be applied in
1299 order via an external patch program. If the value for the \f(CW\*(C`\-p\*(C'\fR
1300 parameter is \f(CW0\fR or \f(CW1\fR is determined by reading the patch
1301 beforehand. The path to each patch is either an absolute path on the
1302 local filesystem or relative to a patch directory specified in the
1303 \&\f(CW\*(C`patches_dir\*(C'\fR configuration variable or in the format of a canonical
1304 distro name. For examples please consult the distroprefs/ directory in
1305 the CPAN.pm distribution (these examples are not installed by
1306 default).
1307 .Sp
1308 Note: if the \f(CW\*(C`applypatch\*(C'\fR program is installed and \f(CW\*(C`CPAN::Config\*(C'\fR
1309 knows about it \fBand\fR a patch is written by the \f(CW\*(C`makepatch\*(C'\fR program,
1310 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
1311 and \f(CW\*(C`applypatch\*(C'\fR are available from CPAN in the \f(CW\*(C`JV/makepatch\-*\*(C'\fR
1312 distribution.
1313 .IP "pl [hash]" 4
1314 .IX Item "pl [hash]"
1315 Processing instructions for the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
1316 Build.PL\*(C'\fR phase of the CPAN mantra. See below under \fIProcessing
1317 Instructions\fR.
1318 .IP "test [hash]" 4
1319 .IX Item "test [hash]"
1320 Processing instructions for the \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR phase
1321 of the CPAN mantra. See below under \fIProcessing Instructions\fR.
1322 .SS "Processing Instructions"
1323 .IX Subsection "Processing Instructions"
1324 .IP "args [array]" 4
1325 .IX Item "args [array]"
1326 Arguments to be added to the command line
1327 .IP commandline 4
1328 .IX Item "commandline"
1329 A full commandline to run via \f(CWsystem()\fR.
1330 During execution, the environment variable PERL is set
1331 to $^X (but with an absolute path). If \f(CW\*(C`commandline\*(C'\fR is specified,
1332 \&\f(CW\*(C`args\*(C'\fR is not used.
1333 .IP "eexpect [hash]" 4
1334 .IX Item "eexpect [hash]"
1335 Extended \f(CW\*(C`expect\*(C'\fR. This is a hash reference with four allowed keys,
1336 \&\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.
1337 .Sp
1338 You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`eexpect\*(C'\fR. CPAN.pm
1339 does not install it for you.
1340 .Sp
1341 \&\f(CW\*(C`mode\*(C'\fR may have the values \f(CW\*(C`deterministic\*(C'\fR for the case where all
1342 questions come in the order written down and \f(CW\*(C`anyorder\*(C'\fR for the case
1343 where the questions may come in any order. The default mode is
1344 \&\f(CW\*(C`deterministic\*(C'\fR.
1345 .Sp
1346 \&\f(CW\*(C`timeout\*(C'\fR denotes a timeout in seconds. Floating\-point timeouts are
1347 OK. With \f(CW\*(C`mode=deterministic\*(C'\fR, the timeout denotes the
1348 timeout per question; with \f(CW\*(C`mode=anyorder\*(C'\fR it denotes the
1349 timeout per byte received from the stream or questions.
1350 .Sp
1351 \&\f(CW\*(C`talk\*(C'\fR is a reference to an array that contains alternating questions
1352 and answers. Questions are regular expressions and answers are literal
1353 strings. The Expect module watches the stream from the
1354 execution of the external program (\f(CW\*(C`perl Makefile.PL\*(C'\fR, \f(CW\*(C`perl
1355 Build.PL\*(C'\fR, \f(CW\*(C`make\*(C'\fR, etc.).
1356 .Sp
1357 For \f(CW\*(C`mode=deterministic\*(C'\fR, the CPAN.pm injects the
1358 corresponding answer as soon as the stream matches the regular expression.
1359 .Sp
1360 For \f(CW\*(C`mode=anyorder\*(C'\fR CPAN.pm answers a question as soon
1361 as the timeout is reached for the next byte in the input stream. In
1362 this mode you can use the \f(CW\*(C`reuse\*(C'\fR parameter to decide what will
1363 happen with a question\-answer pair after it has been used. In the
1364 default case (reuse=0) it is removed from the array, avoiding being
1365 used again accidentally. If you want to answer the
1366 question \f(CW\*(C`Do you really want to do that\*(C'\fR several times, then it must
1367 be included in the array at least as often as you want this answer to
1368 be given. Setting the parameter \f(CW\*(C`reuse\*(C'\fR to 1 makes this repetition
1369 unnecessary.
1370 .IP "env [hash]" 4
1371 .IX Item "env [hash]"
1372 Environment variables to be set during the command
1373 .IP "expect [array]" 4
1374 .IX Item "expect [array]"
1375 You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`expect\*(C'\fR. CPAN.pm
1376 does not install it for you.
1377 .Sp
1378 \&\f(CW\*(C`expect: <array>\*(C'\fR is a short notation for this \f(CW\*(C`eexpect\*(C'\fR:
1379 .Sp
1380 .Vb 4
1381 \& eexpect:
1382 \& mode: deterministic
1383 \& timeout: 15
1384 \& talk: <array>
1385 .Ve
1386 .ie n .SS "Schema verification with ""Kwalify"""
1387 .el .SS "Schema verification with \f(CWKwalify\fP"
1388 .IX Subsection "Schema verification with Kwalify"
1389 If you have the \f(CW\*(C`Kwalify\*(C'\fR module installed (which is part of the
1390 Bundle::CPANxxl), then all your distroprefs files are checked for
1391 syntactic correctness.
1392 .SS "Example Distroprefs Files"
1393 .IX Subsection "Example Distroprefs Files"
1394 \&\f(CW\*(C`CPAN.pm\*(C'\fR comes with a collection of example YAML files. Note that these
1395 are really just examples and should not be used without care because
1396 they cannot fit everybody\*(Aqs purpose. After all, the authors of the
1397 packages that ask questions had a need to ask, so you should watch
1398 their questions and adjust the examples to your environment and your
1399 needs. You have been warned:\-)
1400 .SH "PROGRAMMER\*(AqS INTERFACE"
1401 .IX Header "PROGRAMMER'S INTERFACE"
1402 If you do not enter the shell, shell commands are
1403 available both as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as
1404 functions in the calling package (\f(CWinstall(...)\fR). Before calling low\-level
1405 commands, it makes sense to initialize components of CPAN you need, e.g.:
1406 .PP
1407 .Vb 3
1408 \& CPAN::HandleConfig\->load;
1409 \& CPAN::Shell::setup_output;
1410 \& CPAN::Index\->reload;
1411 .Ve
1412 .PP
1413 High\-level commands do such initializations automatically.
1414 .PP
1415 There\*(Aqs currently only one class that has a stable interface \-
1416 CPAN::Shell. All commands that are available in the CPAN shell are
1417 methods of the class CPAN::Shell. The arguments on the commandline are
1418 passed as arguments to the method.
1419 .PP
1420 So if you take for example the shell command
1421 .PP
1422 .Vb 1
1423 \& notest install A B C
1424 .Ve
1425 .PP
1426 the actually executed command is
1427 .PP
1428 .Vb 1
1429 \& CPAN::Shell\->notest("install","A","B","C");
1430 .Ve
1431 .PP
1432 Each of the commands that produce listings of modules (\f(CW\*(C`r\*(C'\fR,
1433 \&\f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of the IDs of all modules
1434 within the list.
1435 .IP expand($type,@things) 2
1436 .IX Item "expand($type,@things)"
1437 The IDs of all objects available within a program are strings that can
1438 be expanded to the corresponding real objects with the
1439 \&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a
1440 list of CPAN::Module objects according to the \f(CW@things\fR arguments
1441 given. In scalar context, it returns only the first element of the
1442 list.
1443 .IP expandany(@things) 2
1444 .IX Item "expandany(@things)"
1445 Like expand, but returns objects of the appropriate type, i.e.
1446 CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and
1447 CPAN::Distribution objects for distributions. Note: it does not expand
1448 to CPAN::Author objects.
1449 .IP "Programming Examples" 2
1450 .IX Item "Programming Examples"
1451 This enables the programmer to do operations that combine
1452 functionalities that are available in the shell.
1453 .Sp
1454 .Vb 2
1455 \& # install everything that is outdated on my disk:
1456 \& perl \-MCPAN \-e \*(AqCPAN::Shell\->install(CPAN::Shell\->r)\*(Aq
1457 \&
1458 \& # install my favorite programs if necessary:
1459 \& for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
1460 \& CPAN::Shell\->install($mod);
1461 \& }
1462 \&
1463 \& # list all modules on my disk that have no VERSION number
1464 \& for $mod (CPAN::Shell\->expand("Module","/./")) {
1465 \& next unless $mod\->inst_file;
1466 \& # MakeMaker convention for undefined $VERSION:
1467 \& next unless $mod\->inst_version eq "undef";
1468 \& print "No VERSION in ", $mod\->id, "\en";
1469 \& }
1470 \&
1471 \& # find out which distribution on CPAN contains a module:
1472 \& print CPAN::Shell\->expand("Module","Apache::Constants")\->cpan_file
1473 .Ve
1474 .Sp
1475 Or if you want to schedule a \fIcron\fR job to watch CPAN, you could list
1476 all modules that need updating. First a quick and dirty way:
1477 .Sp
1478 .Vb 1
1479 \& perl \-e \*(Aquse CPAN; CPAN::Shell\->r;\*(Aq
1480 .Ve
1481 .Sp
1482 If you don\*(Aqt want any output should all modules be
1483 up to date, parse the output of above command for the regular
1484 expression \f(CW\*(C`/modules are up to date/\*(C'\fR and decide to mail the output
1485 only if it doesn\*(Aqt match.
1486 .Sp
1487 If you prefer to do it more in a programmerish style in one single
1488 process, something like this may better suit you:
1489 .Sp
1490 .Vb 7
1491 \& # list all modules on my disk that have newer versions on CPAN
1492 \& for $mod (CPAN::Shell\->expand("Module","/./")) {
1493 \& next unless $mod\->inst_file;
1494 \& next if $mod\->uptodate;
1495 \& printf "Module %s is installed as %s, could be updated to %s from CPAN\en",
1496 \& $mod\->id, $mod\->inst_version, $mod\->cpan_version;
1497 \& }
1498 .Ve
1499 .Sp
1500 If that gives too much output every day, you may want to
1501 watch only for three modules. You can write
1502 .Sp
1503 .Vb 1
1504 \& for $mod (CPAN::Shell\->expand("Module","/Apache|LWP|CGI/")) {
1505 .Ve
1506 .Sp
1507 as the first line instead. Or you can combine some of the above
1508 tricks:
1509 .Sp
1510 .Vb 5
1511 \& # watch only for a new mod_perl module
1512 \& $mod = CPAN::Shell\->expand("Module","mod_perl");
1513 \& exit if $mod\->uptodate;
1514 \& # new mod_perl arrived, let me know all update recommendations
1515 \& CPAN::Shell\->r;
1516 .Ve
1517 .SS "Methods in the other Classes"
1518 .IX Subsection "Methods in the other Classes"
1519 .IP \fBCPAN::Author::as_glimpse()\fR 4
1520 .IX Item "CPAN::Author::as_glimpse()"
1521 Returns a one\-line description of the author
1522 .IP \fBCPAN::Author::as_string()\fR 4
1523 .IX Item "CPAN::Author::as_string()"
1524 Returns a multi\-line description of the author
1525 .IP \fBCPAN::Author::email()\fR 4
1526 .IX Item "CPAN::Author::email()"
1527 Returns the author\*(Aqs email address
1528 .IP \fBCPAN::Author::fullname()\fR 4
1529 .IX Item "CPAN::Author::fullname()"
1530 Returns the author\*(Aqs name
1531 .IP \fBCPAN::Author::name()\fR 4
1532 .IX Item "CPAN::Author::name()"
1533 An alias for fullname
1534 .IP \fBCPAN::Bundle::as_glimpse()\fR 4
1535 .IX Item "CPAN::Bundle::as_glimpse()"
1536 Returns a one\-line description of the bundle
1537 .IP \fBCPAN::Bundle::as_string()\fR 4
1538 .IX Item "CPAN::Bundle::as_string()"
1539 Returns a multi\-line description of the bundle
1540 .IP \fBCPAN::Bundle::clean()\fR 4
1541 .IX Item "CPAN::Bundle::clean()"
1542 Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle.
1543 .IP \fBCPAN::Bundle::contains()\fR 4
1544 .IX Item "CPAN::Bundle::contains()"
1545 Returns a list of objects\*(Aq IDs contained in a bundle. The associated
1546 objects may be bundles, modules or distributions.
1547 .IP CPAN::Bundle::force($method,@args) 4
1548 .IX Item "CPAN::Bundle::force($method,@args)"
1549 Forces CPAN to perform a task that it normally would have refused to
1550 do. Force takes as arguments a method name to be called and any number
1551 of additional arguments that should be passed to the called method.
1552 The internals of the object get the needed changes so that CPAN.pm
1553 does not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively
1554 to all contained objects. See also the section above on the \f(CW\*(C`force\*(C'\fR
1555 and the \f(CW\*(C`fforce\*(C'\fR pragma.
1556 .IP \fBCPAN::Bundle::get()\fR 4
1557 .IX Item "CPAN::Bundle::get()"
1558 Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle
1559 .IP \fBCPAN::Bundle::inst_file()\fR 4
1560 .IX Item "CPAN::Bundle::inst_file()"
1561 Returns the highest installed version of the bundle in either \f(CW@INC\fR or
1562 \&\f(CW\*(C`$CPAN::Config\->{cpan_home}\*(C'\fR. Note that this is different from
1563 CPAN::Module::inst_file.
1564 .IP \fBCPAN::Bundle::inst_version()\fR 4
1565 .IX Item "CPAN::Bundle::inst_version()"
1566 Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR
1567 .IP \fBCPAN::Bundle::uptodate()\fR 4
1568 .IX Item "CPAN::Bundle::uptodate()"
1569 Returns 1 if the bundle itself and all its members are up\-to\-date.
1570 .IP \fBCPAN::Bundle::install()\fR 4
1571 .IX Item "CPAN::Bundle::install()"
1572 Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle
1573 .IP \fBCPAN::Bundle::make()\fR 4
1574 .IX Item "CPAN::Bundle::make()"
1575 Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle
1576 .IP \fBCPAN::Bundle::readme()\fR 4
1577 .IX Item "CPAN::Bundle::readme()"
1578 Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle
1579 .IP \fBCPAN::Bundle::test()\fR 4
1580 .IX Item "CPAN::Bundle::test()"
1581 Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle
1582 .IP \fBCPAN::Distribution::as_glimpse()\fR 4
1583 .IX Item "CPAN::Distribution::as_glimpse()"
1584 Returns a one\-line description of the distribution
1585 .IP \fBCPAN::Distribution::as_string()\fR 4
1586 .IX Item "CPAN::Distribution::as_string()"
1587 Returns a multi\-line description of the distribution
1588 .IP CPAN::Distribution::author 4
1589 .IX Item "CPAN::Distribution::author"
1590 Returns the CPAN::Author object of the maintainer who uploaded this
1591 distribution
1592 .IP \fBCPAN::Distribution::pretty_id()\fR 4
1593 .IX Item "CPAN::Distribution::pretty_id()"
1594 Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is the
1595 author\*(Aqs PAUSE ID and TARBALL is the distribution filename.
1596 .IP \fBCPAN::Distribution::base_id()\fR 4
1597 .IX Item "CPAN::Distribution::base_id()"
1598 Returns the distribution filename without any archive suffix. E.g
1599 "Foo\-Bar\-0.01"
1600 .IP \fBCPAN::Distribution::clean()\fR 4
1601 .IX Item "CPAN::Distribution::clean()"
1602 Changes to the directory where the distribution has been unpacked and
1603 runs \f(CW\*(C`make clean\*(C'\fR there.
1604 .IP \fBCPAN::Distribution::containsmods()\fR 4
1605 .IX Item "CPAN::Distribution::containsmods()"
1606 Returns a list of IDs of modules contained in a distribution file.
1607 Works only for distributions listed in the 02packages.details.txt.gz
1608 file. This typically means that just most recent version of a
1609 distribution is covered.
1610 .IP \fBCPAN::Distribution::cvs_import()\fR 4
1611 .IX Item "CPAN::Distribution::cvs_import()"
1612 Changes to the directory where the distribution has been unpacked and
1613 runs something like
1614 .Sp
1615 .Vb 1
1616 \& cvs \-d $cvs_root import \-m $cvs_log $cvs_dir $userid v$version
1617 .Ve
1618 .Sp
1619 there.
1620 .IP \fBCPAN::Distribution::dir()\fR 4
1621 .IX Item "CPAN::Distribution::dir()"
1622 Returns the directory into which this distribution has been unpacked.
1623 .IP CPAN::Distribution::force($method,@args) 4
1624 .IX Item "CPAN::Distribution::force($method,@args)"
1625 Forces CPAN to perform a task that it normally would have refused to
1626 do. Force takes as arguments a method name to be called and any number
1627 of additional arguments that should be passed to the called method.
1628 The internals of the object get the needed changes so that CPAN.pm
1629 does not refuse to take the action. See also the section above on the
1630 \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
1631 .IP \fBCPAN::Distribution::get()\fR 4
1632 .IX Item "CPAN::Distribution::get()"
1633 Downloads the distribution from CPAN and unpacks it. Does nothing if
1634 the distribution has already been downloaded and unpacked within the
1635 current session.
1636 .IP \fBCPAN::Distribution::install()\fR 4
1637 .IX Item "CPAN::Distribution::install()"
1638 Changes to the directory where the distribution has been unpacked and
1639 runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not
1640 yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR is issued in
1641 any case and if this fails, the install is cancelled. The
1642 cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for
1643 you.
1644 .Sp
1645 This install method only has the power to install the distribution if
1646 there are no dependencies in the way. To install an object along with all
1647 its dependencies, use CPAN::Shell\->install.
1648 .Sp
1649 Note that \fBinstall()\fR gives no meaningful return value. See \fBuptodate()\fR.
1650 .IP \fBCPAN::Distribution::isa_perl()\fR 4
1651 .IX Item "CPAN::Distribution::isa_perl()"
1652 Returns 1 if this distribution file seems to be a perl distribution.
1653 Normally this is derived from the file name only, but the index from
1654 CPAN can contain a hint to achieve a return value of true for other
1655 filenames too.
1656 .IP \fBCPAN::Distribution::look()\fR 4
1657 .IX Item "CPAN::Distribution::look()"
1658 Changes to the directory where the distribution has been unpacked and
1659 opens a subshell there. Exiting the subshell returns.
1660 .IP \fBCPAN::Distribution::make()\fR 4
1661 .IX Item "CPAN::Distribution::make()"
1662 First runs the \f(CW\*(C`get\*(C'\fR method to make sure the distribution is
1663 downloaded and unpacked. Changes to the directory where the
1664 distribution has been unpacked and runs the external commands \f(CW\*(C`perl
1665 Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there.
1666 .IP \fBCPAN::Distribution::perldoc()\fR 4
1667 .IX Item "CPAN::Distribution::perldoc()"
1668 Downloads the pod documentation of the file associated with a
1669 distribution (in HTML format) and runs it through the external
1670 command \fIlynx\fR specified in \f(CW\*(C`$CPAN::Config\->{lynx}\*(C'\fR. If \fIlynx\fR
1671 isn\*(Aqt available, it converts it to plain text with the external
1672 command \fIhtml2text\fR and runs it through the pager specified
1673 in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR.
1674 .IP \fBCPAN::Distribution::prefs()\fR 4
1675 .IX Item "CPAN::Distribution::prefs()"
1676 Returns the hash reference from the first matching YAML file that the
1677 user has deposited in the \f(CW\*(C`prefs_dir/\*(C'\fR directory. The first
1678 succeeding match wins. The files in the \f(CW\*(C`prefs_dir/\*(C'\fR are processed
1679 alphabetically, and the canonical distro name (e.g.
1680 AUTHOR/Foo\-Bar\-3.14.tar.gz) is matched against the regular expressions
1681 stored in the \f(CW$root\fR\->{match}{distribution} attribute value.
1682 Additionally all module names contained in a distribution are matched
1683 against the regular expressions in the \f(CW$root\fR\->{match}{module} attribute
1684 value. The two match values are ANDed together. Each of the two
1685 attributes are optional.
1686 .IP \fBCPAN::Distribution::prereq_pm()\fR 4
1687 .IX Item "CPAN::Distribution::prereq_pm()"
1688 Returns the hash reference that has been announced by a distribution
1689 as the \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`build_requires\*(C'\fR elements. These can be
1690 declared either by the \f(CW\*(C`META.yml\*(C'\fR (if authoritative) or can be
1691 deposited after the run of \f(CW\*(C`Build.PL\*(C'\fR in the file \f(CW\*(C`./_build/prereqs\*(C'\fR
1692 or after the run of \f(CW\*(C`Makfile.PL\*(C'\fR written as the \f(CW\*(C`PREREQ_PM\*(C'\fR hash in
1693 a comment in the produced \f(CW\*(C`Makefile\*(C'\fR. \fINote\fR: this method only works
1694 after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns
1695 undef otherwise.
1696 .IP \fBCPAN::Distribution::readme()\fR 4
1697 .IX Item "CPAN::Distribution::readme()"
1698 Downloads the README file associated with a distribution and runs it
1699 through the pager specified in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR.
1700 .IP \fBCPAN::Distribution::reports()\fR 4
1701 .IX Item "CPAN::Distribution::reports()"
1702 Downloads report data for this distribution from www.cpantesters.org
1703 and displays a subset of them.
1704 .IP \fBCPAN::Distribution::read_yaml()\fR 4
1705 .IX Item "CPAN::Distribution::read_yaml()"
1706 Returns the content of the META.yml of this distro as a hashref. Note:
1707 works only after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution.
1708 Returns undef otherwise. Also returns undef if the content of META.yml
1709 is not authoritative. (The rules about what exactly makes the content
1710 authoritative are still in flux.)
1711 .IP \fBCPAN::Distribution::test()\fR 4
1712 .IX Item "CPAN::Distribution::test()"
1713 Changes to the directory where the distribution has been unpacked and
1714 runs \f(CW\*(C`make test\*(C'\fR there.
1715 .IP \fBCPAN::Distribution::uptodate()\fR 4
1716 .IX Item "CPAN::Distribution::uptodate()"
1717 Returns 1 if all the modules contained in the distribution are
1718 up\-to\-date. Relies on containsmods.
1719 .IP \fBCPAN::Index::force_reload()\fR 4
1720 .IX Item "CPAN::Index::force_reload()"
1721 Forces a reload of all indices.
1722 .IP \fBCPAN::Index::reload()\fR 4
1723 .IX Item "CPAN::Index::reload()"
1724 Reloads all indices if they have not been read for more than
1725 \&\f(CW\*(C`$CPAN::Config\->{index_expire}\*(C'\fR days.
1726 .IP \fBCPAN::InfoObj::dump()\fR 4
1727 .IX Item "CPAN::InfoObj::dump()"
1728 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
1729 inherit this method. It prints the data structure associated with an
1730 object. Useful for debugging. Note: the data structure is considered
1731 internal and thus subject to change without notice.
1732 .IP \fBCPAN::Module::as_glimpse()\fR 4
1733 .IX Item "CPAN::Module::as_glimpse()"
1734 Returns a one\-line description of the module in four columns: The
1735 first column contains the word \f(CW\*(C`Module\*(C'\fR, the second column consists
1736 of one character: an equals sign if this module is already installed
1737 and up\-to\-date, a less\-than sign if this module is installed but can be
1738 upgraded, and a space if the module is not installed. The third column
1739 is the name of the module and the fourth column gives maintainer or
1740 distribution information.
1741 .IP \fBCPAN::Module::as_string()\fR 4
1742 .IX Item "CPAN::Module::as_string()"
1743 Returns a multi\-line description of the module
1744 .IP \fBCPAN::Module::clean()\fR 4
1745 .IX Item "CPAN::Module::clean()"
1746 Runs a clean on the distribution associated with this module.
1747 .IP \fBCPAN::Module::cpan_file()\fR 4
1748 .IX Item "CPAN::Module::cpan_file()"
1749 Returns the filename on CPAN that is associated with the module.
1750 .IP \fBCPAN::Module::cpan_version()\fR 4
1751 .IX Item "CPAN::Module::cpan_version()"
1752 Returns the latest version of this module available on CPAN.
1753 .IP \fBCPAN::Module::cvs_import()\fR 4
1754 .IX Item "CPAN::Module::cvs_import()"
1755 Runs a cvs_import on the distribution associated with this module.
1756 .IP \fBCPAN::Module::description()\fR 4
1757 .IX Item "CPAN::Module::description()"
1758 Returns a 44 character description of this module. Only available for
1759 modules listed in The Module List (CPAN/modules/00modlist.long.html
1760 or 00modlist.long.txt.gz)
1761 .IP \fBCPAN::Module::distribution()\fR 4
1762 .IX Item "CPAN::Module::distribution()"
1763 Returns the CPAN::Distribution object that contains the current
1764 version of this module.
1765 .IP \fBCPAN::Module::dslip_status()\fR 4
1766 .IX Item "CPAN::Module::dslip_status()"
1767 Returns a hash reference. The keys of the hash are the letters \f(CW\*(C`D\*(C'\fR,
1768 \&\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,
1769 language, interface and public licence respectively. The data for the
1770 DSLIP status are collected by pause.perl.org when authors register
1771 their namespaces. The values of the 5 hash elements are one\-character
1772 words whose meaning is described in the table below. There are also 5
1773 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 <PV> that carry a more
1774 verbose value of the 5 status variables.
1775 .Sp
1776 Where the \*(AqDSLIP\*(Aq characters have the following meanings:
1777 .Sp
1778 .Vb 7
1779 \& D \- Development Stage (Note: *NO IMPLIED TIMESCALES*):
1780 \& i \- Idea, listed to gain consensus or as a placeholder
1781 \& c \- under construction but pre\-alpha (not yet released)
1782 \& a/b \- Alpha/Beta testing
1783 \& R \- Released
1784 \& M \- Mature (no rigorous definition)
1785 \& S \- Standard, supplied with Perl 5
1786 \&
1787 \& S \- Support Level:
1788 \& m \- Mailing\-list
1789 \& d \- Developer
1790 \& u \- Usenet newsgroup comp.lang.perl.modules
1791 \& n \- None known, try comp.lang.perl.modules
1792 \& a \- abandoned; volunteers welcome to take over maintenance
1793 \&
1794 \& L \- Language Used:
1795 \& p \- Perl\-only, no compiler needed, should be platform independent
1796 \& c \- C and perl, a C compiler will be needed
1797 \& h \- Hybrid, written in perl with optional C code, no compiler needed
1798 \& + \- C++ and perl, a C++ compiler will be needed
1799 \& o \- perl and another language other than C or C++
1800 \&
1801 \& I \- Interface Style
1802 \& f \- plain Functions, no references used
1803 \& h \- hybrid, object and function interfaces available
1804 \& n \- no interface at all (huh?)
1805 \& r \- some use of unblessed References or ties
1806 \& O \- Object oriented using blessed references and/or inheritance
1807 \&
1808 \& P \- Public License
1809 \& p \- Standard\-Perl: user may choose between GPL and Artistic
1810 \& g \- GPL: GNU General Public License
1811 \& l \- LGPL: "GNU Lesser General Public License" (previously known as
1812 \& "GNU Library General Public License")
1813 \& b \- BSD: The BSD License
1814 \& a \- Artistic license alone
1815 \& 2 \- Artistic license 2.0 or later
1816 \& o \- open source: approved by www.opensource.org
1817 \& d \- allows distribution without restrictions
1818 \& r \- restricted distribution
1819 \& n \- no license at all
1820 .Ve
1821 .IP CPAN::Module::force($method,@args) 4
1822 .IX Item "CPAN::Module::force($method,@args)"
1823 Forces CPAN to perform a task it would normally refuse to
1824 do. Force takes as arguments a method name to be invoked and any number
1825 of additional arguments to pass that method.
1826 The internals of the object get the needed changes so that CPAN.pm
1827 does not refuse to take the action. See also the section above on the
1828 \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
1829 .IP \fBCPAN::Module::get()\fR 4
1830 .IX Item "CPAN::Module::get()"
1831 Runs a get on the distribution associated with this module.
1832 .IP \fBCPAN::Module::inst_file()\fR 4
1833 .IX Item "CPAN::Module::inst_file()"
1834 Returns the filename of the module found in \f(CW@INC\fR. The first file found
1835 is reported, just as perl itself stops searching \f(CW@INC\fR once it finds a
1836 module.
1837 .IP \fBCPAN::Module::available_file()\fR 4
1838 .IX Item "CPAN::Module::available_file()"
1839 Returns the filename of the module found in PERL5LIB or \f(CW@INC\fR. The
1840 first file found is reported. The advantage of this method over
1841 \&\f(CW\*(C`inst_file\*(C'\fR is that modules that have been tested but not yet
1842 installed are included because PERL5LIB keeps track of tested modules.
1843 .IP \fBCPAN::Module::inst_version()\fR 4
1844 .IX Item "CPAN::Module::inst_version()"
1845 Returns the version number of the installed module in readable format.
1846 .IP \fBCPAN::Module::available_version()\fR 4
1847 .IX Item "CPAN::Module::available_version()"
1848 Returns the version number of the available module in readable format.
1849 .IP \fBCPAN::Module::install()\fR 4
1850 .IX Item "CPAN::Module::install()"
1851 Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module.
1852 .IP \fBCPAN::Module::look()\fR 4
1853 .IX Item "CPAN::Module::look()"
1854 Changes to the directory where the distribution associated with this
1855 module has been unpacked and opens a subshell there. Exiting the
1856 subshell returns.
1857 .IP \fBCPAN::Module::make()\fR 4
1858 .IX Item "CPAN::Module::make()"
1859 Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module.
1860 .IP \fBCPAN::Module::manpage_headline()\fR 4
1861 .IX Item "CPAN::Module::manpage_headline()"
1862 If module is installed, peeks into the module\*(Aqs manpage, reads the
1863 headline, and returns it. Moreover, if the module has been downloaded
1864 within this session, does the equivalent on the downloaded module even
1865 if it hasn\*(Aqt been installed yet.
1866 .IP \fBCPAN::Module::perldoc()\fR 4
1867 .IX Item "CPAN::Module::perldoc()"
1868 Runs a \f(CW\*(C`perldoc\*(C'\fR on this module.
1869 .IP \fBCPAN::Module::readme()\fR 4
1870 .IX Item "CPAN::Module::readme()"
1871 Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module.
1872 .IP \fBCPAN::Module::reports()\fR 4
1873 .IX Item "CPAN::Module::reports()"
1874 Calls the \fBreports()\fR method on the associated distribution object.
1875 .IP \fBCPAN::Module::test()\fR 4
1876 .IX Item "CPAN::Module::test()"
1877 Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module.
1878 .IP \fBCPAN::Module::uptodate()\fR 4
1879 .IX Item "CPAN::Module::uptodate()"
1880 Returns 1 if the module is installed and up\-to\-date.
1881 .IP \fBCPAN::Module::userid()\fR 4
1882 .IX Item "CPAN::Module::userid()"
1883 Returns the author\*(Aqs ID of the module.
1884 .SS "Cache Manager"
1885 .IX Subsection "Cache Manager"
1886 Currently the cache manager only keeps track of the build directory
1887 ($CPAN::Config\->{build_dir}). It is a simple FIFO mechanism that
1888 deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of
1889 all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache}
1890 (in MB). The contents of this cache may be used for later
1891 re\-installations that you intend to do manually, but will never be
1892 trusted by CPAN itself. This is due to the fact that the user might
1893 use these directories for building modules on different architectures.
1894 .PP
1895 There is another directory ($CPAN::Config\->{keep_source_where}) where
1896 the original distribution files are kept. This directory is not
1897 covered by the cache manager and must be controlled by the user. If
1898 you choose to have the same directory as build_dir and as
1899 keep_source_where directory, then your sources will be deleted with
1900 the same fifo mechanism.
1901 .SS Bundles
1902 .IX Subsection "Bundles"
1903 A bundle is just a perl module in the namespace Bundle:: that does not
1904 define any functions or methods. It usually only contains documentation.
1905 .PP
1906 It starts like a perl module with a package declaration and a \f(CW$VERSION\fR
1907 variable. After that the pod section looks like any other pod with the
1908 only difference being that \fIone special pod section\fR exists starting with
1909 (verbatim):
1910 .PP
1911 .Vb 1
1912 \& =head1 CONTENTS
1913 .Ve
1914 .PP
1915 In this pod section each line obeys the format
1916 .PP
1917 .Vb 1
1918 \& Module_Name [Version_String] [\- optional text]
1919 .Ve
1920 .PP
1921 The only required part is the first field, the name of a module
1922 (e.g. Foo::Bar, i.e. \fInot\fR the name of the distribution file). The rest
1923 of the line is optional. The comment part is delimited by a dash just
1924 as in the man page header.
1925 .PP
1926 The distribution of a bundle should follow the same convention as
1927 other distributions.
1928 .PP
1929 Bundles are treated specially in the CPAN package. If you say \*(Aqinstall
1930 Bundle::Tkkit\*(Aq (assuming such a bundle exists), CPAN will install all
1931 the modules in the CONTENTS section of the pod. You can install your
1932 own Bundles locally by placing a conformant Bundle file somewhere into
1933 your \f(CW@INC\fR path. The \fBautobundle()\fR command which is available in the
1934 shell interface does that for you by including all currently installed
1935 modules in a snapshot bundle file.
1936 .SH PREREQUISITES
1937 .IX Header "PREREQUISITES"
1938 The CPAN program is trying to depend on as little as possible so the
1939 user can use it in hostile environment. It works better the more goodies
1940 the environment provides. For example if you try in the CPAN shell
1941 .PP
1942 .Vb 1
1943 \& install Bundle::CPAN
1944 .Ve
1945 .PP
1946 or
1947 .PP
1948 .Vb 1
1949 \& install Bundle::CPANxxl
1950 .Ve
1951 .PP
1952 you will find the shell more convenient than the bare shell before.
1953 .PP
1954 If you have a local mirror of CPAN and can access all files with
1955 "file:" URLs, then you only need a perl later than perl5.003 to run
1956 this module. Otherwise Net::FTP is strongly recommended. LWP may be
1957 required for non\-UNIX systems, or if your nearest CPAN site is
1958 associated with a URL that is not \f(CW\*(C`ftp:\*(C'\fR.
1959 .PP
1960 If you have neither Net::FTP nor LWP, there is a fallback mechanism
1961 implemented for an external ftp command or for an external lynx
1962 command.
1963 .SH UTILITIES
1964 .IX Header "UTILITIES"
1965 .SS "Finding packages and VERSION"
1966 .IX Subsection "Finding packages and VERSION"
1967 This module presumes that all packages on CPAN
1968 .IP \(bu 2
1969 declare their \f(CW$VERSION\fR variable in an easy to parse manner. This
1970 prerequisite can hardly be relaxed because it consumes far too much
1971 memory to load all packages into the running program just to determine
1972 the \f(CW$VERSION\fR variable. Currently all programs that are dealing with
1973 version use something like this
1974 .Sp
1975 .Vb 2
1976 \& perl \-MExtUtils::MakeMaker \-le \e
1977 \& \*(Aqprint MM\->parse_version(shift)\*(Aq filename
1978 .Ve
1979 .Sp
1980 If you are author of a package and wonder if your \f(CW$VERSION\fR can be
1981 parsed, please try the above method.
1982 .IP \(bu 2
1983 come as compressed or gzipped tarfiles or as zip files and contain a
1984 \&\f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR (well, we try to handle a bit more, but
1985 with little enthusiasm).
1986 .SS Debugging
1987 .IX Subsection "Debugging"
1988 Debugging this module is more than a bit complex due to interference from
1989 the software producing the indices on CPAN, the mirroring process on CPAN,
1990 packaging, configuration, synchronicity, and even (gasp!) due to bugs
1991 within the CPAN.pm module itself.
1992 .PP
1993 For debugging the code of CPAN.pm itself in interactive mode, some
1994 debugging aid can be turned on for most packages within
1995 CPAN.pm with one of
1996 .IP "o debug package..." 2
1997 .IX Item "o debug package..."
1998 sets debug mode for packages.
1999 .IP "o debug \-package..." 2
2000 .IX Item "o debug -package..."
2001 unsets debug mode for packages.
2002 .IP "o debug all" 2
2003 .IX Item "o debug all"
2004 turns debugging on for all packages.
2005 .IP "o debug number" 2
2006 .IX Item "o debug number"
2007 .PP
2008 which sets the debugging packages directly. Note that \f(CW\*(C`o debug 0\*(C'\fR
2009 turns debugging off.
2010 .PP
2011 What seems a successful strategy is the combination of \f(CW\*(C`reload
2012 cpan\*(C'\fR and the debugging switches. Add a new debug statement while
2013 running in the shell and then issue a \f(CW\*(C`reload cpan\*(C'\fR and see the new
2014 debugging messages immediately without losing the current context.
2015 .PP
2016 \&\f(CW\*(C`o debug\*(C'\fR without an argument lists the valid package names and the
2017 current set of packages in debugging mode. \f(CW\*(C`o debug\*(C'\fR has built\-in
2018 completion support.
2019 .PP
2020 For debugging of CPAN data there is the \f(CW\*(C`dump\*(C'\fR command which takes
2021 the same arguments as make/test/install and outputs each object\*(Aqs
2022 Data::Dumper dump. If an argument looks like a perl variable and
2023 contains one of \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, it is \fBeval()\fRed and fed to
2024 Data::Dumper directly.
2025 .SS "Floppy, Zip, Offline Mode"
2026 .IX Subsection "Floppy, Zip, Offline Mode"
2027 CPAN.pm works nicely without network access, too. If you maintain machines
2028 that are not networked at all, you should consider working with \f(CW\*(C`file:\*(C'\fR
2029 URLs. You\*(Aqll have to collect your modules somewhere first. So
2030 you might use CPAN.pm to put together all you need on a networked
2031 machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not
2032 \&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind
2033 of a personal CPAN. CPAN.pm on the non\-networked machines works nicely
2034 with this floppy. See also below the paragraph about CD\-ROM support.
2035 .SS "Basic Utilities for Programmers"
2036 .IX Subsection "Basic Utilities for Programmers"
2037 .IP has_inst($module) 2
2038 .IX Item "has_inst($module)"
2039 Returns true if the module is installed. Used to load all modules into
2040 the running CPAN.pm that are considered optional. The config variable
2041 \&\f(CW\*(C`dontload_list\*(C'\fR intercepts the \f(CWhas_inst()\fR call such
2042 that an optional module is not loaded despite being available. For
2043 example, the following command will prevent \f(CW\*(C`YAML.pm\*(C'\fR from being
2044 loaded:
2045 .Sp
2046 .Vb 1
2047 \& cpan> o conf dontload_list push YAML
2048 .Ve
2049 .Sp
2050 See the source for details.
2051 .IP use_inst($module) 2
2052 .IX Item "use_inst($module)"
2053 Similary to \fBhas_inst()\fR tries to load optional library but also dies if
2054 library is not available
2055 .IP has_usable($module) 2
2056 .IX Item "has_usable($module)"
2057 Returns true if the module is installed and in a usable state. Only
2058 useful for a handful of modules that are used internally. See the
2059 source for details.
2060 .IP instance($module) 2
2061 .IX Item "instance($module)"
2062 The constructor for all the singletons used to represent modules,
2063 distributions, authors, and bundles. If the object already exists, this
2064 method returns the object; otherwise, it calls the constructor.
2065 .IP \fBfrontend()\fR 2
2066 .IX Item "frontend()"
2067 .PD 0
2068 .IP frontend($new_frontend) 2
2069 .IX Item "frontend($new_frontend)"
2070 .PD
2071 Getter/setter for frontend object. Method just allows to subclass CPAN.pm.
2072 .SH SECURITY
2073 .IX Header "SECURITY"
2074 There\*(Aqs no strong security layer in CPAN.pm. CPAN.pm helps you to
2075 install foreign, unmasked, unsigned code on your machine. We compare
2076 to a checksum that comes from the net just as the distribution file
2077 itself. But we try to make it easy to add security on demand:
2078 .SS "Cryptographically signed modules"
2079 .IX Subsection "Cryptographically signed modules"
2080 Since release 1.77, CPAN.pm has been able to verify cryptographically
2081 signed module distributions using Module::Signature. The CPAN modules
2082 can be signed by their authors, thus giving more security. The simple
2083 unsigned MD5 checksums that were used before by CPAN protect mainly
2084 against accidental file corruption.
2085 .PP
2086 You will need to have Module::Signature installed, which in turn
2087 requires that you have at least one of Crypt::OpenPGP module or the
2088 command\-line \fIgpg\fR tool installed.
2089 .PP
2090 You will also need to be able to connect over the Internet to the public
2091 key servers, like pgp.mit.edu, and their port 11731 (the HKP protocol).
2092 .PP
2093 The configuration parameter check_sigs is there to turn signature
2094 checking on or off.
2095 .SH EXPORT
2096 .IX Header "EXPORT"
2097 Most functions in package CPAN are exported by default. The reason
2098 for this is that the primary use is intended for the cpan shell or for
2099 one\-liners.
2100 .SH ENVIRONMENT
2101 .IX Header "ENVIRONMENT"
2102 When the CPAN shell enters a subshell via the look command, it sets
2103 the environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
2104 already set.
2105 .PP
2106 When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
2107 to the ID of the running process. It also sets
2108 PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
2109 happen with older versions of Module::Install.
2110 .PP
2111 When running \f(CW\*(C`perl Makefile.PL\*(C'\fR, the environment variable
2112 \&\f(CW\*(C`PERL5_CPAN_IS_EXECUTING\*(C'\fR is set to the full path of the
2113 \&\f(CW\*(C`Makefile.PL\*(C'\fR that is being executed. This prevents runaway processes
2114 with newer versions of Module::Install.
2115 .PP
2116 When the config variable ftp_passive is set, all downloads will be run
2117 with the environment variable FTP_PASSIVE set to this value. This is
2118 in general a good idea as it influences both Net::FTP and LWP based
2119 connections. The same effect can be achieved by starting the cpan
2120 shell with this environment variable set. For Net::FTP alone, one can
2121 also always set passive mode by running libnetcfg.
2122 .SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
2123 .IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
2124 Populating a freshly installed perl with one\*(Aqs favorite modules is pretty
2125 easy if you maintain a private bundle definition file. To get a useful
2126 blueprint of a bundle definition file, the command autobundle can be used
2127 on the CPAN shell command line. This command writes a bundle definition
2128 file for all modules installed for the current perl
2129 interpreter. It\*(Aqs recommended to run this command once only, and from then
2130 on maintain the file manually under a private name, say
2131 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
2132 .PP
2133 .Vb 1
2134 \& cpan> install Bundle::my_bundle
2135 .Ve
2136 .PP
2137 then answer a few questions and go out for coffee (possibly
2138 even in a different city).
2139 .PP
2140 Maintaining a bundle definition file means keeping track of two
2141 things: dependencies and interactivity. CPAN.pm sometimes fails on
2142 calculating dependencies because not all modules define all MakeMaker
2143 attributes correctly, so a bundle definition file should specify
2144 prerequisites as early as possible. On the other hand, it\*(Aqs
2145 annoying that so many distributions need some interactive configuring. So
2146 what you can try to accomplish in your private bundle file is to have the
2147 packages that need to be configured early in the file and the gentle
2148 ones later, so you can go out for coffee after a few minutes and leave CPAN.pm
2149 to churn away unattended.
2150 .SH "WORKING WITH CPAN.pm BEHIND FIREWALLS"
2151 .IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS"
2152 Thanks to Graham Barr for contributing the following paragraphs about
2153 the interaction between perl, and various firewall configurations. For
2154 further information on firewalls, it is recommended to consult the
2155 documentation that comes with the \fIncftp\fR program. If you are unable to
2156 go through the firewall with a simple Perl setup, it is likely
2157 that you can configure \fIncftp\fR so that it works through your firewall.
2158 .SS "Three basic types of firewalls"
2159 .IX Subsection "Three basic types of firewalls"
2160 Firewalls can be categorized into three basic types.
2161 .IP "http firewall" 4
2162 .IX Item "http firewall"
2163 This is when the firewall machine runs a web server, and to access the
2164 outside world, you must do so via that web server. If you set environment
2165 variables like http_proxy or ftp_proxy to values beginning with http://,
2166 or in your web browser you\*(Aqve proxy information set, then you know
2167 you are running behind an http firewall.
2168 .Sp
2169 To access servers outside these types of firewalls with perl (even for
2170 ftp), you need LWP or HTTP::Tiny.
2171 .IP "ftp firewall" 4
2172 .IX Item "ftp firewall"
2173 This where the firewall machine runs an ftp server. This kind of
2174 firewall will only let you access ftp servers outside the firewall.
2175 This is usually done by connecting to the firewall with ftp, then
2176 entering a username like "[email protected]".
2177 .Sp
2178 To access servers outside these type of firewalls with perl, you
2179 need Net::FTP.
2180 .IP "One\-way visibility" 4
2181 .IX Item "One-way visibility"
2182 One\-way visibility means these firewalls try to make themselves
2183 invisible to users inside the firewall. An FTP data connection is
2184 normally created by sending your IP address to the remote server and then
2185 listening for the return connection. But the remote server will not be able to
2186 connect to you because of the firewall. For these types of firewall,
2187 FTP connections need to be done in a passive mode.
2188 .Sp
2189 There are two that I can think off.
2190 .RS 4
2191 .IP SOCKS 4
2192 .IX Item "SOCKS"
2193 If you are using a SOCKS firewall, you will need to compile perl and link
2194 it with the SOCKS library. This is what is normally called a \*(Aqsocksified\*(Aq
2195 perl. With this executable you will be able to connect to servers outside
2196 the firewall as if it were not there.
2197 .IP "IP Masquerade" 4
2198 .IX Item "IP Masquerade"
2199 This is when the firewall implemented in the kernel (via NAT, or networking
2200 address translation), it allows you to hide a complete network behind one
2201 IP address. With this firewall no special compiling is needed as you can
2202 access hosts directly.
2203 .Sp
2204 For accessing ftp servers behind such firewalls you usually need to
2205 set the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR or the config variable
2206 ftp_passive to a true value.
2207 .RE
2208 .RS 4
2209 .RE
2210 .SS "Configuring lynx or ncftp for going through a firewall"
2211 .IX Subsection "Configuring lynx or ncftp for going through a firewall"
2212 If you can go through your firewall with e.g. lynx, presumably with a
2213 command such as
2214 .PP
2215 .Vb 1
2216 \& /usr/local/bin/lynx \-pscott:tiger
2217 .Ve
2218 .PP
2219 then you would configure CPAN.pm with the command
2220 .PP
2221 .Vb 1
2222 \& o conf lynx "/usr/local/bin/lynx \-pscott:tiger"
2223 .Ve
2224 .PP
2225 That\*(Aqs all. Similarly for ncftp or ftp, you would configure something
2226 like
2227 .PP
2228 .Vb 1
2229 \& o conf ncftp "/usr/bin/ncftp \-f /home/scott/ncftplogin.cfg"
2230 .Ve
2231 .PP
2232 Your mileage may vary...
2233 .SH FAQ
2234 .IX Header "FAQ"
2235 .IP 1) 4
2236 .IX Item "1)"
2237 I installed a new version of module X but CPAN keeps saying,
2238 I have the old version installed
2239 .Sp
2240 Probably you \fBdo\fR have the old version installed. This can
2241 happen if a module installs itself into a different directory in the
2242 \&\f(CW@INC\fR path than it was previously installed. This is not really a
2243 CPAN.pm problem, you would have the same problem when installing the
2244 module manually. The easiest way to prevent this behaviour is to add
2245 the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why
2246 many people add this argument permanently by configuring
2247 .Sp
2248 .Vb 1
2249 \& o conf make_install_arg UNINST=1
2250 .Ve
2251 .IP 2) 4
2252 .IX Item "2)"
2253 So why is UNINST=1 not the default?
2254 .Sp
2255 Because there are people who have their precise expectations about who
2256 may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In
2257 fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage.
2258 .IP 3) 4
2259 .IX Item "3)"
2260 I want to clean up my mess, and install a new perl along with
2261 all modules I have. How do I go about it?
2262 .Sp
2263 Run the autobundle command for your old perl and optionally rename the
2264 resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
2265 with the Configure option prefix, e.g.
2266 .Sp
2267 .Vb 1
2268 \& ./Configure \-Dprefix=/usr/local/perl\-5.6.78.9
2269 .Ve
2270 .Sp
2271 Install the bundle file you produced in the first step with something like
2272 .Sp
2273 .Vb 1
2274 \& cpan> install Bundle::mybundle
2275 .Ve
2276 .Sp
2277 and you\*(Aqre done.
2278 .IP 4) 4
2279 .IX Item "4)"
2280 When I install bundles or multiple modules with one command
2281 there is too much output to keep track of.
2282 .Sp
2283 You may want to configure something like
2284 .Sp
2285 .Vb 2
2286 \& o conf make_arg "| tee \-ai /root/.cpan/logs/make.out"
2287 \& o conf make_install_arg "| tee \-ai /root/.cpan/logs/make_install.out"
2288 .Ve
2289 .Sp
2290 so that STDOUT is captured in a file for later inspection.
2291 .IP 5) 4
2292 .IX Item "5)"
2293 I am not root, how can I install a module in a personal directory?
2294 .Sp
2295 As of CPAN 1.9463, if you do not have permission to write the default perl
2296 library directories, CPAN\*(Aqs configuration process will ask you whether
2297 you want to bootstrap <local::lib>, which makes keeping a personal
2298 perl library directory easy.
2299 .Sp
2300 Another thing you should bear in mind is that the UNINST parameter can
2301 be dangerous when you are installing into a private area because you
2302 might accidentally remove modules that other people depend on that are
2303 not using the private area.
2304 .IP 6) 4
2305 .IX Item "6)"
2306 How to get a package, unwrap it, and make a change before building it?
2307 .Sp
2308 Have a look at the \f(CW\*(C`look\*(C'\fR (!) command.
2309 .IP 7) 4
2310 .IX Item "7)"
2311 I installed a Bundle and had a couple of fails. When I
2312 retried, everything resolved nicely. Can this be fixed to work
2313 on first try?
2314 .Sp
2315 The reason for this is that CPAN does not know the dependencies of all
2316 modules when it starts out. To decide about the additional items to
2317 install, it just uses data found in the META.yml file or the generated
2318 Makefile. An undetected missing piece breaks the process. But it may
2319 well be that your Bundle installs some prerequisite later than some
2320 depending item and thus your second try is able to resolve everything.
2321 Please note, CPAN.pm does not know the dependency tree in advance and
2322 cannot sort the queue of things to install in a topologically correct
2323 order. It resolves perfectly well \fBif\fR all modules declare the
2324 prerequisites correctly with the PREREQ_PM attribute to MakeMaker or
2325 the \f(CW\*(C`requires\*(C'\fR stanza of Module::Build. For bundles which fail and
2326 you need to install often, it is recommended to sort the Bundle
2327 definition file manually.
2328 .IP 8) 4
2329 .IX Item "8)"
2330 In our intranet, we have many modules for internal use. How
2331 can I integrate these modules with CPAN.pm but without uploading
2332 the modules to CPAN?
2333 .Sp
2334 Have a look at the CPAN::Site module.
2335 .IP 9) 4
2336 .IX Item "9)"
2337 When I run CPAN\*(Aqs shell, I get an error message about things in my
2338 \&\f(CW\*(C`/etc/inputrc\*(C'\fR (or \f(CW\*(C`~/.inputrc\*(C'\fR) file.
2339 .Sp
2340 These are readline issues and can only be fixed by studying readline
2341 configuration on your architecture and adjusting the referenced file
2342 accordingly. Please make a backup of the \f(CW\*(C`/etc/inputrc\*(C'\fR or \f(CW\*(C`~/.inputrc\*(C'\fR
2343 and edit them. Quite often harmless changes like uppercasing or
2344 lowercasing some arguments solves the problem.
2345 .IP 10) 4
2346 .IX Item "10)"
2347 Some authors have strange characters in their names.
2348 .Sp
2349 Internally CPAN.pm uses the UTF\-8 charset. If your terminal is
2350 expecting ISO\-8859\-1 charset, a converter can be activated by setting
2351 term_is_latin to a true value in your config file. One way of doing so
2352 would be
2353 .Sp
2354 .Vb 1
2355 \& cpan> o conf term_is_latin 1
2356 .Ve
2357 .Sp
2358 If other charset support is needed, please file a bug report against
2359 CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend
2360 the support or maybe UTF\-8 terminals become widely available.
2361 .Sp
2362 Note: this config variable is deprecated and will be removed in a
2363 future version of CPAN.pm. It will be replaced with the conventions
2364 around the family of \f(CW$LANG\fR and \f(CW$LC_\fR* environment variables.
2365 .IP 11) 4
2366 .IX Item "11)"
2367 When an install fails for some reason and then I correct the error
2368 condition and retry, CPAN.pm refuses to install the module, saying
2369 \&\f(CW\*(C`Already tried without success\*(C'\fR.
2370 .Sp
2371 You could use the force pragma like so
2372 .Sp
2373 .Vb 1
2374 \& force install Foo::Bar
2375 .Ve
2376 .Sp
2377 Or, to avoid a force install (which would install even if the tests
2378 fail), you can force only the test and then install:
2379 .Sp
2380 .Vb 2
2381 \& force test Foo::Bar
2382 \& install Foo::Bar
2383 .Ve
2384 .Sp
2385 Or you can use
2386 .Sp
2387 .Vb 1
2388 \& look Foo::Bar
2389 .Ve
2390 .Sp
2391 and then \f(CW\*(C`make install\*(C'\fR directly in the subshell.
2392 .IP 12) 4
2393 .IX Item "12)"
2394 How do I install a "DEVELOPER RELEASE" of a module?
2395 .Sp
2396 By default, CPAN will install the latest non\-developer release of a
2397 module. If you want to install a dev release, you have to specify the
2398 partial path starting with the author id to the tarball you wish to
2399 install, like so:
2400 .Sp
2401 .Vb 1
2402 \& cpan> install KWILLIAMS/Module\-Build\-0.27_07.tar.gz
2403 .Ve
2404 .Sp
2405 Note that you can use the \f(CW\*(C`ls\*(C'\fR command to get this path listed.
2406 .IP 13) 4
2407 .IX Item "13)"
2408 How do I install a module and all its dependencies from the commandline,
2409 without being prompted for anything, despite my CPAN configuration
2410 (or lack thereof)?
2411 .Sp
2412 CPAN uses ExtUtils::MakeMaker\*(Aqs \fBprompt()\fR function to ask its questions, so
2413 if you set the PERL_MM_USE_DEFAULT environment variable, you shouldn\*(Aqt be
2414 asked any questions at all (assuming the modules you are installing are
2415 nice about obeying that variable as well):
2416 .Sp
2417 .Vb 1
2418 \& % PERL_MM_USE_DEFAULT=1 perl \-MCPAN \-e \*(Aqinstall My::Module\*(Aq
2419 .Ve
2420 .IP 14) 4
2421 .IX Item "14)"
2422 How do I create a Module::Build based Build.PL derived from an
2423 ExtUtils::MakeMaker focused Makefile.PL?
2424 .Sp
2425 http://search.cpan.org/dist/Module\-Build\-Convert/
2426 .IP 15) 4
2427 .IX Item "15)"
2428 I\*(Aqm frequently irritated with the CPAN shell\*(Aqs inability to help me
2429 select a good mirror.
2430 .Sp
2431 CPAN can now help you select a "good" mirror, based on which ones have the
2432 lowest \*(Aqping\*(Aq round\-trip times. From the shell, use the command \*(Aqo conf init
2433 urllist\*(Aq and allow CPAN to automatically select mirrors for you.
2434 .Sp
2435 Beyond that help, the urllist config parameter is yours. You can add and remove
2436 sites at will. You should find out which sites have the best up\-to\-dateness,
2437 bandwidth, reliability, etc. and are topologically close to you. Some people
2438 prefer fast downloads, others up\-to\-dateness, others reliability. You decide
2439 which to try in which order.
2440 .Sp
2441 Henk P. Penning maintains a site that collects data about CPAN sites:
2442 .Sp
2443 .Vb 1
2444 \& http://mirrors.cpan.org/
2445 .Ve
2446 .Sp
2447 Also, feel free to play with experimental features. Run
2448 .Sp
2449 .Vb 1
2450 \& o conf init randomize_urllist ftpstats_period ftpstats_size
2451 .Ve
2452 .Sp
2453 and choose your favorite parameters. After a few downloads running the
2454 \&\f(CW\*(C`hosts\*(C'\fR command will probably assist you in choosing the best mirror
2455 sites.
2456 .IP 16) 4
2457 .IX Item "16)"
2458 Why do I get asked the same questions every time I start the shell?
2459 .Sp
2460 You can make your configuration changes permanent by calling the
2461 command \f(CW\*(C`o conf commit\*(C'\fR. Alternatively set the \f(CW\*(C`auto_commit\*(C'\fR
2462 variable to true by running \f(CW\*(C`o conf init auto_commit\*(C'\fR and answering
2463 the following question with yes.
2464 .IP 17) 4
2465 .IX Item "17)"
2466 Older versions of CPAN.pm had the original root directory of all
2467 tarballs in the build directory. Now there are always random
2468 characters appended to these directory names. Why was this done?
2469 .Sp
2470 The random characters are provided by File::Temp and ensure that each
2471 module\*(Aqs individual build directory is unique. This makes running
2472 CPAN.pm in concurrent processes simultaneously safe.
2473 .IP 18) 4
2474 .IX Item "18)"
2475 Speaking of the build directory. Do I have to clean it up myself?
2476 .Sp
2477 You have the choice to set the config variable \f(CW\*(C`scan_cache\*(C'\fR to
2478 \&\f(CW\*(C`never\*(C'\fR. Then you must clean it up yourself. The other possible
2479 values, \f(CW\*(C`atstart\*(C'\fR and \f(CW\*(C`atexit\*(C'\fR clean up the build directory when you
2480 start (or more precisely, after the first extraction into the build
2481 directory) or exit the CPAN shell, respectively. If you never start up
2482 the CPAN shell, you probably also have to clean up the build directory
2483 yourself.
2484 .IP 19) 4
2485 .IX Item "19)"
2486 How can I switch to sudo instead of local::lib?
2487 .Sp
2488 The following 5 environment veriables need to be reset to the previous
2489 values: PATH, PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MB_OPT, PERL_MM_OPT;
2490 and these two CPAN.pm config variables must be reconfigured:
2491 make_install_make_command and mbuild_install_build_command. The five
2492 env variables have probably been overwritten in your \f(CW$HOME\fR/.bashrc or
2493 some equivalent. You either find them there and delete their traces
2494 and logout/login or you override them temporarily, depending on your
2495 exact desire. The two cpanpm config variables can be set with:
2496 .Sp
2497 .Vb 1
2498 \& o conf init /install_.*_command/
2499 .Ve
2500 .Sp
2501 probably followed by
2502 .Sp
2503 .Vb 1
2504 \& o conf commit
2505 .Ve
2506 .IP 20) 4
2507 .IX Item "20)"
2508 How do recommends_policy and suggests_policy work, exactly?
2509 .Sp
2510 The terms \f(CW\*(C`recommends\*(C'\fR and \f(CW\*(C`suggests\*(C'\fR have been standardized in
2511 https://metacpan.org/pod/CPAN::Meta::Spec
2512 .Sp
2513 In CPAN.pm, if you set \f(CW\*(C`recommands_policy\*(C'\fR to a true value, that
2514 means: if you then install a distribution \f(CW\*(C`Foo\*(C'\fR that \fIrecommends\fR a
2515 module \f(CW\*(C`Bar\*(C'\fR, both \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR will be tested and potentially
2516 installed.
2517 .Sp
2518 Similarly, if you set \f(CW\*(C`suggests_policy\*(C'\fR to a true value, it means: if
2519 you install a distribution \f(CW\*(C`Foo\*(C'\fR that \fIsuggests\fR a module \f(CW\*(C`Bar\*(C'\fR,
2520 both \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR will be tested and potentially installed.
2521 .Sp
2522 In either case, when \f(CW\*(C`Foo\*(C'\fR passes its tests and \f(CW\*(C`Bar\*(C'\fR does not pass
2523 its tests, \f(CW\*(C`Foo\*(C'\fR will be installed nontheless. But if \f(CW\*(C`Foo\*(C'\fR does not
2524 pass its tests, neither will be installed.
2525 .Sp
2526 This also works recursively for all recommends and suggests of the
2527 module \f(CW\*(C`Bar\*(C'\fR.
2528 .Sp
2529 This has also been illustrated by a cpan tester, who wrote:
2530 .Sp
2531 I just tested Starlink\-AST\-3.03 which recommends Tk::Zinc;
2532 Tk\-Zinc\-3.306 fails with
2533 http://www.cpantesters.org/cpan/report/a2de7c38\-810d\-11ee\-9ad4\-e2167316189a
2534 ; nonetheless Starlink\-AST\-3.03 succeeds with
2535 http://www.cpantesters.org/cpan/report/9352e754\-810d\-11ee\-90e9\-46117316189a
2536 .SH COMPATIBILITY
2537 .IX Header "COMPATIBILITY"
2538 .SS "OLD PERL VERSIONS"
2539 .IX Subsection "OLD PERL VERSIONS"
2540 CPAN.pm is regularly tested to run under 5.005 and assorted
2541 newer versions. It is getting more and more difficult to get the
2542 minimal prerequisites working on older perls. It is close to
2543 impossible to get the whole Bundle::CPAN working there. If you\*(Aqre in
2544 the position to have only these old versions, be advised that CPAN is
2545 designed to work fine without the Bundle::CPAN installed.
2546 .PP
2547 To get things going, note that GBARR/Scalar\-List\-Utils\-1.18.tar.gz is
2548 compatible with ancient perls and that File::Temp is listed as a
2549 prerequisite but CPAN has reasonable workarounds if it is missing.
2550 .SS CPANPLUS
2551 .IX Subsection "CPANPLUS"
2552 This module and its competitor, the CPANPLUS module, are both much
2553 cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
2554 more modular, but it was never intended to be compatible with CPAN.pm.
2555 .SS CPANMINUS
2556 .IX Subsection "CPANMINUS"
2557 In the year 2010 App::cpanminus was launched as a new approach to a
2558 cpan shell with a considerably smaller footprint. Very cool stuff.
2559 .SH "SECURITY ADVICE"
2560 .IX Header "SECURITY ADVICE"
2561 This software enables you to upgrade software on your computer and so
2562 is inherently dangerous because the newly installed software may
2563 contain bugs and may alter the way your computer works or even make it
2564 unusable. Please consider backing up your data before every upgrade.
2565 .SH BUGS
2566 .IX Header "BUGS"
2567 Please report bugs via <http://rt.cpan.org/>
2568 .PP
2569 Before submitting a bug, please make sure that the traditional method
2570 of building a Perl module package from a shell by following the
2571 installation instructions of that package still works in your
2572 environment.
2573 .SH AUTHOR
2574 .IX Header "AUTHOR"
2575 Andreas Koenig \f(CW\*(C`<[email protected]>\*(C'\fR
2576 .SH LICENSE
2577 .IX Header "LICENSE"
2578 This program is free software; you can redistribute it and/or
2579 modify it under the same terms as Perl itself.
2580 .PP
2581 See <http://www.perl.com/perl/misc/Artistic.html>
2582 .SH TRANSLATIONS
2583 .IX Header "TRANSLATIONS"
2584 Kawai,Takanori provides a Japanese translation of a very old version
2585 of this manpage at
2586 <http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
2587 .SH "SEE ALSO"
2588 .IX Header "SEE ALSO"
2589 Many people enter the CPAN shell by running the cpan utility
2590 program which is installed in the same directory as perl itself. So if
2591 you have this directory in your PATH variable (or some equivalent in
2592 your operating system) then typing \f(CW\*(C`cpan\*(C'\fR in a console window will
2593 work for you as well. Above that the utility provides several
2594 commandline shortcuts.
2595 .PP
2596 melezhik (Alexey) sent me a link where he published a chef recipe to
2597 work with CPAN.pm: http://community.opscode.com/cookbooks/cpan.