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