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