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