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