| 1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
| 6 | .br |
| 7 | .if t .Sp |
| 8 | .ne 5 |
| 9 | .PP |
| 10 | \fB\\$1\fR |
| 11 | .PP |
| 12 | .. |
| 13 | .de Sp \" Vertical space (when we can't use .PP) |
| 14 | .if t .sp .5v |
| 15 | .if n .sp |
| 16 | .. |
| 17 | .de Vb \" Begin verbatim text |
| 18 | .ft CW |
| 19 | .nf |
| 20 | .ne \\$1 |
| 21 | .. |
| 22 | .de Ve \" End verbatim text |
| 23 | .ft R |
| 24 | .fi |
| 25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
| 29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| 30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| 31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| 32 | .tr \(*W-|\(bv\*(Tr |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
| 36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 39 | . ds L" "" |
| 40 | . ds R" "" |
| 41 | . ds C` "" |
| 42 | . ds C' "" |
| 43 | 'br\} |
| 44 | .el\{\ |
| 45 | . ds -- \|\(em\| |
| 46 | . ds PI \(*p |
| 47 | . ds L" `` |
| 48 | . ds R" '' |
| 49 | 'br\} |
| 50 | .\" |
| 51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| 53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 54 | .\" output yourself in some meaningful fashion. |
| 55 | .if \nF \{\ |
| 56 | . de IX |
| 57 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 58 | .. |
| 59 | . nr % 0 |
| 60 | . rr F |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 64 | .\" way too many mistakes in technical documents. |
| 65 | .hy 0 |
| 66 | .if n .na |
| 67 | .\" |
| 68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 70 | . \" fudge factors for nroff and troff |
| 71 | .if n \{\ |
| 72 | . ds #H 0 |
| 73 | . ds #V .8m |
| 74 | . ds #F .3m |
| 75 | . ds #[ \f1 |
| 76 | . ds #] \fP |
| 77 | .\} |
| 78 | .if t \{\ |
| 79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 80 | . ds #V .6m |
| 81 | . ds #F 0 |
| 82 | . ds #[ \& |
| 83 | . ds #] \& |
| 84 | .\} |
| 85 | . \" simple accents for nroff and troff |
| 86 | .if n \{\ |
| 87 | . ds ' \& |
| 88 | . ds ` \& |
| 89 | . ds ^ \& |
| 90 | . ds , \& |
| 91 | . ds ~ ~ |
| 92 | . ds / |
| 93 | .\} |
| 94 | .if t \{\ |
| 95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 101 | .\} |
| 102 | . \" troff and (daisy-wheel) nroff accents |
| 103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 110 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 112 | . \" corrections for vroff |
| 113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 115 | . \" for low resolution devices (crt and lpr) |
| 116 | .if \n(.H>23 .if \n(.V>19 \ |
| 117 | \{\ |
| 118 | . ds : e |
| 119 | . ds 8 ss |
| 120 | . ds o a |
| 121 | . ds d- d\h'-1'\(ga |
| 122 | . ds D- D\h'-1'\(hy |
| 123 | . ds th \o'bp' |
| 124 | . ds Th \o'LP' |
| 125 | . ds ae ae |
| 126 | . ds Ae AE |
| 127 | .\} |
| 128 | .rm #[ #] #H #V #F C |
| 129 | .\" ======================================================================== |
| 130 | .\" |
| 131 | .IX Title "CPAN 3" |
| 132 | .TH CPAN 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" |
| 133 | .SH "NAME" |
| 134 | CPAN \- query, download and build perl modules from CPAN sites |
| 135 | .SH "SYNOPSIS" |
| 136 | .IX Header "SYNOPSIS" |
| 137 | Interactive mode: |
| 138 | .PP |
| 139 | .Vb 1 |
| 140 | \& perl -MCPAN -e shell; |
| 141 | .Ve |
| 142 | .PP |
| 143 | Batch mode: |
| 144 | .PP |
| 145 | .Vb 1 |
| 146 | \& use CPAN; |
| 147 | .Ve |
| 148 | .PP |
| 149 | .Vb 1 |
| 150 | \& autobundle, clean, install, make, recompile, test |
| 151 | .Ve |
| 152 | .SH "STATUS" |
| 153 | .IX Header "STATUS" |
| 154 | This module will eventually be replaced by \s-1CPANPLUS\s0. \s-1CPANPLUS\s0 is kind |
| 155 | of a modern rewrite from ground up with greater extensibility and more |
| 156 | features but no full compatibility. If you're new to \s-1CPAN\s0.pm, you |
| 157 | probably should investigate if \s-1CPANPLUS\s0 is the better choice for you. |
| 158 | If you're already used to \s-1CPAN\s0.pm you're welcome to continue using it, |
| 159 | if you accept that its development is mostly (though not completely) |
| 160 | stalled. |
| 161 | .SH "DESCRIPTION" |
| 162 | .IX Header "DESCRIPTION" |
| 163 | The \s-1CPAN\s0 module is designed to automate the make and install of perl |
| 164 | modules and extensions. It includes some primitive searching capabilities and |
| 165 | knows how to use Net::FTP or \s-1LWP\s0 (or lynx or an external ftp client) |
| 166 | to fetch the raw data from the net. |
| 167 | .PP |
| 168 | Modules are fetched from one or more of the mirrored \s-1CPAN\s0 |
| 169 | (Comprehensive Perl Archive Network) sites and unpacked in a dedicated |
| 170 | directory. |
| 171 | .PP |
| 172 | The \s-1CPAN\s0 module also supports the concept of named and versioned |
| 173 | \&\fIbundles\fR of modules. Bundles simplify the handling of sets of |
| 174 | related modules. See Bundles below. |
| 175 | .PP |
| 176 | The package contains a session manager and a cache manager. There is |
| 177 | no status retained between sessions. The session manager keeps track |
| 178 | of what has been fetched, built and installed in the current |
| 179 | session. The cache manager keeps track of the disk space occupied by |
| 180 | the make processes and deletes excess space according to a simple \s-1FIFO\s0 |
| 181 | mechanism. |
| 182 | .PP |
| 183 | For extended searching capabilities there's a plugin for \s-1CPAN\s0 available, |
| 184 | \&\f(CW\*(C`CPAN::WAIT\*(C'\fR. \f(CW\*(C`CPAN::WAIT\*(C'\fR is a full-text search engine |
| 185 | that indexes all documents available in \s-1CPAN\s0 authors directories. If |
| 186 | \&\f(CW\*(C`CPAN::WAIT\*(C'\fR is installed on your system, the interactive shell of |
| 187 | \&\s-1CPAN\s0.pm will enable the \f(CW\*(C`wq\*(C'\fR, \f(CW\*(C`wr\*(C'\fR, \f(CW\*(C`wd\*(C'\fR, \f(CW\*(C`wl\*(C'\fR, and \f(CW\*(C`wh\*(C'\fR commands |
| 188 | which send queries to the \s-1WAIT\s0 server that has been configured for your |
| 189 | installation. |
| 190 | .PP |
| 191 | All other methods provided are accessible in a programmer style and in an |
| 192 | interactive shell style. |
| 193 | .Sh "Interactive Mode" |
| 194 | .IX Subsection "Interactive Mode" |
| 195 | The interactive mode is entered by running |
| 196 | .PP |
| 197 | .Vb 1 |
| 198 | \& perl -MCPAN -e shell |
| 199 | .Ve |
| 200 | .PP |
| 201 | which puts you into a readline interface. You will have the most fun if |
| 202 | you install Term::ReadKey and Term::ReadLine to enjoy both history and |
| 203 | command completion. |
| 204 | .PP |
| 205 | Once you are on the command line, type 'h' and the rest should be |
| 206 | self\-explanatory. |
| 207 | .PP |
| 208 | The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments, one is the |
| 209 | prompt, the second is the default initial command line (the latter |
| 210 | only works if a real ReadLine interface module is installed). |
| 211 | .PP |
| 212 | The most common uses of the interactive modes are |
| 213 | .IP "Searching for authors, bundles, distribution files and modules" 2 |
| 214 | .IX Item "Searching for authors, bundles, distribution files and modules" |
| 215 | 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 |
| 216 | for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the |
| 217 | mentioned four. Each of the four entities is implemented as a class |
| 218 | with slightly differing methods for displaying an object. |
| 219 | .Sp |
| 220 | Arguments you pass to these commands are either strings exactly matching |
| 221 | the identification string of an object or regular expressions that are |
| 222 | then matched case-insensitively against various attributes of the |
| 223 | objects. The parser recognizes a regular expression only if you |
| 224 | enclose it between two slashes. |
| 225 | .Sp |
| 226 | The principle is that the number of found objects influences how an |
| 227 | item is displayed. If the search finds one item, the result is |
| 228 | displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if we find |
| 229 | more than one, we display each object with the terse method |
| 230 | <as_glimpse>. |
| 231 | .IP "make, test, install, clean modules or distributions" 2 |
| 232 | .IX Item "make, test, install, clean modules or distributions" |
| 233 | These commands take any number of arguments and investigate what is |
| 234 | necessary to perform the action. If the argument is a distribution |
| 235 | file name (recognized by embedded slashes), it is processed. If it is |
| 236 | a module, \s-1CPAN\s0 determines the distribution file in which this module |
| 237 | is included and processes that, following any dependencies named in |
| 238 | the module's Makefile.PL (this behavior is controlled by |
| 239 | \&\fIprerequisites_policy\fR.) |
| 240 | .Sp |
| 241 | Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR are run unconditionally. An |
| 242 | .Sp |
| 243 | .Vb 1 |
| 244 | \& install <distribution_file> |
| 245 | .Ve |
| 246 | .Sp |
| 247 | also is run unconditionally. But for |
| 248 | .Sp |
| 249 | .Vb 1 |
| 250 | \& install <module> |
| 251 | .Ve |
| 252 | .Sp |
| 253 | \&\s-1CPAN\s0 checks if an install is actually needed for it and prints |
| 254 | \&\fImodule up to date\fR in the case that the distribution file containing |
| 255 | the module doesn't need to be updated. |
| 256 | .Sp |
| 257 | \&\s-1CPAN\s0 also keeps track of what it has done within the current session |
| 258 | and doesn't try to build a package a second time regardless if it |
| 259 | succeeded or not. The \f(CW\*(C`force\*(C'\fR command takes as a first argument the |
| 260 | method to invoke (currently: \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, or \f(CW\*(C`install\*(C'\fR) and executes the |
| 261 | command from scratch. |
| 262 | .Sp |
| 263 | Example: |
| 264 | .Sp |
| 265 | .Vb 7 |
| 266 | \& cpan> install OpenGL |
| 267 | \& OpenGL is up to date. |
| 268 | \& cpan> force install OpenGL |
| 269 | \& Running make |
| 270 | \& OpenGL-0.4/ |
| 271 | \& OpenGL-0.4/COPYRIGHT |
| 272 | \& [...] |
| 273 | .Ve |
| 274 | .Sp |
| 275 | A \f(CW\*(C`clean\*(C'\fR command results in a |
| 276 | .Sp |
| 277 | .Vb 1 |
| 278 | \& make clean |
| 279 | .Ve |
| 280 | .Sp |
| 281 | being executed within the distribution file's working directory. |
| 282 | .IP "get, readme, look module or distribution" 2 |
| 283 | .IX Item "get, readme, look module or distribution" |
| 284 | \&\f(CW\*(C`get\*(C'\fR downloads a distribution file without further action. \f(CW\*(C`readme\*(C'\fR |
| 285 | displays the \s-1README\s0 file of the associated distribution. \f(CW\*(C`Look\*(C'\fR gets |
| 286 | and untars (if not yet done) the distribution file, changes to the |
| 287 | appropriate directory and opens a subshell process in that directory. |
| 288 | .IP "ls author" 2 |
| 289 | .IX Item "ls author" |
| 290 | \&\f(CW\*(C`ls\*(C'\fR lists all distribution files in and below an author's \s-1CPAN\s0 |
| 291 | directory. Only those files that contain modules are listed and if |
| 292 | there is more than one for any given module, only the most recent one |
| 293 | is listed. |
| 294 | .IP "Signals" 2 |
| 295 | .IX Item "Signals" |
| 296 | \&\s-1CPAN\s0.pm installs signal handlers for \s-1SIGINT\s0 and \s-1SIGTERM\s0. While you are |
| 297 | in the cpan-shell it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and |
| 298 | return to the cpan-shell prompt. A \s-1SIGTERM\s0 will cause the cpan-shell |
| 299 | to clean up and leave the shell loop. You can emulate the effect of a |
| 300 | \&\s-1SIGTERM\s0 by sending two consecutive SIGINTs, which usually means by |
| 301 | pressing \f(CW\*(C`^C\*(C'\fR twice. |
| 302 | .Sp |
| 303 | \&\s-1CPAN\s0.pm ignores a \s-1SIGPIPE\s0. If the user sets inactivity_timeout, a |
| 304 | \&\s-1SIGALRM\s0 is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR subprocess. |
| 305 | .Sh "CPAN::Shell" |
| 306 | .IX Subsection "CPAN::Shell" |
| 307 | The commands that are available in the shell interface are methods in |
| 308 | the package CPAN::Shell. If you enter the shell command, all your |
| 309 | input is split by the \fIText::ParseWords::shellwords()\fR routine which |
| 310 | acts like most shells do. The first word is being interpreted as the |
| 311 | method to be called and the rest of the words are treated as arguments |
| 312 | to this method. Continuation lines are supported if a line ends with a |
| 313 | literal backslash. |
| 314 | .Sh "autobundle" |
| 315 | .IX Subsection "autobundle" |
| 316 | \&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the |
| 317 | \&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains |
| 318 | a list of all modules that are both available from \s-1CPAN\s0 and currently |
| 319 | installed within \f(CW@INC\fR. The name of the bundle file is based on the |
| 320 | current date and a counter. |
| 321 | .Sh "recompile" |
| 322 | .IX Subsection "recompile" |
| 323 | \&\fIrecompile()\fR is a very special command in that it takes no argument and |
| 324 | runs the make/test/install cycle with brute force over all installed |
| 325 | dynamically loadable extensions (aka \s-1XS\s0 modules) with 'force' in |
| 326 | effect. The primary purpose of this command is to finish a network |
| 327 | installation. Imagine, you have a common source tree for two different |
| 328 | architectures. You decide to do a completely independent fresh |
| 329 | installation. You start on one architecture with the help of a Bundle |
| 330 | file produced earlier. \s-1CPAN\s0 installs the whole Bundle for you, but |
| 331 | when you try to repeat the job on the second architecture, \s-1CPAN\s0 |
| 332 | responds with a \f(CW"Foo up to date"\fR message for all modules. So you |
| 333 | invoke \s-1CPAN\s0's recompile on the second architecture and you're done. |
| 334 | .PP |
| 335 | Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your |
| 336 | perl breaks binary compatibility. If one of the modules that \s-1CPAN\s0 uses |
| 337 | is in turn depending on binary compatibility (so you cannot run \s-1CPAN\s0 |
| 338 | commands), then you should try the CPAN::Nox module for recovery. |
| 339 | .ie n .Sh "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution" |
| 340 | .el .Sh "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution" |
| 341 | .IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution" |
| 342 | Although it may be considered internal, the class hierarchy does matter |
| 343 | for both users and programmer. \s-1CPAN\s0.pm deals with above mentioned four |
| 344 | classes, and all those classes share a set of methods. A classical |
| 345 | single polymorphism is in effect. A metaclass object registers all |
| 346 | objects of all kinds and indexes them with a string. The strings |
| 347 | referencing objects have a separated namespace (well, not completely |
| 348 | separated): |
| 349 | .PP |
| 350 | .Vb 1 |
| 351 | \& Namespace Class |
| 352 | .Ve |
| 353 | .PP |
| 354 | .Vb 3 |
| 355 | \& words containing a "/" (slash) Distribution |
| 356 | \& words starting with Bundle:: Bundle |
| 357 | \& everything else Module or Author |
| 358 | .Ve |
| 359 | .PP |
| 360 | Modules know their associated Distribution objects. They always refer |
| 361 | to the most recent official release. Developers may mark their releases |
| 362 | as unstable development versions (by inserting an underbar into the |
| 363 | module version number which will also be reflected in the distribution |
| 364 | name when you run 'make dist'), so the really hottest and newest |
| 365 | distribution is not always the default. If a module Foo circulates |
| 366 | on \s-1CPAN\s0 in both version 1.23 and 1.23_90, \s-1CPAN\s0.pm offers a convenient |
| 367 | way to install version 1.23 by saying |
| 368 | .PP |
| 369 | .Vb 1 |
| 370 | \& install Foo |
| 371 | .Ve |
| 372 | .PP |
| 373 | This would install the complete distribution file (say |
| 374 | BAR/Foo\-1.23.tar.gz) with all accompanying material. But if you would |
| 375 | like to install version 1.23_90, you need to know where the |
| 376 | distribution file resides on \s-1CPAN\s0 relative to the authors/id/ |
| 377 | directory. If the author is \s-1BAR\s0, this might be BAR/Foo\-1.23_90.tar.gz; |
| 378 | so you would have to say |
| 379 | .PP |
| 380 | .Vb 1 |
| 381 | \& install BAR/Foo-1.23_90.tar.gz |
| 382 | .Ve |
| 383 | .PP |
| 384 | The first example will be driven by an object of the class |
| 385 | CPAN::Module, the second by an object of class CPAN::Distribution. |
| 386 | .Sh "Programmer's interface" |
| 387 | .IX Subsection "Programmer's interface" |
| 388 | If you do not enter the shell, the available shell commands are both |
| 389 | available as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as |
| 390 | functions in the calling package (\f(CW\*(C`install(...)\*(C'\fR). |
| 391 | .PP |
| 392 | There's currently only one class that has a stable interface \- |
| 393 | CPAN::Shell. All commands that are available in the \s-1CPAN\s0 shell are |
| 394 | methods of the class CPAN::Shell. Each of the commands that produce |
| 395 | listings of modules (\f(CW\*(C`r\*(C'\fR, \f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of |
| 396 | the IDs of all modules within the list. |
| 397 | .IP "expand($type,@things)" 2 |
| 398 | .IX Item "expand($type,@things)" |
| 399 | The IDs of all objects available within a program are strings that can |
| 400 | be expanded to the corresponding real objects with the |
| 401 | \&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a |
| 402 | list of CPAN::Module objects according to the \f(CW@things\fR arguments |
| 403 | given. In scalar context it only returns the first element of the |
| 404 | list. |
| 405 | .IP "expandany(@things)" 2 |
| 406 | .IX Item "expandany(@things)" |
| 407 | Like expand, but returns objects of the appropriate type, i.e. |
| 408 | CPAN::Bundle objects for bundles, CPAN::Module objects for modules and |
| 409 | CPAN::Distribution objects fro distributions. |
| 410 | .IP "Programming Examples" 2 |
| 411 | .IX Item "Programming Examples" |
| 412 | This enables the programmer to do operations that combine |
| 413 | functionalities that are available in the shell. |
| 414 | .Sp |
| 415 | .Vb 2 |
| 416 | \& # install everything that is outdated on my disk: |
| 417 | \& perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)' |
| 418 | .Ve |
| 419 | .Sp |
| 420 | .Vb 5 |
| 421 | \& # install my favorite programs if necessary: |
| 422 | \& for $mod (qw(Net::FTP Digest::MD5 Data::Dumper)){ |
| 423 | \& my $obj = CPAN::Shell->expand('Module',$mod); |
| 424 | \& $obj->install; |
| 425 | \& } |
| 426 | .Ve |
| 427 | .Sp |
| 428 | .Vb 7 |
| 429 | \& # list all modules on my disk that have no VERSION number |
| 430 | \& for $mod (CPAN::Shell->expand("Module","/./")){ |
| 431 | \& next unless $mod->inst_file; |
| 432 | \& # MakeMaker convention for undefined $VERSION: |
| 433 | \& next unless $mod->inst_version eq "undef"; |
| 434 | \& print "No VERSION in ", $mod->id, "\en"; |
| 435 | \& } |
| 436 | .Ve |
| 437 | .Sp |
| 438 | .Vb 2 |
| 439 | \& # find out which distribution on CPAN contains a module: |
| 440 | \& print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file |
| 441 | .Ve |
| 442 | .Sp |
| 443 | Or if you want to write a cronjob to watch The \s-1CPAN\s0, you could list |
| 444 | all modules that need updating. First a quick and dirty way: |
| 445 | .Sp |
| 446 | .Vb 1 |
| 447 | \& perl -e 'use CPAN; CPAN::Shell->r;' |
| 448 | .Ve |
| 449 | .Sp |
| 450 | If you don't want to get any output in the case that all modules are |
| 451 | up to date, you can parse the output of above command for the regular |
| 452 | expression //modules are up to date// and decide to mail the output |
| 453 | only if it doesn't match. Ick? |
| 454 | .Sp |
| 455 | If you prefer to do it more in a programmer style in one single |
| 456 | process, maybe something like this suits you better: |
| 457 | .Sp |
| 458 | .Vb 7 |
| 459 | \& # list all modules on my disk that have newer versions on CPAN |
| 460 | \& for $mod (CPAN::Shell->expand("Module","/./")){ |
| 461 | \& next unless $mod->inst_file; |
| 462 | \& next if $mod->uptodate; |
| 463 | \& printf "Module %s is installed as %s, could be updated to %s from CPAN\en", |
| 464 | \& $mod->id, $mod->inst_version, $mod->cpan_version; |
| 465 | \& } |
| 466 | .Ve |
| 467 | .Sp |
| 468 | If that gives you too much output every day, you maybe only want to |
| 469 | watch for three modules. You can write |
| 470 | .Sp |
| 471 | .Vb 1 |
| 472 | \& for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")){ |
| 473 | .Ve |
| 474 | .Sp |
| 475 | as the first line instead. Or you can combine some of the above |
| 476 | tricks: |
| 477 | .Sp |
| 478 | .Vb 5 |
| 479 | \& # watch only for a new mod_perl module |
| 480 | \& $mod = CPAN::Shell->expand("Module","mod_perl"); |
| 481 | \& exit if $mod->uptodate; |
| 482 | \& # new mod_perl arrived, let me know all update recommendations |
| 483 | \& CPAN::Shell->r; |
| 484 | .Ve |
| 485 | .Sh "Methods in the other Classes" |
| 486 | .IX Subsection "Methods in the other Classes" |
| 487 | The programming interface for the classes CPAN::Module, |
| 488 | CPAN::Distribution, CPAN::Bundle, and CPAN::Author is still considered |
| 489 | beta and partially even alpha. In the following paragraphs only those |
| 490 | methods are documented that have proven useful over a longer time and |
| 491 | thus are unlikely to change. |
| 492 | .IP "\fICPAN::Author::as_glimpse()\fR" 4 |
| 493 | .IX Item "CPAN::Author::as_glimpse()" |
| 494 | Returns a one-line description of the author |
| 495 | .IP "\fICPAN::Author::as_string()\fR" 4 |
| 496 | .IX Item "CPAN::Author::as_string()" |
| 497 | Returns a multi-line description of the author |
| 498 | .IP "\fICPAN::Author::email()\fR" 4 |
| 499 | .IX Item "CPAN::Author::email()" |
| 500 | Returns the author's email address |
| 501 | .IP "\fICPAN::Author::fullname()\fR" 4 |
| 502 | .IX Item "CPAN::Author::fullname()" |
| 503 | Returns the author's name |
| 504 | .IP "\fICPAN::Author::name()\fR" 4 |
| 505 | .IX Item "CPAN::Author::name()" |
| 506 | An alias for fullname |
| 507 | .IP "\fICPAN::Bundle::as_glimpse()\fR" 4 |
| 508 | .IX Item "CPAN::Bundle::as_glimpse()" |
| 509 | Returns a one-line description of the bundle |
| 510 | .IP "\fICPAN::Bundle::as_string()\fR" 4 |
| 511 | .IX Item "CPAN::Bundle::as_string()" |
| 512 | Returns a multi-line description of the bundle |
| 513 | .IP "\fICPAN::Bundle::clean()\fR" 4 |
| 514 | .IX Item "CPAN::Bundle::clean()" |
| 515 | Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle. |
| 516 | .IP "\fICPAN::Bundle::contains()\fR" 4 |
| 517 | .IX Item "CPAN::Bundle::contains()" |
| 518 | Returns a list of objects' IDs contained in a bundle. The associated |
| 519 | objects may be bundles, modules or distributions. |
| 520 | .IP "CPAN::Bundle::force($method,@args)" 4 |
| 521 | .IX Item "CPAN::Bundle::force($method,@args)" |
| 522 | Forces \s-1CPAN\s0 to perform a task that normally would have failed. Force |
| 523 | takes as arguments a method name to be called and any number of |
| 524 | additional arguments that should be passed to the called method. The |
| 525 | internals of the object get the needed changes so that \s-1CPAN\s0.pm does |
| 526 | not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively to |
| 527 | all contained objects. |
| 528 | .IP "\fICPAN::Bundle::get()\fR" 4 |
| 529 | .IX Item "CPAN::Bundle::get()" |
| 530 | Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle |
| 531 | .IP "\fICPAN::Bundle::inst_file()\fR" 4 |
| 532 | .IX Item "CPAN::Bundle::inst_file()" |
| 533 | Returns the highest installed version of the bundle in either \f(CW@INC\fR or |
| 534 | \&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{cpan_home}>. Note that this is different from |
| 535 | CPAN::Module::inst_file. |
| 536 | .IP "\fICPAN::Bundle::inst_version()\fR" 4 |
| 537 | .IX Item "CPAN::Bundle::inst_version()" |
| 538 | Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR |
| 539 | .IP "\fICPAN::Bundle::uptodate()\fR" 4 |
| 540 | .IX Item "CPAN::Bundle::uptodate()" |
| 541 | Returns 1 if the bundle itself and all its members are uptodate. |
| 542 | .IP "\fICPAN::Bundle::install()\fR" 4 |
| 543 | .IX Item "CPAN::Bundle::install()" |
| 544 | Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle |
| 545 | .IP "\fICPAN::Bundle::make()\fR" 4 |
| 546 | .IX Item "CPAN::Bundle::make()" |
| 547 | Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle |
| 548 | .IP "\fICPAN::Bundle::readme()\fR" 4 |
| 549 | .IX Item "CPAN::Bundle::readme()" |
| 550 | Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle |
| 551 | .IP "\fICPAN::Bundle::test()\fR" 4 |
| 552 | .IX Item "CPAN::Bundle::test()" |
| 553 | Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle |
| 554 | .IP "\fICPAN::Distribution::as_glimpse()\fR" 4 |
| 555 | .IX Item "CPAN::Distribution::as_glimpse()" |
| 556 | Returns a one-line description of the distribution |
| 557 | .IP "\fICPAN::Distribution::as_string()\fR" 4 |
| 558 | .IX Item "CPAN::Distribution::as_string()" |
| 559 | Returns a multi-line description of the distribution |
| 560 | .IP "\fICPAN::Distribution::clean()\fR" 4 |
| 561 | .IX Item "CPAN::Distribution::clean()" |
| 562 | Changes to the directory where the distribution has been unpacked and |
| 563 | runs \f(CW\*(C`make clean\*(C'\fR there. |
| 564 | .IP "\fICPAN::Distribution::containsmods()\fR" 4 |
| 565 | .IX Item "CPAN::Distribution::containsmods()" |
| 566 | Returns a list of IDs of modules contained in a distribution file. |
| 567 | Only works for distributions listed in the 02packages.details.txt.gz |
| 568 | file. This typically means that only the most recent version of a |
| 569 | distribution is covered. |
| 570 | .IP "\fICPAN::Distribution::cvs_import()\fR" 4 |
| 571 | .IX Item "CPAN::Distribution::cvs_import()" |
| 572 | Changes to the directory where the distribution has been unpacked and |
| 573 | runs something like |
| 574 | .Sp |
| 575 | .Vb 1 |
| 576 | \& cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version |
| 577 | .Ve |
| 578 | .Sp |
| 579 | there. |
| 580 | .IP "\fICPAN::Distribution::dir()\fR" 4 |
| 581 | .IX Item "CPAN::Distribution::dir()" |
| 582 | Returns the directory into which this distribution has been unpacked. |
| 583 | .IP "CPAN::Distribution::force($method,@args)" 4 |
| 584 | .IX Item "CPAN::Distribution::force($method,@args)" |
| 585 | Forces \s-1CPAN\s0 to perform a task that normally would have failed. Force |
| 586 | takes as arguments a method name to be called and any number of |
| 587 | additional arguments that should be passed to the called method. The |
| 588 | internals of the object get the needed changes so that \s-1CPAN\s0.pm does |
| 589 | not refuse to take the action. |
| 590 | .IP "\fICPAN::Distribution::get()\fR" 4 |
| 591 | .IX Item "CPAN::Distribution::get()" |
| 592 | Downloads the distribution from \s-1CPAN\s0 and unpacks it. Does nothing if |
| 593 | the distribution has already been downloaded and unpacked within the |
| 594 | current session. |
| 595 | .IP "\fICPAN::Distribution::install()\fR" 4 |
| 596 | .IX Item "CPAN::Distribution::install()" |
| 597 | Changes to the directory where the distribution has been unpacked and |
| 598 | runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not |
| 599 | yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR will be issued in |
| 600 | any case and if this fails, the install will be canceled. The |
| 601 | cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for |
| 602 | you. |
| 603 | .IP "\fICPAN::Distribution::isa_perl()\fR" 4 |
| 604 | .IX Item "CPAN::Distribution::isa_perl()" |
| 605 | Returns 1 if this distribution file seems to be a perl distribution. |
| 606 | Normally this is derived from the file name only, but the index from |
| 607 | \&\s-1CPAN\s0 can contain a hint to achieve a return value of true for other |
| 608 | filenames too. |
| 609 | .IP "\fICPAN::Distribution::look()\fR" 4 |
| 610 | .IX Item "CPAN::Distribution::look()" |
| 611 | Changes to the directory where the distribution has been unpacked and |
| 612 | opens a subshell there. Exiting the subshell returns. |
| 613 | .IP "\fICPAN::Distribution::make()\fR" 4 |
| 614 | .IX Item "CPAN::Distribution::make()" |
| 615 | First runs the \f(CW\*(C`get\*(C'\fR method to make sure the distribution is |
| 616 | downloaded and unpacked. Changes to the directory where the |
| 617 | distribution has been unpacked and runs the external commands \f(CW\*(C`perl |
| 618 | Makefile.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there. |
| 619 | .IP "\fICPAN::Distribution::prereq_pm()\fR" 4 |
| 620 | .IX Item "CPAN::Distribution::prereq_pm()" |
| 621 | Returns the hash reference that has been announced by a distribution |
| 622 | as the \s-1PREREQ_PM\s0 hash in the Makefile.PL. Note: works only after an |
| 623 | attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns undef |
| 624 | otherwise. |
| 625 | .IP "\fICPAN::Distribution::readme()\fR" 4 |
| 626 | .IX Item "CPAN::Distribution::readme()" |
| 627 | Downloads the \s-1README\s0 file associated with a distribution and runs it |
| 628 | through the pager specified in \f(CW\*(C`$CPAN::Config\-\*(C'\fR{pager}>. |
| 629 | .IP "\fICPAN::Distribution::test()\fR" 4 |
| 630 | .IX Item "CPAN::Distribution::test()" |
| 631 | Changes to the directory where the distribution has been unpacked and |
| 632 | runs \f(CW\*(C`make test\*(C'\fR there. |
| 633 | .IP "\fICPAN::Distribution::uptodate()\fR" 4 |
| 634 | .IX Item "CPAN::Distribution::uptodate()" |
| 635 | Returns 1 if all the modules contained in the distribution are |
| 636 | uptodate. Relies on containsmods. |
| 637 | .IP "\fICPAN::Index::force_reload()\fR" 4 |
| 638 | .IX Item "CPAN::Index::force_reload()" |
| 639 | Forces a reload of all indices. |
| 640 | .IP "\fICPAN::Index::reload()\fR" 4 |
| 641 | .IX Item "CPAN::Index::reload()" |
| 642 | Reloads all indices if they have been read more than |
| 643 | \&\f(CW\*(C`$CPAN::Config\-\*(C'\fR{index_expire}> days. |
| 644 | .IP "\fICPAN::InfoObj::dump()\fR" 4 |
| 645 | .IX Item "CPAN::InfoObj::dump()" |
| 646 | CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution |
| 647 | inherit this method. It prints the data structure associated with an |
| 648 | object. Useful for debugging. Note: the data structure is considered |
| 649 | internal and thus subject to change without notice. |
| 650 | .IP "\fICPAN::Module::as_glimpse()\fR" 4 |
| 651 | .IX Item "CPAN::Module::as_glimpse()" |
| 652 | Returns a one-line description of the module |
| 653 | .IP "\fICPAN::Module::as_string()\fR" 4 |
| 654 | .IX Item "CPAN::Module::as_string()" |
| 655 | Returns a multi-line description of the module |
| 656 | .IP "\fICPAN::Module::clean()\fR" 4 |
| 657 | .IX Item "CPAN::Module::clean()" |
| 658 | Runs a clean on the distribution associated with this module. |
| 659 | .IP "\fICPAN::Module::cpan_file()\fR" 4 |
| 660 | .IX Item "CPAN::Module::cpan_file()" |
| 661 | Returns the filename on \s-1CPAN\s0 that is associated with the module. |
| 662 | .IP "\fICPAN::Module::cpan_version()\fR" 4 |
| 663 | .IX Item "CPAN::Module::cpan_version()" |
| 664 | Returns the latest version of this module available on \s-1CPAN\s0. |
| 665 | .IP "\fICPAN::Module::cvs_import()\fR" 4 |
| 666 | .IX Item "CPAN::Module::cvs_import()" |
| 667 | Runs a cvs_import on the distribution associated with this module. |
| 668 | .IP "\fICPAN::Module::description()\fR" 4 |
| 669 | .IX Item "CPAN::Module::description()" |
| 670 | Returns a 44 character description of this module. Only available for |
| 671 | modules listed in The Module List (CPAN/modules/00modlist.long.html |
| 672 | or 00modlist.long.txt.gz) |
| 673 | .IP "CPAN::Module::force($method,@args)" 4 |
| 674 | .IX Item "CPAN::Module::force($method,@args)" |
| 675 | Forces \s-1CPAN\s0 to perform a task that normally would have failed. Force |
| 676 | takes as arguments a method name to be called and any number of |
| 677 | additional arguments that should be passed to the called method. The |
| 678 | internals of the object get the needed changes so that \s-1CPAN\s0.pm does |
| 679 | not refuse to take the action. |
| 680 | .IP "\fICPAN::Module::get()\fR" 4 |
| 681 | .IX Item "CPAN::Module::get()" |
| 682 | Runs a get on the distribution associated with this module. |
| 683 | .IP "\fICPAN::Module::inst_file()\fR" 4 |
| 684 | .IX Item "CPAN::Module::inst_file()" |
| 685 | Returns the filename of the module found in \f(CW@INC\fR. The first file found |
| 686 | is reported just like perl itself stops searching \f(CW@INC\fR when it finds a |
| 687 | module. |
| 688 | .IP "\fICPAN::Module::inst_version()\fR" 4 |
| 689 | .IX Item "CPAN::Module::inst_version()" |
| 690 | Returns the version number of the module in readable format. |
| 691 | .IP "\fICPAN::Module::install()\fR" 4 |
| 692 | .IX Item "CPAN::Module::install()" |
| 693 | Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module. |
| 694 | .IP "\fICPAN::Module::look()\fR" 4 |
| 695 | .IX Item "CPAN::Module::look()" |
| 696 | Changes to the directory where the distribution associated with this |
| 697 | module has been unpacked and opens a subshell there. Exiting the |
| 698 | subshell returns. |
| 699 | .IP "\fICPAN::Module::make()\fR" 4 |
| 700 | .IX Item "CPAN::Module::make()" |
| 701 | Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module. |
| 702 | .IP "\fICPAN::Module::manpage_headline()\fR" 4 |
| 703 | .IX Item "CPAN::Module::manpage_headline()" |
| 704 | If module is installed, peeks into the module's manpage, reads the |
| 705 | headline and returns it. Moreover, if the module has been downloaded |
| 706 | within this session, does the equivalent on the downloaded module even |
| 707 | if it is not installed. |
| 708 | .IP "\fICPAN::Module::readme()\fR" 4 |
| 709 | .IX Item "CPAN::Module::readme()" |
| 710 | Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module. |
| 711 | .IP "\fICPAN::Module::test()\fR" 4 |
| 712 | .IX Item "CPAN::Module::test()" |
| 713 | Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module. |
| 714 | .IP "\fICPAN::Module::uptodate()\fR" 4 |
| 715 | .IX Item "CPAN::Module::uptodate()" |
| 716 | Returns 1 if the module is installed and up\-to\-date. |
| 717 | .IP "\fICPAN::Module::userid()\fR" 4 |
| 718 | .IX Item "CPAN::Module::userid()" |
| 719 | Returns the author's \s-1ID\s0 of the module. |
| 720 | .Sh "Cache Manager" |
| 721 | .IX Subsection "Cache Manager" |
| 722 | Currently the cache manager only keeps track of the build directory |
| 723 | ($CPAN::Config\->{build_dir}). It is a simple \s-1FIFO\s0 mechanism that |
| 724 | deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of |
| 725 | all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache} |
| 726 | (in \s-1MB\s0). The contents of this cache may be used for later |
| 727 | re-installations that you intend to do manually, but will never be |
| 728 | trusted by \s-1CPAN\s0 itself. This is due to the fact that the user might |
| 729 | use these directories for building modules on different architectures. |
| 730 | .PP |
| 731 | There is another directory ($CPAN::Config\->{keep_source_where}) where |
| 732 | the original distribution files are kept. This directory is not |
| 733 | covered by the cache manager and must be controlled by the user. If |
| 734 | you choose to have the same directory as build_dir and as |
| 735 | keep_source_where directory, then your sources will be deleted with |
| 736 | the same fifo mechanism. |
| 737 | .Sh "Bundles" |
| 738 | .IX Subsection "Bundles" |
| 739 | A bundle is just a perl module in the namespace Bundle:: that does not |
| 740 | define any functions or methods. It usually only contains documentation. |
| 741 | .PP |
| 742 | It starts like a perl module with a package declaration and a \f(CW$VERSION\fR |
| 743 | variable. After that the pod section looks like any other pod with the |
| 744 | only difference being that \fIone special pod section\fR exists starting with |
| 745 | (verbatim): |
| 746 | .PP |
| 747 | .Vb 1 |
| 748 | \& =head1 CONTENTS |
| 749 | .Ve |
| 750 | .PP |
| 751 | In this pod section each line obeys the format |
| 752 | .PP |
| 753 | .Vb 1 |
| 754 | \& Module_Name [Version_String] [- optional text] |
| 755 | .Ve |
| 756 | .PP |
| 757 | The only required part is the first field, the name of a module |
| 758 | (e.g. Foo::Bar, ie. \fInot\fR the name of the distribution file). The rest |
| 759 | of the line is optional. The comment part is delimited by a dash just |
| 760 | as in the man page header. |
| 761 | .PP |
| 762 | The distribution of a bundle should follow the same convention as |
| 763 | other distributions. |
| 764 | .PP |
| 765 | Bundles are treated specially in the \s-1CPAN\s0 package. If you say 'install |
| 766 | Bundle::Tkkit' (assuming such a bundle exists), \s-1CPAN\s0 will install all |
| 767 | the modules in the \s-1CONTENTS\s0 section of the pod. You can install your |
| 768 | own Bundles locally by placing a conformant Bundle file somewhere into |
| 769 | your \f(CW@INC\fR path. The \fIautobundle()\fR command which is available in the |
| 770 | shell interface does that for you by including all currently installed |
| 771 | modules in a snapshot bundle file. |
| 772 | .Sh "Prerequisites" |
| 773 | .IX Subsection "Prerequisites" |
| 774 | If you have a local mirror of \s-1CPAN\s0 and can access all files with |
| 775 | \&\*(L"file:\*(R" URLs, then you only need a perl better than perl5.003 to run |
| 776 | this module. Otherwise Net::FTP is strongly recommended. \s-1LWP\s0 may be |
| 777 | required for non-UNIX systems or if your nearest \s-1CPAN\s0 site is |
| 778 | associated with a \s-1URL\s0 that is not \f(CW\*(C`ftp:\*(C'\fR. |
| 779 | .PP |
| 780 | If you have neither Net::FTP nor \s-1LWP\s0, there is a fallback mechanism |
| 781 | implemented for an external ftp command or for an external lynx |
| 782 | command. |
| 783 | .Sh "Finding packages and \s-1VERSION\s0" |
| 784 | .IX Subsection "Finding packages and VERSION" |
| 785 | This module presumes that all packages on \s-1CPAN\s0 |
| 786 | .IP "\(bu" 2 |
| 787 | declare their \f(CW$VERSION\fR variable in an easy to parse manner. This |
| 788 | prerequisite can hardly be relaxed because it consumes far too much |
| 789 | memory to load all packages into the running program just to determine |
| 790 | the \f(CW$VERSION\fR variable. Currently all programs that are dealing with |
| 791 | version use something like this |
| 792 | .Sp |
| 793 | .Vb 2 |
| 794 | \& perl -MExtUtils::MakeMaker -le \e |
| 795 | \& 'print MM->parse_version(shift)' filename |
| 796 | .Ve |
| 797 | .Sp |
| 798 | If you are author of a package and wonder if your \f(CW$VERSION\fR can be |
| 799 | parsed, please try the above method. |
| 800 | .IP "\(bu" 2 |
| 801 | come as compressed or gzipped tarfiles or as zip files and contain a |
| 802 | Makefile.PL (well, we try to handle a bit more, but without much |
| 803 | enthusiasm). |
| 804 | .Sh "Debugging" |
| 805 | .IX Subsection "Debugging" |
| 806 | The debugging of this module is a bit complex, because we have |
| 807 | interferences of the software producing the indices on \s-1CPAN\s0, of the |
| 808 | mirroring process on \s-1CPAN\s0, of packaging, of configuration, of |
| 809 | synchronicity, and of bugs within \s-1CPAN\s0.pm. |
| 810 | .PP |
| 811 | For code debugging in interactive mode you can try \*(L"o debug\*(R" which |
| 812 | will list options for debugging the various parts of the code. You |
| 813 | should know that \*(L"o debug\*(R" has built-in completion support. |
| 814 | .PP |
| 815 | For data debugging there is the \f(CW\*(C`dump\*(C'\fR command which takes the same |
| 816 | arguments as make/test/install and outputs the object's Data::Dumper |
| 817 | dump. |
| 818 | .Sh "Floppy, Zip, Offline Mode" |
| 819 | .IX Subsection "Floppy, Zip, Offline Mode" |
| 820 | \&\s-1CPAN\s0.pm works nicely without network too. If you maintain machines |
| 821 | that are not networked at all, you should consider working with file: |
| 822 | URLs. Of course, you have to collect your modules somewhere first. So |
| 823 | you might use \s-1CPAN\s0.pm to put together all you need on a networked |
| 824 | machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not |
| 825 | \&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind |
| 826 | of a personal \s-1CPAN\s0. \s-1CPAN\s0.pm on the non-networked machines works nicely |
| 827 | with this floppy. See also below the paragraph about CD-ROM support. |
| 828 | .SH "CONFIGURATION" |
| 829 | .IX Header "CONFIGURATION" |
| 830 | When the \s-1CPAN\s0 module is used for the first time, a configuration |
| 831 | dialog tries to determine a couple of site specific options. The |
| 832 | result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR |
| 833 | in a file CPAN/Config.pm. |
| 834 | .PP |
| 835 | The default values defined in the CPAN/Config.pm file can be |
| 836 | overridden in a user specific file: CPAN/MyConfig.pm. Such a file is |
| 837 | best placed in \f(CW$HOME\fR/.cpan/CPAN/MyConfig.pm, because \f(CW$HOME\fR/.cpan is |
| 838 | added to the search path of the \s-1CPAN\s0 module before the \fIuse()\fR or |
| 839 | \&\fIrequire()\fR statements. |
| 840 | .PP |
| 841 | The configuration dialog can be started any time later again by |
| 842 | issueing the command \f(CW\*(C` o conf init \*(C'\fR in the \s-1CPAN\s0 shell. |
| 843 | .PP |
| 844 | Currently the following keys in the hash reference \f(CW$CPAN::Config\fR are |
| 845 | defined: |
| 846 | .PP |
| 847 | .Vb 35 |
| 848 | \& build_cache size of cache for directories to build modules |
| 849 | \& build_dir locally accessible directory to build modules |
| 850 | \& index_expire after this many days refetch index files |
| 851 | \& cache_metadata use serializer to cache metadata |
| 852 | \& cpan_home local directory reserved for this package |
| 853 | \& dontload_hash anonymous hash: modules in the keys will not be |
| 854 | \& loaded by the CPAN::has_inst() routine |
| 855 | \& gzip location of external program gzip |
| 856 | \& histfile file to maintain history between sessions |
| 857 | \& histsize maximum number of lines to keep in histfile |
| 858 | \& inactivity_timeout breaks interactive Makefile.PLs after this |
| 859 | \& many seconds inactivity. Set to 0 to never break. |
| 860 | \& inhibit_startup_message |
| 861 | \& if true, does not print the startup message |
| 862 | \& keep_source_where directory in which to keep the source (if we do) |
| 863 | \& make location of external make program |
| 864 | \& make_arg arguments that should always be passed to 'make' |
| 865 | \& make_install_arg same as make_arg for 'make install' |
| 866 | \& makepl_arg arguments passed to 'perl Makefile.PL' |
| 867 | \& pager location of external program more (or any pager) |
| 868 | \& prerequisites_policy |
| 869 | \& what to do if you are missing module prerequisites |
| 870 | \& ('follow' automatically, 'ask' me, or 'ignore') |
| 871 | \& proxy_user username for accessing an authenticating proxy |
| 872 | \& proxy_pass password for accessing an authenticating proxy |
| 873 | \& scan_cache controls scanning of cache ('atstart' or 'never') |
| 874 | \& tar location of external program tar |
| 875 | \& term_is_latin if true internal UTF-8 is translated to ISO-8859-1 |
| 876 | \& (and nonsense for characters outside latin range) |
| 877 | \& unzip location of external program unzip |
| 878 | \& urllist arrayref to nearby CPAN sites (or equivalent locations) |
| 879 | \& wait_list arrayref to a wait server to try (See CPAN::WAIT) |
| 880 | \& ftp_proxy, } the three usual variables for configuring |
| 881 | \& http_proxy, } proxy requests. Both as CPAN::Config variables |
| 882 | \& no_proxy } and as environment variables configurable. |
| 883 | .Ve |
| 884 | .PP |
| 885 | You can set and query each of these options interactively in the cpan |
| 886 | shell with the command set defined within the \f(CW\*(C`o conf\*(C'\fR command: |
| 887 | .ie n .IP """o conf <scalar option>""" 2 |
| 888 | .el .IP "\f(CWo conf <scalar option>\fR" 2 |
| 889 | .IX Item "o conf <scalar option>" |
| 890 | prints the current value of the \fIscalar option\fR |
| 891 | .ie n .IP """o conf <scalar option> <value>""" 2 |
| 892 | .el .IP "\f(CWo conf <scalar option> <value>\fR" 2 |
| 893 | .IX Item "o conf <scalar option> <value>" |
| 894 | Sets the value of the \fIscalar option\fR to \fIvalue\fR |
| 895 | .ie n .IP """o conf <list option>""" 2 |
| 896 | .el .IP "\f(CWo conf <list option>\fR" 2 |
| 897 | .IX Item "o conf <list option>" |
| 898 | prints the current value of the \fIlist option\fR in MakeMaker's |
| 899 | neatvalue format. |
| 900 | .ie n .IP """o conf <list option> [shift|pop]""" 2 |
| 901 | .el .IP "\f(CWo conf <list option> [shift|pop]\fR" 2 |
| 902 | .IX Item "o conf <list option> [shift|pop]" |
| 903 | shifts or pops the array in the \fIlist option\fR variable |
| 904 | .ie n .IP """o conf <list option> [unshift|push|splice] <list>""" 2 |
| 905 | .el .IP "\f(CWo conf <list option> [unshift|push|splice] <list>\fR" 2 |
| 906 | .IX Item "o conf <list option> [unshift|push|splice] <list>" |
| 907 | works like the corresponding perl commands. |
| 908 | .Sh "Note on urllist parameter's format" |
| 909 | .IX Subsection "Note on urllist parameter's format" |
| 910 | urllist parameters are URLs according to \s-1RFC\s0 1738. We do a little |
| 911 | guessing if your \s-1URL\s0 is not compliant, but if you have problems with |
| 912 | file URLs, please try the correct format. Either: |
| 913 | .PP |
| 914 | .Vb 1 |
| 915 | \& file://localhost/whatever/ftp/pub/CPAN/ |
| 916 | .Ve |
| 917 | .PP |
| 918 | or |
| 919 | .PP |
| 920 | .Vb 1 |
| 921 | \& file:///home/ftp/pub/CPAN/ |
| 922 | .Ve |
| 923 | .Sh "urllist parameter has CD-ROM support" |
| 924 | .IX Subsection "urllist parameter has CD-ROM support" |
| 925 | The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of |
| 926 | URLs that are to be used for downloading. If the list contains any |
| 927 | \&\f(CW\*(C`file\*(C'\fR URLs, \s-1CPAN\s0 always tries to get files from there first. This |
| 928 | feature is disabled for index files. So the recommendation for the |
| 929 | owner of a CD-ROM with \s-1CPAN\s0 contents is: include your local, possibly |
| 930 | outdated CD-ROM as a \f(CW\*(C`file\*(C'\fR \s-1URL\s0 at the end of urllist, e.g. |
| 931 | .PP |
| 932 | .Vb 1 |
| 933 | \& o conf urllist push file://localhost/CDROM/CPAN |
| 934 | .Ve |
| 935 | .PP |
| 936 | \&\s-1CPAN\s0.pm will then fetch the index files from one of the \s-1CPAN\s0 sites |
| 937 | that come at the beginning of urllist. It will later check for each |
| 938 | module if there is a local copy of the most recent version. |
| 939 | .PP |
| 940 | Another peculiarity of urllist is that the site that we could |
| 941 | successfully fetch the last file from automatically gets a preference |
| 942 | token and is tried as the first site for the next request. So if you |
| 943 | add a new site at runtime it may happen that the previously preferred |
| 944 | site will be tried another time. This means that if you want to disallow |
| 945 | a site for the next transfer, it must be explicitly removed from |
| 946 | urllist. |
| 947 | .SH "SECURITY" |
| 948 | .IX Header "SECURITY" |
| 949 | There's no strong security layer in \s-1CPAN\s0.pm. \s-1CPAN\s0.pm helps you to |
| 950 | install foreign, unmasked, unsigned code on your machine. We compare |
| 951 | to a checksum that comes from the net just as the distribution file |
| 952 | itself. If somebody has managed to tamper with the distribution file, |
| 953 | they may have as well tampered with the \s-1CHECKSUMS\s0 file. Future |
| 954 | development will go towards strong authentication. |
| 955 | .SH "EXPORT" |
| 956 | .IX Header "EXPORT" |
| 957 | Most functions in package \s-1CPAN\s0 are exported per default. The reason |
| 958 | for this is that the primary use is intended for the cpan shell or for |
| 959 | one\-liners. |
| 960 | .SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES" |
| 961 | .IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES" |
| 962 | Populating a freshly installed perl with my favorite modules is pretty |
| 963 | easy if you maintain a private bundle definition file. To get a useful |
| 964 | blueprint of a bundle definition file, the command autobundle can be used |
| 965 | on the \s-1CPAN\s0 shell command line. This command writes a bundle definition |
| 966 | file for all modules that are installed for the currently running perl |
| 967 | interpreter. It's recommended to run this command only once and from then |
| 968 | on maintain the file manually under a private name, say |
| 969 | Bundle/my_bundle.pm. With a clever bundle file you can then simply say |
| 970 | .PP |
| 971 | .Vb 1 |
| 972 | \& cpan> install Bundle::my_bundle |
| 973 | .Ve |
| 974 | .PP |
| 975 | then answer a few questions and then go out for a coffee. |
| 976 | .PP |
| 977 | Maintaining a bundle definition file means keeping track of two |
| 978 | things: dependencies and interactivity. \s-1CPAN\s0.pm sometimes fails on |
| 979 | calculating dependencies because not all modules define all MakeMaker |
| 980 | attributes correctly, so a bundle definition file should specify |
| 981 | prerequisites as early as possible. On the other hand, it's a bit |
| 982 | annoying that many distributions need some interactive configuring. So |
| 983 | what I try to accomplish in my private bundle file is to have the |
| 984 | packages that need to be configured early in the file and the gentle |
| 985 | ones later, so I can go out after a few minutes and leave \s-1CPAN\s0.pm |
| 986 | untended. |
| 987 | .SH "WORKING WITH CPAN.pm BEHIND FIREWALLS" |
| 988 | .IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS" |
| 989 | Thanks to Graham Barr for contributing the following paragraphs about |
| 990 | the interaction between perl, and various firewall configurations. For |
| 991 | further informations on firewalls, it is recommended to consult the |
| 992 | documentation that comes with the ncftp program. If you are unable to |
| 993 | go through the firewall with a simple Perl setup, it is very likely |
| 994 | that you can configure ncftp so that it works for your firewall. |
| 995 | .Sh "Three basic types of firewalls" |
| 996 | .IX Subsection "Three basic types of firewalls" |
| 997 | Firewalls can be categorized into three basic types. |
| 998 | .IP "http firewall" 4 |
| 999 | .IX Item "http firewall" |
| 1000 | This is where the firewall machine runs a web server and to access the |
| 1001 | outside world you must do it via the web server. If you set environment |
| 1002 | variables like http_proxy or ftp_proxy to a values beginning with http:// |
| 1003 | or in your web browser you have to set proxy information then you know |
| 1004 | you are running an http firewall. |
| 1005 | .Sp |
| 1006 | To access servers outside these types of firewalls with perl (even for |
| 1007 | ftp) you will need to use \s-1LWP\s0. |
| 1008 | .IP "ftp firewall" 4 |
| 1009 | .IX Item "ftp firewall" |
| 1010 | This where the firewall machine runs an ftp server. This kind of |
| 1011 | firewall will only let you access ftp servers outside the firewall. |
| 1012 | This is usually done by connecting to the firewall with ftp, then |
| 1013 | entering a username like \*(L"user@outside.host.com\*(R" |
| 1014 | .Sp |
| 1015 | To access servers outside these type of firewalls with perl you |
| 1016 | will need to use Net::FTP. |
| 1017 | .IP "One way visibility" 4 |
| 1018 | .IX Item "One way visibility" |
| 1019 | I say one way visibility as these firewalls try to make themselves look |
| 1020 | invisible to the users inside the firewall. An \s-1FTP\s0 data connection is |
| 1021 | normally created by sending the remote server your \s-1IP\s0 address and then |
| 1022 | listening for the connection. But the remote server will not be able to |
| 1023 | connect to you because of the firewall. So for these types of firewall |
| 1024 | \&\s-1FTP\s0 connections need to be done in a passive mode. |
| 1025 | .Sp |
| 1026 | There are two that I can think off. |
| 1027 | .RS 4 |
| 1028 | .IP "\s-1SOCKS\s0" 4 |
| 1029 | .IX Item "SOCKS" |
| 1030 | If you are using a \s-1SOCKS\s0 firewall you will need to compile perl and link |
| 1031 | it with the \s-1SOCKS\s0 library, this is what is normally called a 'socksified' |
| 1032 | perl. With this executable you will be able to connect to servers outside |
| 1033 | the firewall as if it is not there. |
| 1034 | .IP "\s-1IP\s0 Masquerade" 4 |
| 1035 | .IX Item "IP Masquerade" |
| 1036 | This is the firewall implemented in the Linux kernel, it allows you to |
| 1037 | hide a complete network behind one \s-1IP\s0 address. With this firewall no |
| 1038 | special compiling is needed as you can access hosts directly. |
| 1039 | .Sp |
| 1040 | For accessing ftp servers behind such firewalls you may need to set |
| 1041 | the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR to a true value, e.g. |
| 1042 | .Sp |
| 1043 | .Vb 1 |
| 1044 | \& env FTP_PASSIVE=1 perl -MCPAN -eshell |
| 1045 | .Ve |
| 1046 | .Sp |
| 1047 | or |
| 1048 | .Sp |
| 1049 | .Vb 1 |
| 1050 | \& perl -MCPAN -e '$ENV{FTP_PASSIVE} = 1; shell' |
| 1051 | .Ve |
| 1052 | .RE |
| 1053 | .RS 4 |
| 1054 | .RE |
| 1055 | .Sh "Configuring lynx or ncftp for going through a firewall" |
| 1056 | .IX Subsection "Configuring lynx or ncftp for going through a firewall" |
| 1057 | If you can go through your firewall with e.g. lynx, presumably with a |
| 1058 | command such as |
| 1059 | .PP |
| 1060 | .Vb 1 |
| 1061 | \& /usr/local/bin/lynx -pscott:tiger |
| 1062 | .Ve |
| 1063 | .PP |
| 1064 | then you would configure \s-1CPAN\s0.pm with the command |
| 1065 | .PP |
| 1066 | .Vb 1 |
| 1067 | \& o conf lynx "/usr/local/bin/lynx -pscott:tiger" |
| 1068 | .Ve |
| 1069 | .PP |
| 1070 | That's all. Similarly for ncftp or ftp, you would configure something |
| 1071 | like |
| 1072 | .PP |
| 1073 | .Vb 1 |
| 1074 | \& o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg" |
| 1075 | .Ve |
| 1076 | .PP |
| 1077 | Your mileage may vary... |
| 1078 | .SH "FAQ" |
| 1079 | .IX Header "FAQ" |
| 1080 | .IP "1)" 4 |
| 1081 | I installed a new version of module X but \s-1CPAN\s0 keeps saying, |
| 1082 | I have the old version installed |
| 1083 | .Sp |
| 1084 | Most probably you \fBdo\fR have the old version installed. This can |
| 1085 | happen if a module installs itself into a different directory in the |
| 1086 | \&\f(CW@INC\fR path than it was previously installed. This is not really a |
| 1087 | \&\s-1CPAN\s0.pm problem, you would have the same problem when installing the |
| 1088 | module manually. The easiest way to prevent this behaviour is to add |
| 1089 | the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why |
| 1090 | many people add this argument permanently by configuring |
| 1091 | .Sp |
| 1092 | .Vb 1 |
| 1093 | \& o conf make_install_arg UNINST=1 |
| 1094 | .Ve |
| 1095 | .IP "2)" 4 |
| 1096 | So why is UNINST=1 not the default? |
| 1097 | .Sp |
| 1098 | Because there are people who have their precise expectations about who |
| 1099 | may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In |
| 1100 | fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage. |
| 1101 | .IP "3)" 4 |
| 1102 | I want to clean up my mess, and install a new perl along with |
| 1103 | all modules I have. How do I go about it? |
| 1104 | .Sp |
| 1105 | Run the autobundle command for your old perl and optionally rename the |
| 1106 | resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl |
| 1107 | with the Configure option prefix, e.g. |
| 1108 | .Sp |
| 1109 | .Vb 1 |
| 1110 | \& ./Configure -Dprefix=/usr/local/perl-5.6.78.9 |
| 1111 | .Ve |
| 1112 | .Sp |
| 1113 | Install the bundle file you produced in the first step with something like |
| 1114 | .Sp |
| 1115 | .Vb 1 |
| 1116 | \& cpan> install Bundle::mybundle |
| 1117 | .Ve |
| 1118 | .Sp |
| 1119 | and you're done. |
| 1120 | .IP "4)" 4 |
| 1121 | When I install bundles or multiple modules with one command |
| 1122 | there is too much output to keep track of. |
| 1123 | .Sp |
| 1124 | You may want to configure something like |
| 1125 | .Sp |
| 1126 | .Vb 2 |
| 1127 | \& o conf make_arg "| tee -ai /root/.cpan/logs/make.out" |
| 1128 | \& o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out" |
| 1129 | .Ve |
| 1130 | .Sp |
| 1131 | so that \s-1STDOUT\s0 is captured in a file for later inspection. |
| 1132 | .IP "5)" 4 |
| 1133 | I am not root, how can I install a module in a personal directory? |
| 1134 | .Sp |
| 1135 | You will most probably like something like this: |
| 1136 | .Sp |
| 1137 | .Vb 4 |
| 1138 | \& o conf makepl_arg "LIB=~/myperl/lib \e |
| 1139 | \& INSTALLMAN1DIR=~/myperl/man/man1 \e |
| 1140 | \& INSTALLMAN3DIR=~/myperl/man/man3" |
| 1141 | \& install Sybase::Sybperl |
| 1142 | .Ve |
| 1143 | .Sp |
| 1144 | You can make this setting permanent like all \f(CW\*(C`o conf\*(C'\fR settings with |
| 1145 | \&\f(CW\*(C`o conf commit\*(C'\fR. |
| 1146 | .Sp |
| 1147 | You will have to add ~/myperl/man to the \s-1MANPATH\s0 environment variable |
| 1148 | and also tell your perl programs to look into ~/myperl/lib, e.g. by |
| 1149 | including |
| 1150 | .Sp |
| 1151 | .Vb 1 |
| 1152 | \& use lib "$ENV{HOME}/myperl/lib"; |
| 1153 | .Ve |
| 1154 | .Sp |
| 1155 | or setting the \s-1PERL5LIB\s0 environment variable. |
| 1156 | .Sp |
| 1157 | Another thing you should bear in mind is that the \s-1UNINST\s0 parameter |
| 1158 | should never be set if you are not root. |
| 1159 | .IP "6)" 4 |
| 1160 | How to get a package, unwrap it, and make a change before building it? |
| 1161 | .Sp |
| 1162 | .Vb 1 |
| 1163 | \& look Sybase::Sybperl |
| 1164 | .Ve |
| 1165 | .IP "7)" 4 |
| 1166 | I installed a Bundle and had a couple of fails. When I |
| 1167 | retried, everything resolved nicely. Can this be fixed to work |
| 1168 | on first try? |
| 1169 | .Sp |
| 1170 | The reason for this is that \s-1CPAN\s0 does not know the dependencies of all |
| 1171 | modules when it starts out. To decide about the additional items to |
| 1172 | install, it just uses data found in the generated Makefile. An |
| 1173 | undetected missing piece breaks the process. But it may well be that |
| 1174 | your Bundle installs some prerequisite later than some depending item |
| 1175 | and thus your second try is able to resolve everything. Please note, |
| 1176 | \&\s-1CPAN\s0.pm does not know the dependency tree in advance and cannot sort |
| 1177 | the queue of things to install in a topologically correct order. It |
| 1178 | resolves perfectly well \s-1IFF\s0 all modules declare the prerequisites |
| 1179 | correctly with the \s-1PREREQ_PM\s0 attribute to MakeMaker. For bundles which |
| 1180 | fail and you need to install often, it is recommended sort the Bundle |
| 1181 | definition file manually. It is planned to improve the metadata |
| 1182 | situation for dependencies on \s-1CPAN\s0 in general, but this will still |
| 1183 | take some time. |
| 1184 | .IP "8)" 4 |
| 1185 | In our intranet we have many modules for internal use. How |
| 1186 | can I integrate these modules with \s-1CPAN\s0.pm but without uploading |
| 1187 | the modules to \s-1CPAN\s0? |
| 1188 | .Sp |
| 1189 | Have a look at the CPAN::Site module. |
| 1190 | .IP "9)" 4 |
| 1191 | When I run \s-1CPAN\s0's shell, I get error msg about line 1 to 4, |
| 1192 | setting meta input/output via the /etc/inputrc file. |
| 1193 | .Sp |
| 1194 | Some versions of readline are picky about capitalization in the |
| 1195 | /etc/inputrc file and specifically RedHat 6.2 comes with a |
| 1196 | /etc/inputrc that contains the word \f(CW\*(C`on\*(C'\fR in lowercase. Change the |
| 1197 | occurrences of \f(CW\*(C`on\*(C'\fR to \f(CW\*(C`On\*(C'\fR and the bug should disappear. |
| 1198 | .IP "10)" 4 |
| 1199 | .IX Item "10)" |
| 1200 | Some authors have strange characters in their names. |
| 1201 | .Sp |
| 1202 | Internally \s-1CPAN\s0.pm uses the \s-1UTF\-8\s0 charset. If your terminal is |
| 1203 | expecting \s-1ISO\-8859\-1\s0 charset, a converter can be activated by setting |
| 1204 | term_is_latin to a true value in your config file. One way of doing so |
| 1205 | would be |
| 1206 | .Sp |
| 1207 | .Vb 1 |
| 1208 | \& cpan> ! $CPAN::Config->{term_is_latin}=1 |
| 1209 | .Ve |
| 1210 | .Sp |
| 1211 | Extended support for converters will be made available as soon as perl |
| 1212 | becomes stable with regard to charset issues. |
| 1213 | .SH "BUGS" |
| 1214 | .IX Header "BUGS" |
| 1215 | We should give coverage for \fBall\fR of the \s-1CPAN\s0 and not just the \s-1PAUSE\s0 |
| 1216 | part, right? In this discussion \s-1CPAN\s0 and \s-1PAUSE\s0 have become equal \*(-- |
| 1217 | but they are not. \s-1PAUSE\s0 is authors/, modules/ and scripts/. \s-1CPAN\s0 is |
| 1218 | \&\s-1PAUSE\s0 plus the clpa/, doc/, misc/, ports/, and src/. |
| 1219 | .PP |
| 1220 | Future development should be directed towards a better integration of |
| 1221 | the other parts. |
| 1222 | .PP |
| 1223 | If a Makefile.PL requires special customization of libraries, prompts |
| 1224 | the user for special input, etc. then you may find \s-1CPAN\s0 is not able to |
| 1225 | build the distribution. In that case, you should attempt the |
| 1226 | traditional method of building a Perl module package from a shell. |
| 1227 | .SH "AUTHOR" |
| 1228 | .IX Header "AUTHOR" |
| 1229 | Andreas Koenig <andreas.koenig@anima.de> |
| 1230 | .SH "TRANSLATIONS" |
| 1231 | .IX Header "TRANSLATIONS" |
| 1232 | Kawai,Takanori provides a Japanese translation of this manpage at |
| 1233 | http://member.nifty.ne.jp/hippo2000/perltips/CPAN.htm |
| 1234 | .SH "SEE ALSO" |
| 1235 | .IX Header "SEE ALSO" |
| 1236 | \&\fIperl\fR\|(1), \fICPAN::Nox\fR\|(3) |