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