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