cpan/CPAN/lib/CPAN.pm

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