Debian Codegraph @

upstream/debian-unstable/man3/CPAN.3perl

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