| 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. |