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