cpan/CPAN/lib/CPAN.pm

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