Commit | Line | Data |
---|---|---|
920dae64 AT |
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) |