This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
4f028505f8e6d4f5295e6e3743251f4283ef965d
[perl5.git] / cpan / CPAN / lib / CPAN.pm
1 # -*- Mode: cperl; coding: utf-8; cperl-indent-level: 4 -*-
2 # vim: ts=4 sts=4 sw=4:
3 use strict;
4 package CPAN;
5 $CPAN::VERSION = '2.18';
6 $CPAN::VERSION =~ s/_//;
7
8 # we need to run chdir all over and we would get at wrong libraries
9 # there
10 use File::Spec ();
11 BEGIN {
12     if (File::Spec->can("rel2abs")) {
13         for my $inc (@INC) {
14             $inc = File::Spec->rel2abs($inc) unless ref $inc;
15         }
16     }
17     $SIG{WINCH} = 'IGNORE' if exists $SIG{WINCH};
18 }
19 use CPAN::Author;
20 use CPAN::HandleConfig;
21 use CPAN::Version;
22 use CPAN::Bundle;
23 use CPAN::CacheMgr;
24 use CPAN::Complete;
25 use CPAN::Debug;
26 use CPAN::Distribution;
27 use CPAN::Distrostatus;
28 use CPAN::FTP;
29 use CPAN::Index 1.93; # https://rt.cpan.org/Ticket/Display.html?id=43349
30 use CPAN::InfoObj;
31 use CPAN::Module;
32 use CPAN::Prompt;
33 use CPAN::URL;
34 use CPAN::Queue;
35 use CPAN::Tarzip;
36 use CPAN::DeferredCode;
37 use CPAN::Shell;
38 use CPAN::LWP::UserAgent;
39 use CPAN::Exception::RecursiveDependency;
40 use CPAN::Exception::yaml_not_installed;
41 use CPAN::Exception::yaml_process_error;
42
43 use Carp ();
44 use Config ();
45 use Cwd qw(chdir);
46 use DirHandle ();
47 use Exporter ();
48 use ExtUtils::MakeMaker qw(prompt); # for some unknown reason,
49                                     # 5.005_04 does not work without
50                                     # this
51 use File::Basename ();
52 use File::Copy ();
53 use File::Find;
54 use File::Path ();
55 use FileHandle ();
56 use Fcntl qw(:flock);
57 use Safe ();
58 use Sys::Hostname qw(hostname);
59 use Text::ParseWords ();
60 use Text::Wrap ();
61
62 # protect against "called too early"
63 sub find_perl ();
64 sub anycwd ();
65 sub _uniq;
66
67 no lib ".";
68
69 require Mac::BuildTools if $^O eq 'MacOS';
70 if ($ENV{PERL5_CPAN_IS_RUNNING} && $$ != $ENV{PERL5_CPAN_IS_RUNNING}) {
71     $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION} ||= $ENV{PERL5_CPAN_IS_RUNNING};
72     my @rec = _uniq split(/,/, $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION}), $$;
73     $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION} = join ",", @rec;
74     # warn "# Note: Recursive call of CPAN.pm detected\n";
75     my $w = sprintf "# Note: CPAN.pm is running in process %d now", pop @rec;
76     my %sleep = (
77                  5 => 30,
78                  6 => 60,
79                  7 => 120,
80                 );
81     my $sleep = @rec > 7 ? 300 : ($sleep{scalar @rec}||0);
82     my $verbose = @rec >= 4;
83     while (@rec) {
84         $w .= sprintf " which has been called by process %d", pop @rec;
85     }
86     if ($sleep) {
87         $w .= ".\n\n# Sleeping $sleep seconds to protect other processes\n";
88     }
89     if ($verbose) {
90         warn $w;
91     }
92     local $| = 1;
93     while ($sleep > 0) {
94         printf "\r#%5d", --$sleep;
95         sleep 1;
96     }
97     print "\n";
98 }
99 $ENV{PERL5_CPAN_IS_RUNNING}=$$;
100 $ENV{PERL5_CPANPLUS_IS_RUNNING}=$$; # https://rt.cpan.org/Ticket/Display.html?id=23735
101
102 END { $CPAN::End++; &cleanup; }
103
104 $CPAN::Signal ||= 0;
105 $CPAN::Frontend ||= "CPAN::Shell";
106 unless (@CPAN::Defaultsites) {
107     @CPAN::Defaultsites = map {
108         CPAN::URL->new(TEXT => $_, FROM => "DEF")
109     }
110         "http://www.perl.org/CPAN/",
111         "ftp://ftp.perl.org/pub/CPAN/";
112 }
113 # $CPAN::iCwd (i for initial)
114 $CPAN::iCwd ||= CPAN::anycwd();
115 $CPAN::Perl ||= CPAN::find_perl();
116 $CPAN::Defaultdocs ||= "http://search.cpan.org/perldoc?";
117 $CPAN::Defaultrecent ||= "http://search.cpan.org/uploads.rdf";
118 $CPAN::Defaultrecent ||= "http://cpan.uwinnipeg.ca/htdocs/cpan.xml";
119
120 # our globals are getting a mess
121 use vars qw(
122             $AUTOLOAD
123             $Be_Silent
124             $CONFIG_DIRTY
125             $Defaultdocs
126             $Echo_readline
127             $Frontend
128             $GOTOSHELL
129             $HAS_USABLE
130             $Have_warned
131             $MAX_RECURSION
132             $META
133             $RUN_DEGRADED
134             $Signal
135             $SQLite
136             $Suppress_readline
137             $VERSION
138             $autoload_recursion
139             $term
140             @Defaultsites
141             @EXPORT
142            );
143
144 $MAX_RECURSION = 32;
145
146 @CPAN::ISA = qw(CPAN::Debug Exporter);
147
148 # note that these functions live in CPAN::Shell and get executed via
149 # AUTOLOAD when called directly
150 @EXPORT = qw(
151              autobundle
152              bundle
153              clean
154              cvs_import
155              expand
156              force
157              fforce
158              get
159              install
160              install_tested
161              is_tested
162              make
163              mkmyconfig
164              notest
165              perldoc
166              readme
167              recent
168              recompile
169              report
170              shell
171              smoke
172              test
173              upgrade
174             );
175
176 sub soft_chdir_with_alternatives ($);
177
178 {
179     $autoload_recursion ||= 0;
180
181     #-> sub CPAN::AUTOLOAD ;
182     sub AUTOLOAD { ## no critic
183         $autoload_recursion++;
184         my($l) = $AUTOLOAD;
185         $l =~ s/.*:://;
186         if ($CPAN::Signal) {
187             warn "Refusing to autoload '$l' while signal pending";
188             $autoload_recursion--;
189             return;
190         }
191         if ($autoload_recursion > 1) {
192             my $fullcommand = join " ", map { "'$_'" } $l, @_;
193             warn "Refusing to autoload $fullcommand in recursion\n";
194             $autoload_recursion--;
195             return;
196         }
197         my(%export);
198         @export{@EXPORT} = '';
199         CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
200         if (exists $export{$l}) {
201             CPAN::Shell->$l(@_);
202         } else {
203             die(qq{Unknown CPAN command "$AUTOLOAD". }.
204                 qq{Type ? for help.\n});
205         }
206         $autoload_recursion--;
207     }
208 }
209
210 {
211     my $x = *SAVEOUT; # avoid warning
212     open($x,">&STDOUT") or die "dup failed";
213     my $redir = 0;
214     sub _redirect(@) {
215         #die if $redir;
216         local $_;
217         push(@_,undef);
218         while(defined($_=shift)) {
219             if (s/^\s*>//){
220                 my ($m) = s/^>// ? ">" : "";
221                 s/\s+//;
222                 $_=shift unless length;
223                 die "no dest" unless defined;
224                 open(STDOUT,">$m$_") or die "open:$_:$!\n";
225                 $redir=1;
226             } elsif ( s/^\s*\|\s*// ) {
227                 my $pipe="| $_";
228                 while(defined($_[0])){
229                     $pipe .= ' ' . shift;
230                 }
231                 open(STDOUT,$pipe) or die "open:$pipe:$!\n";
232                 $redir=1;
233             } else {
234                 push(@_,$_);
235             }
236         }
237         return @_;
238     }
239     sub _unredirect {
240         return unless $redir;
241         $redir = 0;
242         ## redirect: unredirect and propagate errors.  explicit close to wait for pipe.
243         close(STDOUT);
244         open(STDOUT,">&SAVEOUT");
245         die "$@" if "$@";
246         ## redirect: done
247     }
248 }
249
250 sub _uniq {
251     my(@list) = @_;
252     my %seen;
253     return grep { !$seen{$_}++ } @list;
254 }
255
256 #-> sub CPAN::shell ;
257 sub shell {
258     my($self) = @_;
259     $Suppress_readline = ! -t STDIN unless defined $Suppress_readline;
260     CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
261
262     my $oprompt = shift || CPAN::Prompt->new;
263     my $prompt = $oprompt;
264     my $commandline = shift || "";
265     $CPAN::CurrentCommandId ||= 1;
266
267     local($^W) = 1;
268     unless ($Suppress_readline) {
269         require Term::ReadLine;
270         if (! $term
271             or
272             $term->ReadLine eq "Term::ReadLine::Stub"
273            ) {
274             $term = Term::ReadLine->new('CPAN Monitor');
275         }
276         if ($term->ReadLine eq "Term::ReadLine::Gnu") {
277             my $attribs = $term->Attribs;
278             $attribs->{attempted_completion_function} = sub {
279                 &CPAN::Complete::gnu_cpl;
280             }
281         } else {
282             $readline::rl_completion_function =
283                 $readline::rl_completion_function = 'CPAN::Complete::cpl';
284         }
285         if (my $histfile = $CPAN::Config->{'histfile'}) {{
286             unless ($term->can("AddHistory")) {
287                 $CPAN::Frontend->mywarn("Terminal does not support AddHistory.\n");
288                 last;
289             }
290             $META->readhist($term,$histfile);
291         }}
292         for ($CPAN::Config->{term_ornaments}) { # alias
293             local $Term::ReadLine::termcap_nowarn = 1;
294             $term->ornaments($_) if defined;
295         }
296         # $term->OUT is autoflushed anyway
297         my $odef = select STDERR;
298         $| = 1;
299         select STDOUT;
300         $| = 1;
301         select $odef;
302     }
303
304     $META->checklock();
305     my @cwd = grep { defined $_ and length $_ }
306         CPAN::anycwd(),
307               File::Spec->can("tmpdir") ? File::Spec->tmpdir() : (),
308                     File::Spec->rootdir();
309     my $try_detect_readline;
310     $try_detect_readline = $term->ReadLine eq "Term::ReadLine::Stub" if $term;
311     unless ($CPAN::Config->{inhibit_startup_message}) {
312         my $rl_avail = $Suppress_readline ? "suppressed" :
313             ($term->ReadLine ne "Term::ReadLine::Stub") ? "enabled" :
314                 "available (maybe install Bundle::CPAN or Bundle::CPANxxl?)";
315         $CPAN::Frontend->myprint(
316                                  sprintf qq{
317 cpan shell -- CPAN exploration and modules installation (v%s)
318 Enter 'h' for help.
319
320 },
321                                  $CPAN::VERSION,
322                                 )
323     }
324     my($continuation) = "";
325     my $last_term_ornaments;
326   SHELLCOMMAND: while () {
327         if ($Suppress_readline) {
328             if ($Echo_readline) {
329                 $|=1;
330             }
331             print $prompt;
332             last SHELLCOMMAND unless defined ($_ = <> );
333             if ($Echo_readline) {
334                 # backdoor: I could not find a way to record sessions
335                 print $_;
336             }
337             chomp;
338         } else {
339             last SHELLCOMMAND unless
340                 defined ($_ = $term->readline($prompt, $commandline));
341         }
342         $_ = "$continuation$_" if $continuation;
343         s/^\s+//;
344         next SHELLCOMMAND if /^$/;
345         s/^\s*\?\s*/help /;
346         if (/^(?:q(?:uit)?|bye|exit)\s*$/i) {
347             last SHELLCOMMAND;
348         } elsif (s/\\$//s) {
349             chomp;
350             $continuation = $_;
351             $prompt = "    > ";
352         } elsif (/^\!/) {
353             s/^\!//;
354             my($eval) = $_;
355             package
356                 CPAN::Eval; # hide from the indexer
357             use strict;
358             use vars qw($import_done);
359             CPAN->import(':DEFAULT') unless $import_done++;
360             CPAN->debug("eval[$eval]") if $CPAN::DEBUG;
361             eval($eval);
362             warn $@ if $@;
363             $continuation = "";
364             $prompt = $oprompt;
365         } elsif (/./) {
366             my(@line);
367             eval { @line = Text::ParseWords::shellwords($_) };
368             warn($@), next SHELLCOMMAND if $@;
369             warn("Text::Parsewords could not parse the line [$_]"),
370                 next SHELLCOMMAND unless @line;
371             $CPAN::META->debug("line[".join("|",@line)."]") if $CPAN::DEBUG;
372             my $command = shift @line;
373             eval {
374                 local (*STDOUT)=*STDOUT;
375                 @line = _redirect(@line);
376                 CPAN::Shell->$command(@line)
377               };
378             my $command_error = $@;
379             _unredirect;
380             my $reported_error;
381             if ($command_error) {
382                 my $err = $command_error;
383                 if (ref $err and $err->isa('CPAN::Exception::blocked_urllist')) {
384                     $CPAN::Frontend->mywarn("Client not fully configured, please proceed with configuring.$err");
385                     $reported_error = ref $err;
386                 } else {
387                     # I'd prefer never to arrive here and make all errors exception objects
388                     if ($err =~ /\S/) {
389                         require Carp;
390                         require Dumpvalue;
391                         my $dv = Dumpvalue->new(tick => '"');
392                         Carp::cluck(sprintf "Catching error: %s", $dv->stringify($err));
393                     }
394                 }
395             }
396             if ($command =~ /^(
397                              # classic commands
398                              make
399                              |test
400                              |install
401                              |clean
402
403                              # pragmas for classic commands
404                              |ff?orce
405                              |notest
406
407                              # compounds
408                              |report
409                              |smoke
410                              |upgrade
411                             )$/x) {
412                 # only commands that tell us something about failed distros
413                 # eval necessary for people without an urllist
414                 eval {CPAN::Shell->failed($CPAN::CurrentCommandId,1);};
415                 if (my $err = $@) {
416                     unless (ref $err and $reported_error eq ref $err) {
417                         die $@;
418                     }
419                 }
420             }
421             soft_chdir_with_alternatives(\@cwd);
422             $CPAN::Frontend->myprint("\n");
423             $continuation = "";
424             $CPAN::CurrentCommandId++;
425             $prompt = $oprompt;
426         }
427     } continue {
428         $commandline = ""; # I do want to be able to pass a default to
429                            # shell, but on the second command I see no
430                            # use in that
431         $Signal=0;
432         CPAN::Queue->nullify_queue;
433         if ($try_detect_readline) {
434             if ($CPAN::META->has_inst("Term::ReadLine::Gnu")
435                 ||
436                 $CPAN::META->has_inst("Term::ReadLine::Perl")
437             ) {
438                 delete $INC{"Term/ReadLine.pm"};
439                 my $redef = 0;
440                 local($SIG{__WARN__}) = CPAN::Shell::paintdots_onreload(\$redef);
441                 require Term::ReadLine;
442                 $CPAN::Frontend->myprint("\n$redef subroutines in ".
443                                          "Term::ReadLine redefined\n");
444                 $GOTOSHELL = 1;
445             }
446         }
447         if ($term and $term->can("ornaments")) {
448             for ($CPAN::Config->{term_ornaments}) { # alias
449                 if (defined $_) {
450                     if (not defined $last_term_ornaments
451                         or $_ != $last_term_ornaments
452                     ) {
453                         local $Term::ReadLine::termcap_nowarn = 1;
454                         $term->ornaments($_);
455                         $last_term_ornaments = $_;
456                     }
457                 } else {
458                     undef $last_term_ornaments;
459                 }
460             }
461         }
462         for my $class (qw(Module Distribution)) {
463             # again unsafe meta access?
464             for my $dm (sort keys %{$CPAN::META->{readwrite}{"CPAN::$class"}}) {
465                 next unless $CPAN::META->{readwrite}{"CPAN::$class"}{$dm}{incommandcolor};
466                 CPAN->debug("BUG: $class '$dm' was in command state, resetting");
467                 delete $CPAN::META->{readwrite}{"CPAN::$class"}{$dm}{incommandcolor};
468             }
469         }
470         if ($GOTOSHELL) {
471             $GOTOSHELL = 0; # not too often
472             $META->savehist if $CPAN::term && $CPAN::term->can("GetHistory");
473             @_ = ($oprompt,"");
474             goto &shell;
475         }
476     }
477     soft_chdir_with_alternatives(\@cwd);
478 }
479
480 #-> CPAN::soft_chdir_with_alternatives ;
481 sub soft_chdir_with_alternatives ($) {
482     my($cwd) = @_;
483     unless (@$cwd) {
484         my $root = File::Spec->rootdir();
485         $CPAN::Frontend->mywarn(qq{Warning: no good directory to chdir to!
486 Trying '$root' as temporary haven.
487 });
488         push @$cwd, $root;
489     }
490     while () {
491         if (chdir $cwd->[0]) {
492             return;
493         } else {
494             if (@$cwd>1) {
495                 $CPAN::Frontend->mywarn(qq{Could not chdir to "$cwd->[0]": $!
496 Trying to chdir to "$cwd->[1]" instead.
497 });
498                 shift @$cwd;
499             } else {
500                 $CPAN::Frontend->mydie(qq{Could not chdir to "$cwd->[0]": $!});
501             }
502         }
503     }
504 }
505
506 sub _flock {
507     my($fh,$mode) = @_;
508     if ( $Config::Config{d_flock} || $Config::Config{d_fcntl_can_lock} ) {
509         return flock $fh, $mode;
510     } elsif (!$Have_warned->{"d_flock"}++) {
511         $CPAN::Frontend->mywarn("Your OS does not seem to support locking; continuing and ignoring all locking issues\n");
512         $CPAN::Frontend->mysleep(5);
513         return 1;
514     } else {
515         return 1;
516     }
517 }
518
519 sub _yaml_module () {
520     my $yaml_module = $CPAN::Config->{yaml_module} || "YAML";
521     if (
522         $yaml_module ne "YAML"
523         &&
524         !$CPAN::META->has_inst($yaml_module)
525        ) {
526         # $CPAN::Frontend->mywarn("'$yaml_module' not installed, falling back to 'YAML'\n");
527         $yaml_module = "YAML";
528     }
529     if ($yaml_module eq "YAML"
530         &&
531         $CPAN::META->has_inst($yaml_module)
532         &&
533         $YAML::VERSION < 0.60
534         &&
535         !$Have_warned->{"YAML"}++
536        ) {
537         $CPAN::Frontend->mywarn("Warning: YAML version '$YAML::VERSION' is too low, please upgrade!\n".
538                                 "I'll continue but problems are *very* likely to happen.\n"
539                                );
540         $CPAN::Frontend->mysleep(5);
541     }
542     return $yaml_module;
543 }
544
545 # CPAN::_yaml_loadfile
546 sub _yaml_loadfile {
547     my($self,$local_file) = @_;
548     return +[] unless -s $local_file;
549     my $yaml_module = _yaml_module;
550     if ($CPAN::META->has_inst($yaml_module)) {
551         # temporarily enable yaml code deserialisation
552         no strict 'refs';
553         # 5.6.2 could not do the local() with the reference
554         # so we do it manually instead
555         my $old_loadcode = ${"$yaml_module\::LoadCode"};
556         ${ "$yaml_module\::LoadCode" } = $CPAN::Config->{yaml_load_code} || 0;
557
558         my ($code, @yaml);
559         if ($code = UNIVERSAL::can($yaml_module, "LoadFile")) {
560             eval { @yaml = $code->($local_file); };
561             if ($@) {
562                 # this shall not be done by the frontend
563                 die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
564             }
565         } elsif ($code = UNIVERSAL::can($yaml_module, "Load")) {
566             local *FH;
567             open FH, $local_file or die "Could not open '$local_file': $!";
568             local $/;
569             my $ystream = <FH>;
570             eval { @yaml = $code->($ystream); };
571             if ($@) {
572                 # this shall not be done by the frontend
573                 die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
574             }
575         }
576         ${"$yaml_module\::LoadCode"} = $old_loadcode;
577         return \@yaml;
578     } else {
579         # this shall not be done by the frontend
580         die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "parse");
581     }
582     return +[];
583 }
584
585 # CPAN::_yaml_dumpfile
586 sub _yaml_dumpfile {
587     my($self,$local_file,@what) = @_;
588     my $yaml_module = _yaml_module;
589     if ($CPAN::META->has_inst($yaml_module)) {
590         my $code;
591         if (UNIVERSAL::isa($local_file, "FileHandle")) {
592             $code = UNIVERSAL::can($yaml_module, "Dump");
593             eval { print $local_file $code->(@what) };
594         } elsif ($code = UNIVERSAL::can($yaml_module, "DumpFile")) {
595             eval { $code->($local_file,@what); };
596         } elsif ($code = UNIVERSAL::can($yaml_module, "Dump")) {
597             local *FH;
598             open FH, ">$local_file" or die "Could not open '$local_file': $!";
599             print FH $code->(@what);
600         }
601         if ($@) {
602             die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"dump",$@);
603         }
604     } else {
605         if (UNIVERSAL::isa($local_file, "FileHandle")) {
606             # I think this case does not justify a warning at all
607         } else {
608             die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "dump");
609         }
610     }
611 }
612
613 sub _init_sqlite () {
614     unless ($CPAN::META->has_inst("CPAN::SQLite")) {
615         $CPAN::Frontend->mywarn(qq{CPAN::SQLite not installed, trying to work without\n})
616             unless $Have_warned->{"CPAN::SQLite"}++;
617         return;
618     }
619     require CPAN::SQLite::META; # not needed since CVS version of 2006-12-17
620     $CPAN::SQLite ||= CPAN::SQLite::META->new($CPAN::META);
621 }
622
623 {
624     my $negative_cache = {};
625     sub _sqlite_running {
626         if ($negative_cache->{time} && time < $negative_cache->{time} + 60) {
627             # need to cache the result, otherwise too slow
628             return $negative_cache->{fact};
629         } else {
630             $negative_cache = {}; # reset
631         }
632         my $ret = $CPAN::Config->{use_sqlite} && ($CPAN::SQLite || _init_sqlite());
633         return $ret if $ret; # fast anyway
634         $negative_cache->{time} = time;
635         return $negative_cache->{fact} = $ret;
636     }
637 }
638
639 $META ||= CPAN->new; # In case we re-eval ourselves we need the ||
640
641 # from here on only subs.
642 ################################################################################
643
644 sub _perl_fingerprint {
645     my($self,$other_fingerprint) = @_;
646     my $dll = eval {OS2::DLLname()};
647     my $mtime_dll = 0;
648     if (defined $dll) {
649         $mtime_dll = (-f $dll ? (stat(_))[9] : '-1');
650     }
651     my $mtime_perl = (-f CPAN::find_perl ? (stat(_))[9] : '-1');
652     my $this_fingerprint = {
653                             '$^X' => CPAN::find_perl,
654                             sitearchexp => $Config::Config{sitearchexp},
655                             'mtime_$^X' => $mtime_perl,
656                             'mtime_dll' => $mtime_dll,
657                            };
658     if ($other_fingerprint) {
659         if (exists $other_fingerprint->{'stat($^X)'}) { # repair fp from rev. 1.88_57
660             $other_fingerprint->{'mtime_$^X'} = $other_fingerprint->{'stat($^X)'}[9];
661         }
662         # mandatory keys since 1.88_57
663         for my $key (qw($^X sitearchexp mtime_dll mtime_$^X)) {
664             return unless $other_fingerprint->{$key} eq $this_fingerprint->{$key};
665         }
666         return 1;
667     } else {
668         return $this_fingerprint;
669     }
670 }
671
672 sub suggest_myconfig () {
673   SUGGEST_MYCONFIG: if(!$INC{'CPAN/MyConfig.pm'}) {
674         $CPAN::Frontend->myprint("You don't seem to have a user ".
675                                  "configuration (MyConfig.pm) yet.\n");
676         my $new = CPAN::Shell::colorable_makemaker_prompt("Do you want to create a ".
677                                               "user configuration now? (Y/n)",
678                                               "yes");
679         if($new =~ m{^y}i) {
680             CPAN::Shell->mkmyconfig();
681             return &checklock;
682         } else {
683             $CPAN::Frontend->mydie("OK, giving up.");
684         }
685     }
686 }
687
688 #-> sub CPAN::all_objects ;
689 sub all_objects {
690     my($mgr,$class) = @_;
691     CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
692     CPAN->debug("mgr[$mgr] class[$class]") if $CPAN::DEBUG;
693     CPAN::Index->reload;
694     values %{ $META->{readwrite}{$class} }; # unsafe meta access, ok
695 }
696
697 # Called by shell, not in batch mode. In batch mode I see no risk in
698 # having many processes updating something as installations are
699 # continually checked at runtime. In shell mode I suspect it is
700 # unintentional to open more than one shell at a time
701
702 #-> sub CPAN::checklock ;
703 sub checklock {
704     my($self) = @_;
705     my $lockfile = File::Spec->catfile($CPAN::Config->{cpan_home},".lock");
706     if (-f $lockfile && -M _ > 0) {
707         my $fh = FileHandle->new($lockfile) or
708             $CPAN::Frontend->mydie("Could not open lockfile '$lockfile': $!");
709         my $otherpid  = <$fh>;
710         my $otherhost = <$fh>;
711         $fh->close;
712         if (defined $otherpid && length $otherpid) {
713             chomp $otherpid;
714         }
715         if (defined $otherhost && length $otherhost) {
716             chomp $otherhost;
717         }
718         my $thishost  = hostname();
719         my $ask_if_degraded_wanted = 0;
720         if (defined $otherhost && defined $thishost &&
721             $otherhost ne '' && $thishost ne '' &&
722             $otherhost ne $thishost) {
723             $CPAN::Frontend->mydie(sprintf("CPAN.pm panic: Lockfile '$lockfile'\n".
724                                            "reports other host $otherhost and other ".
725                                            "process $otherpid.\n".
726                                            "Cannot proceed.\n"));
727         } elsif ($RUN_DEGRADED) {
728             $CPAN::Frontend->mywarn("Running in downgraded mode (experimental)\n");
729         } elsif (defined $otherpid && $otherpid) {
730             return if $$ == $otherpid; # should never happen
731             $CPAN::Frontend->mywarn(
732                                     qq{
733 There seems to be running another CPAN process (pid $otherpid).  Contacting...
734 });
735             if (kill 0, $otherpid or $!{EPERM}) {
736                 $CPAN::Frontend->mywarn(qq{Other job is running.\n});
737                 $ask_if_degraded_wanted = 1;
738             } elsif (-w $lockfile) {
739                 my($ans) =
740                     CPAN::Shell::colorable_makemaker_prompt
741                         (qq{Other job not responding. Shall I overwrite }.
742                         qq{the lockfile '$lockfile'? (Y/n)},"y");
743             $CPAN::Frontend->myexit("Ok, bye\n")
744                 unless $ans =~ /^y/i;
745             } else {
746                 Carp::croak(
747                     qq{Lockfile '$lockfile' not writable by you. }.
748                     qq{Cannot proceed.\n}.
749                     qq{    On UNIX try:\n}.
750                     qq{    rm '$lockfile'\n}.
751                     qq{  and then rerun us.\n}
752                 );
753             }
754         } elsif ($^O eq "MSWin32") {
755             $CPAN::Frontend->mywarn(
756                                     qq{
757 There seems to be running another CPAN process according to '$lockfile'.
758 });
759             $ask_if_degraded_wanted = 1;
760         } else {
761             $CPAN::Frontend->mydie(sprintf("CPAN.pm panic: Found invalid lockfile ".
762                                            "'$lockfile', please remove. Cannot proceed.\n"));
763         }
764         if ($ask_if_degraded_wanted) {
765             my($ans) =
766                 CPAN::Shell::colorable_makemaker_prompt
767                     (qq{Shall I try to run in downgraded }.
768                      qq{mode? (Y/n)},"y");
769             if ($ans =~ /^y/i) {
770                 $CPAN::Frontend->mywarn("Running in downgraded mode (experimental).
771 Please report if something unexpected happens\n");
772                 $RUN_DEGRADED = 1;
773                 for ($CPAN::Config) {
774                     # XXX
775                     # $_->{build_dir_reuse} = 0; # 2006-11-17 akoenig Why was that?
776                     $_->{commandnumber_in_prompt} = 0; # visibility
777                     $_->{histfile}       = "";  # who should win otherwise?
778                     $_->{cache_metadata} = 0;   # better would be a lock?
779                     $_->{use_sqlite}     = 0;   # better would be a write lock!
780                     $_->{auto_commit}    = 0;   # we are violent, do not persist
781                     $_->{test_report}    = 0;   # Oliver Paukstadt had sent wrong reports in degraded mode
782                 }
783             } else {
784                 my $msg = "You may want to kill the other job and delete the lockfile.";
785                 if (defined $otherpid) {
786                     $msg .= " Something like:
787     kill $otherpid
788     rm $lockfile
789 ";
790                 }
791                 $CPAN::Frontend->mydie("\n$msg");
792             }
793         }
794     }
795     my $dotcpan = $CPAN::Config->{cpan_home};
796     eval { File::Path::mkpath($dotcpan);};
797     if ($@) {
798         # A special case at least for Jarkko.
799         my $firsterror = $@;
800         my $seconderror;
801         my $symlinkcpan;
802         if (-l $dotcpan) {
803             $symlinkcpan = readlink $dotcpan;
804             die "readlink $dotcpan failed: $!" unless defined $symlinkcpan;
805             eval { File::Path::mkpath($symlinkcpan); };
806             if ($@) {
807                 $seconderror = $@;
808             } else {
809                 $CPAN::Frontend->mywarn(qq{
810 Working directory $symlinkcpan created.
811 });
812             }
813         }
814         unless (-d $dotcpan) {
815             my $mess = qq{
816 Your configuration suggests "$dotcpan" as your
817 CPAN.pm working directory. I could not create this directory due
818 to this error: $firsterror\n};
819             $mess .= qq{
820 As "$dotcpan" is a symlink to "$symlinkcpan",
821 I tried to create that, but I failed with this error: $seconderror
822 } if $seconderror;
823             $mess .= qq{
824 Please make sure the directory exists and is writable.
825 };
826             $CPAN::Frontend->mywarn($mess);
827             return suggest_myconfig;
828         }
829     } # $@ after eval mkpath $dotcpan
830     if (0) { # to test what happens when a race condition occurs
831         for (reverse 1..10) {
832             print $_, "\n";
833             sleep 1;
834         }
835     }
836     # locking
837     if (!$RUN_DEGRADED && !$self->{LOCKFH}) {
838         my $fh;
839         unless ($fh = FileHandle->new("+>>$lockfile")) {
840             $CPAN::Frontend->mywarn(qq{
841
842 Your configuration suggests that CPAN.pm should use a working
843 directory of
844     $CPAN::Config->{cpan_home}
845 Unfortunately we could not create the lock file
846     $lockfile
847 due to '$!'.
848
849 Please make sure that the configuration variable
850     \$CPAN::Config->{cpan_home}
851 points to a directory where you can write a .lock file. You can set
852 this variable in either a CPAN/MyConfig.pm or a CPAN/Config.pm in your
853 \@INC path;
854 });
855             return suggest_myconfig;
856         }
857         my $sleep = 1;
858         while (!CPAN::_flock($fh, LOCK_EX|LOCK_NB)) {
859             if ($sleep>10) {
860                 $CPAN::Frontend->mydie("Giving up\n");
861             }
862             $CPAN::Frontend->mysleep($sleep++);
863             $CPAN::Frontend->mywarn("Could not lock lockfile with flock: $!; retrying\n");
864         }
865
866         seek $fh, 0, 0;
867         truncate $fh, 0;
868         $fh->autoflush(1);
869         $fh->print($$, "\n");
870         $fh->print(hostname(), "\n");
871         $self->{LOCK} = $lockfile;
872         $self->{LOCKFH} = $fh;
873     }
874     $SIG{TERM} = sub {
875         my $sig = shift;
876         &cleanup;
877         $CPAN::Frontend->mydie("Got SIG$sig, leaving");
878     };
879     $SIG{INT} = sub {
880       # no blocks!!!
881         my $sig = shift;
882         &cleanup if $Signal;
883         die "Got yet another signal" if $Signal > 1;
884         $CPAN::Frontend->mydie("Got another SIG$sig") if $Signal;
885         $CPAN::Frontend->mywarn("Caught SIG$sig, trying to continue\n");
886         $Signal++;
887     };
888
889 #       From: Larry Wall <larry@wall.org>
890 #       Subject: Re: deprecating SIGDIE
891 #       To: perl5-porters@perl.org
892 #       Date: Thu, 30 Sep 1999 14:58:40 -0700 (PDT)
893 #
894 #       The original intent of __DIE__ was only to allow you to substitute one
895 #       kind of death for another on an application-wide basis without respect
896 #       to whether you were in an eval or not.  As a global backstop, it should
897 #       not be used any more lightly (or any more heavily :-) than class
898 #       UNIVERSAL.  Any attempt to build a general exception model on it should
899 #       be politely squashed.  Any bug that causes every eval {} to have to be
900 #       modified should be not so politely squashed.
901 #
902 #       Those are my current opinions.  It is also my opinion that polite
903 #       arguments degenerate to personal arguments far too frequently, and that
904 #       when they do, it's because both people wanted it to, or at least didn't
905 #       sufficiently want it not to.
906 #
907 #       Larry
908
909     # global backstop to cleanup if we should really die
910     $SIG{__DIE__} = \&cleanup;
911     $self->debug("Signal handler set.") if $CPAN::DEBUG;
912 }
913
914 #-> sub CPAN::DESTROY ;
915 sub DESTROY {
916     &cleanup; # need an eval?
917 }
918
919 #-> sub CPAN::anycwd ;
920 sub anycwd () {
921     my $getcwd;
922     $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
923     CPAN->$getcwd();
924 }
925
926 #-> sub CPAN::cwd ;
927 sub cwd {Cwd::cwd();}
928
929 #-> sub CPAN::getcwd ;
930 sub getcwd {Cwd::getcwd();}
931
932 #-> sub CPAN::fastcwd ;
933 sub fastcwd {Cwd::fastcwd();}
934
935 #-> sub CPAN::getdcwd ;
936 sub getdcwd {Cwd::getdcwd();}
937
938 #-> sub CPAN::backtickcwd ;
939 sub backtickcwd {my $cwd = `cwd`; chomp $cwd; $cwd}
940
941 # Adapted from Probe::Perl
942 #-> sub CPAN::_perl_is_same
943 sub _perl_is_same {
944   my ($perl) = @_;
945   return MM->maybe_command($perl)
946     && `$perl -MConfig=myconfig -e print -e myconfig` eq Config->myconfig;
947 }
948
949 # Adapted in part from Probe::Perl
950 #-> sub CPAN::find_perl ;
951 sub find_perl () {
952     if ( File::Spec->file_name_is_absolute($^X) ) {
953         return $^X;
954     }
955     else {
956         my $exe = $Config::Config{exe_ext};
957         my @candidates = (
958             File::Spec->catfile($CPAN::iCwd,$^X),
959             $Config::Config{'perlpath'},
960         );
961         for my $perl_name ($^X, 'perl', 'perl5', "perl$]") {
962             for my $path (File::Spec->path(), $Config::Config{'binexp'}) {
963                 if ( defined($path) && length $path && -d $path ) {
964                     my $perl = File::Spec->catfile($path,$perl_name);
965                     push @candidates, $perl;
966                     # try with extension if not provided already
967                     if ($^O eq 'VMS') {
968                         # VMS might have a file version at the end
969                         push @candidates, $perl . $exe
970                             unless $perl =~ m/$exe(;\d+)?$/i;
971                     } elsif (defined $exe && length $exe) {
972                         push @candidates, $perl . $exe
973                             unless $perl =~ m/$exe$/i;
974                     }
975                 }
976             }
977         }
978         for my $perl ( @candidates ) {
979             if (MM->maybe_command($perl) && _perl_is_same($perl)) {
980                 $^X = $perl;
981                 return $perl;
982             }
983         }
984     }
985     return $^X; # default fall back
986 }
987
988 #-> sub CPAN::exists ;
989 sub exists {
990     my($mgr,$class,$id) = @_;
991     CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
992     CPAN::Index->reload;
993     ### Carp::croak "exists called without class argument" unless $class;
994     $id ||= "";
995     $id =~ s/:+/::/g if $class eq "CPAN::Module";
996     my $exists;
997     if (CPAN::_sqlite_running) {
998         $exists = (exists $META->{readonly}{$class}{$id} or
999                    $CPAN::SQLite->set($class, $id));
1000     } else {
1001         $exists =  exists $META->{readonly}{$class}{$id};
1002     }
1003     $exists ||= exists $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
1004 }
1005
1006 #-> sub CPAN::delete ;
1007 sub delete {
1008   my($mgr,$class,$id) = @_;
1009   delete $META->{readonly}{$class}{$id}; # unsafe meta access, ok
1010   delete $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
1011 }
1012
1013 #-> sub CPAN::has_usable
1014 # has_inst is sometimes too optimistic, we should replace it with this
1015 # has_usable whenever a case is given
1016 sub has_usable {
1017     my($self,$mod,$message) = @_;
1018     return 1 if $HAS_USABLE->{$mod};
1019     my $has_inst = $self->has_inst($mod,$message);
1020     return unless $has_inst;
1021     my $usable;
1022     $usable = {
1023
1024                #
1025                # these subroutines die if they believe the installed version is unusable;
1026                #
1027                'CPAN::Meta' => [
1028                             sub {
1029                                 require CPAN::Meta;
1030                                 unless (CPAN::Version->vge(CPAN::Meta->VERSION, 2.110350)) {
1031                                     for ("Will not use CPAN::Meta, need version 2.110350\n") {
1032                                         $CPAN::Frontend->mywarn($_);
1033                                         die $_;
1034                                     }
1035                                 }
1036                             },
1037                            ],
1038
1039                'CPAN::Meta::Requirements' => [
1040                             sub {
1041                                 require CPAN::Meta::Requirements;
1042                                 unless (CPAN::Version->vge(CPAN::Meta::Requirements->VERSION, 2.120920)) {
1043                                     for ("Will not use CPAN::Meta::Requirements, need version 2.120920\n") {
1044                                         $CPAN::Frontend->mywarn($_);
1045                                         die $_;
1046                                     }
1047                                 }
1048                             },
1049                            ],
1050
1051                LWP => [ # we frequently had "Can't locate object
1052                         # method "new" via package "LWP::UserAgent" at
1053                         # (eval 69) line 2006
1054                        sub {require LWP},
1055                        sub {require LWP::UserAgent},
1056                        sub {require HTTP::Request},
1057                        sub {require URI::URL;
1058                             unless (CPAN::Version->vge(URI::URL::->VERSION,0.08)) {
1059                                 for ("Will not use URI::URL, need 0.08\n") {
1060                                     $CPAN::Frontend->mywarn($_);
1061                                     die $_;
1062                                 }
1063                             }
1064                        },
1065                       ],
1066                'Net::FTP' => [
1067                             sub {
1068                                 my $var = $CPAN::Config->{ftp_proxy} || $ENV{ftp_proxy};
1069                                 if ($var and $var =~ /^http:/i) {
1070                                     # rt #110833
1071                                     for ("Net::FTP cannot handle http proxy") {
1072                                         $CPAN::Frontend->mywarn($_);
1073                                         die $_;
1074                                     }
1075                                 }
1076                             },
1077                             sub {require Net::FTP},
1078                             sub {require Net::Config},
1079                            ],
1080                'HTTP::Tiny' => [
1081                             sub {
1082                                 require HTTP::Tiny;
1083                                 unless (CPAN::Version->vge(HTTP::Tiny->VERSION, 0.005)) {
1084                                     for ("Will not use HTTP::Tiny, need version 0.005\n") {
1085                                         $CPAN::Frontend->mywarn($_);
1086                                         die $_;
1087                                     }
1088                                 }
1089                             },
1090                            ],
1091                'File::HomeDir' => [
1092                                    sub {require File::HomeDir;
1093                                         unless (CPAN::Version->vge(File::HomeDir::->VERSION, 0.52)) {
1094                                             for ("Will not use File::HomeDir, need 0.52\n") {
1095                                                 $CPAN::Frontend->mywarn($_);
1096                                                 die $_;
1097                                             }
1098                                         }
1099                                     },
1100                                   ],
1101                'Archive::Tar' => [
1102                                   sub {require Archive::Tar;
1103                                        my $demand = "1.50";
1104                                        unless (CPAN::Version->vge(Archive::Tar::->VERSION, $demand)) {
1105                                             my $atv = Archive::Tar->VERSION;
1106                                             for ("You have Archive::Tar $atv, but $demand or later is recommended. Please upgrade.\n") {
1107                                                 $CPAN::Frontend->mywarn($_);
1108                                             # don't die, because we may need
1109                                             # Archive::Tar to upgrade
1110                                             }
1111
1112                                        }
1113                                   },
1114                                  ],
1115                'File::Temp' => [
1116                                 # XXX we should probably delete from
1117                                 # %INC too so we can load after we
1118                                 # installed a new enough version --
1119                                 # I'm not sure.
1120                                 sub {require File::Temp;
1121                                      unless (CPAN::Version->vge(File::Temp::->VERSION,0.16)) {
1122                                          for ("Will not use File::Temp, need 0.16\n") {
1123                                                 $CPAN::Frontend->mywarn($_);
1124                                                 die $_;
1125                                          }
1126                                      }
1127                                 },
1128                                ]
1129               };
1130     if ($usable->{$mod}) {
1131         local @INC = @INC;
1132         pop @INC if $INC[-1] eq '.';
1133         for my $c (0..$#{$usable->{$mod}}) {
1134             my $code = $usable->{$mod}[$c];
1135             my $ret = eval { &$code() };
1136             $ret = "" unless defined $ret;
1137             if ($@) {
1138                 # warn "DEBUG: c[$c]\$\@[$@]ret[$ret]";
1139                 return;
1140             }
1141         }
1142     }
1143     return $HAS_USABLE->{$mod} = 1;
1144 }
1145
1146 sub frontend {
1147     shift;
1148     $CPAN::Frontend = shift if @_;
1149     $CPAN::Frontend;
1150 }
1151
1152 sub use_inst {
1153     my ($self, $module) = @_;
1154
1155     unless ($self->has_inst($module)) {
1156         $self->frontend->mydie("$module not installed, cannot continue");
1157     }
1158 }
1159
1160 #-> sub CPAN::has_inst
1161 sub has_inst {
1162     my($self,$mod,$message) = @_;
1163     Carp::croak("CPAN->has_inst() called without an argument")
1164         unless defined $mod;
1165     my %dont = map { $_ => 1 } keys %{$CPAN::META->{dontload_hash}||{}},
1166         keys %{$CPAN::Config->{dontload_hash}||{}},
1167             @{$CPAN::Config->{dontload_list}||[]};
1168     if (defined $message && $message eq "no"  # as far as I remember only used by Nox
1169         ||
1170         $dont{$mod}
1171        ) {
1172       $CPAN::META->{dontload_hash}{$mod}||=1; # unsafe meta access, ok
1173       return 0;
1174     }
1175     local @INC = @INC;
1176     pop @INC if $INC[-1] eq '.';
1177     my $file = $mod;
1178     my $obj;
1179     $file =~ s|::|/|g;
1180     $file .= ".pm";
1181     if ($INC{$file}) {
1182         # checking %INC is wrong, because $INC{LWP} may be true
1183         # although $INC{"URI/URL.pm"} may have failed. But as
1184         # I really want to say "blah loaded OK", I have to somehow
1185         # cache results.
1186         ### warn "$file in %INC"; #debug
1187         return 1;
1188     } elsif (eval { require $file }) {
1189         # eval is good: if we haven't yet read the database it's
1190         # perfect and if we have installed the module in the meantime,
1191         # it tries again. The second require is only a NOOP returning
1192         # 1 if we had success, otherwise it's retrying
1193
1194         my $mtime = (stat $INC{$file})[9];
1195         # privileged files loaded by has_inst; Note: we use $mtime
1196         # as a proxy for a checksum.
1197         $CPAN::Shell::reload->{$file} = $mtime;
1198         my $v = eval "\$$mod\::VERSION";
1199         $v = $v ? " (v$v)" : "";
1200         CPAN::Shell->optprint("load_module","CPAN: $mod loaded ok$v\n");
1201         if ($mod eq "CPAN::WAIT") {
1202             push @CPAN::Shell::ISA, 'CPAN::WAIT';
1203         }
1204         return 1;
1205     } elsif ($mod eq "Net::FTP") {
1206         $CPAN::Frontend->mywarn(qq{
1207   Please, install Net::FTP as soon as possible. CPAN.pm installs it for you
1208   if you just type
1209       install Bundle::libnet
1210
1211 }) unless $Have_warned->{"Net::FTP"}++;
1212         $CPAN::Frontend->mysleep(3);
1213     } elsif ($mod eq "Digest::SHA") {
1214         if ($Have_warned->{"Digest::SHA"}++) {
1215             $CPAN::Frontend->mywarn(qq{CPAN: checksum security checks disabled }.
1216                                      qq{because Digest::SHA not installed.\n});
1217         } else {
1218             $CPAN::Frontend->mywarn(qq{
1219   CPAN: checksum security checks disabled because Digest::SHA not installed.
1220   Please consider installing the Digest::SHA module.
1221
1222 });
1223             $CPAN::Frontend->mysleep(2);
1224         }
1225     } elsif ($mod eq "Module::Signature") {
1226         # NOT prefs_lookup, we are not a distro
1227         my $check_sigs = $CPAN::Config->{check_sigs};
1228         if (not $check_sigs) {
1229             # they do not want us:-(
1230         } elsif (not $Have_warned->{"Module::Signature"}++) {
1231             # No point in complaining unless the user can
1232             # reasonably install and use it.
1233             if (eval { require Crypt::OpenPGP; 1 } ||
1234                 (
1235                  defined $CPAN::Config->{'gpg'}
1236                  &&
1237                  $CPAN::Config->{'gpg'} =~ /\S/
1238                 )
1239                ) {
1240                 $CPAN::Frontend->mywarn(qq{
1241   CPAN: Module::Signature security checks disabled because Module::Signature
1242   not installed.  Please consider installing the Module::Signature module.
1243   You may also need to be able to connect over the Internet to the public
1244   key servers like pool.sks-keyservers.net or pgp.mit.edu.
1245
1246 });
1247                 $CPAN::Frontend->mysleep(2);
1248             }
1249         }
1250     } else {
1251         delete $INC{$file}; # if it inc'd LWP but failed during, say, URI
1252     }
1253     return 0;
1254 }
1255
1256 #-> sub CPAN::instance ;
1257 sub instance {
1258     my($mgr,$class,$id) = @_;
1259     CPAN::Index->reload;
1260     $id ||= "";
1261     # unsafe meta access, ok?
1262     return $META->{readwrite}{$class}{$id} if exists $META->{readwrite}{$class}{$id};
1263     $META->{readwrite}{$class}{$id} ||= $class->new(ID => $id);
1264 }
1265
1266 #-> sub CPAN::new ;
1267 sub new {
1268     bless {}, shift;
1269 }
1270
1271 #-> sub CPAN::_exit_messages ;
1272 sub _exit_messages {
1273     my ($self) = @_;
1274     $self->{exit_messages} ||= [];
1275 }
1276
1277 #-> sub CPAN::cleanup ;
1278 sub cleanup {
1279   # warn "cleanup called with arg[@_] End[$CPAN::End] Signal[$Signal]";
1280   local $SIG{__DIE__} = '';
1281   my($message) = @_;
1282   my $i = 0;
1283   my $ineval = 0;
1284   my($subroutine);
1285   while ((undef,undef,undef,$subroutine) = caller(++$i)) {
1286       $ineval = 1, last if
1287         $subroutine eq '(eval)';
1288   }
1289   return if $ineval && !$CPAN::End;
1290   return unless defined $META->{LOCK};
1291   return unless -f $META->{LOCK};
1292   $META->savehist;
1293   $META->{cachemgr} ||= CPAN::CacheMgr->new('atexit');
1294   close $META->{LOCKFH};
1295   unlink $META->{LOCK};
1296   # require Carp;
1297   # Carp::cluck("DEBUGGING");
1298   if ( $CPAN::CONFIG_DIRTY ) {
1299       $CPAN::Frontend->mywarn("Warning: Configuration not saved.\n");
1300   }
1301   $CPAN::Frontend->myprint("Lockfile removed.\n");
1302   for my $msg ( @{ $META->_exit_messages } ) {
1303       $CPAN::Frontend->myprint($msg);
1304   }
1305 }
1306
1307 #-> sub CPAN::readhist
1308 sub readhist {
1309     my($self,$term,$histfile) = @_;
1310     my $histsize = $CPAN::Config->{'histsize'} || 100;
1311     $term->Attribs->{'MaxHistorySize'} = $histsize if (defined($term->Attribs->{'MaxHistorySize'}));
1312     my($fh) = FileHandle->new;
1313     open $fh, "<$histfile" or return;
1314     local $/ = "\n";
1315     while (<$fh>) {
1316         chomp;
1317         $term->AddHistory($_);
1318     }
1319     close $fh;
1320 }
1321
1322 #-> sub CPAN::savehist
1323 sub savehist {
1324     my($self) = @_;
1325     my($histfile,$histsize);
1326     unless ($histfile = $CPAN::Config->{'histfile'}) {
1327         $CPAN::Frontend->mywarn("No history written (no histfile specified).\n");
1328         return;
1329     }
1330     $histsize = $CPAN::Config->{'histsize'} || 100;
1331     if ($CPAN::term) {
1332         unless ($CPAN::term->can("GetHistory")) {
1333             $CPAN::Frontend->mywarn("Terminal does not support GetHistory.\n");
1334             return;
1335         }
1336     } else {
1337         return;
1338     }
1339     my @h = $CPAN::term->GetHistory;
1340     splice @h, 0, @h-$histsize if @h>$histsize;
1341     my($fh) = FileHandle->new;
1342     open $fh, ">$histfile" or $CPAN::Frontend->mydie("Couldn't open >$histfile: $!");
1343     local $\ = local $, = "\n";
1344     print $fh @h;
1345     close $fh;
1346 }
1347
1348 #-> sub CPAN::is_tested
1349 sub is_tested {
1350     my($self,$what,$when) = @_;
1351     unless ($what) {
1352         Carp::cluck("DEBUG: empty what");
1353         return;
1354     }
1355     $self->{is_tested}{$what} = $when;
1356 }
1357
1358 #-> sub CPAN::reset_tested
1359 # forget all distributions tested -- resets what gets included in PERL5LIB
1360 sub reset_tested {
1361     my ($self) = @_;
1362     $self->{is_tested} = {};
1363 }
1364
1365 #-> sub CPAN::is_installed
1366 # unsets the is_tested flag: as soon as the thing is installed, it is
1367 # not needed in set_perl5lib anymore
1368 sub is_installed {
1369     my($self,$what) = @_;
1370     delete $self->{is_tested}{$what};
1371 }
1372
1373 sub _list_sorted_descending_is_tested {
1374     my($self) = @_;
1375     my $foul = 0;
1376     my @sorted = sort
1377         { ($self->{is_tested}{$b}||0) <=> ($self->{is_tested}{$a}||0) }
1378             grep
1379                 { if ($foul){ 0 } elsif (-e) { 1 } else { $foul = $_; 0 } }
1380                     keys %{$self->{is_tested}};
1381     if ($foul) {
1382         $CPAN::Frontend->mywarn("Lost build_dir detected ($foul), giving up all cached test results of currently running session.\n");
1383         for my $dbd (sort keys %{$self->{is_tested}}) { # distro-build-dir
1384         SEARCH: for my $d (sort { $a->id cmp $b->id } $CPAN::META->all_objects("CPAN::Distribution")) {
1385                 if ($d->{build_dir} && $d->{build_dir} eq $dbd) {
1386                     $CPAN::Frontend->mywarn(sprintf "Flushing cache for %s\n", $d->pretty_id);
1387                     $d->fforce("");
1388                     last SEARCH;
1389                 }
1390             }
1391             delete $self->{is_tested}{$dbd};
1392         }
1393         return ();
1394     } else {
1395         return @sorted;
1396     }
1397 }
1398
1399 #-> sub CPAN::set_perl5lib
1400 # Notes on max environment variable length:
1401 #   - Win32 : XP or later, 8191; Win2000 or NT4, 2047
1402 {
1403 my $fh;
1404 sub set_perl5lib {
1405     my($self,$for) = @_;
1406     unless ($for) {
1407         (undef,undef,undef,$for) = caller(1);
1408         $for =~ s/.*://;
1409     }
1410     $self->{is_tested} ||= {};
1411     return unless %{$self->{is_tested}};
1412     my $env = $ENV{PERL5LIB};
1413     $env = $ENV{PERLLIB} unless defined $env;
1414     my @env;
1415     push @env, split /\Q$Config::Config{path_sep}\E/, $env if defined $env and length $env;
1416     #my @dirs = map {("$_/blib/arch", "$_/blib/lib")} keys %{$self->{is_tested}};
1417     #$CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB.\n");
1418
1419     my @dirs = map {("$_/blib/arch", "$_/blib/lib")} $self->_list_sorted_descending_is_tested;
1420     return if !@dirs;
1421
1422     if (@dirs < 12) {
1423         $CPAN::Frontend->optprint('perl5lib', "Prepending @dirs to PERL5LIB for '$for'\n");
1424         $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1425     } elsif (@dirs < 24 ) {
1426         my @d = map {my $cp = $_;
1427                      $cp =~ s/^\Q$CPAN::Config->{build_dir}\E/%BUILDDIR%/;
1428                      $cp
1429                  } @dirs;
1430         $CPAN::Frontend->optprint('perl5lib', "Prepending @d to PERL5LIB; ".
1431                                  "%BUILDDIR%=$CPAN::Config->{build_dir} ".
1432                                  "for '$for'\n"
1433                                 );
1434         $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1435     } else {
1436         my $cnt = keys %{$self->{is_tested}};
1437         $CPAN::Frontend->optprint('perl5lib', "Prepending blib/arch and blib/lib of ".
1438                                  "$cnt build dirs to PERL5LIB; ".
1439                                  "for '$for'\n"
1440                                 );
1441         $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1442     }
1443 }}
1444
1445
1446 1;
1447
1448
1449 __END__
1450
1451 =head1 NAME
1452
1453 CPAN - query, download and build perl modules from CPAN sites
1454
1455 =head1 SYNOPSIS
1456
1457 Interactive mode:
1458
1459   perl -MCPAN -e shell
1460
1461 --or--
1462
1463   cpan
1464
1465 Basic commands:
1466
1467   # Modules:
1468
1469   cpan> install Acme::Meta                       # in the shell
1470
1471   CPAN::Shell->install("Acme::Meta");            # in perl
1472
1473   # Distributions:
1474
1475   cpan> install NWCLARK/Acme-Meta-0.02.tar.gz    # in the shell
1476
1477   CPAN::Shell->
1478     install("NWCLARK/Acme-Meta-0.02.tar.gz");    # in perl
1479
1480   # module objects:
1481
1482   $mo = CPAN::Shell->expandany($mod);
1483   $mo = CPAN::Shell->expand("Module",$mod);      # same thing
1484
1485   # distribution objects:
1486
1487   $do = CPAN::Shell->expand("Module",$mod)->distribution;
1488   $do = CPAN::Shell->expandany($distro);         # same thing
1489   $do = CPAN::Shell->expand("Distribution",
1490                             $distro);            # same thing
1491
1492 =head1 DESCRIPTION
1493
1494 The CPAN module automates or at least simplifies the make and install
1495 of perl modules and extensions. It includes some primitive searching
1496 capabilities and knows how to use LWP, HTTP::Tiny, Net::FTP and certain
1497 external download clients to fetch distributions from the net.
1498
1499 These are fetched from one or more mirrored CPAN (Comprehensive
1500 Perl Archive Network) sites and unpacked in a dedicated directory.
1501
1502 The CPAN module also supports named and versioned
1503 I<bundles> of modules. Bundles simplify handling of sets of
1504 related modules. See Bundles below.
1505
1506 The package contains a session manager and a cache manager. The
1507 session manager keeps track of what has been fetched, built, and
1508 installed in the current session. The cache manager keeps track of the
1509 disk space occupied by the make processes and deletes excess space
1510 using a simple FIFO mechanism.
1511
1512 All methods provided are accessible in a programmer style and in an
1513 interactive shell style.
1514
1515 =head2 CPAN::shell([$prompt, $command]) Starting Interactive Mode
1516
1517 Enter interactive mode by running
1518
1519     perl -MCPAN -e shell
1520
1521 or
1522
1523     cpan
1524
1525 which puts you into a readline interface. If C<Term::ReadKey> and
1526 either of C<Term::ReadLine::Perl> or C<Term::ReadLine::Gnu> are installed,
1527 history and command completion are supported.
1528
1529 Once at the command line, type C<h> for one-page help
1530 screen; the rest should be self-explanatory.
1531
1532 The function call C<shell> takes two optional arguments: one the
1533 prompt, the second the default initial command line (the latter
1534 only works if a real ReadLine interface module is installed).
1535
1536 The most common uses of the interactive modes are
1537
1538 =over 2
1539
1540 =item Searching for authors, bundles, distribution files and modules
1541
1542 There are corresponding one-letter commands C<a>, C<b>, C<d>, and C<m>
1543 for each of the four categories and another, C<i> for any of the
1544 mentioned four. Each of the four entities is implemented as a class
1545 with slightly differing methods for displaying an object.
1546
1547 Arguments to these commands are either strings exactly matching
1548 the identification string of an object, or regular expressions
1549 matched case-insensitively against various attributes of the
1550 objects. The parser only recognizes a regular expression when you
1551 enclose it with slashes.
1552
1553 The principle is that the number of objects found influences how an
1554 item is displayed. If the search finds one item, the result is
1555 displayed with the rather verbose method C<as_string>, but if
1556 more than one is found, each object is displayed with the terse method
1557 C<as_glimpse>.
1558
1559 Examples:
1560
1561   cpan> m Acme::MetaSyntactic
1562   Module id = Acme::MetaSyntactic
1563       CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
1564       CPAN_VERSION 0.99
1565       CPAN_FILE    B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
1566       UPLOAD_DATE  2006-11-06
1567       MANPAGE      Acme::MetaSyntactic - Themed metasyntactic variables names
1568       INST_FILE    /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
1569       INST_VERSION 0.99
1570   cpan> a BOOK
1571   Author id = BOOK
1572       EMAIL        [...]
1573       FULLNAME     Philippe Bruhat (BooK)
1574   cpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz
1575   Distribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
1576       CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
1577       CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
1578       UPLOAD_DATE  2006-11-06
1579   cpan> m /lorem/
1580   Module  = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz)
1581   Module    Text::Lorem            (ADEOLA/Text-Lorem-0.3.tar.gz)
1582   Module    Text::Lorem::More      (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
1583   Module    Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
1584   cpan> i /berlin/
1585   Distribution    BEATNIK/Filter-NumberLines-0.02.tar.gz
1586   Module  = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz)
1587   Module    Filter::NumberLines    (BEATNIK/Filter-NumberLines-0.02.tar.gz)
1588   Author          [...]
1589
1590 The examples illustrate several aspects: the first three queries
1591 target modules, authors, or distros directly and yield exactly one
1592 result. The last two use regular expressions and yield several
1593 results. The last one targets all of bundles, modules, authors, and
1594 distros simultaneously. When more than one result is available, they
1595 are printed in one-line format.
1596
1597 =item C<get>, C<make>, C<test>, C<install>, C<clean> modules or distributions
1598
1599 These commands take any number of arguments and investigate what is
1600 necessary to perform the action. Argument processing is as follows:
1601
1602   known module name in format Foo/Bar.pm   module
1603   other embedded slash                     distribution
1604     - with trailing slash dot              directory
1605   enclosing slashes                        regexp
1606   known module name in format Foo::Bar     module
1607
1608 If the argument is a distribution file name (recognized by embedded
1609 slashes), it is processed. If it is a module, CPAN determines the
1610 distribution file in which this module is included and processes that,
1611 following any dependencies named in the module's META.yml or
1612 Makefile.PL (this behavior is controlled by the configuration
1613 parameter C<prerequisites_policy>). If an argument is enclosed in
1614 slashes it is treated as a regular expression: it is expanded and if
1615 the result is a single object (distribution, bundle or module), this
1616 object is processed.
1617
1618 Example:
1619
1620     install Dummy::Perl                   # installs the module
1621     install AUXXX/Dummy-Perl-3.14.tar.gz  # installs that distribution
1622     install /Dummy-Perl-3.14/             # same if the regexp is unambiguous
1623
1624 C<get> downloads a distribution file and untars or unzips it, C<make>
1625 builds it, C<test> runs the test suite, and C<install> installs it.
1626
1627 Any C<make> or C<test> is run unconditionally. An
1628
1629   install <distribution_file>
1630
1631 is also run unconditionally. But for
1632
1633   install <module>
1634
1635 CPAN checks whether an install is needed and prints
1636 I<module up to date> if the distribution file containing
1637 the module doesn't need updating.
1638
1639 CPAN also keeps track of what it has done within the current session
1640 and doesn't try to build a package a second time regardless of whether it
1641 succeeded or not. It does not repeat a test run if the test
1642 has been run successfully before. Same for install runs.
1643
1644 The C<force> pragma may precede another command (currently: C<get>,
1645 C<make>, C<test>, or C<install>) to execute the command from scratch
1646 and attempt to continue past certain errors. See the section below on
1647 the C<force> and the C<fforce> pragma.
1648
1649 The C<notest> pragma skips the test part in the build
1650 process.
1651
1652 Example:
1653
1654     cpan> notest install Tk
1655
1656 A C<clean> command results in a
1657
1658   make clean
1659
1660 being executed within the distribution file's working directory.
1661
1662 =item C<readme>, C<perldoc>, C<look> module or distribution
1663
1664 C<readme> displays the README file of the associated distribution.
1665 C<Look> gets and untars (if not yet done) the distribution file,
1666 changes to the appropriate directory and opens a subshell process in
1667 that directory. C<perldoc> displays the module's pod documentation
1668 in html or plain text format.
1669
1670 =item C<ls> author
1671
1672 =item C<ls> globbing_expression
1673
1674 The first form lists all distribution files in and below an author's
1675 CPAN directory as stored in the CHECKSUMS files distributed on
1676 CPAN. The listing recurses into subdirectories.
1677
1678 The second form limits or expands the output with shell
1679 globbing as in the following examples:
1680
1681       ls JV/make*
1682       ls GSAR/*make*
1683       ls */*make*
1684
1685 The last example is very slow and outputs extra progress indicators
1686 that break the alignment of the result.
1687
1688 Note that globbing only lists directories explicitly asked for, for
1689 example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be
1690 regarded as a bug that may be changed in some future version.
1691
1692 =item C<failed>
1693
1694 The C<failed> command reports all distributions that failed on one of
1695 C<make>, C<test> or C<install> for some reason in the currently
1696 running shell session.
1697
1698 =item Persistence between sessions
1699
1700 If the C<YAML> or the C<YAML::Syck> module is installed a record of
1701 the internal state of all modules is written to disk after each step.
1702 The files contain a signature of the currently running perl version
1703 for later perusal.
1704
1705 If the configurations variable C<build_dir_reuse> is set to a true
1706 value, then CPAN.pm reads the collected YAML files. If the stored
1707 signature matches the currently running perl, the stored state is
1708 loaded into memory such that persistence between sessions
1709 is effectively established.
1710
1711 =item The C<force> and the C<fforce> pragma
1712
1713 To speed things up in complex installation scenarios, CPAN.pm keeps
1714 track of what it has already done and refuses to do some things a
1715 second time. A C<get>, a C<make>, and an C<install> are not repeated.
1716 A C<test> is repeated only if the previous test was unsuccessful. The
1717 diagnostic message when CPAN.pm refuses to do something a second time
1718 is one of I<Has already been >C<unwrapped|made|tested successfully> or
1719 something similar. Another situation where CPAN refuses to act is an
1720 C<install> if the corresponding C<test> was not successful.
1721
1722 In all these cases, the user can override this stubborn behaviour by
1723 prepending the command with the word force, for example:
1724
1725   cpan> force get Foo
1726   cpan> force make AUTHOR/Bar-3.14.tar.gz
1727   cpan> force test Baz
1728   cpan> force install Acme::Meta
1729
1730 Each I<forced> command is executed with the corresponding part of its
1731 memory erased.
1732
1733 The C<fforce> pragma is a variant that emulates a C<force get> which
1734 erases the entire memory followed by the action specified, effectively
1735 restarting the whole get/make/test/install procedure from scratch.
1736
1737 =item Lockfile
1738
1739 Interactive sessions maintain a lockfile, by default C<~/.cpan/.lock>.
1740 Batch jobs can run without a lockfile and not disturb each other.
1741
1742 The shell offers to run in I<downgraded mode> when another process is
1743 holding the lockfile. This is an experimental feature that is not yet
1744 tested very well. This second shell then does not write the history
1745 file, does not use the metadata file, and has a different prompt.
1746
1747 =item Signals
1748
1749 CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
1750 in the cpan-shell, it is intended that you can press C<^C> anytime and
1751 return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
1752 to clean up and leave the shell loop. You can emulate the effect of a
1753 SIGTERM by sending two consecutive SIGINTs, which usually means by
1754 pressing C<^C> twice.
1755
1756 CPAN.pm ignores SIGPIPE. If the user sets C<inactivity_timeout>, a
1757 SIGALRM is used during the run of the C<perl Makefile.PL> or C<perl
1758 Build.PL> subprocess. A SIGALRM is also used during module version
1759 parsing, and is controlled by C<version_timeout>.
1760
1761 =back
1762
1763 =head2 CPAN::Shell
1764
1765 The commands available in the shell interface are methods in
1766 the package CPAN::Shell. If you enter the shell command, your
1767 input is split by the Text::ParseWords::shellwords() routine, which
1768 acts like most shells do. The first word is interpreted as the
1769 method to be invoked, and the rest of the words are treated as the method's arguments.
1770 Continuation lines are supported by ending a line with a
1771 literal backslash.
1772
1773 =head2 autobundle
1774
1775 C<autobundle> writes a bundle file into the
1776 C<$CPAN::Config-E<gt>{cpan_home}/Bundle> directory. The file contains
1777 a list of all modules that are both available from CPAN and currently
1778 installed within @INC. Duplicates of each distribution are suppressed.
1779 The name of the bundle file is based on the current date and a
1780 counter, e.g. F<Bundle/Snapshot_2012_05_21_00.pm>. This is installed
1781 again by running C<cpan Bundle::Snapshot_2012_05_21_00>, or installing
1782 C<Bundle::Snapshot_2012_05_21_00> from the CPAN shell.
1783
1784 Return value: path to the written file.
1785
1786 =head2 hosts
1787
1788 Note: this feature is still in alpha state and may change in future
1789 versions of CPAN.pm
1790
1791 This commands provides a statistical overview over recent download
1792 activities. The data for this is collected in the YAML file
1793 C<FTPstats.yml> in your C<cpan_home> directory. If no YAML module is
1794 configured or YAML not installed, no stats are provided.
1795
1796 =over
1797
1798 =item install_tested
1799
1800 Install all distributions that have been tested successfully but have
1801 not yet been installed. See also C<is_tested>.
1802
1803 =item is_tested
1804
1805 List all build directories of distributions that have been tested
1806 successfully but have not yet been installed. See also
1807 C<install_tested>.
1808
1809 =back
1810
1811 =head2 mkmyconfig
1812
1813 mkmyconfig() writes your own CPAN::MyConfig file into your C<~/.cpan/>
1814 directory so that you can save your own preferences instead of the
1815 system-wide ones.
1816
1817 =head2 r [Module|/Regexp/]...
1818
1819 scans current perl installation for modules that have a newer version
1820 available on CPAN and provides a list of them. If called without
1821 argument, all potential upgrades are listed; if called with arguments
1822 the list is filtered to the modules and regexps given as arguments.
1823
1824 The listing looks something like this:
1825
1826   Package namespace         installed    latest  in CPAN file
1827   CPAN                        1.94_64    1.9600  ANDK/CPAN-1.9600.tar.gz
1828   CPAN::Reporter               1.1801    1.1902  DAGOLDEN/CPAN-Reporter-1.1902.tar.gz
1829   YAML                           0.70      0.73  INGY/YAML-0.73.tar.gz
1830   YAML::Syck                     1.14      1.17  AVAR/YAML-Syck-1.17.tar.gz
1831   YAML::Tiny                     1.44      1.50  ADAMK/YAML-Tiny-1.50.tar.gz
1832   CGI                            3.43      3.55  MARKSTOS/CGI.pm-3.55.tar.gz
1833   Module::Build::YAML            1.40      1.41  DAGOLDEN/Module-Build-0.3800.tar.gz
1834   TAP::Parser::Result::YAML      3.22      3.23  ANDYA/Test-Harness-3.23.tar.gz
1835   YAML::XS                       0.34      0.35  INGY/YAML-LibYAML-0.35.tar.gz
1836
1837 It suppresses duplicates in the column C<in CPAN file> such that
1838 distributions with many upgradeable modules are listed only once.
1839
1840 Note that the list is not sorted.
1841
1842 =head2 recent ***EXPERIMENTAL COMMAND***
1843
1844 The C<recent> command downloads a list of recent uploads to CPAN and
1845 displays them I<slowly>. While the command is running, a $SIG{INT}
1846 exits the loop after displaying the current item.
1847
1848 B<Note>: This command requires XML::LibXML installed.
1849
1850 B<Note>: This whole command currently is just a hack and will
1851 probably change in future versions of CPAN.pm, but the general
1852 approach will likely remain.
1853
1854 B<Note>: See also L<smoke>
1855
1856 =head2 recompile
1857
1858 recompile() is a special command that takes no argument and
1859 runs the make/test/install cycle with brute force over all installed
1860 dynamically loadable extensions (a.k.a. XS modules) with 'force' in
1861 effect. The primary purpose of this command is to finish a network
1862 installation. Imagine you have a common source tree for two different
1863 architectures. You decide to do a completely independent fresh
1864 installation. You start on one architecture with the help of a Bundle
1865 file produced earlier. CPAN installs the whole Bundle for you, but
1866 when you try to repeat the job on the second architecture, CPAN
1867 responds with a C<"Foo up to date"> message for all modules. So you
1868 invoke CPAN's recompile on the second architecture and you're done.
1869
1870 Another popular use for C<recompile> is to act as a rescue in case your
1871 perl breaks binary compatibility. If one of the modules that CPAN uses
1872 is in turn depending on binary compatibility (so you cannot run CPAN
1873 commands), then you should try the CPAN::Nox module for recovery.
1874
1875 =head2 report Bundle|Distribution|Module
1876
1877 The C<report> command temporarily turns on the C<test_report> config
1878 variable, then runs the C<force test> command with the given
1879 arguments. The C<force> pragma reruns the tests and repeats
1880 every step that might have failed before.
1881
1882 =head2 smoke ***EXPERIMENTAL COMMAND***
1883
1884 B<*** WARNING: this command downloads and executes software from CPAN to
1885 your computer of completely unknown status. You should never do
1886 this with your normal account and better have a dedicated well
1887 separated and secured machine to do this. ***>
1888
1889 The C<smoke> command takes the list of recent uploads to CPAN as
1890 provided by the C<recent> command and tests them all. While the
1891 command is running $SIG{INT} is defined to mean that the current item
1892 shall be skipped.
1893
1894 B<Note>: This whole command currently is just a hack and will
1895 probably change in future versions of CPAN.pm, but the general
1896 approach will likely remain.
1897
1898 B<Note>: See also L<recent>
1899
1900 =head2 upgrade [Module|/Regexp/]...
1901
1902 The C<upgrade> command first runs an C<r> command with the given
1903 arguments and then installs the newest versions of all modules that
1904 were listed by that.
1905
1906 =head2 The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution
1907
1908 Although it may be considered internal, the class hierarchy does matter
1909 for both users and programmer. CPAN.pm deals with the four
1910 classes mentioned above, and those classes all share a set of methods. Classical
1911 single polymorphism is in effect. A metaclass object registers all
1912 objects of all kinds and indexes them with a string. The strings
1913 referencing objects have a separated namespace (well, not completely
1914 separated):
1915
1916          Namespace                         Class
1917
1918    words containing a "/" (slash)      Distribution
1919     words starting with Bundle::          Bundle
1920           everything else            Module or Author
1921
1922 Modules know their associated Distribution objects. They always refer
1923 to the most recent official release. Developers may mark their releases
1924 as unstable development versions (by inserting an underscore into the
1925 module version number which will also be reflected in the distribution
1926 name when you run 'make dist'), so the really hottest and newest
1927 distribution is not always the default.  If a module Foo circulates
1928 on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
1929 way to install version 1.23 by saying
1930
1931     install Foo
1932
1933 This would install the complete distribution file (say
1934 BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
1935 like to install version 1.23_90, you need to know where the
1936 distribution file resides on CPAN relative to the authors/id/
1937 directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
1938 so you would have to say
1939
1940     install BAR/Foo-1.23_90.tar.gz
1941
1942 The first example will be driven by an object of the class
1943 CPAN::Module, the second by an object of class CPAN::Distribution.
1944
1945 =head2 Integrating local directories
1946
1947 Note: this feature is still in alpha state and may change in future
1948 versions of CPAN.pm
1949
1950 Distribution objects are normally distributions from the CPAN, but
1951 there is a slightly degenerate case for Distribution objects, too, of
1952 projects held on the local disk. These distribution objects have the
1953 same name as the local directory and end with a dot. A dot by itself
1954 is also allowed for the current directory at the time CPAN.pm was
1955 used. All actions such as C<make>, C<test>, and C<install> are applied
1956 directly to that directory. This gives the command C<cpan .> an
1957 interesting touch: while the normal mantra of installing a CPAN module
1958 without CPAN.pm is one of
1959
1960     perl Makefile.PL                 perl Build.PL
1961            ( go and get prerequisites )
1962     make                             ./Build
1963     make test                        ./Build test
1964     make install                     ./Build install
1965
1966 the command C<cpan .> does all of this at once. It figures out which
1967 of the two mantras is appropriate, fetches and installs all
1968 prerequisites, takes care of them recursively, and finally finishes the
1969 installation of the module in the current directory, be it a CPAN
1970 module or not.
1971
1972 The typical usage case is for private modules or working copies of
1973 projects from remote repositories on the local disk.
1974
1975 =head2 Redirection
1976
1977 The usual shell redirection symbols C< | > and C<< > >> are recognized
1978 by the cpan shell B<only when surrounded by whitespace>. So piping to
1979 pager or redirecting output into a file works somewhat as in a normal
1980 shell, with the stipulation that you must type extra spaces.
1981
1982 =head2 Plugin support ***EXPERIMENTAL***
1983
1984 Plugins are objects that implement any of currently eight methods:
1985
1986   pre_get
1987   post_get
1988   pre_make
1989   post_make
1990   pre_test
1991   post_test
1992   pre_install
1993   post_install
1994
1995 The C<plugin_list> configuration parameter holds a list of strings of
1996 the form
1997
1998   Modulename=arg0,arg1,arg2,arg3,...
1999
2000 eg:
2001
2002   CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1
2003
2004 At run time, each listed plugin is instantiated as a singleton object
2005 by running the equivalent of this pseudo code:
2006
2007   my $plugin = <string representation from config>;
2008   <generate Modulename and arguments from $plugin>;
2009   my $p = $instance{$plugin} ||= Modulename->new($arg0,$arg1,...);
2010
2011 The generated singletons are kept around from instantiation until the
2012 end of the shell session. <plugin_list> can be reconfigured at any
2013 time at run time. While the cpan shell is running, it checks all
2014 activated plugins at each of the 8 reference points listed above and
2015 runs the respective method if it is implemented for that object. The
2016 method is called with the active CPAN::Distribution object passed in
2017 as an argument.
2018
2019 =head1 CONFIGURATION
2020
2021 When the CPAN module is used for the first time, a configuration
2022 dialogue tries to determine a couple of site specific options. The
2023 result of the dialog is stored in a hash reference C< $CPAN::Config >
2024 in a file CPAN/Config.pm.
2025
2026 Default values defined in the CPAN/Config.pm file can be
2027 overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
2028 best placed in C<$HOME/.cpan/CPAN/MyConfig.pm>, because C<$HOME/.cpan> is
2029 added to the search path of the CPAN module before the use() or
2030 require() statements. The mkmyconfig command writes this file for you.
2031
2032 The C<o conf> command has various bells and whistles:
2033
2034 =over
2035
2036 =item completion support
2037
2038 If you have a ReadLine module installed, you can hit TAB at any point
2039 of the commandline and C<o conf> will offer you completion for the
2040 built-in subcommands and/or config variable names.
2041
2042 =item displaying some help: o conf help
2043
2044 Displays a short help
2045
2046 =item displaying current values: o conf [KEY]
2047
2048 Displays the current value(s) for this config variable. Without KEY,
2049 displays all subcommands and config variables.
2050
2051 Example:
2052
2053   o conf shell
2054
2055 If KEY starts and ends with a slash, the string in between is
2056 treated as a regular expression and only keys matching this regexp
2057 are displayed
2058
2059 Example:
2060
2061   o conf /color/
2062
2063 =item changing of scalar values: o conf KEY VALUE
2064
2065 Sets the config variable KEY to VALUE. The empty string can be
2066 specified as usual in shells, with C<''> or C<"">
2067
2068 Example:
2069
2070   o conf wget /usr/bin/wget
2071
2072 =item changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
2073
2074 If a config variable name ends with C<list>, it is a list. C<o conf
2075 KEY shift> removes the first element of the list, C<o conf KEY pop>
2076 removes the last element of the list. C<o conf KEYS unshift LIST>
2077 prepends a list of values to the list, C<o conf KEYS push LIST>
2078 appends a list of valued to the list.
2079
2080 Likewise, C<o conf KEY splice LIST> passes the LIST to the corresponding
2081 splice command.
2082
2083 Finally, any other list of arguments is taken as a new list value for
2084 the KEY variable discarding the previous value.
2085
2086 Examples:
2087
2088   o conf urllist unshift http://cpan.dev.local/CPAN
2089   o conf urllist splice 3 1
2090   o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
2091
2092 =item reverting to saved: o conf defaults
2093
2094 Reverts all config variables to the state in the saved config file.
2095
2096 =item saving the config: o conf commit
2097
2098 Saves all config variables to the current config file (CPAN/Config.pm
2099 or CPAN/MyConfig.pm that was loaded at start).
2100
2101 =back
2102
2103 The configuration dialog can be started any time later again by
2104 issuing the command C< o conf init > in the CPAN shell. A subset of
2105 the configuration dialog can be run by issuing C<o conf init WORD>
2106 where WORD is any valid config variable or a regular expression.
2107
2108 =head2 Config Variables
2109
2110 The following keys in the hash reference $CPAN::Config are
2111 currently defined:
2112
2113   applypatch         path to external prg
2114   auto_commit        commit all changes to config variables to disk
2115   build_cache        size of cache for directories to build modules
2116   build_dir          locally accessible directory to build modules
2117   build_dir_reuse    boolean if distros in build_dir are persistent
2118   build_requires_install_policy
2119                      to install or not to install when a module is
2120                      only needed for building. yes|no|ask/yes|ask/no
2121   bzip2              path to external prg
2122   cache_metadata     use serializer to cache metadata
2123   check_sigs         if signatures should be verified
2124   cleanup_after_install
2125                      remove build directory immediately after a
2126                      successful install
2127   colorize_debug     Term::ANSIColor attributes for debugging output
2128   colorize_output    boolean if Term::ANSIColor should colorize output
2129   colorize_print     Term::ANSIColor attributes for normal output
2130   colorize_warn      Term::ANSIColor attributes for warnings
2131   commandnumber_in_prompt
2132                      boolean if you want to see current command number
2133   commands_quote     preferred character to use for quoting external
2134                      commands when running them. Defaults to double
2135                      quote on Windows, single tick everywhere else;
2136                      can be set to space to disable quoting
2137   connect_to_internet_ok
2138                      whether to ask if opening a connection is ok before
2139                      urllist is specified
2140   cpan_home          local directory reserved for this package
2141   curl               path to external prg
2142   dontload_hash      DEPRECATED
2143   dontload_list      arrayref: modules in the list will not be
2144                      loaded by the CPAN::has_inst() routine
2145   ftp                path to external prg
2146   ftp_passive        if set, the environment variable FTP_PASSIVE is set
2147                      for downloads
2148   ftp_proxy          proxy host for ftp requests
2149   ftpstats_period    max number of days to keep download statistics
2150   ftpstats_size      max number of items to keep in the download statistics
2151   getcwd             see below
2152   gpg                path to external prg
2153   gzip               location of external program gzip
2154   halt_on_failure    stop processing after the first failure of queued
2155                      items or dependencies
2156   histfile           file to maintain history between sessions
2157   histsize           maximum number of lines to keep in histfile
2158   http_proxy         proxy host for http requests
2159   inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
2160                      after this many seconds inactivity. Set to 0 to
2161                      disable timeouts.
2162   index_expire       refetch index files after this many days
2163   inhibit_startup_message
2164                      if true, suppress the startup message
2165   keep_source_where  directory in which to keep the source (if we do)
2166   load_module_verbosity
2167                      report loading of optional modules used by CPAN.pm
2168   lynx               path to external prg
2169   make               location of external make program
2170   make_arg           arguments that should always be passed to 'make'
2171   make_install_make_command
2172                      the make command for running 'make install', for
2173                      example 'sudo make'
2174   make_install_arg   same as make_arg for 'make install'
2175   makepl_arg         arguments passed to 'perl Makefile.PL'
2176   mbuild_arg         arguments passed to './Build'
2177   mbuild_install_arg arguments passed to './Build install'
2178   mbuild_install_build_command
2179                      command to use instead of './Build' when we are
2180                      in the install stage, for example 'sudo ./Build'
2181   mbuildpl_arg       arguments passed to 'perl Build.PL'
2182   ncftp              path to external prg
2183   ncftpget           path to external prg
2184   no_proxy           don't proxy to these hosts/domains (comma separated list)
2185   pager              location of external program more (or any pager)
2186   password           your password if you CPAN server wants one
2187   patch              path to external prg
2188   patches_dir        local directory containing patch files
2189   perl5lib_verbosity verbosity level for PERL5LIB additions
2190   plugin_list        list of active hooks (see Plugin support above
2191                      and the CPAN::Plugin module)
2192   prefer_external_tar
2193                      per default all untar operations are done with
2194                      Archive::Tar; by setting this variable to true
2195                      the external tar command is used if available
2196   prefer_installer   legal values are MB and EUMM: if a module comes
2197                      with both a Makefile.PL and a Build.PL, use the
2198                      former (EUMM) or the latter (MB); if the module
2199                      comes with only one of the two, that one will be
2200                      used no matter the setting
2201   prerequisites_policy
2202                      what to do if you are missing module prerequisites
2203                      ('follow' automatically, 'ask' me, or 'ignore')
2204                      For 'follow', also sets PERL_AUTOINSTALL and
2205                      PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if
2206                      not already set
2207   prefs_dir          local directory to store per-distro build options
2208   proxy_user         username for accessing an authenticating proxy
2209   proxy_pass         password for accessing an authenticating proxy
2210   randomize_urllist  add some randomness to the sequence of the urllist
2211   recommends_policy  whether recommended prerequisites should be included
2212   scan_cache         controls scanning of cache ('atstart', 'atexit' or 'never')
2213   shell              your favorite shell
2214   show_unparsable_versions
2215                      boolean if r command tells which modules are versionless
2216   show_upload_date   boolean if commands should try to determine upload date
2217   show_zero_versions boolean if r command tells for which modules $version==0
2218   suggests_policy    whether suggested prerequisites should be included
2219   tar                location of external program tar
2220   tar_verbosity      verbosity level for the tar command
2221   term_is_latin      deprecated: if true Unicode is translated to ISO-8859-1
2222                      (and nonsense for characters outside latin range)
2223   term_ornaments     boolean to turn ReadLine ornamenting on/off
2224   test_report        email test reports (if CPAN::Reporter is installed)
2225   trust_test_report_history
2226                      skip testing when previously tested ok (according to
2227                      CPAN::Reporter history)
2228   unzip              location of external program unzip
2229   urllist            arrayref to nearby CPAN sites (or equivalent locations)
2230   use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
2231   use_sqlite         use CPAN::SQLite for metadata storage (fast and lean)
2232   username           your username if you CPAN server wants one
2233   version_timeout    stops version parsing after this many seconds.
2234                      Default is 15 secs. Set to 0 to disable.
2235   wait_list          arrayref to a wait server to try (See CPAN::WAIT)
2236   wget               path to external prg
2237   yaml_load_code     enable YAML code deserialisation via CPAN::DeferredCode
2238   yaml_module        which module to use to read/write YAML files
2239
2240 You can set and query each of these options interactively in the cpan
2241 shell with the C<o conf> or the C<o conf init> command as specified below.
2242
2243 =over 2
2244
2245 =item C<o conf E<lt>scalar optionE<gt>>
2246
2247 prints the current value of the I<scalar option>
2248
2249 =item C<o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>>
2250
2251 Sets the value of the I<scalar option> to I<value>
2252
2253 =item C<o conf E<lt>list optionE<gt>>
2254
2255 prints the current value of the I<list option> in MakeMaker's
2256 neatvalue format.
2257
2258 =item C<o conf E<lt>list optionE<gt> [shift|pop]>
2259
2260 shifts or pops the array in the I<list option> variable
2261
2262 =item C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>>
2263
2264 works like the corresponding perl commands.
2265
2266 =item interactive editing: o conf init [MATCH|LIST]
2267
2268 Runs an interactive configuration dialog for matching variables.
2269 Without argument runs the dialog over all supported config variables.
2270 To specify a MATCH the argument must be enclosed by slashes.
2271
2272 Examples:
2273
2274   o conf init ftp_passive ftp_proxy
2275   o conf init /color/
2276
2277 Note: this method of setting config variables often provides more
2278 explanation about the functioning of a variable than the manpage.
2279
2280 =back
2281
2282 =head2 CPAN::anycwd($path): Note on config variable getcwd
2283
2284 CPAN.pm changes the current working directory often and needs to
2285 determine its own current working directory. By default it uses
2286 Cwd::cwd, but if for some reason this doesn't work on your system,
2287 configure alternatives according to the following table:
2288
2289 =over 4
2290
2291 =item cwd
2292
2293 Calls Cwd::cwd
2294
2295 =item getcwd
2296
2297 Calls Cwd::getcwd
2298
2299 =item fastcwd
2300
2301 Calls Cwd::fastcwd
2302
2303 =item getdcwd
2304
2305 Calls Cwd::getdcwd
2306
2307 =item backtickcwd
2308
2309 Calls the external command cwd.
2310
2311 =back
2312
2313 =head2 Note on the format of the urllist parameter
2314
2315 urllist parameters are URLs according to RFC 1738. We do a little
2316 guessing if your URL is not compliant, but if you have problems with
2317 C<file> URLs, please try the correct format. Either:
2318
2319     file://localhost/whatever/ftp/pub/CPAN/
2320
2321 or
2322
2323     file:///home/ftp/pub/CPAN/
2324
2325 =head2 The urllist parameter has CD-ROM support
2326
2327 The C<urllist> parameter of the configuration table contains a list of
2328 URLs used for downloading. If the list contains any
2329 C<file> URLs, CPAN always tries there first. This
2330 feature is disabled for index files. So the recommendation for the
2331 owner of a CD-ROM with CPAN contents is: include your local, possibly
2332 outdated CD-ROM as a C<file> URL at the end of urllist, e.g.
2333
2334   o conf urllist push file://localhost/CDROM/CPAN
2335
2336 CPAN.pm will then fetch the index files from one of the CPAN sites
2337 that come at the beginning of urllist. It will later check for each
2338 module to see whether there is a local copy of the most recent version.
2339
2340 Another peculiarity of urllist is that the site that we could
2341 successfully fetch the last file from automatically gets a preference
2342 token and is tried as the first site for the next request. So if you
2343 add a new site at runtime it may happen that the previously preferred
2344 site will be tried another time. This means that if you want to disallow
2345 a site for the next transfer, it must be explicitly removed from
2346 urllist.
2347
2348 =head2 Maintaining the urllist parameter
2349
2350 If you have YAML.pm (or some other YAML module configured in
2351 C<yaml_module>) installed, CPAN.pm collects a few statistical data
2352 about recent downloads. You can view the statistics with the C<hosts>
2353 command or inspect them directly by looking into the C<FTPstats.yml>
2354 file in your C<cpan_home> directory.
2355
2356 To get some interesting statistics, it is recommended that
2357 C<randomize_urllist> be set; this introduces some amount of
2358 randomness into the URL selection.
2359
2360 =head2 The C<requires> and C<build_requires> dependency declarations
2361
2362 Since CPAN.pm version 1.88_51 modules declared as C<build_requires> by
2363 a distribution are treated differently depending on the config
2364 variable C<build_requires_install_policy>. By setting
2365 C<build_requires_install_policy> to C<no>, such a module is not
2366 installed. It is only built and tested, and then kept in the list of
2367 tested but uninstalled modules. As such, it is available during the
2368 build of the dependent module by integrating the path to the
2369 C<blib/arch> and C<blib/lib> directories in the environment variable
2370 PERL5LIB. If C<build_requires_install_policy> is set ti C<yes>, then
2371 both modules declared as C<requires> and those declared as
2372 C<build_requires> are treated alike. By setting to C<ask/yes> or
2373 C<ask/no>, CPAN.pm asks the user and sets the default accordingly.
2374
2375 =head2 Configuration for individual distributions (I<Distroprefs>)
2376
2377 (B<Note:> This feature has been introduced in CPAN.pm 1.8854)
2378
2379 Distributions on CPAN usually behave according to what we call the
2380 CPAN mantra. Or since the advent of Module::Build we should talk about
2381 two mantras:
2382
2383     perl Makefile.PL     perl Build.PL
2384     make                 ./Build
2385     make test            ./Build test
2386     make install         ./Build install
2387
2388 But some modules cannot be built with this mantra. They try to get
2389 some extra data from the user via the environment, extra arguments, or
2390 interactively--thus disturbing the installation of large bundles like
2391 Phalanx100 or modules with many dependencies like Plagger.
2392
2393 The distroprefs system of C<CPAN.pm> addresses this problem by
2394 allowing the user to specify extra informations and recipes in YAML
2395 files to either
2396
2397 =over
2398
2399 =item
2400
2401 pass additional arguments to one of the four commands,
2402
2403 =item
2404
2405 set environment variables
2406
2407 =item
2408
2409 instantiate an Expect object that reads from the console, waits for
2410 some regular expressions and enters some answers
2411
2412 =item
2413
2414 temporarily override assorted C<CPAN.pm> configuration variables
2415
2416 =item
2417
2418 specify dependencies the original maintainer forgot
2419
2420 =item
2421
2422 disable the installation of an object altogether
2423
2424 =back
2425
2426 See the YAML and Data::Dumper files that come with the C<CPAN.pm>
2427 distribution in the C<distroprefs/> directory for examples.
2428
2429 =head2 Filenames
2430
2431 The YAML files themselves must have the C<.yml> extension; all other
2432 files are ignored (for two exceptions see I<Fallback Data::Dumper and
2433 Storable> below). The containing directory can be specified in
2434 C<CPAN.pm> in the C<prefs_dir> config variable. Try C<o conf init
2435 prefs_dir> in the CPAN shell to set and activate the distroprefs
2436 system.
2437
2438 Every YAML file may contain arbitrary documents according to the YAML
2439 specification, and every document is treated as an entity that
2440 can specify the treatment of a single distribution.
2441
2442 Filenames can be picked arbitrarily; C<CPAN.pm> always reads
2443 all files (in alphabetical order) and takes the key C<match> (see
2444 below in I<Language Specs>) as a hashref containing match criteria
2445 that determine if the current distribution matches the YAML document
2446 or not.
2447
2448 =head2 Fallback Data::Dumper and Storable
2449
2450 If neither your configured C<yaml_module> nor YAML.pm is installed,
2451 CPAN.pm falls back to using Data::Dumper and Storable and looks for
2452 files with the extensions C<.dd> or C<.st> in the C<prefs_dir>
2453 directory. These files are expected to contain one or more hashrefs.
2454 For Data::Dumper generated files, this is expected to be done with by
2455 defining C<$VAR1>, C<$VAR2>, etc. The YAML shell would produce these
2456 with the command
2457
2458     ysh < somefile.yml > somefile.dd
2459
2460 For Storable files the rule is that they must be constructed such that
2461 C<Storable::retrieve(file)> returns an array reference and the array
2462 elements represent one distropref object each. The conversion from
2463 YAML would look like so:
2464
2465     perl -MYAML=LoadFile -MStorable=nstore -e '
2466         @y=LoadFile(shift);
2467         nstore(\@y, shift)' somefile.yml somefile.st
2468
2469 In bootstrapping situations it is usually sufficient to translate only
2470 a few YAML files to Data::Dumper for crucial modules like
2471 C<YAML::Syck>, C<YAML.pm> and C<Expect.pm>. If you prefer Storable
2472 over Data::Dumper, remember to pull out a Storable version that writes
2473 an older format than all the other Storable versions that will need to
2474 read them.
2475
2476 =head2 Blueprint
2477
2478 The following example contains all supported keywords and structures
2479 with the exception of C<eexpect> which can be used instead of
2480 C<expect>.
2481
2482   ---
2483   comment: "Demo"
2484   match:
2485     module: "Dancing::Queen"
2486     distribution: "^CHACHACHA/Dancing-"
2487     not_distribution: "\.zip$"
2488     perl: "/usr/local/cariba-perl/bin/perl"
2489     perlconfig:
2490       archname: "freebsd"
2491       not_cc: "gcc"
2492     env:
2493       DANCING_FLOOR: "Shubiduh"
2494   disabled: 1
2495   cpanconfig:
2496     make: gmake
2497   pl:
2498     args:
2499       - "--somearg=specialcase"
2500
2501     env: {}
2502
2503     expect:
2504       - "Which is your favorite fruit"
2505       - "apple\n"
2506
2507   make:
2508     args:
2509       - all
2510       - extra-all
2511
2512     env: {}
2513
2514     expect: []
2515
2516     commandline: "echo SKIPPING make"
2517
2518   test:
2519     args: []
2520
2521     env: {}
2522
2523     expect: []
2524
2525   install:
2526     args: []
2527
2528     env:
2529       WANT_TO_INSTALL: YES
2530
2531     expect:
2532       - "Do you really want to install"
2533       - "y\n"
2534
2535   patches:
2536     - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
2537
2538   depends:
2539     configure_requires:
2540       LWP: 5.8
2541     build_requires:
2542       Test::Exception: 0.25
2543     requires:
2544       Spiffy: 0.30
2545
2546
2547 =head2 Language Specs
2548
2549 Every YAML document represents a single hash reference. The valid keys
2550 in this hash are as follows:
2551
2552 =over
2553
2554 =item comment [scalar]
2555
2556 A comment
2557
2558 =item cpanconfig [hash]
2559
2560 Temporarily override assorted C<CPAN.pm> configuration variables.
2561
2562 Supported are: C<build_requires_install_policy>, C<check_sigs>,
2563 C<make>, C<make_install_make_command>, C<prefer_installer>,
2564 C<test_report>. Please report as a bug when you need another one
2565 supported.
2566
2567 =item depends [hash] *** EXPERIMENTAL FEATURE ***
2568
2569 All three types, namely C<configure_requires>, C<build_requires>, and
2570 C<requires> are supported in the way specified in the META.yml
2571 specification. The current implementation I<merges> the specified
2572 dependencies with those declared by the package maintainer. In a
2573 future implementation this may be changed to override the original
2574 declaration.
2575
2576 =item disabled [boolean]
2577
2578 Specifies that this distribution shall not be processed at all.
2579
2580 =item features [array] *** EXPERIMENTAL FEATURE ***
2581
2582 Experimental implementation to deal with optional_features from
2583 META.yml. Still needs coordination with installer software and
2584 currently works only for META.yml declaring C<dynamic_config=0>. Use
2585 with caution.
2586
2587 =item goto [string]
2588
2589 The canonical name of a delegate distribution to install
2590 instead. Useful when a new version, although it tests OK itself,
2591 breaks something else or a developer release or a fork is already
2592 uploaded that is better than the last released version.
2593
2594 =item install [hash]
2595
2596 Processing instructions for the C<make install> or C<./Build install>
2597 phase of the CPAN mantra. See below under I<Processing Instructions>.
2598
2599 =item make [hash]
2600
2601 Processing instructions for the C<make> or C<./Build> phase of the
2602 CPAN mantra. See below under I<Processing Instructions>.
2603
2604 =item match [hash]
2605
2606 A hashref with one or more of the keys C<distribution>, C<module>,
2607 C<perl>, C<perlconfig>, and C<env> that specify whether a document is
2608 targeted at a specific CPAN distribution or installation.
2609 Keys prefixed with C<not_> negates the corresponding match.
2610
2611 The corresponding values are interpreted as regular expressions. The
2612 C<distribution> related one will be matched against the canonical
2613 distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
2614
2615 The C<module> related one will be matched against I<all> modules
2616 contained in the distribution until one module matches.
2617
2618 The C<perl> related one will be matched against C<$^X> (but with the
2619 absolute path).
2620
2621 The value associated with C<perlconfig> is itself a hashref that is
2622 matched against corresponding values in the C<%Config::Config> hash
2623 living in the C<Config.pm> module.
2624 Keys prefixed with C<not_> negates the corresponding match.
2625
2626 The value associated with C<env> is itself a hashref that is
2627 matched against corresponding values in the C<%ENV> hash.
2628 Keys prefixed with C<not_> negates the corresponding match.
2629
2630 If more than one restriction of C<module>, C<distribution>, etc. is
2631 specified, the results of the separately computed match values must
2632 all match. If so, the hashref represented by the
2633 YAML document is returned as the preference structure for the current
2634 distribution.
2635
2636 =item patches [array]
2637
2638 An array of patches on CPAN or on the local disk to be applied in
2639 order via an external patch program. If the value for the C<-p>
2640 parameter is C<0> or C<1> is determined by reading the patch
2641 beforehand. The path to each patch is either an absolute path on the
2642 local filesystem or relative to a patch directory specified in the
2643 C<patches_dir> configuration variable or in the format of a canonical
2644 distro name. For examples please consult the distroprefs/ directory in
2645 the CPAN.pm distribution (these examples are not installed by
2646 default).
2647
2648 Note: if the C<applypatch> program is installed and C<CPAN::Config>
2649 knows about it B<and> a patch is written by the C<makepatch> program,
2650 then C<CPAN.pm> lets C<applypatch> apply the patch. Both C<makepatch>
2651 and C<applypatch> are available from CPAN in the C<JV/makepatch-*>
2652 distribution.
2653
2654 =item pl [hash]
2655
2656 Processing instructions for the C<perl Makefile.PL> or C<perl
2657 Build.PL> phase of the CPAN mantra. See below under I<Processing
2658 Instructions>.
2659
2660 =item test [hash]
2661
2662 Processing instructions for the C<make test> or C<./Build test> phase
2663 of the CPAN mantra. See below under I<Processing Instructions>.
2664
2665 =back
2666
2667 =head2 Processing Instructions
2668
2669 =over
2670
2671 =item args [array]
2672
2673 Arguments to be added to the command line
2674
2675 =item commandline
2676
2677 A full commandline to run via C<system()>.
2678 During execution, the environment variable PERL is set
2679 to $^X (but with an absolute path). If C<commandline> is specified,
2680 C<args> is not used.
2681
2682 =item eexpect [hash]
2683
2684 Extended C<expect>. This is a hash reference with four allowed keys,
2685 C<mode>, C<timeout>, C<reuse>, and C<talk>.
2686
2687 You must install the C<Expect> module to use C<eexpect>. CPAN.pm
2688 does not install it for you.
2689
2690 C<mode> may have the values C<deterministic> for the case where all
2691 questions come in the order written down and C<anyorder> for the case
2692 where the questions may come in any order. The default mode is
2693 C<deterministic>.
2694
2695 C<timeout> denotes a timeout in seconds. Floating-point timeouts are
2696 OK. With C<mode=deterministic>, the timeout denotes the
2697 timeout per question; with C<mode=anyorder> it denotes the
2698 timeout per byte received from the stream or questions.
2699
2700 C<talk> is a reference to an array that contains alternating questions
2701 and answers. Questions are regular expressions and answers are literal
2702 strings. The Expect module watches the stream from the
2703 execution of the external program (C<perl Makefile.PL>, C<perl
2704 Build.PL>, C<make>, etc.).
2705
2706 For C<mode=deterministic>, the CPAN.pm injects the
2707 corresponding answer as soon as the stream matches the regular expression.
2708
2709 For C<mode=anyorder> CPAN.pm answers a question as soon
2710 as the timeout is reached for the next byte in the input stream. In
2711 this mode you can use the C<reuse> parameter to decide what will
2712 happen with a question-answer pair after it has been used. In the
2713 default case (reuse=0) it is removed from the array, avoiding being
2714 used again accidentally. If you want to answer the
2715 question C<Do you really want to do that> several times, then it must
2716 be included in the array at least as often as you want this answer to
2717 be given. Setting the parameter C<reuse> to 1 makes this repetition
2718 unnecessary.
2719
2720 =item env [hash]
2721
2722 Environment variables to be set during the command
2723
2724 =item expect [array]
2725
2726 You must install the C<Expect> module to use C<expect>. CPAN.pm
2727 does not install it for you.
2728
2729 C<< expect: <array> >> is a short notation for this C<eexpect>:
2730
2731         eexpect:
2732                 mode: deterministic
2733                 timeout: 15
2734                 talk: <array>
2735
2736 =back
2737
2738 =head2 Schema verification with C<Kwalify>
2739
2740 If you have the C<Kwalify> module installed (which is part of the
2741 Bundle::CPANxxl), then all your distroprefs files are checked for
2742 syntactic correctness.
2743
2744 =head2 Example Distroprefs Files
2745
2746 C<CPAN.pm> comes with a collection of example YAML files. Note that these
2747 are really just examples and should not be used without care because
2748 they cannot fit everybody's purpose. After all, the authors of the
2749 packages that ask questions had a need to ask, so you should watch
2750 their questions and adjust the examples to your environment and your
2751 needs. You have been warned:-)
2752
2753 =head1 PROGRAMMER'S INTERFACE
2754
2755 If you do not enter the shell, shell commands are
2756 available both as methods (C<CPAN::Shell-E<gt>install(...)>) and as
2757 functions in the calling package (C<install(...)>).  Before calling low-level
2758 commands, it makes sense to initialize components of CPAN you need, e.g.:
2759
2760   CPAN::HandleConfig->load;
2761   CPAN::Shell::setup_output;
2762   CPAN::Index->reload;
2763
2764 High-level commands do such initializations automatically.
2765
2766 There's currently only one class that has a stable interface -
2767 CPAN::Shell. All commands that are available in the CPAN shell are
2768 methods of the class CPAN::Shell. The arguments on the commandline are
2769 passed as arguments to the method.
2770
2771 So if you take for example the shell command
2772
2773   notest install A B C
2774
2775 the actually executed command is
2776
2777   CPAN::Shell->notest("install","A","B","C");
2778
2779 Each of the commands that produce listings of modules (C<r>,
2780 C<autobundle>, C<u>) also return a list of the IDs of all modules
2781 within the list.
2782
2783 =over 2
2784
2785 =item expand($type,@things)
2786
2787 The IDs of all objects available within a program are strings that can
2788 be expanded to the corresponding real objects with the
2789 C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a
2790 list of CPAN::Module objects according to the C<@things> arguments
2791 given. In scalar context, it returns only the first element of the
2792 list.
2793
2794 =item expandany(@things)
2795
2796 Like expand, but returns objects of the appropriate type, i.e.
2797 CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and
2798 CPAN::Distribution objects for distributions. Note: it does not expand
2799 to CPAN::Author objects.
2800
2801 =item Programming Examples
2802
2803 This enables the programmer to do operations that combine
2804 functionalities that are available in the shell.
2805
2806     # install everything that is outdated on my disk:
2807     perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
2808
2809     # install my favorite programs if necessary:
2810     for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
2811         CPAN::Shell->install($mod);
2812     }
2813
2814     # list all modules on my disk that have no VERSION number
2815     for $mod (CPAN::Shell->expand("Module","/./")) {
2816         next unless $mod->inst_file;
2817         # MakeMaker convention for undefined $VERSION:
2818         next unless $mod->inst_version eq "undef";
2819         print "No VERSION in ", $mod->id, "\n";
2820     }
2821
2822     # find out which distribution on CPAN contains a module:
2823     print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
2824
2825 Or if you want to schedule a I<cron> job to watch CPAN, you could list
2826 all modules that need updating. First a quick and dirty way:
2827
2828     perl -e 'use CPAN; CPAN::Shell->r;'
2829
2830 If you don't want any output should all modules be
2831 up to date, parse the output of above command for the regular
2832 expression C</modules are up to date/> and decide to mail the output
2833 only if it doesn't match.
2834
2835 If you prefer to do it more in a programmerish style in one single
2836 process, something like this may better suit you:
2837
2838   # list all modules on my disk that have newer versions on CPAN
2839   for $mod (CPAN::Shell->expand("Module","/./")) {
2840     next unless $mod->inst_file;
2841     next if $mod->uptodate;
2842     printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
2843         $mod->id, $mod->inst_version, $mod->cpan_version;
2844   }
2845
2846 If that gives too much output every day, you may want to
2847 watch only for three modules. You can write
2848
2849   for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {
2850
2851 as the first line instead. Or you can combine some of the above
2852 tricks:
2853
2854   # watch only for a new mod_perl module
2855   $mod = CPAN::Shell->expand("Module","mod_perl");
2856   exit if $mod->uptodate;
2857   # new mod_perl arrived, let me know all update recommendations
2858   CPAN::Shell->r;
2859
2860 =back
2861
2862 =head2 Methods in the other Classes
2863
2864 =over 4
2865
2866 =item CPAN::Author::as_glimpse()
2867
2868 Returns a one-line description of the author
2869
2870 =item CPAN::Author::as_string()
2871
2872 Returns a multi-line description of the author
2873
2874 =item CPAN::Author::email()
2875
2876 Returns the author's email address
2877
2878 =item CPAN::Author::fullname()
2879
2880 Returns the author's name
2881
2882 =item CPAN::Author::name()
2883
2884 An alias for fullname
2885
2886 =item CPAN::Bundle::as_glimpse()
2887
2888 Returns a one-line description of the bundle
2889
2890 =item CPAN::Bundle::as_string()
2891
2892 Returns a multi-line description of the bundle
2893
2894 =item CPAN::Bundle::clean()
2895
2896 Recursively runs the C<clean> method on all items contained in the bundle.
2897
2898 =item CPAN::Bundle::contains()
2899
2900 Returns a list of objects' IDs contained in a bundle. The associated
2901 objects may be bundles, modules or distributions.
2902
2903 =item CPAN::Bundle::force($method,@args)
2904
2905 Forces CPAN to perform a task that it normally would have refused to
2906 do. Force takes as arguments a method name to be called and any number
2907 of additional arguments that should be passed to the called method.
2908 The internals of the object get the needed changes so that CPAN.pm
2909 does not refuse to take the action. The C<force> is passed recursively
2910 to all contained objects. See also the section above on the C<force>
2911 and the C<fforce> pragma.
2912
2913 =item CPAN::Bundle::get()
2914
2915 Recursively runs the C<get> method on all items contained in the bundle
2916
2917 =item CPAN::Bundle::inst_file()
2918
2919 Returns the highest installed version of the bundle in either @INC or
2920 C<< $CPAN::Config->{cpan_home} >>. Note that this is different from
2921 CPAN::Module::inst_file.
2922
2923 =item CPAN::Bundle::inst_version()
2924
2925 Like CPAN::Bundle::inst_file, but returns the $VERSION
2926
2927 =item CPAN::Bundle::uptodate()
2928
2929 Returns 1 if the bundle itself and all its members are up-to-date.
2930
2931 =item CPAN::Bundle::install()
2932
2933 Recursively runs the C<install> method on all items contained in the bundle
2934
2935 =item CPAN::Bundle::make()
2936
2937 Recursively runs the C<make> method on all items contained in the bundle
2938
2939 =item CPAN::Bundle::readme()
2940
2941 Recursively runs the C<readme> method on all items contained in the bundle
2942
2943 =item CPAN::Bundle::test()
2944
2945 Recursively runs the C<test> method on all items contained in the bundle
2946
2947 =item CPAN::Distribution::as_glimpse()
2948
2949 Returns a one-line description of the distribution
2950
2951 =item CPAN::Distribution::as_string()
2952
2953 Returns a multi-line description of the distribution
2954
2955 =item CPAN::Distribution::author
2956
2957 Returns the CPAN::Author object of the maintainer who uploaded this
2958 distribution
2959
2960 =item CPAN::Distribution::pretty_id()
2961
2962 Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is the
2963 author's PAUSE ID and TARBALL is the distribution filename.
2964
2965 =item CPAN::Distribution::base_id()
2966
2967 Returns the distribution filename without any archive suffix.  E.g
2968 "Foo-Bar-0.01"
2969
2970 =item CPAN::Distribution::clean()
2971
2972 Changes to the directory where the distribution has been unpacked and
2973 runs C<make clean> there.
2974
2975 =item CPAN::Distribution::containsmods()
2976
2977 Returns a list of IDs of modules contained in a distribution file.
2978 Works only for distributions listed in the 02packages.details.txt.gz
2979 file. This typically means that just most recent version of a
2980 distribution is covered.
2981
2982 =item CPAN::Distribution::cvs_import()
2983
2984 Changes to the directory where the distribution has been unpacked and
2985 runs something like
2986
2987     cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
2988
2989 there.
2990
2991 =item CPAN::Distribution::dir()
2992
2993 Returns the directory into which this distribution has been unpacked.
2994
2995 =item CPAN::Distribution::force($method,@args)
2996
2997 Forces CPAN to perform a task that it normally would have refused to
2998 do. Force takes as arguments a method name to be called and any number
2999 of additional arguments that should be passed to the called method.
3000 The internals of the object get the needed changes so that CPAN.pm
3001 does not refuse to take the action. See also the section above on the
3002 C<force> and the C<fforce> pragma.
3003
3004 =item CPAN::Distribution::get()
3005
3006 Downloads the distribution from CPAN and unpacks it. Does nothing if
3007 the distribution has already been downloaded and unpacked within the
3008 current session.
3009
3010 =item CPAN::Distribution::install()
3011
3012 Changes to the directory where the distribution has been unpacked and
3013 runs the external command C<make install> there. If C<make> has not
3014 yet been run, it will be run first. A C<make test> is issued in
3015 any case and if this fails, the install is cancelled. The
3016 cancellation can be avoided by letting C<force> run the C<install> for
3017 you.
3018
3019 This install method only has the power to install the distribution if
3020 there are no dependencies in the way. To install an object along with all
3021 its dependencies, use CPAN::Shell->install.
3022
3023 Note that install() gives no meaningful return value. See uptodate().
3024
3025 =item CPAN::Distribution::isa_perl()
3026
3027 Returns 1 if this distribution file seems to be a perl distribution.
3028 Normally this is derived from the file name only, but the index from
3029 CPAN can contain a hint to achieve a return value of true for other
3030 filenames too.
3031
3032 =item CPAN::Distribution::look()
3033
3034 Changes to the directory where the distribution has been unpacked and
3035 opens a subshell there. Exiting the subshell returns.
3036
3037 =item CPAN::Distribution::make()
3038
3039 First runs the C<get> method to make sure the distribution is
3040 downloaded and unpacked. Changes to the directory where the
3041 distribution has been unpacked and runs the external commands C<perl
3042 Makefile.PL> or C<perl Build.PL> and C<make> there.
3043
3044 =item CPAN::Distribution::perldoc()
3045
3046 Downloads the pod documentation of the file associated with a
3047 distribution (in HTML format) and runs it through the external
3048 command I<lynx> specified in C<< $CPAN::Config->{lynx} >>. If I<lynx>
3049 isn't available, it converts it to plain text with the external
3050 command I<html2text> and runs it through the pager specified
3051 in C<< $CPAN::Config->{pager} >>.
3052
3053 =item CPAN::Distribution::prefs()
3054
3055 Returns the hash reference from the first matching YAML file that the
3056 user has deposited in the C<prefs_dir/> directory. The first
3057 succeeding match wins. The files in the C<prefs_dir/> are processed
3058 alphabetically, and the canonical distro name (e.g.
3059 AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions
3060 stored in the $root->{match}{distribution} attribute value.
3061 Additionally all module names contained in a distribution are matched
3062 against the regular expressions in the $root->{match}{module} attribute
3063 value. The two match values are ANDed together. Each of the two
3064 attributes are optional.
3065
3066 =item CPAN::Distribution::prereq_pm()
3067
3068 Returns the hash reference that has been announced by a distribution
3069 as the C<requires> and C<build_requires> elements. These can be
3070 declared either by the C<META.yml> (if authoritative) or can be
3071 deposited after the run of C<Build.PL> in the file C<./_build/prereqs>
3072 or after the run of C<Makfile.PL> written as the C<PREREQ_PM> hash in
3073 a comment in the produced C<Makefile>. I<Note>: this method only works
3074 after an attempt has been made to C<make> the distribution. Returns
3075 undef otherwise.
3076
3077 =item CPAN::Distribution::readme()
3078
3079 Downloads the README file associated with a distribution and runs it
3080 through the pager specified in C<< $CPAN::Config->{pager} >>.
3081
3082 =item CPAN::Distribution::reports()
3083
3084 Downloads report data for this distribution from www.cpantesters.org
3085 and displays a subset of them.
3086
3087 =item CPAN::Distribution::read_yaml()
3088
3089 Returns the content of the META.yml of this distro as a hashref. Note:
3090 works only after an attempt has been made to C<make> the distribution.
3091 Returns undef otherwise. Also returns undef if the content of META.yml
3092 is not authoritative. (The rules about what exactly makes the content
3093 authoritative are still in flux.)
3094
3095 =item CPAN::Distribution::test()
3096
3097 Changes to the directory where the distribution has been unpacked and
3098 runs C<make test> there.
3099
3100 =item CPAN::Distribution::uptodate()
3101
3102 Returns 1 if all the modules contained in the distribution are
3103 up-to-date. Relies on containsmods.
3104
3105 =item CPAN::Index::force_reload()
3106
3107 Forces a reload of all indices.
3108
3109 =item CPAN::Index::reload()
3110
3111 Reloads all indices if they have not been read for more than
3112 C<< $CPAN::Config->{index_expire} >> days.
3113
3114 =item CPAN::InfoObj::dump()
3115
3116 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
3117 inherit this method. It prints the data structure associated with an
3118 object. Useful for debugging. Note: the data structure is considered
3119 internal and thus subject to change without notice.
3120
3121 =item CPAN::Module::as_glimpse()
3122
3123 Returns a one-line description of the module in four columns: The
3124 first column contains the word C<Module>, the second column consists
3125 of one character: an equals sign if this module is already installed
3126 and up-to-date, a less-than sign if this module is installed but can be
3127 upgraded, and a space if the module is not installed. The third column
3128 is the name of the module and the fourth column gives maintainer or
3129 distribution information.
3130
3131 =item CPAN::Module::as_string()
3132
3133 Returns a multi-line description of the module
3134
3135 =item CPAN::Module::clean()
3136
3137 Runs a clean on the distribution associated with this module.
3138
3139 =item CPAN::Module::cpan_file()
3140
3141 Returns the filename on CPAN that is associated with the module.
3142
3143 =item CPAN::Module::cpan_version()
3144
3145 Returns the latest version of this module available on CPAN.
3146
3147 =item CPAN::Module::cvs_import()
3148
3149 Runs a cvs_import on the distribution associated with this module.
3150
3151 =item CPAN::Module::description()
3152
3153 Returns a 44 character description of this module. Only available for
3154 modules listed in The Module List (CPAN/modules/00modlist.long.html
3155 or 00modlist.long.txt.gz)
3156
3157 =item CPAN::Module::distribution()
3158
3159 Returns the CPAN::Distribution object that contains the current
3160 version of this module.
3161
3162 =item CPAN::Module::dslip_status()
3163
3164 Returns a hash reference. The keys of the hash are the letters C<D>,
3165 C<S>, C<L>, C<I>, and <P>, for development status, support level,
3166 language, interface and public licence respectively. The data for the
3167 DSLIP status are collected by pause.perl.org when authors register
3168 their namespaces. The values of the 5 hash elements are one-character
3169 words whose meaning is described in the table below. There are also 5
3170 hash elements C<DV>, C<SV>, C<LV>, C<IV>, and <PV> that carry a more
3171 verbose value of the 5 status variables.
3172
3173 Where the 'DSLIP' characters have the following meanings:
3174
3175   D - Development Stage  (Note: *NO IMPLIED TIMESCALES*):
3176     i   - Idea, listed to gain consensus or as a placeholder
3177     c   - under construction but pre-alpha (not yet released)
3178     a/b - Alpha/Beta testing
3179     R   - Released
3180     M   - Mature (no rigorous definition)
3181     S   - Standard, supplied with Perl 5
3182
3183   S - Support Level:
3184     m   - Mailing-list
3185     d   - Developer
3186     u   - Usenet newsgroup comp.lang.perl.modules
3187     n   - None known, try comp.lang.perl.modules
3188     a   - abandoned; volunteers welcome to take over maintenance
3189
3190   L - Language Used:
3191     p   - Perl-only, no compiler needed, should be platform independent
3192     c   - C and perl, a C compiler will be needed
3193     h   - Hybrid, written in perl with optional C code, no compiler needed
3194     +   - C++ and perl, a C++ compiler will be needed
3195     o   - perl and another language other than C or C++
3196
3197   I - Interface Style
3198     f   - plain Functions, no references used
3199     h   - hybrid, object and function interfaces available
3200     n   - no interface at all (huh?)
3201     r   - some use of unblessed References or ties
3202     O   - Object oriented using blessed references and/or inheritance
3203
3204   P - Public License
3205     p   - Standard-Perl: user may choose between GPL and Artistic
3206     g   - GPL: GNU General Public License
3207     l   - LGPL: "GNU Lesser General Public License" (previously known as
3208           "GNU Library General Public License")
3209     b   - BSD: The BSD License
3210     a   - Artistic license alone
3211     2   - Artistic license 2.0 or later
3212     o   - open source: approved by www.opensource.org
3213     d   - allows distribution without restrictions
3214     r   - restricted distribution
3215     n   - no license at all
3216
3217 =item CPAN::Module::force($method,@args)
3218
3219 Forces CPAN to perform a task it would normally refuse to
3220 do. Force takes as arguments a method name to be invoked and any number
3221 of additional arguments to pass that method.
3222 The internals of the object get the needed changes so that CPAN.pm
3223 does not refuse to take the action. See also the section above on the
3224 C<force> and the C<fforce> pragma.
3225
3226 =item CPAN::Module::get()
3227
3228 Runs a get on the distribution associated with this module.
3229
3230 =item CPAN::Module::inst_file()
3231
3232 Returns the filename of the module found in @INC. The first file found
3233 is reported, just as perl itself stops searching @INC once it finds a
3234 module.
3235
3236 =item CPAN::Module::available_file()
3237
3238 Returns the filename of the module found in PERL5LIB or @INC. The
3239 first file found is reported. The advantage of this method over
3240 C<inst_file> is that modules that have been tested but not yet
3241 installed are included because PERL5LIB keeps track of tested modules.
3242
3243 =item CPAN::Module::inst_version()
3244
3245 Returns the version number of the installed module in readable format.
3246
3247 =item CPAN::Module::available_version()
3248
3249 Returns the version number of the available module in readable format.
3250
3251 =item CPAN::Module::install()
3252
3253 Runs an C<install> on the distribution associated with this module.
3254
3255 =item CPAN::Module::look()
3256
3257 Changes to the directory where the distribution associated with this
3258 module has been unpacked and opens a subshell there. Exiting the
3259 subshell returns.
3260
3261 =item CPAN::Module::make()
3262
3263 Runs a C<make> on the distribution associated with this module.
3264
3265 =item CPAN::Module::manpage_headline()
3266
3267 If module is installed, peeks into the module's manpage, reads the
3268 headline, and returns it. Moreover, if the module has been downloaded
3269 within this session, does the equivalent on the downloaded module even
3270 if it hasn't been installed yet.
3271
3272 =item CPAN::Module::perldoc()
3273
3274 Runs a C<perldoc> on this module.
3275
3276 =item CPAN::Module::readme()
3277
3278 Runs a C<readme> on the distribution associated with this module.
3279
3280 =item CPAN::Module::reports()
3281
3282 Calls the reports() method on the associated distribution object.
3283
3284 =item CPAN::Module::test()
3285
3286 Runs a C<test> on the distribution associated with this module.
3287
3288 =item CPAN::Module::uptodate()
3289
3290 Returns 1 if the module is installed and up-to-date.
3291
3292 =item CPAN::Module::userid()
3293
3294 Returns the author's ID of the module.
3295
3296 =back
3297
3298 =head2 Cache Manager
3299
3300 Currently the cache manager only keeps track of the build directory
3301 ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
3302 deletes complete directories below C<build_dir> as soon as the size of
3303 all directories there gets bigger than $CPAN::Config->{build_cache}
3304 (in MB). The contents of this cache may be used for later
3305 re-installations that you intend to do manually, but will never be
3306 trusted by CPAN itself. This is due to the fact that the user might
3307 use these directories for building modules on different architectures.
3308
3309 There is another directory ($CPAN::Config->{keep_source_where}) where
3310 the original distribution files are kept. This directory is not
3311 covered by the cache manager and must be controlled by the user. If
3312 you choose to have the same directory as build_dir and as
3313 keep_source_where directory, then your sources will be deleted with
3314 the same fifo mechanism.
3315
3316 =head2 Bundles
3317
3318 A bundle is just a perl module in the namespace Bundle:: that does not
3319 define any functions or methods. It usually only contains documentation.
3320
3321 It starts like a perl module with a package declaration and a $VERSION
3322 variable. After that the pod section looks like any other pod with the
3323 only difference being that I<one special pod section> exists starting with
3324 (verbatim):
3325
3326     =head1 CONTENTS
3327
3328 In this pod section each line obeys the format
3329
3330         Module_Name [Version_String] [- optional text]
3331
3332 The only required part is the first field, the name of a module
3333 (e.g. Foo::Bar, i.e. I<not> the name of the distribution file). The rest
3334 of the line is optional. The comment part is delimited by a dash just
3335 as in the man page header.
3336
3337 The distribution of a bundle should follow the same convention as
3338 other distributions.
3339
3340 Bundles are treated specially in the CPAN package. If you say 'install
3341 Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
3342 the modules in the CONTENTS section of the pod. You can install your
3343 own Bundles locally by placing a conformant Bundle file somewhere into
3344 your @INC path. The autobundle() command which is available in the
3345 shell interface does that for you by including all currently installed
3346 modules in a snapshot bundle file.
3347
3348 =head1 PREREQUISITES
3349
3350 The CPAN program is trying to depend on as little as possible so the
3351 user can use it in hostile environment. It works better the more goodies
3352 the environment provides. For example if you try in the CPAN shell
3353
3354   install Bundle::CPAN
3355
3356 or
3357
3358   install Bundle::CPANxxl
3359
3360 you will find the shell more convenient than the bare shell before.
3361
3362 If you have a local mirror of CPAN and can access all files with
3363 "file:" URLs, then you only need a perl later than perl5.003 to run
3364 this module. Otherwise Net::FTP is strongly recommended. LWP may be
3365 required for non-UNIX systems, or if your nearest CPAN site is
3366 associated with a URL that is not C<ftp:>.
3367
3368 If you have neither Net::FTP nor LWP, there is a fallback mechanism
3369 implemented for an external ftp command or for an external lynx
3370 command.
3371
3372 =head1 UTILITIES
3373
3374 =head2 Finding packages and VERSION
3375
3376 This module presumes that all packages on CPAN
3377
3378 =over 2
3379
3380 =item *
3381
3382 declare their $VERSION variable in an easy to parse manner. This
3383 prerequisite can hardly be relaxed because it consumes far too much
3384 memory to load all packages into the running program just to determine
3385 the $VERSION variable. Currently all programs that are dealing with
3386 version use something like this
3387
3388     perl -MExtUtils::MakeMaker -le \
3389         'print MM->parse_version(shift)' filename
3390
3391 If you are author of a package and wonder if your $VERSION can be
3392 parsed, please try the above method.
3393
3394 =item *
3395
3396 come as compressed or gzipped tarfiles or as zip files and contain a
3397 C<Makefile.PL> or C<Build.PL> (well, we try to handle a bit more, but
3398 with little enthusiasm).
3399
3400 =back
3401
3402 =head2 Debugging
3403
3404 Debugging this module is more than a bit complex due to interference from
3405 the software producing the indices on CPAN, the mirroring process on CPAN,
3406 packaging, configuration, synchronicity, and even (gasp!) due to bugs
3407 within the CPAN.pm module itself.
3408
3409 For debugging the code of CPAN.pm itself in interactive mode, some
3410 debugging aid can be turned on for most packages within
3411 CPAN.pm with one of
3412
3413 =over 2
3414
3415 =item o debug package...
3416
3417 sets debug mode for packages.
3418
3419 =item o debug -package...
3420
3421 unsets debug mode for packages.
3422
3423 =item o debug all
3424
3425 turns debugging on for all packages.
3426
3427 =item o debug number
3428
3429 =back
3430
3431 which sets the debugging packages directly. Note that C<o debug 0>
3432 turns debugging off.
3433
3434 What seems a successful strategy is the combination of C<reload
3435 cpan> and the debugging switches. Add a new debug statement while
3436 running in the shell and then issue a C<reload cpan> and see the new
3437 debugging messages immediately without losing the current context.
3438
3439 C<o debug> without an argument lists the valid package names and the
3440 current set of packages in debugging mode. C<o debug> has built-in
3441 completion support.
3442
3443 For debugging of CPAN data there is the C<dump> command which takes
3444 the same arguments as make/test/install and outputs each object's
3445 Data::Dumper dump. If an argument looks like a perl variable and
3446 contains one of C<$>, C<@> or C<%>, it is eval()ed and fed to
3447 Data::Dumper directly.
3448
3449 =head2 Floppy, Zip, Offline Mode
3450
3451 CPAN.pm works nicely without network access, too. If you maintain machines
3452 that are not networked at all, you should consider working with C<file:>
3453 URLs. You'll have to collect your modules somewhere first. So
3454 you might use CPAN.pm to put together all you need on a networked
3455 machine. Then copy the $CPAN::Config->{keep_source_where} (but not
3456 $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
3457 of a personal CPAN. CPAN.pm on the non-networked machines works nicely
3458 with this floppy. See also below the paragraph about CD-ROM support.
3459
3460 =head2 Basic Utilities for Programmers
3461
3462 =over 2
3463
3464 =item has_inst($module)
3465
3466 Returns true if the module is installed. Used to load all modules into
3467 the running CPAN.pm that are considered optional. The config variable
3468 C<dontload_list> intercepts the C<has_inst()> call such
3469 that an optional module is not loaded despite being available. For
3470 example, the following command will prevent C<YAML.pm> from being
3471 loaded:
3472
3473     cpan> o conf dontload_list push YAML
3474
3475 See the source for details.
3476
3477 =item use_inst($module)
3478
3479 Similary to L<has_inst()> tries to load optional library but also dies if
3480 library is not available
3481
3482 =item has_usable($module)
3483
3484 Returns true if the module is installed and in a usable state. Only
3485 useful for a handful of modules that are used internally. See the
3486 source for details.
3487
3488 =item instance($module)
3489
3490 The constructor for all the singletons used to represent modules,
3491 distributions, authors, and bundles. If the object already exists, this
3492 method returns the object; otherwise, it calls the constructor.
3493
3494 =item frontend()
3495
3496 =item frontend($new_frontend)
3497
3498 Getter/setter for frontend object. Method just allows to subclass CPAN.pm.
3499
3500 =back
3501
3502 =head1 SECURITY
3503
3504 There's no strong security layer in CPAN.pm. CPAN.pm helps you to
3505 install foreign, unmasked, unsigned code on your machine. We compare
3506 to a checksum that comes from the net just as the distribution file
3507 itself. But we try to make it easy to add security on demand:
3508
3509 =head2 Cryptographically signed modules
3510
3511 Since release 1.77, CPAN.pm has been able to verify cryptographically
3512 signed module distributions using Module::Signature.  The CPAN modules
3513 can be signed by their authors, thus giving more security.  The simple
3514 unsigned MD5 checksums that were used before by CPAN protect mainly
3515 against accidental file corruption.
3516
3517 You will need to have Module::Signature installed, which in turn
3518 requires that you have at least one of Crypt::OpenPGP module or the
3519 command-line F<gpg> tool installed.
3520
3521 You will also need to be able to connect over the Internet to the public
3522 key servers, like pgp.mit.edu, and their port 11731 (the HKP protocol).
3523
3524 The configuration parameter check_sigs is there to turn signature
3525 checking on or off.
3526
3527 =head1 EXPORT
3528
3529 Most functions in package CPAN are exported by default. The reason
3530 for this is that the primary use is intended for the cpan shell or for
3531 one-liners.
3532
3533 =head1 ENVIRONMENT
3534
3535 When the CPAN shell enters a subshell via the look command, it sets
3536 the environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
3537 already set.
3538
3539 When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
3540 to the ID of the running process. It also sets
3541 PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
3542 happen with older versions of Module::Install.
3543
3544 When running C<perl Makefile.PL>, the environment variable
3545 C<PERL5_CPAN_IS_EXECUTING> is set to the full path of the
3546 C<Makefile.PL> that is being executed. This prevents runaway processes
3547 with newer versions of Module::Install.
3548
3549 When the config variable ftp_passive is set, all downloads will be run
3550 with the environment variable FTP_PASSIVE set to this value. This is
3551 in general a good idea as it influences both Net::FTP and LWP based
3552 connections. The same effect can be achieved by starting the cpan
3553 shell with this environment variable set. For Net::FTP alone, one can
3554 also always set passive mode by running libnetcfg.
3555
3556 =head1 POPULATE AN INSTALLATION WITH LOTS OF MODULES
3557
3558 Populating a freshly installed perl with one's favorite modules is pretty
3559 easy if you maintain a private bundle definition file. To get a useful
3560 blueprint of a bundle definition file, the command autobundle can be used
3561 on the CPAN shell command line. This command writes a bundle definition
3562 file for all modules installed for the current perl
3563 interpreter. It's recommended to run this command once only, and from then
3564 on maintain the file manually under a private name, say
3565 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
3566
3567     cpan> install Bundle::my_bundle
3568
3569 then answer a few questions and go out for coffee (possibly
3570 even in a different city).
3571
3572 Maintaining a bundle definition file means keeping track of two
3573 things: dependencies and interactivity. CPAN.pm sometimes fails on
3574 calculating dependencies because not all modules define all MakeMaker
3575 attributes correctly, so a bundle definition file should specify
3576 prerequisites as early as possible. On the other hand, it's
3577 annoying that so many distributions need some interactive configuring. So
3578 what you can try to accomplish in your private bundle file is to have the
3579 packages that need to be configured early in the file and the gentle
3580 ones later, so you can go out for coffee after a few minutes and leave CPAN.pm
3581 to churn away unattended.
3582
3583 =head1 WORKING WITH CPAN.pm BEHIND FIREWALLS
3584
3585 Thanks to Graham Barr for contributing the following paragraphs about
3586 the interaction between perl, and various firewall configurations. For
3587 further information on firewalls, it is recommended to consult the
3588 documentation that comes with the I<ncftp> program. If you are unable to
3589 go through the firewall with a simple Perl setup, it is likely
3590 that you can configure I<ncftp> so that it works through your firewall.
3591
3592 =head2 Three basic types of firewalls
3593
3594 Firewalls can be categorized into three basic types.
3595
3596 =over 4
3597
3598 =item http firewall
3599
3600 This is when the firewall machine runs a web server, and to access the
3601 outside world, you must do so via that web server. If you set environment
3602 variables like http_proxy or ftp_proxy to values beginning with http://,
3603 or in your web browser you've proxy information set, then you know
3604 you are running behind an http firewall.
3605
3606 To access servers outside these types of firewalls with perl (even for
3607 ftp), you need LWP or HTTP::Tiny.
3608
3609 =item ftp firewall
3610
3611 This where the firewall machine runs an ftp server. This kind of
3612 firewall will only let you access ftp servers outside the firewall.
3613 This is usually done by connecting to the firewall with ftp, then
3614 entering a username like "user@outside.host.com".
3615
3616 To access servers outside these type of firewalls with perl, you
3617 need Net::FTP.
3618
3619 =item One-way visibility
3620
3621 One-way visibility means these firewalls try to make themselves
3622 invisible to users inside the firewall. An FTP data connection is
3623 normally created by sending your IP address to the remote server and then
3624 listening for the return connection. But the remote server will not be able to
3625 connect to you because of the firewall. For these types of firewall,
3626 FTP connections need to be done in a passive mode.
3627
3628 There are two that I can think off.
3629
3630 =over 4
3631
3632 =item SOCKS
3633
3634 If you are using a SOCKS firewall, you will need to compile perl and link
3635 it with the SOCKS library.  This is what is normally called a 'socksified'
3636 perl. With this executable you will be able to connect to servers outside
3637 the firewall as if it were not there.
3638
3639 =item IP Masquerade
3640
3641 This is when the firewall implemented in the kernel (via NAT, or networking
3642 address translation), it allows you to hide a complete network behind one
3643 IP address. With this firewall no special compiling is needed as you can
3644 access hosts directly.
3645
3646 For accessing ftp servers behind such firewalls you usually need to
3647 set the environment variable C<FTP_PASSIVE> or the config variable
3648 ftp_passive to a true value.
3649
3650 =back
3651
3652 =back
3653
3654 =head2 Configuring lynx or ncftp for going through a firewall
3655
3656 If you can go through your firewall with e.g. lynx, presumably with a
3657 command such as
3658
3659     /usr/local/bin/lynx -pscott:tiger
3660
3661 then you would configure CPAN.pm with the command
3662
3663     o conf lynx "/usr/local/bin/lynx -pscott:tiger"
3664
3665 That's all. Similarly for ncftp or ftp, you would configure something
3666 like
3667
3668     o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"
3669
3670 Your mileage may vary...
3671
3672 =head1 FAQ
3673
3674 =over 4
3675
3676 =item 1)
3677
3678 I installed a new version of module X but CPAN keeps saying,
3679 I have the old version installed
3680
3681 Probably you B<do> have the old version installed. This can
3682 happen if a module installs itself into a different directory in the
3683 @INC path than it was previously installed. This is not really a
3684 CPAN.pm problem, you would have the same problem when installing the
3685 module manually. The easiest way to prevent this behaviour is to add
3686 the argument C<UNINST=1> to the C<make install> call, and that is why
3687 many people add this argument permanently by configuring
3688
3689   o conf make_install_arg UNINST=1
3690
3691 =item 2)
3692
3693 So why is UNINST=1 not the default?
3694
3695 Because there are people who have their precise expectations about who
3696 may install where in the @INC path and who uses which @INC array. In
3697 fine tuned environments C<UNINST=1> can cause damage.
3698
3699 =item 3)
3700
3701 I want to clean up my mess, and install a new perl along with
3702 all modules I have. How do I go about it?
3703
3704 Run the autobundle command for your old perl and optionally rename the
3705 resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
3706 with the Configure option prefix, e.g.
3707
3708     ./Configure -Dprefix=/usr/local/perl-5.6.78.9
3709
3710 Install the bundle file you produced in the first step with something like
3711
3712     cpan> install Bundle::mybundle
3713
3714 and you're done.
3715
3716 =item 4)
3717
3718 When I install bundles or multiple modules with one command
3719 there is too much output to keep track of.
3720
3721 You may want to configure something like
3722
3723   o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
3724   o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"
3725
3726 so that STDOUT is captured in a file for later inspection.
3727
3728
3729 =item 5)
3730
3731 I am not root, how can I install a module in a personal directory?
3732
3733 As of CPAN 1.9463, if you do not have permission to write the default perl
3734 library directories, CPAN's configuration process will ask you whether
3735 you want to bootstrap <local::lib>, which makes keeping a personal
3736 perl library directory easy.
3737
3738 Another thing you should bear in mind is that the UNINST parameter can
3739 be dangerous when you are installing into a private area because you
3740 might accidentally remove modules that other people depend on that are
3741 not using the private area.
3742
3743 =item 6)
3744
3745 How to get a package, unwrap it, and make a change before building it?
3746
3747 Have a look at the C<look> (!) command.
3748
3749 =item 7)
3750
3751 I installed a Bundle and had a couple of fails. When I
3752 retried, everything resolved nicely. Can this be fixed to work
3753 on first try?
3754
3755 The reason for this is that CPAN does not know the dependencies of all
3756 modules when it starts out. To decide about the additional items to
3757 install, it just uses data found in the META.yml file or the generated
3758 Makefile. An undetected missing piece breaks the process. But it may
3759 well be that your Bundle installs some prerequisite later than some
3760 depending item and thus your second try is able to resolve everything.
3761 Please note, CPAN.pm does not know the dependency tree in advance and
3762 cannot sort the queue of things to install in a topologically correct
3763 order. It resolves perfectly well B<if> all modules declare the
3764 prerequisites correctly with the PREREQ_PM attribute to MakeMaker or
3765 the C<requires> stanza of Module::Build. For bundles which fail and
3766 you need to install often, it is recommended to sort the Bundle
3767 definition file manually.
3768
3769 =item 8)
3770
3771 In our intranet, we have many modules for internal use. How
3772 can I integrate these modules with CPAN.pm but without uploading
3773 the modules to CPAN?
3774
3775 Have a look at the CPAN::Site module.
3776
3777 =item 9)
3778
3779 When I run CPAN's shell, I get an error message about things in my
3780 C</etc/inputrc> (or C<~/.inputrc>) file.
3781
3782 These are readline issues and can only be fixed by studying readline
3783 configuration on your architecture and adjusting the referenced file
3784 accordingly. Please make a backup of the C</etc/inputrc> or C<~/.inputrc>
3785 and edit them. Quite often harmless changes like uppercasing or
3786 lowercasing some arguments solves the problem.
3787
3788 =item 10)
3789
3790 Some authors have strange characters in their names.
3791
3792 Internally CPAN.pm uses the UTF-8 charset. If your terminal is
3793 expecting ISO-8859-1 charset, a converter can be activated by setting
3794 term_is_latin to a true value in your config file. One way of doing so
3795 would be
3796
3797     cpan> o conf term_is_latin 1
3798
3799 If other charset support is needed, please file a bug report against
3800 CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend
3801 the support or maybe UTF-8 terminals become widely available.
3802
3803 Note: this config variable is deprecated and will be removed in a
3804 future version of CPAN.pm. It will be replaced with the conventions
3805 around the family of $LANG and $LC_* environment variables.
3806
3807 =item 11)
3808
3809 When an install fails for some reason and then I correct the error
3810 condition and retry, CPAN.pm refuses to install the module, saying
3811 C<Already tried without success>.
3812
3813 Use the force pragma like so
3814
3815   force install Foo::Bar
3816
3817 Or you can use
3818
3819   look Foo::Bar
3820
3821 and then C<make install> directly in the subshell.
3822
3823 =item 12)
3824
3825 How do I install a "DEVELOPER RELEASE" of a module?
3826
3827 By default, CPAN will install the latest non-developer release of a
3828 module. If you want to install a dev release, you have to specify the
3829 partial path starting with the author id to the tarball you wish to
3830 install, like so:
3831
3832     cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
3833
3834 Note that you can use the C<ls> command to get this path listed.
3835
3836 =item 13)
3837
3838 How do I install a module and all its dependencies from the commandline,
3839 without being prompted for anything, despite my CPAN configuration
3840 (or lack thereof)?
3841
3842 CPAN uses ExtUtils::MakeMaker's prompt() function to ask its questions, so
3843 if you set the PERL_MM_USE_DEFAULT environment variable, you shouldn't be
3844 asked any questions at all (assuming the modules you are installing are
3845 nice about obeying that variable as well):
3846
3847     % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'
3848
3849 =item 14)
3850
3851 How do I create a Module::Build based Build.PL derived from an
3852 ExtUtils::MakeMaker focused Makefile.PL?
3853
3854 http://search.cpan.org/dist/Module-Build-Convert/
3855
3856 =item 15)
3857
3858 I'm frequently irritated with the CPAN shell's inability to help me
3859 select a good mirror.
3860
3861 CPAN can now help you select a "good" mirror, based on which ones have the
3862 lowest 'ping' round-trip times.  From the shell, use the command 'o conf init
3863 urllist' and allow CPAN to automatically select mirrors for you.
3864
3865 Beyond that help, the urllist config parameter is yours. You can add and remove
3866 sites at will. You should find out which sites have the best up-to-dateness,
3867 bandwidth, reliability, etc. and are topologically close to you. Some people
3868 prefer fast downloads, others up-to-dateness, others reliability.  You decide
3869 which to try in which order.
3870
3871 Henk P. Penning maintains a site that collects data about CPAN sites:
3872
3873   http://mirrors.cpan.org/
3874
3875 Also, feel free to play with experimental features. Run
3876
3877   o conf init randomize_urllist ftpstats_period ftpstats_size
3878
3879 and choose your favorite parameters. After a few downloads running the
3880 C<hosts> command will probably assist you in choosing the best mirror
3881 sites.
3882
3883 =item 16)
3884
3885 Why do I get asked the same questions every time I start the shell?
3886
3887 You can make your configuration changes permanent by calling the
3888 command C<o conf commit>. Alternatively set the C<auto_commit>
3889 variable to true by running C<o conf init auto_commit> and answering
3890 the following question with yes.
3891
3892 =item 17)
3893
3894 Older versions of CPAN.pm had the original root directory of all
3895 tarballs in the build directory. Now there are always random
3896 characters appended to these directory names. Why was this done?
3897
3898 The random characters are provided by File::Temp and ensure that each
3899 module's individual build directory is unique. This makes running
3900 CPAN.pm in concurrent processes simultaneously safe.
3901
3902 =item 18)
3903
3904 Speaking of the build directory. Do I have to clean it up myself?
3905
3906 You have the choice to set the config variable C<scan_cache> to
3907 C<never>. Then you must clean it up yourself. The other possible
3908 values, C<atstart> and C<atexit> clean up the build directory when you
3909 start (or more precisely, after the first extraction into the build
3910 directory) or exit the CPAN shell, respectively. If you never start up
3911 the CPAN shell, you probably also have to clean up the build directory
3912 yourself.
3913
3914 =back
3915
3916 =head1 COMPATIBILITY
3917
3918 =head2 OLD PERL VERSIONS
3919
3920 CPAN.pm is regularly tested to run under 5.005 and assorted
3921 newer versions. It is getting more and more difficult to get the
3922 minimal prerequisites working on older perls. It is close to
3923 impossible to get the whole Bundle::CPAN working there. If you're in
3924 the position to have only these old versions, be advised that CPAN is
3925 designed to work fine without the Bundle::CPAN installed.
3926
3927 To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
3928 compatible with ancient perls and that File::Temp is listed as a
3929 prerequisite but CPAN has reasonable workarounds if it is missing.
3930
3931 =head2 CPANPLUS
3932
3933 This module and its competitor, the CPANPLUS module, are both much
3934 cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
3935 more modular, but it was never intended to be compatible with CPAN.pm.
3936
3937 =head2 CPANMINUS
3938
3939 In the year 2010 App::cpanminus was launched as a new approach to a
3940 cpan shell with a considerably smaller footprint. Very cool stuff.
3941
3942 =head1 SECURITY ADVICE
3943
3944 This software enables you to upgrade software on your computer and so
3945 is inherently dangerous because the newly installed software may
3946 contain bugs and may alter the way your computer works or even make it
3947 unusable. Please consider backing up your data before every upgrade.
3948
3949 =head1 BUGS
3950
3951 Please report bugs via L<http://rt.cpan.org/>
3952
3953 Before submitting a bug, please make sure that the traditional method
3954 of building a Perl module package from a shell by following the
3955 installation instructions of that package still works in your
3956 environment.
3957
3958 =head1 AUTHOR
3959
3960 Andreas Koenig C<< <andk@cpan.org> >>
3961
3962 =head1 LICENSE
3963
3964 This program is free software; you can redistribute it and/or
3965 modify it under the same terms as Perl itself.
3966
3967 See L<http://www.perl.com/perl/misc/Artistic.html>
3968
3969 =head1 TRANSLATIONS
3970
3971 Kawai,Takanori provides a Japanese translation of a very old version
3972 of this manpage at
3973 L<http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
3974
3975 =head1 SEE ALSO
3976
3977 Many people enter the CPAN shell by running the L<cpan> utility
3978 program which is installed in the same directory as perl itself. So if
3979 you have this directory in your PATH variable (or some equivalent in
3980 your operating system) then typing C<cpan> in a console window will
3981 work for you as well. Above that the utility provides several
3982 commandline shortcuts.
3983
3984 melezhik (Alexey) sent me a link where he published a chef recipe to
3985 work with CPAN.pm: http://community.opscode.com/cookbooks/cpan.
3986
3987
3988 =cut