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