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