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