2 use vars qw{$Try_autoload $Revision
3 $META $Signal $Cwd $End
4 $Suppress_readline %Dontload
10 # $Id: CPAN.pm,v 1.226 1998/07/08 22:29:29 k Exp k $
12 # only used during development:
14 # $Revision = "[".substr(q$Revision: 1.226 $, 10)."]";
21 use ExtUtils::MakeMaker ();
22 use File::Basename ();
28 use Text::ParseWords ();
31 END { $End++; &cleanup; }
52 $CPAN::Frontend ||= "CPAN::Shell";
53 $CPAN::Defaultsite ||= "ftp://ftp.perl.org/pub/CPAN";
56 use vars qw($VERSION @EXPORT $AUTOLOAD $DEBUG $META $term);
59 @CPAN::ISA = qw(CPAN::Debug Exporter MM); # MM will go away
60 # soonish. Already version
61 # 1.29 doesn't rely on
62 # catfile and catdir being
64 # inheritance. Anything else
68 autobundle bundle expand force get
69 install make readme recompile shell test clean
72 #-> sub CPAN::AUTOLOAD ;
77 @EXPORT{@EXPORT} = '';
78 if (exists $EXPORT{$l}){
81 my $ok = CPAN::Shell->try_dot_al($AUTOLOAD);
85 # $CPAN::Frontend->mywarn("Could not autoload $AUTOLOAD");
87 $CPAN::Frontend->mywarn(qq{Unknown command "$AUTOLOAD". }.
95 $Suppress_readline ||= ! -t STDIN;
97 my $prompt = "cpan> ";
99 unless ($Suppress_readline) {
100 require Term::ReadLine;
101 # import Term::ReadLine;
102 $term = Term::ReadLine->new('CPAN Monitor');
103 $readline::rl_completion_function =
104 $readline::rl_completion_function = 'CPAN::Complete::cpl';
110 $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
111 my $cwd = CPAN->$getcwd();
112 my $rl_avail = $Suppress_readline ? "suppressed" :
113 ($term->ReadLine ne "Term::ReadLine::Stub") ? "enabled" :
114 "available (try ``install Bundle::CPAN'')";
116 $CPAN::Frontend->myprint(
118 cpan shell -- CPAN exploration and modules installation (v$CPAN::VERSION$CPAN::Revision)
119 ReadLine support $rl_avail
121 }) unless $CPAN::Config->{'inhibit_startup_message'} ;
122 my($continuation) = "";
124 if ($Suppress_readline) {
126 last unless defined ($_ = <> );
129 last unless defined ($_ = $term->readline($prompt));
131 $_ = "$continuation$_" if $continuation;
134 $_ = 'h' if $_ eq '?';
135 if (/^(?:q(?:uit)?|bye|exit)$/i) {
145 use vars qw($import_done);
146 CPAN->import(':DEFAULT') unless $import_done++;
147 CPAN->debug("eval[$eval]") if $CPAN::DEBUG;
154 if ($] < 5.00322) { # parsewords had a bug until recently
157 eval { @line = Text::ParseWords::shellwords($_) };
158 warn($@), next if $@;
160 $CPAN::META->debug("line[".join("|",@line)."]") if $CPAN::DEBUG;
161 my $command = shift @line;
162 eval { CPAN::Shell->$command(@line) };
165 $CPAN::Frontend->myprint("\n");
174 package CPAN::CacheMgr;
175 @CPAN::CacheMgr::ISA = qw(CPAN::InfoObj CPAN);
178 package CPAN::Config;
179 import ExtUtils::MakeMaker 'neatvalue';
180 use vars qw(%can $dot_cpan);
183 'commit' => "Commit changes to disk",
184 'defaults' => "Reload defaults from disk",
185 'init' => "Interactive setting of all options",
189 use vars qw($Ua $Thesite $Themethod);
190 @CPAN::FTP::ISA = qw(CPAN::Debug);
192 package CPAN::Complete;
193 @CPAN::Complete::ISA = qw(CPAN::Debug);
196 use vars qw($last_time $date_of_03);
197 @CPAN::Index::ISA = qw(CPAN::Debug);
201 package CPAN::InfoObj;
202 @CPAN::InfoObj::ISA = qw(CPAN::Debug);
204 package CPAN::Author;
205 @CPAN::Author::ISA = qw(CPAN::InfoObj);
207 package CPAN::Distribution;
208 @CPAN::Distribution::ISA = qw(CPAN::InfoObj);
210 package CPAN::Bundle;
211 @CPAN::Bundle::ISA = qw(CPAN::Module);
213 package CPAN::Module;
214 @CPAN::Module::ISA = qw(CPAN::InfoObj);
217 use vars qw($AUTOLOAD $redef @ISA);
218 @CPAN::Shell::ISA = qw(CPAN::Debug);
220 #-> sub CPAN::Shell::AUTOLOAD ;
222 my($autoload) = $AUTOLOAD;
223 my $class = shift(@_);
224 # warn "autoload[$autoload] class[$class]";
225 $autoload =~ s/.*:://;
226 if ($autoload =~ /^w/) {
227 if ($CPAN::META->has_inst('CPAN::WAIT')) {
228 CPAN::WAIT->$autoload(@_);
230 $CPAN::Frontend->mywarn(qq{
231 Commands starting with "w" require CPAN::WAIT to be installed.
232 Please consider installing CPAN::WAIT to use the fulltext index.
233 For this you just need to type
238 my $ok = CPAN::Shell->try_dot_al($AUTOLOAD);
242 # $CPAN::Frontend->mywarn("Could not autoload $autoload");
244 $CPAN::Frontend->mywarn(qq{Unknown command '$autoload'. }.
250 #-> CPAN::Shell::try_dot_al
252 my($class,$autoload) = @_;
253 return unless $CPAN::Try_autoload;
254 # I don't see how to re-use that from the AutoLoader...
256 # Braces used to preserve $1 et al.
258 my ($pkg,$func) = $autoload =~ /(.*)::([^:]+)$/;
260 if (defined($name=$INC{"$pkg.pm"}))
262 $name =~ s|^(.*)$pkg\.pm$|$1auto/$pkg/$func.al|;
263 $name = undef unless (-r $name);
265 unless (defined $name)
267 $name = "auto/$autoload.al";
272 eval {local $SIG{__DIE__};require $name};
274 if (substr($autoload,-9) eq '::DESTROY') {
278 if ($name =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){
279 eval {local $SIG{__DIE__};require $name};
292 # my $lm = Carp::longmess();
293 # warn "ok[$ok] autoload[$autoload] longmess[$lm]"; # debug
297 #### autoloader is experimental
298 #### to try it we have to set $Try_autoload and uncomment
299 #### the use statement and uncomment the __END__ below
300 #### You also need AutoSplit 1.01 available. MakeMaker will
301 #### then build CPAN with all the AutoLoad stuff.
305 if ($CPAN::Try_autoload) {
308 CPAN::Author CPAN::Bundle CPAN::CacheMgr CPAN::Complete
309 CPAN::Config CPAN::Debug CPAN::Distribution CPAN::FTP
310 CPAN::FTP::netrc CPAN::Index CPAN::InfoObj CPAN::Module
312 *{"$p\::AUTOLOAD"} = \&AutoLoader::AUTOLOAD;
316 package CPAN::Tarzip;
317 use vars qw($AUTOLOAD @ISA);
318 @CPAN::Tarzip::ISA = qw(CPAN::Debug);
321 # currently only used to determine if we should or shouldn't announce
322 # the availability of a new CPAN module
324 my($class,$mod) = @_;
325 # warn "Queue object for mod[$mod]";
326 bless {mod => $mod}, $class;
331 $META ||= CPAN->new; # In case we reeval ourselves we
334 # Do this after you have set up the whole inheritance
335 CPAN::Config->load unless defined $CPAN::No_Config_is_ok;
339 # __END__ # uncomment this and AutoSplit version 1.01 will split it
341 #-> sub CPAN::autobundle ;
343 #-> sub CPAN::bundle ;
345 #-> sub CPAN::expand ;
347 #-> sub CPAN::force ;
349 #-> sub CPAN::install ;
353 #-> sub CPAN::clean ;
360 my($mgr,$class) = @_;
361 CPAN->debug("mgr[$mgr] class[$class]") if $CPAN::DEBUG;
363 values %{ $META->{$class} };
366 # Called by shell, not in batch mode. Not clean XXX
367 #-> sub CPAN::checklock ;
370 my $lockfile = MM->catfile($CPAN::Config->{cpan_home},".lock");
371 if (-f $lockfile && -M _ > 0) {
372 my $fh = FileHandle->new($lockfile);
375 if (defined $other && $other) {
377 return if $$==$other; # should never happen
378 $CPAN::Frontend->mywarn(
380 There seems to be running another CPAN process ($other). Contacting...
382 if (kill 0, $other) {
383 $CPAN::Frontend->mydie(qq{Other job is running.
384 You may want to kill it and delete the lockfile, maybe. On UNIX try:
388 } elsif (-w $lockfile) {
390 ExtUtils::MakeMaker::prompt
391 (qq{Other job not responding. Shall I overwrite }.
392 qq{the lockfile? (Y/N)},"y");
393 $CPAN::Frontend->myexit("Ok, bye\n")
394 unless $ans =~ /^y/i;
397 qq{Lockfile $lockfile not writeable by you. }.
398 qq{Cannot proceed.\n}.
401 qq{ and then rerun us.\n}
406 File::Path::mkpath($CPAN::Config->{cpan_home});
408 unless ($fh = FileHandle->new(">$lockfile")) {
409 if ($! =~ /Permission/) {
410 my $incc = $INC{'CPAN/Config.pm'};
411 my $myincc = MM->catfile($ENV{HOME},'.cpan','CPAN','MyConfig.pm');
412 $CPAN::Frontend->myprint(qq{
414 Your configuration suggests that CPAN.pm should use a working
416 $CPAN::Config->{cpan_home}
417 Unfortunately we could not create the lock file
419 due to permission problems.
421 Please make sure that the configuration variable
422 \$CPAN::Config->{cpan_home}
423 points to a directory where you can write a .lock file. You can set
424 this variable in either
431 $CPAN::Frontend->mydie("Could not open >$lockfile: $!");
433 $fh->print($$, "\n");
434 $self->{LOCK} = $lockfile;
438 $CPAN::Frontend->mydie("Got SIGTERM, leaving");
443 $CPAN::Frontend->mydie("Got another SIGINT") if $Signal;
444 print "Caught SIGINT\n";
447 $SIG{'__DIE__'} = \&cleanup;
448 $self->debug("Signal handler set.") if $CPAN::DEBUG;
451 #-> sub CPAN::DESTROY ;
453 &cleanup; # need an eval?
457 sub cwd {Cwd::cwd();}
459 #-> sub CPAN::getcwd ;
460 sub getcwd {Cwd::getcwd();}
462 #-> sub CPAN::exists ;
464 my($mgr,$class,$id) = @_;
466 ### Carp::croak "exists called without class argument" unless $class;
468 exists $META->{$class}{$id};
471 #-> sub CPAN::delete ;
473 my($mgr,$class,$id) = @_;
474 delete $META->{$class}{$id};
477 #-> sub CPAN::has_inst
479 my($self,$mod,$message) = @_;
480 Carp::croak("CPAN->has_inst() called without an argument")
482 if (defined $message && $message eq "no") {
485 } elsif (exists $Dontload{$mod}) {
491 $file =~ s|/|\\|g if $^O eq 'MSWin32';
494 # warn "$file in %INC"; #debug
496 } elsif (eval { require $file }) {
497 # eval is good: if we haven't yet read the database it's
498 # perfect and if we have installed the module in the meantime,
499 # it tries again. The second require is only a NOOP returning
500 # 1 if we had success, otherwise it's retrying
501 $CPAN::Frontend->myprint("CPAN: $mod loaded ok\n");
502 if ($mod eq "CPAN::WAIT") {
503 push @CPAN::Shell::ISA, CPAN::WAIT;
506 } elsif ($mod eq "Net::FTP") {
508 Please, install Net::FTP as soon as possible. CPAN.pm installs it for you
510 install Bundle::libnet
514 } elsif ($mod eq "MD5"){
515 $CPAN::Frontend->myprint(qq{
516 CPAN: MD5 security checks disabled because MD5 not installed.
517 Please consider installing the MD5 module.
525 #-> sub CPAN::instance ;
527 my($mgr,$class,$id) = @_;
530 $META->{$class}{$id} ||= $class->new(ID => $id );
538 #-> sub CPAN::cleanup ;
540 local $SIG{__DIE__} = '';
541 my $i = 0; my $ineval = 0; my $sub;
542 while ((undef,undef,undef,$sub) = caller(++$i)) {
543 $ineval = 1, last if $sub eq '(eval)';
545 return if $ineval && !$End;
546 return unless defined $META->{'LOCK'};
547 return unless -f $META->{'LOCK'};
548 unlink $META->{'LOCK'};
549 $CPAN::Frontend->mywarn("Lockfile removed.\n");
552 package CPAN::CacheMgr;
554 #-> sub CPAN::CacheMgr::as_string ;
556 eval { require Data::Dumper };
558 return shift->SUPER::as_string;
560 return Data::Dumper::Dumper(shift);
564 #-> sub CPAN::CacheMgr::cachesize ;
571 return unless -d $self->{ID};
572 while ($self->{DU} > $self->{'MAX'} ) {
573 my($toremove) = shift @{$self->{FIFO}};
574 $CPAN::Frontend->myprint(sprintf(
575 "Deleting from cache".
576 ": $toremove (%.1f>%.1f MB)\n",
577 $self->{DU}, $self->{'MAX'})
579 return if $CPAN::Signal;
580 $self->force_clean_cache($toremove);
581 return if $CPAN::Signal;
585 #-> sub CPAN::CacheMgr::dir ;
590 #-> sub CPAN::CacheMgr::entries ;
593 return unless defined $dir;
594 $self->debug("reading dir[$dir]") if $CPAN::DEBUG;
595 $dir ||= $self->{ID};
597 $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
598 my($cwd) = CPAN->$getcwd();
599 chdir $dir or Carp::croak("Can't chdir to $dir: $!");
600 my $dh = DirHandle->new(".") or Carp::croak("Couldn't opendir $dir: $!");
603 next if $_ eq "." || $_ eq "..";
605 push @entries, MM->catfile($dir,$_);
607 push @entries, MM->catdir($dir,$_);
609 $CPAN::Frontend->mywarn("Warning: weird direntry in $dir: $_\n");
612 chdir $cwd or Carp::croak("Can't chdir to $cwd: $!");
613 sort { -M $b <=> -M $a} @entries;
616 #-> sub CPAN::CacheMgr::disk_usage ;
619 return if exists $self->{SIZE}{$dir};
620 return if $CPAN::Signal;
624 $File::Find::prune++ if $CPAN::Signal;
630 return if $CPAN::Signal;
631 $self->{SIZE}{$dir} = $Du/1024/1024;
632 push @{$self->{FIFO}}, $dir;
633 $self->debug("measured $dir is $Du") if $CPAN::DEBUG;
634 $self->{DU} += $Du/1024/1024;
638 #-> sub CPAN::CacheMgr::force_clean_cache ;
639 sub force_clean_cache {
641 return unless -e $dir;
642 $self->debug("have to rmtree $dir, will free $self->{SIZE}{$dir}")
644 File::Path::rmtree($dir);
645 $self->{DU} -= $self->{SIZE}{$dir};
646 delete $self->{SIZE}{$dir};
649 #-> sub CPAN::CacheMgr::new ;
656 ID => $CPAN::Config->{'build_dir'},
657 MAX => $CPAN::Config->{'build_cache'},
660 File::Path::mkpath($self->{ID});
661 my $dh = DirHandle->new($self->{ID});
664 $CPAN::Frontend->myprint(
665 sprintf("Scanning cache %s for sizes\n",
667 for $e ($self->entries($self->{ID})) {
668 next if $e eq ".." || $e eq ".";
669 $self->disk_usage($e);
670 return if $CPAN::Signal;
674 $debug .= "timing of CacheMgr->new: ".($t2 - $time);
676 CPAN->debug($debug) if $CPAN::DEBUG;
682 #-> sub CPAN::Debug::debug ;
685 my($caller,$func,$line,@rest) = caller(1); # caller(0) eg
686 # Complete, caller(1)
688 ($caller) = caller(0);
690 $arg = "" unless defined $arg;
691 my $rest = join "|", map { defined $_ ? $_ : "UNDEF" } @rest;
692 if ($CPAN::DEBUG{$caller} & $CPAN::DEBUG){
693 if ($arg and ref $arg) {
694 eval { require Data::Dumper };
696 $CPAN::Frontend->myprint($arg->as_string);
698 $CPAN::Frontend->myprint(Data::Dumper::Dumper($arg));
701 $CPAN::Frontend->myprint("Debug($caller:$func,$line,[$rest]): $arg\n");
706 package CPAN::Config;
708 #-> sub CPAN::Config::edit ;
710 my($class,@args) = @_;
712 CPAN->debug("class[$class]args[".join(" | ",@args)."]");
713 my($o,$str,$func,$args,$key_exists);
719 if (ref($CPAN::Config->{$o}) eq ARRAY) {
722 # Let's avoid eval, it's easier to comprehend without.
723 if ($func eq "push") {
724 push @{$CPAN::Config->{$o}}, @args;
725 } elsif ($func eq "pop") {
726 pop @{$CPAN::Config->{$o}};
727 } elsif ($func eq "shift") {
728 shift @{$CPAN::Config->{$o}};
729 } elsif ($func eq "unshift") {
730 unshift @{$CPAN::Config->{$o}}, @args;
731 } elsif ($func eq "splice") {
732 splice @{$CPAN::Config->{$o}}, @args;
734 $CPAN::Config->{$o} = [@args];
736 $CPAN::Frontend->myprint(
739 ExtUtils::MakeMaker::neatvalue($CPAN::Config->{$o}),
744 $CPAN::Config->{$o} = $args[0] if defined $args[0];
745 $CPAN::Frontend->myprint(" $o " .
746 (defined $CPAN::Config->{$o} ?
747 $CPAN::Config->{$o} : "UNDEFINED"));
752 #-> sub CPAN::Config::commit ;
754 my($self,$configpm) = @_;
755 unless (defined $configpm){
756 $configpm ||= $INC{"CPAN/MyConfig.pm"};
757 $configpm ||= $INC{"CPAN/Config.pm"};
758 $configpm || Carp::confess(qq{
759 CPAN::Config::commit called without an argument.
760 Please specify a filename where to save the configuration or try
761 "o conf init" to have an interactive course through configing.
766 $mode = (stat $configpm)[2];
767 if ($mode && ! -w _) {
768 Carp::confess("$configpm is not writable");
772 my $msg = <<EOF unless $configpm =~ /MyConfig/;
774 # This is CPAN.pm's systemwide configuration file. This file provides
775 # defaults for users, and the values can be changed in a per-user
776 # configuration file. The user-config file is being looked for as
777 # ~/.cpan/CPAN/MyConfig.pm.
781 my($fh) = FileHandle->new;
782 open $fh, ">$configpm" or warn "Couldn't open >$configpm: $!";
783 $fh->print(qq[$msg\$CPAN::Config = \{\n]);
784 foreach (sort keys %$CPAN::Config) {
787 ExtUtils::MakeMaker::neatvalue($CPAN::Config->{$_}),
792 $fh->print("};\n1;\n__END__\n");
795 #$mode = 0444 | ( $mode & 0111 ? 0111 : 0 );
796 #chmod $mode, $configpm;
797 ###why was that so? $self->defaults;
798 $CPAN::Frontend->myprint("commit: wrote $configpm\n");
802 *default = \&defaults;
803 #-> sub CPAN::Config::defaults ;
813 undef $CPAN::Config->{'inhibit_startup_message'}; # lazy trick to
822 #-> sub CPAN::Config::load ;
826 eval {require CPAN::Config;}; # We eval because of some
828 unless ($dot_cpan++){
829 unshift @INC, MM->catdir($ENV{HOME},".cpan");
830 eval {require CPAN::MyConfig;}; # where you can override
831 # system wide settings
834 return unless @miss = $self->not_loaded;
835 # XXX better check for arrayrefs too
836 require CPAN::FirstTime;
837 my($configpm,$fh,$redo,$theycalled);
839 $theycalled++ if @miss==1 && $miss[0] eq 'inhibit_startup_message';
840 if (defined $INC{"CPAN/Config.pm"} && -w $INC{"CPAN/Config.pm"}) {
841 $configpm = $INC{"CPAN/Config.pm"};
843 } elsif (defined $INC{"CPAN/MyConfig.pm"} && -w $INC{"CPAN/MyConfig.pm"}) {
844 $configpm = $INC{"CPAN/MyConfig.pm"};
847 my($path_to_cpan) = File::Basename::dirname($INC{"CPAN.pm"});
848 my($configpmdir) = MM->catdir($path_to_cpan,"CPAN");
849 my($configpmtest) = MM->catfile($configpmdir,"Config.pm");
850 if (-d $configpmdir or File::Path::mkpath($configpmdir)) {
851 if (-w $configpmtest) {
852 $configpm = $configpmtest;
853 } elsif (-w $configpmdir) {
854 #_#_# following code dumped core on me with 5.003_11, a.k.
855 unlink "$configpmtest.bak" if -f "$configpmtest.bak";
856 rename $configpmtest, "$configpmtest.bak" if -f $configpmtest;
857 my $fh = FileHandle->new;
858 if ($fh->open(">$configpmtest")) {
860 $configpm = $configpmtest;
862 # Should never happen
863 Carp::confess("Cannot open >$configpmtest");
868 $configpmdir = MM->catdir($ENV{HOME},".cpan","CPAN");
869 File::Path::mkpath($configpmdir);
870 $configpmtest = MM->catfile($configpmdir,"MyConfig.pm");
871 if (-w $configpmtest) {
872 $configpm = $configpmtest;
873 } elsif (-w $configpmdir) {
874 #_#_# following code dumped core on me with 5.003_11, a.k.
875 my $fh = FileHandle->new;
876 if ($fh->open(">$configpmtest")) {
878 $configpm = $configpmtest;
880 # Should never happen
881 Carp::confess("Cannot open >$configpmtest");
884 Carp::confess(qq{WARNING: CPAN.pm is unable to }.
885 qq{create a configuration file.});
890 $CPAN::Frontend->myprint(qq{
891 We have to reconfigure CPAN.pm due to following uninitialized parameters:
894 }) if $redo && ! $theycalled;
895 $CPAN::Frontend->myprint(qq{
896 $configpm initialized.
899 CPAN::FirstTime::init($configpm);
902 #-> sub CPAN::Config::not_loaded ;
906 cpan_home keep_source_where build_dir build_cache index_expire
907 gzip tar unzip make pager makepl_arg make_arg make_install_arg
908 urllist inhibit_startup_message ftp_proxy http_proxy no_proxy
910 push @miss, $_ unless defined $CPAN::Config->{$_};
915 #-> sub CPAN::Config::unload ;
917 delete $INC{'CPAN/MyConfig.pm'};
918 delete $INC{'CPAN/Config.pm'};
922 #-> sub CPAN::Config::help ;
924 $CPAN::Frontend->myprint(qq{
926 defaults reload default config values from disk
927 commit commit session changes to disk
928 init go through a dialog to set all parameters
930 You may edit key values in the follow fashion:
932 o conf build_cache 15
934 o conf build_dir "/foo/bar"
938 o conf urllist unshift ftp://ftp.foo.bar/
941 undef; #don't reprint CPAN::Config
944 #-> sub CPAN::Config::cpl ;
946 my($word,$line,$pos) = @_;
948 CPAN->debug("word[$word] line[$line] pos[$pos]") if $CPAN::DEBUG;
949 my(@words) = split " ", substr($line,0,$pos+1);
954 $words[2] =~ /list$/ && @words == 3
956 $words[2] =~ /list$/ && @words == 4 && length($word)
959 return grep /^\Q$word\E/, qw(splice shift unshift pop push);
960 } elsif (@words >= 4) {
963 my(@o_conf) = (keys %CPAN::Config::can, keys %$CPAN::Config);
964 return grep /^\Q$word\E/, @o_conf;
969 #-> sub CPAN::Shell::h ;
971 my($class,$about) = @_;
972 if (defined $about) {
973 $CPAN::Frontend->myprint("Detailed help not yet implemented\n");
975 $CPAN::Frontend->myprint(q{
976 command arguments description
979 d /regex/ info distributions
981 i none anything of above
983 r as reinstall recommendations
984 u above uninstalled distributions
985 See manpage for autobundle, recompile, force, look, etc.
988 test modules, make test (implies make)
989 install dists, bundles, make install (implies test)
990 clean "r" or "u" make clean
991 readme display the README file
993 reload index|cpan load most recent indices/CPAN.pm
994 h or ? display this menu
995 o various set and query options
996 ! perl-code eval a perl command
997 q quit the shell subroutine
1004 #-> sub CPAN::Shell::a ;
1005 sub a { $CPAN::Frontend->myprint(shift->format_result('Author',@_));}
1006 #-> sub CPAN::Shell::b ;
1008 my($self,@which) = @_;
1009 CPAN->debug("which[@which]") if $CPAN::DEBUG;
1010 my($incdir,$bdir,$dh);
1011 foreach $incdir ($CPAN::Config->{'cpan_home'},@INC) {
1012 $bdir = MM->catdir($incdir,"Bundle");
1013 if ($dh = DirHandle->new($bdir)) { # may fail
1015 for $entry ($dh->read) {
1016 next if -d MM->catdir($bdir,$entry);
1017 next unless $entry =~ s/\.pm$//;
1018 $CPAN::META->instance('CPAN::Bundle',"Bundle::$entry");
1022 $CPAN::Frontend->myprint($self->format_result('Bundle',@which));
1024 #-> sub CPAN::Shell::d ;
1025 sub d { $CPAN::Frontend->myprint(shift->format_result('Distribution',@_));}
1026 #-> sub CPAN::Shell::m ;
1027 sub m { $CPAN::Frontend->myprint(shift->format_result('Module',@_));}
1029 #-> sub CPAN::Shell::i ;
1034 @type = qw/Author Bundle Distribution Module/;
1035 @args = '/./' unless @args;
1038 push @result, $self->expand($type,@args);
1040 my $result = @result == 1 ?
1041 $result[0]->as_string :
1042 join "", map {$_->as_glimpse} @result;
1043 $result ||= "No objects found of any type for argument @args\n";
1044 $CPAN::Frontend->myprint($result);
1047 #-> sub CPAN::Shell::o ;
1049 my($self,$o_type,@o_what) = @_;
1051 CPAN->debug("o_type[$o_type] o_what[".join(" | ",@o_what)."]\n");
1052 if ($o_type eq 'conf') {
1053 shift @o_what if @o_what && $o_what[0] eq 'help';
1056 $CPAN::Frontend->myprint("CPAN::Config options");
1057 if (exists $INC{'CPAN/Config.pm'}) {
1058 $CPAN::Frontend->myprint(" from $INC{'CPAN/Config.pm'}");
1060 if (exists $INC{'CPAN/MyConfig.pm'}) {
1061 $CPAN::Frontend->myprint(" and $INC{'CPAN/MyConfig.pm'}");
1063 $CPAN::Frontend->myprint(":\n");
1064 for $k (sort keys %CPAN::Config::can) {
1065 $v = $CPAN::Config::can{$k};
1066 $CPAN::Frontend->myprint(sprintf " %-18s %s\n", $k, $v);
1068 $CPAN::Frontend->myprint("\n");
1069 for $k (sort keys %$CPAN::Config) {
1070 $v = $CPAN::Config->{$k};
1072 $CPAN::Frontend->myprint(
1079 map {"\t$_\n"} @{$v}
1083 $CPAN::Frontend->myprint(sprintf " %-18s %s\n", $k, $v);
1086 $CPAN::Frontend->myprint("\n");
1087 } elsif (!CPAN::Config->edit(@o_what)) {
1088 $CPAN::Frontend->myprint(qq[Type 'o conf' to view configuration edit options\n\n]);
1090 } elsif ($o_type eq 'debug') {
1092 @o_what = () if defined $o_what[0] && $o_what[0] =~ /help/i;
1095 my($what) = shift @o_what;
1096 if ( exists $CPAN::DEBUG{$what} ) {
1097 $CPAN::DEBUG |= $CPAN::DEBUG{$what};
1098 } elsif ($what =~ /^\d/) {
1099 $CPAN::DEBUG = $what;
1100 } elsif (lc $what eq 'all') {
1102 for (values %CPAN::DEBUG) {
1105 $CPAN::DEBUG = $max;
1108 for (keys %CPAN::DEBUG) {
1109 next unless lc($_) eq lc($what);
1110 $CPAN::DEBUG |= $CPAN::DEBUG{$_};
1113 $CPAN::Frontend->myprint("unknown argument [$what]\n")
1118 $CPAN::Frontend->myprint("Valid options for debug are ".
1119 join(", ",sort(keys %CPAN::DEBUG), 'all').
1120 qq{ or a number. Completion works on the options. }.
1121 qq{Case is ignored.\n\n});
1124 $CPAN::Frontend->myprint("Options set for debugging:\n");
1126 for $k (sort {$CPAN::DEBUG{$a} <=> $CPAN::DEBUG{$b}} keys %CPAN::DEBUG) {
1127 $v = $CPAN::DEBUG{$k};
1128 $CPAN::Frontend->myprint(sprintf " %-14s(%s)\n", $k, $v) if $v & $CPAN::DEBUG;
1131 $CPAN::Frontend->myprint("Debugging turned off completely.\n");
1134 $CPAN::Frontend->myprint(qq{
1136 conf set or get configuration variables
1137 debug set or get debugging options
1142 #-> sub CPAN::Shell::reload ;
1144 my($self,$command,@arg) = @_;
1146 $self->debug("self[$self]command[$command]arg[@arg]") if $CPAN::DEBUG;
1147 if ($command =~ /cpan/i) {
1148 CPAN->debug("reloading the whole CPAN.pm") if $CPAN::DEBUG;
1149 my $fh = FileHandle->new($INC{'CPAN.pm'});
1153 local($SIG{__WARN__})
1155 if ( $_[0] =~ /Subroutine \w+ redefined/ ) {
1158 $CPAN::Frontend->myprint(".");
1165 $CPAN::Frontend->myprint("\n$redef subroutines redefined\n");
1166 } elsif ($command =~ /index/) {
1167 CPAN::Index->force_reload;
1169 $CPAN::Frontend->myprint(qq{cpan re-evals the CPAN.pm file
1170 index re-reads the index files
1175 #-> sub CPAN::Shell::_binary_extensions ;
1176 sub _binary_extensions {
1177 my($self) = shift @_;
1178 my(@result,$module,%seen,%need,$headerdone);
1179 my $isaperl = q{perl5[._-]\\d{3}(_[0-4][0-9])?\\.tar[._-]gz$};
1180 for $module ($self->expand('Module','/./')) {
1181 my $file = $module->cpan_file;
1182 next if $file eq "N/A";
1183 next if $file =~ /^Contact Author/;
1184 next if $file =~ / $isaperl /xo;
1185 next unless $module->xs_file;
1187 $CPAN::Frontend->myprint(".");
1188 push @result, $module;
1190 # print join " | ", @result;
1191 $CPAN::Frontend->myprint("\n");
1195 #-> sub CPAN::Shell::recompile ;
1197 my($self) = shift @_;
1198 my($module,@module,$cpan_file,%dist);
1199 @module = $self->_binary_extensions();
1200 for $module (@module){ # we force now and compile later, so we
1202 $cpan_file = $module->cpan_file;
1203 my $pack = $CPAN::META->instance('CPAN::Distribution',$cpan_file);
1205 $dist{$cpan_file}++;
1207 for $cpan_file (sort keys %dist) {
1208 $CPAN::Frontend->myprint(" CPAN: Recompiling $cpan_file\n\n");
1209 my $pack = $CPAN::META->instance('CPAN::Distribution',$cpan_file);
1211 $CPAN::Signal = 0; # it's tempting to reset Signal, so we can
1212 # stop a package from recompiling,
1213 # e.g. IO-1.12 when we have perl5.003_10
1217 #-> sub CPAN::Shell::_u_r_common ;
1219 my($self) = shift @_;
1220 my($what) = shift @_;
1221 CPAN->debug("self[$self] what[$what] args[@_]") if $CPAN::DEBUG;
1222 Carp::croak "Usage: \$obj->_u_r_common($what)" unless defined $what;
1223 Carp::croak "Usage: \$obj->_u_r_common(a|r|u)" unless $what =~ /^[aru]$/;
1225 @args = '/./' unless @args;
1226 my(@result,$module,%seen,%need,$headerdone,
1227 $version_undefs,$version_zeroes);
1228 $version_undefs = $version_zeroes = 0;
1229 my $sprintf = "%-25s %9s %9s %s\n";
1230 for $module ($self->expand('Module',@args)) {
1231 my $file = $module->cpan_file;
1232 next unless defined $file; # ??
1233 my($latest) = $module->cpan_version;
1234 my($inst_file) = $module->inst_file;
1236 return if $CPAN::Signal;
1239 $have = $module->inst_version;
1240 } elsif ($what eq "r") {
1241 $have = $module->inst_version;
1243 if ($have eq "undef"){
1245 } elsif ($have == 0){
1248 next if $have >= $latest;
1249 # to be pedantic we should probably say:
1250 # && !($have eq "undef" && $latest ne "undef" && $latest gt "");
1251 # to catch the case where CPAN has a version 0 and we have a version undef
1252 } elsif ($what eq "u") {
1258 } elsif ($what eq "r") {
1260 } elsif ($what eq "u") {
1264 return if $CPAN::Signal; # this is sometimes lengthy
1267 push @result, sprintf "%s %s\n", $module->id, $have;
1268 } elsif ($what eq "r") {
1269 push @result, $module->id;
1270 next if $seen{$file}++;
1271 } elsif ($what eq "u") {
1272 push @result, $module->id;
1273 next if $seen{$file}++;
1274 next if $file =~ /^Contact/;
1276 unless ($headerdone++){
1277 $CPAN::Frontend->myprint("\n");
1278 $CPAN::Frontend->myprint(sprintf(
1280 "Package namespace",
1286 $latest = substr($latest,0,8) if length($latest) > 8;
1287 $have = substr($have,0,8) if length($have) > 8;
1288 $CPAN::Frontend->myprint(sprintf $sprintf, $module->id, $have, $latest, $file);
1289 $need{$module->id}++;
1293 $CPAN::Frontend->myprint("No modules found for @args\n");
1294 } elsif ($what eq "r") {
1295 $CPAN::Frontend->myprint("All modules are up to date for @args\n");
1299 if ($version_zeroes) {
1300 my $s_has = $version_zeroes > 1 ? "s have" : " has";
1301 $CPAN::Frontend->myprint(qq{$version_zeroes installed module$s_has }.
1302 qq{a version number of 0\n});
1304 if ($version_undefs) {
1305 my $s_has = $version_undefs > 1 ? "s have" : " has";
1306 $CPAN::Frontend->myprint(qq{$version_undefs installed module$s_has no }.
1307 qq{parseable version number\n});
1313 #-> sub CPAN::Shell::r ;
1315 shift->_u_r_common("r",@_);
1318 #-> sub CPAN::Shell::u ;
1320 shift->_u_r_common("u",@_);
1323 #-> sub CPAN::Shell::autobundle ;
1326 my(@bundle) = $self->_u_r_common("a",@_);
1327 my($todir) = MM->catdir($CPAN::Config->{'cpan_home'},"Bundle");
1328 File::Path::mkpath($todir);
1329 unless (-d $todir) {
1330 $CPAN::Frontend->myprint("Couldn't mkdir $todir for some reason\n");
1333 my($y,$m,$d) = (localtime)[5,4,3];
1337 my($me) = sprintf "Snapshot_%04d_%02d_%02d_%02d", $y, $m, $d, $c;
1338 my($to) = MM->catfile($todir,"$me.pm");
1340 $me = sprintf "Snapshot_%04d_%02d_%02d_%02d", $y, $m, $d, ++$c;
1341 $to = MM->catfile($todir,"$me.pm");
1343 my($fh) = FileHandle->new(">$to") or Carp::croak "Can't open >$to: $!";
1345 "package Bundle::$me;\n\n",
1346 "\$VERSION = '0.01';\n\n",
1350 "Bundle::$me - Snapshot of installation on ",
1351 $Config::Config{'myhostname'},
1354 "\n\n=head1 SYNOPSIS\n\n",
1355 "perl -MCPAN -e 'install Bundle::$me'\n\n",
1356 "=head1 CONTENTS\n\n",
1357 join("\n", @bundle),
1358 "\n\n=head1 CONFIGURATION\n\n",
1360 "\n\n=head1 AUTHOR\n\n",
1361 "This Bundle has been generated automatically ",
1362 "by the autobundle routine in CPAN.pm.\n",
1365 $CPAN::Frontend->myprint("\nWrote bundle file
1369 #-> sub CPAN::Shell::expand ;
1372 my($type,@args) = @_;
1376 if ($arg =~ m|^/(.*)/$|) {
1379 my $class = "CPAN::$type";
1381 if (defined $regex) {
1382 for $obj ( sort {$a->id cmp $b->id} $CPAN::META->all($class)) {
1385 $obj->id =~ /$regex/i
1389 $] < 5.00303 ### provide sort of compatibility with 5.003
1394 $obj->name =~ /$regex/i
1399 if ( $type eq 'Bundle' ) {
1400 $xarg =~ s/^(Bundle::)?(.*)/Bundle::$2/;
1402 if ($CPAN::META->exists($class,$xarg)) {
1403 $obj = $CPAN::META->instance($class,$xarg);
1404 } elsif ($CPAN::META->exists($class,$arg)) {
1405 $obj = $CPAN::META->instance($class,$arg);
1412 return wantarray ? @m : $m[0];
1415 #-> sub CPAN::Shell::format_result ;
1418 my($type,@args) = @_;
1419 @args = '/./' unless @args;
1420 my(@result) = $self->expand($type,@args);
1421 my $result = @result == 1 ?
1422 $result[0]->as_string :
1423 join "", map {$_->as_glimpse} @result;
1424 $result ||= "No objects of type $type found for argument @args\n";
1428 # The only reason for this method is currently to have a reliable
1429 # debugging utility that reveals which output is going through which
1430 # channel. No, I don't like the colors ;-)
1431 sub print_ornamented {
1432 my($self,$what,$ornament) = @_;
1434 my $ornamenting = 0; # turn the colors on
1437 unless (defined &color) {
1438 if ($CPAN::META->has_inst("Term::ANSIColor")) {
1439 import Term::ANSIColor "color";
1441 *color = sub { return "" };
1445 for $line (split /\n/, $what) {
1446 $longest = length($line) if length($line) > $longest;
1448 my $sprintf = "%-" . $longest . "s";
1450 $what =~ s/(.*\n?)//m;
1453 my($nl) = chomp $line ? "\n" : "";
1454 # print "line[$line]ornament[$ornament]sprintf[$sprintf]\n";
1455 print color($ornament), sprintf($sprintf,$line), color("reset"), $nl;
1463 my($self,$what) = @_;
1464 $self->print_ornamented($what, 'bold blue on_yellow');
1468 my($self,$what) = @_;
1469 $self->myprint($what);
1474 my($self,$what) = @_;
1475 $self->print_ornamented($what, 'bold red on_yellow');
1479 my($self,$what) = @_;
1480 $self->print_ornamented($what, 'bold red on_white');
1481 Carp::confess "died";
1485 my($self,$what) = @_;
1486 $self->print_ornamented($what, 'bold red on_white');
1490 #-> sub CPAN::Shell::rematein ;
1491 # RE-adme||MA-ke||TE-st||IN-stall
1494 my($meth,@some) = @_;
1496 if ($meth eq 'force') {
1498 $meth = shift @some;
1500 CPAN->debug("pragma[$pragma]meth[$meth] some[@some]") if $CPAN::DEBUG;
1502 foreach $s (@some) {
1506 } elsif ($s =~ m|/|) { # looks like a file
1507 $obj = $CPAN::META->instance('CPAN::Distribution',$s);
1508 } elsif ($s =~ m|^Bundle::|) {
1509 $CPAN::META->{'CPAN::Queue'}{$s} ||= CPAN::Queue->new($s);
1510 $obj = $CPAN::META->instance('CPAN::Bundle',$s);
1512 $CPAN::META->{'CPAN::Queue'}{$s} ||= CPAN::Queue->new($s);
1513 $obj = $CPAN::META->instance('CPAN::Module',$s)
1514 if $CPAN::META->exists('CPAN::Module',$s);
1518 qq{pragma[$pragma] meth[$meth] obj[$obj] as_string\[}.
1526 ($] < 5.00303 || $obj->can($pragma)); ###
1530 if ($]>=5.00303 && $obj->can('called_for')) {
1531 $obj->called_for($s);
1534 } elsif ($CPAN::META->exists('CPAN::Author',$s)) {
1535 $obj = $CPAN::META->instance('CPAN::Author',$s);
1536 $CPAN::Frontend->myprint(
1538 "Don't be silly, you can't $meth ",
1543 $CPAN::Frontend->myprint(qq{Warning: Cannot $meth $s, don\'t know what it is.
1548 to find objects with similar identifiers.
1554 #-> sub CPAN::Shell::force ;
1555 sub force { shift->rematein('force',@_); }
1556 #-> sub CPAN::Shell::get ;
1557 sub get { shift->rematein('get',@_); }
1558 #-> sub CPAN::Shell::readme ;
1559 sub readme { shift->rematein('readme',@_); }
1560 #-> sub CPAN::Shell::make ;
1561 sub make { shift->rematein('make',@_); }
1562 #-> sub CPAN::Shell::test ;
1563 sub test { shift->rematein('test',@_); }
1564 #-> sub CPAN::Shell::install ;
1565 sub install { shift->rematein('install',@_); }
1566 #-> sub CPAN::Shell::clean ;
1567 sub clean { shift->rematein('clean',@_); }
1568 #-> sub CPAN::Shell::look ;
1569 sub look { shift->rematein('look',@_); }
1573 #-> sub CPAN::FTP::ftp_get ;
1575 my($class,$host,$dir,$file,$target) = @_;
1577 qq[Going to fetch file [$file] from dir [$dir]
1578 on host [$host] as local [$target]\n]
1580 my $ftp = Net::FTP->new($host);
1581 return 0 unless defined $ftp;
1582 $ftp->debug(1) if $CPAN::DEBUG{'FTP'} & $CPAN::DEBUG;
1583 $class->debug(qq[Going to ->login("anonymous","$Config::Config{'cf_email'}")\n]);
1584 unless ( $ftp->login("anonymous",$Config::Config{'cf_email'}) ){
1585 warn "Couldn't login on $host";
1588 unless ( $ftp->cwd($dir) ){
1589 warn "Couldn't cwd $dir";
1593 $class->debug(qq[Going to ->get("$file","$target")\n]) if $CPAN::DEBUG;
1594 unless ( $ftp->get($file,$target) ){
1595 warn "Couldn't fetch $file from $host\n";
1598 $ftp->quit; # it's ok if this fails
1602 # If more accuracy is wanted/needed, Chris Leach sent me this patch...
1604 # leach,> *** /install/perl/live/lib/CPAN.pm- Wed Sep 24 13:08:48 1997
1605 # leach,> --- /tmp/cp Wed Sep 24 13:26:40 1997
1606 # leach,> ***************
1607 # leach,> *** 1562,1567 ****
1608 # leach,> --- 1562,1580 ----
1609 # leach,> return 1 if substr($url,0,4) eq "file";
1610 # leach,> return 1 unless $url =~ m|://([^/]+)|;
1611 # leach,> my $host = $1;
1612 # leach,> + my $proxy = $CPAN::Config->{'http_proxy'} || $ENV{'http_proxy'};
1613 # leach,> + if ($proxy) {
1614 # leach,> + $proxy =~ m|://([^/:]+)|;
1615 # leach,> + $proxy = $1;
1616 # leach,> + my $noproxy = $CPAN::Config->{'no_proxy'} || $ENV{'no_proxy'};
1617 # leach,> + if ($noproxy) {
1618 # leach,> + if ($host !~ /$noproxy$/) {
1619 # leach,> + $host = $proxy;
1621 # leach,> + } else {
1622 # leach,> + $host = $proxy;
1625 # leach,> require Net::Ping;
1626 # leach,> return 1 unless $Net::Ping::VERSION >= 2;
1630 # this is quite optimistic and returns one on several occasions where
1631 # inappropriate. But this does no harm. It would do harm if we were
1632 # too pessimistic (as I was before the http_proxy
1634 my($self,$url) = @_;
1635 return 1; # we can't simply roll our own, firewalls may break ping
1636 return 0 unless $url;
1637 return 1 if substr($url,0,4) eq "file";
1638 return 1 unless $url =~ m|^(\w+)://([^/]+)|;
1639 my $proxytype = $1 . "_proxy"; # ftp_proxy or http_proxy
1641 return 1 if $CPAN::Config->{$proxytype} || $ENV{$proxytype};
1643 return 1 unless $Net::Ping::VERSION >= 2;
1645 # 1.3101 had it different: only if the first eval raised an
1646 # exception we tried it with TCP. Now we are happy if icmp wins
1647 # the order and return, we don't even check for $@. Thanks to
1648 # thayer@uis.edu for the suggestion.
1649 eval {$p = Net::Ping->new("icmp");};
1650 return 1 if $p && ref($p) && $p->ping($host, 10);
1651 eval {$p = Net::Ping->new("tcp");};
1652 $CPAN::Frontend->mydie($@) if $@;
1653 return $p->ping($host, 10);
1656 #-> sub CPAN::FTP::localize ;
1657 # sorry for the ugly code here, I'll clean it up as soon as Net::FTP
1660 my($self,$file,$aslocal,$force) = @_;
1662 Carp::croak "Usage: ->localize(cpan_file,as_local_file[,$force])"
1663 unless defined $aslocal;
1664 $self->debug("file[$file] aslocal[$aslocal] force[$force]")
1667 return $aslocal if -f $aslocal && -r _ && !($force & 1);
1670 rename $aslocal, "$aslocal.bak";
1674 my($aslocal_dir) = File::Basename::dirname($aslocal);
1675 File::Path::mkpath($aslocal_dir);
1676 $CPAN::Frontend->mywarn(qq{Warning: You are not allowed to write into }.
1677 qq{directory "$aslocal_dir".
1678 I\'ll continue, but if you encounter problems, they may be due
1679 to insufficient permissions.\n}) unless -w $aslocal_dir;
1681 # Inheritance is not easier to manage than a few if/else branches
1682 if ($CPAN::META->has_inst('LWP')) {
1683 require LWP::UserAgent;
1685 $Ua = LWP::UserAgent->new;
1687 $Ua->proxy('ftp', $var)
1688 if $var = $CPAN::Config->{'ftp_proxy'} || $ENV{'ftp_proxy'};
1689 $Ua->proxy('http', $var)
1690 if $var = $CPAN::Config->{'http_proxy'} || $ENV{'http_proxy'};
1692 if $var = $CPAN::Config->{'no_proxy'} || $ENV{'no_proxy'};
1696 # Try the list of urls for each single object. We keep a record
1697 # where we did get a file from
1698 my(@reordered,$last);
1699 $CPAN::Config->{urllist} ||= [];
1700 $last = $#{$CPAN::Config->{urllist}};
1701 if ($force & 2) { # local cpans probably out of date, don't reorder
1702 @reordered = (0..$last);
1706 (substr($CPAN::Config->{urllist}[$b],0,4) eq "file")
1708 (substr($CPAN::Config->{urllist}[$a],0,4) eq "file")
1717 # ((grep { substr($CPAN::Config->{urllist}[$_],0,4)
1718 # eq "file" } 0..$last),
1719 # (grep { substr($CPAN::Config->{urllist}[$_],0,4)
1720 # ne "file" } 0..$last));
1724 @levels = ($Themethod, grep {$_ ne $Themethod} qw/easy hard hardest/);
1726 @levels = qw/easy hard hardest/;
1728 for $level (@levels) {
1729 my $method = "host$level";
1730 my @host_seq = $level eq "easy" ?
1731 @reordered : 0..$last; # reordered has CDROM up front
1732 @host_seq = (0) unless @host_seq;
1733 my $ret = $self->$method(\@host_seq,$file,$aslocal);
1735 $Themethod = $level;
1736 $self->debug("level[$level]") if $CPAN::DEBUG;
1742 qq{Please check, if the URLs I found in your configuration file \(}.
1743 join(", ", @{$CPAN::Config->{urllist}}).
1744 qq{\) are valid. The urllist can be edited.},
1745 qq{E.g. with ``o conf urllist push ftp://myurl/''};
1746 $CPAN::Frontend->myprint(Text::Wrap::wrap("","",@mess). "\n\n");
1748 $CPAN::Frontend->myprint("Cannot fetch $file\n\n");
1750 rename "$aslocal.bak", $aslocal;
1751 $CPAN::Frontend->myprint("Trying to get away with old file:\n" .
1752 $self->ls($aslocal));
1759 my($self,$host_seq,$file,$aslocal) = @_;
1761 HOSTEASY: for $i (@$host_seq) {
1762 my $url = $CPAN::Config->{urllist}[$i] || $CPAN::Defaultsite;
1763 unless ($self->is_reachable($url)) {
1764 $CPAN::Frontend->myprint("Skipping $url (seems to be not reachable)\n");
1768 $url .= "/" unless substr($url,-1) eq "/";
1770 $self->debug("localizing perlish[$url]") if $CPAN::DEBUG;
1771 if ($url =~ /^file:/) {
1773 if ($CPAN::META->has_inst('LWP')) {
1775 my $u = URI::URL->new($url);
1777 } else { # works only on Unix, is poorly constructed, but
1778 # hopefully better than nothing.
1779 # RFC 1738 says fileurl BNF is
1780 # fileurl = "file://" [ host | "localhost" ] "/" fpath
1781 # Thanks to "Mark D. Baushke" <mdb@cisco.com> for
1783 ($l = $url) =~ s,^file://[^/]+,,; # discard the host part
1784 $l =~ s/^file://; # assume they meant file://localhost
1786 if ( -f $l && -r _) {
1790 # Maybe mirror has compressed it?
1792 $self->debug("found compressed $l.gz") if $CPAN::DEBUG;
1793 CPAN::Tarzip->gunzip("$l.gz", $aslocal);
1800 if ($CPAN::META->has_inst('LWP')) {
1801 $CPAN::Frontend->myprint("Fetching with LWP:
1804 my $res = $Ua->mirror($url, $aslocal);
1805 if ($res->is_success) {
1808 } elsif ($url !~ /\.gz$/) {
1809 my $gzurl = "$url.gz";
1810 $CPAN::Frontend->myprint("Fetching with LWP:
1813 $res = $Ua->mirror($gzurl, "$aslocal.gz");
1814 if ($res->is_success &&
1815 CPAN::Tarzip->gunzip("$aslocal.gz",$aslocal)
1823 # Alan Burlison informed me that in firewall envs Net::FTP
1824 # can still succeed where LWP fails. So we do not skip
1825 # Net::FTP anymore when LWP is available.
1829 $self->debug("LWP not installed") if $CPAN::DEBUG;
1831 if ($url =~ m|^ftp://(.*?)/(.*)/(.*)|) {
1832 # that's the nice and easy way thanks to Graham
1833 my($host,$dir,$getfile) = ($1,$2,$3);
1834 if ($CPAN::META->has_inst('Net::FTP')) {
1836 $CPAN::Frontend->myprint("Fetching with Net::FTP:
1839 $self->debug("getfile[$getfile]dir[$dir]host[$host]" .
1840 "aslocal[$aslocal]") if $CPAN::DEBUG;
1841 if (CPAN::FTP->ftp_get($host,$dir,$getfile,$aslocal)) {
1845 if ($aslocal !~ /\.gz$/) {
1846 my $gz = "$aslocal.gz";
1847 $CPAN::Frontend->myprint("Fetching with Net::FTP
1850 if (CPAN::FTP->ftp_get($host,
1854 CPAN::Tarzip->gunzip($gz,$aslocal)
1867 my($self,$host_seq,$file,$aslocal) = @_;
1869 # Came back if Net::FTP couldn't establish connection (or
1870 # failed otherwise) Maybe they are behind a firewall, but they
1871 # gave us a socksified (or other) ftp program...
1874 my($aslocal_dir) = File::Basename::dirname($aslocal);
1875 File::Path::mkpath($aslocal_dir);
1876 HOSTHARD: for $i (@$host_seq) {
1877 my $url = $CPAN::Config->{urllist}[$i] || $CPAN::Defaultsite;
1878 unless ($self->is_reachable($url)) {
1879 $CPAN::Frontend->myprint("Skipping $url (not reachable)\n");
1882 $url .= "/" unless substr($url,-1) eq "/";
1884 my($proto,$host,$dir,$getfile);
1886 # Courtesy Mark Conty mark_conty@cargill.com change from
1887 # if ($url =~ m|^ftp://(.*?)/(.*)/(.*)|) {
1889 if ($url =~ m|^([^:]+)://(.*?)/(.*)/(.*)|) {
1890 # proto not yet used
1891 ($proto,$host,$dir,$getfile) = ($1,$2,$3,$4);
1893 next HOSTHARD; # who said, we could ftp anything except ftp?
1895 $self->debug("localizing funkyftpwise[$url]") if $CPAN::DEBUG;
1897 for $f ('lynx','ncftp') {
1898 next unless exists $CPAN::Config->{$f};
1899 $funkyftp = $CPAN::Config->{$f};
1900 next unless defined $funkyftp;
1901 next if $funkyftp =~ /^\s*$/;
1902 my($want_compressed);
1903 my $aslocal_uncompressed;
1904 ($aslocal_uncompressed = $aslocal) =~ s/\.gz//;
1905 my($source_switch) = "";
1906 $source_switch = "-source" if $funkyftp =~ /\blynx$/;
1907 $source_switch = "-c" if $funkyftp =~ /\bncftp$/;
1908 $CPAN::Frontend->myprint(
1910 Trying with "$funkyftp $source_switch" to get
1913 my($system) = "$funkyftp $source_switch '$url' > ".
1914 "$aslocal_uncompressed";
1915 $self->debug("system[$system]") if $CPAN::DEBUG;
1917 if (($wstatus = system($system)) == 0
1919 -s $aslocal_uncompressed # lynx returns 0 on my
1920 # system even if it fails
1922 if ($aslocal_uncompressed ne $aslocal) {
1923 # test gzip integrity
1925 CPAN::Tarzip->gtest($aslocal_uncompressed)
1927 rename $aslocal_uncompressed, $aslocal;
1929 CPAN::Tarzip->gzip($aslocal_uncompressed,
1930 "$aslocal_uncompressed.gz");
1935 } elsif ($url !~ /\.gz$/) {
1936 my $gz = "$aslocal.gz";
1937 my $gzurl = "$url.gz";
1938 $CPAN::Frontend->myprint(
1940 Trying with "$funkyftp $source_switch" to get
1943 my($system) = "$funkyftp $source_switch '$url.gz' > ".
1944 "$aslocal_uncompressed.gz";
1945 $self->debug("system[$system]") if $CPAN::DEBUG;
1947 if (($wstatus = system($system)) == 0
1949 -s "$aslocal_uncompressed.gz"
1951 # test gzip integrity
1952 if (CPAN::Tarzip->gtest("$aslocal_uncompressed.gz")) {
1953 CPAN::Tarzip->gunzip("$aslocal_uncompressed.gz",
1956 rename $aslocal_uncompressed, $aslocal;
1963 my $estatus = $wstatus >> 8;
1964 my $size = -f $aslocal ? ", left\n$aslocal with size ".-s _ : "";
1965 $CPAN::Frontend->myprint(qq{
1966 System call "$system"
1967 returned status $estatus (wstat $wstatus)$size
1975 my($self,$host_seq,$file,$aslocal) = @_;
1978 my($aslocal_dir) = File::Basename::dirname($aslocal);
1979 File::Path::mkpath($aslocal_dir);
1980 HOSTHARDEST: for $i (@$host_seq) {
1981 unless (length $CPAN::Config->{'ftp'}) {
1982 $CPAN::Frontend->myprint("No external ftp command available\n\n");
1985 my $url = $CPAN::Config->{urllist}[$i] || $CPAN::Defaultsite;
1986 unless ($self->is_reachable($url)) {
1987 $CPAN::Frontend->myprint("Skipping $url (not reachable)\n");
1990 $url .= "/" unless substr($url,-1) eq "/";
1992 $self->debug("localizing ftpwise[$url]") if $CPAN::DEBUG;
1993 unless ($url =~ m|^ftp://(.*?)/(.*)/(.*)|) {
1996 my($host,$dir,$getfile) = ($1,$2,$3);
1999 my($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,
2000 $ctime,$blksize,$blocks) = stat($aslocal);
2001 $timestamp = $mtime ||= 0;
2002 my($netrc) = CPAN::FTP::netrc->new;
2003 my($verbose) = $CPAN::DEBUG{'FTP'} & $CPAN::DEBUG ? " -v" : "";
2004 my $targetfile = File::Basename::basename($aslocal);
2010 map("cd $_", split "/", $dir), # RFC 1738
2012 "get $getfile $targetfile",
2015 if (! $netrc->netrc) {
2016 CPAN->debug("No ~/.netrc file found") if $CPAN::DEBUG;
2017 } elsif ($netrc->hasdefault || $netrc->contains($host)) {
2018 CPAN->debug(sprintf("hasdef[%d]cont($host)[%d]",
2020 $netrc->contains($host))) if $CPAN::DEBUG;
2021 if ($netrc->protected) {
2022 $CPAN::Frontend->myprint(qq{
2023 Trying with external ftp to get
2025 As this requires some features that are not thoroughly tested, we\'re
2026 not sure, that we get it right....
2030 $self->talk_ftp("$CPAN::Config->{'ftp'}$verbose $host",
2032 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
2033 $atime,$mtime,$ctime,$blksize,$blocks) = stat($aslocal);
2035 if ($mtime > $timestamp) {
2036 $CPAN::Frontend->myprint("GOT $aslocal\n");
2040 $CPAN::Frontend->myprint("Hmm... Still failed!\n");
2043 $CPAN::Frontend->mywarn(qq{Your $netrcfile is not }.
2044 qq{correctly protected.\n});
2047 $CPAN::Frontend->mywarn("Your ~/.netrc neither contains $host
2048 nor does it have a default entry\n");
2051 # OK, they don't have a valid ~/.netrc. Use 'ftp -n'
2052 # then and login manually to host, using e-mail as
2054 $CPAN::Frontend->myprint(qq{Issuing "$CPAN::Config->{'ftp'}$verbose -n"\n});
2058 "user anonymous $Config::Config{'cf_email'}"
2060 $self->talk_ftp("$CPAN::Config->{'ftp'}$verbose -n", @dialog);
2061 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
2062 $atime,$mtime,$ctime,$blksize,$blocks) = stat($aslocal);
2064 if ($mtime > $timestamp) {
2065 $CPAN::Frontend->myprint("GOT $aslocal\n");
2069 $CPAN::Frontend->myprint("Bad luck... Still failed!\n");
2071 $CPAN::Frontend->myprint("Can't access URL $url.\n\n");
2077 my($self,$command,@dialog) = @_;
2078 my $fh = FileHandle->new;
2079 $fh->open("|$command") or die "Couldn't open ftp: $!";
2080 foreach (@dialog) { $fh->print("$_\n") }
2081 $fh->close; # Wait for process to complete
2083 my $estatus = $wstatus >> 8;
2084 $CPAN::Frontend->myprint(qq{
2085 Subprocess "|$command"
2086 returned status $estatus (wstat $wstatus)
2091 # find2perl needs modularization, too, all the following is stolen
2095 my($self,$name) = @_;
2096 my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$sizemm,
2097 $atime,$mtime,$ctime,$blksize,$blocks) = lstat($name);
2099 my($perms,%user,%group);
2103 $blocks = int(($blocks + 1) / 2);
2106 $blocks = int(($sizemm + 1023) / 1024);
2109 if (-f _) { $perms = '-'; }
2110 elsif (-d _) { $perms = 'd'; }
2111 elsif (-c _) { $perms = 'c'; $sizemm = &sizemm; }
2112 elsif (-b _) { $perms = 'b'; $sizemm = &sizemm; }
2113 elsif (-p _) { $perms = 'p'; }
2114 elsif (-S _) { $perms = 's'; }
2115 else { $perms = 'l'; $pname .= ' -> ' . readlink($_); }
2117 my(@rwx) = ('---','--x','-w-','-wx','r--','r-x','rw-','rwx');
2118 my(@moname) = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
2119 my $tmpmode = $mode;
2120 my $tmp = $rwx[$tmpmode & 7];
2122 $tmp = $rwx[$tmpmode & 7] . $tmp;
2124 $tmp = $rwx[$tmpmode & 7] . $tmp;
2125 substr($tmp,2,1) =~ tr/-x/Ss/ if -u _;
2126 substr($tmp,5,1) =~ tr/-x/Ss/ if -g _;
2127 substr($tmp,8,1) =~ tr/-x/Tt/ if -k _;
2130 my $user = $user{$uid} || $uid; # too lazy to implement lookup
2131 my $group = $group{$gid} || $gid;
2133 my($sec,$min,$hour,$mday,$mon,$year) = localtime($mtime);
2135 my($moname) = $moname[$mon];
2136 if (-M _ > 365.25 / 2) {
2137 $timeyear = $year + 1900;
2140 $timeyear = sprintf("%02d:%02d", $hour, $min);
2143 sprintf "%5lu %4ld %-10s %2d %-8s %-8s %8s %s %2d %5s %s\n",
2157 package CPAN::FTP::netrc;
2161 my $file = MM->catfile($ENV{HOME},".netrc");
2163 my($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
2164 $atime,$mtime,$ctime,$blksize,$blocks)
2169 my($fh,@machines,$hasdefault);
2171 $fh = FileHandle->new or die "Could not create a filehandle";
2173 if($fh->open($file)){
2174 $protected = ($mode & 077) == 0;
2176 NETRC: while (<$fh>) {
2177 my(@tokens) = split " ", $_;
2178 TOKEN: while (@tokens) {
2179 my($t) = shift @tokens;
2180 if ($t eq "default"){
2184 last TOKEN if $t eq "macdef";
2185 if ($t eq "machine") {
2186 push @machines, shift @tokens;
2191 $file = $hasdefault = $protected = "";
2195 'mach' => [@machines],
2197 'hasdefault' => $hasdefault,
2198 'protected' => $protected,
2202 sub hasdefault { shift->{'hasdefault'} }
2203 sub netrc { shift->{'netrc'} }
2204 sub protected { shift->{'protected'} }
2206 my($self,$mach) = @_;
2207 for ( @{$self->{'mach'}} ) {
2208 return 1 if $_ eq $mach;
2213 package CPAN::Complete;
2215 #-> sub CPAN::Complete::cpl ;
2217 my($word,$line,$pos) = @_;
2221 CPAN->debug("word [$word] line[$line] pos[$pos]") if $CPAN::DEBUG;
2223 if ($line =~ s/^(force\s*)//) {
2231 ! a b d h i m o q r u autobundle clean
2232 make test install force reload look
2235 } elsif ( $line !~ /^[\!abdhimorutl]/ ) {
2237 } elsif ($line =~ /^a\s/) {
2238 @return = cplx('CPAN::Author',$word);
2239 } elsif ($line =~ /^b\s/) {
2240 @return = cplx('CPAN::Bundle',$word);
2241 } elsif ($line =~ /^d\s/) {
2242 @return = cplx('CPAN::Distribution',$word);
2243 } elsif ($line =~ /^([mru]|make|clean|test|install|readme|look)\s/ ) {
2244 @return = (cplx('CPAN::Module',$word),cplx('CPAN::Bundle',$word));
2245 } elsif ($line =~ /^i\s/) {
2246 @return = cpl_any($word);
2247 } elsif ($line =~ /^reload\s/) {
2248 @return = cpl_reload($word,$line,$pos);
2249 } elsif ($line =~ /^o\s/) {
2250 @return = cpl_option($word,$line,$pos);
2257 #-> sub CPAN::Complete::cplx ;
2259 my($class, $word) = @_;
2260 grep /^\Q$word\E/, map { $_->id } $CPAN::META->all($class);
2263 #-> sub CPAN::Complete::cpl_any ;
2267 cplx('CPAN::Author',$word),
2268 cplx('CPAN::Bundle',$word),
2269 cplx('CPAN::Distribution',$word),
2270 cplx('CPAN::Module',$word),
2274 #-> sub CPAN::Complete::cpl_reload ;
2276 my($word,$line,$pos) = @_;
2278 my(@words) = split " ", $line;
2279 CPAN->debug("word[$word] line[$line] pos[$pos]") if $CPAN::DEBUG;
2280 my(@ok) = qw(cpan index);
2281 return @ok if @words == 1;
2282 return grep /^\Q$word\E/, @ok if @words == 2 && $word;
2285 #-> sub CPAN::Complete::cpl_option ;
2287 my($word,$line,$pos) = @_;
2289 my(@words) = split " ", $line;
2290 CPAN->debug("word[$word] line[$line] pos[$pos]") if $CPAN::DEBUG;
2291 my(@ok) = qw(conf debug);
2292 return @ok if @words == 1;
2293 return grep /^\Q$word\E/, @ok if @words == 2 && length($word);
2295 } elsif ($words[1] eq 'index') {
2297 } elsif ($words[1] eq 'conf') {
2298 return CPAN::Config::cpl(@_);
2299 } elsif ($words[1] eq 'debug') {
2300 return sort grep /^\Q$word\E/, sort keys %CPAN::DEBUG, 'all';
2304 package CPAN::Index;
2306 #-> sub CPAN::Index::force_reload ;
2309 $CPAN::Index::last_time = 0;
2313 #-> sub CPAN::Index::reload ;
2315 my($cl,$force) = @_;
2318 # XXX check if a newer one is available. (We currently read it
2319 # from time to time)
2320 for ($CPAN::Config->{index_expire}) {
2321 $_ = 0.001 unless $_ > 0.001;
2323 return if $last_time + $CPAN::Config->{index_expire}*86400 > $time
2328 my $needshort = $^O eq "dos";
2330 $cl->rd_authindex($cl->reload_x(
2331 "authors/01mailrc.txt.gz",
2332 $needshort ? "01mailrc.gz" : "",
2335 $debug = "timing reading 01[".($t2 - $time)."]";
2337 return if $CPAN::Signal; # this is sometimes lengthy
2338 $cl->rd_modpacks($cl->reload_x(
2339 "modules/02packages.details.txt.gz",
2340 $needshort ? "02packag.gz" : "",
2343 $debug .= "02[".($t2 - $time)."]";
2345 return if $CPAN::Signal; # this is sometimes lengthy
2346 $cl->rd_modlist($cl->reload_x(
2347 "modules/03modlist.data.gz",
2348 $needshort ? "03mlist.gz" : "",
2351 $debug .= "03[".($t2 - $time)."]";
2353 CPAN->debug($debug) if $CPAN::DEBUG;
2356 #-> sub CPAN::Index::reload_x ;
2358 my($cl,$wanted,$localname,$force) = @_;
2359 $force |= 2; # means we're dealing with an index here
2360 CPAN::Config->load; # we should guarantee loading wherever we rely
2362 $localname ||= $wanted;
2363 my $abs_wanted = MM->catfile($CPAN::Config->{'keep_source_where'},
2367 -M $abs_wanted < $CPAN::Config->{'index_expire'} &&
2370 my $s = $CPAN::Config->{'index_expire'} == 1 ? "" : "s";
2371 $cl->debug(qq{$abs_wanted younger than $CPAN::Config->{'index_expire'} }.
2372 qq{day$s. I\'ll use that.});
2375 $force |= 1; # means we're quite serious about it.
2377 return CPAN::FTP->localize($wanted,$abs_wanted,$force);
2380 #-> sub CPAN::Index::rd_authindex ;
2382 my($cl,$index_target) = @_;
2383 return unless defined $index_target;
2384 $CPAN::Frontend->myprint("Going to read $index_target\n");
2385 # my $fh = CPAN::Tarzip->TIEHANDLE($index_target);
2386 # while ($_ = $fh->READLINE) {
2389 tie *FH, CPAN::Tarzip, $index_target;
2393 my($userid,$fullname,$email) =
2394 /alias\s+(\S+)\s+\"([^\"\<]+)\s+<([^\>]+)\>\"/;
2395 next unless $userid && $fullname && $email;
2397 # instantiate an author object
2398 my $userobj = $CPAN::META->instance('CPAN::Author',$userid);
2399 $userobj->set('FULLNAME' => $fullname, 'EMAIL' => $email);
2400 return if $CPAN::Signal;
2405 my($self,$dist) = @_;
2406 $dist = $self->{'id'} unless defined $dist;
2407 my($ret) = $dist =~ m|(?:\w/\w\w/)?([^/]+)/|;
2411 #-> sub CPAN::Index::rd_modpacks ;
2413 my($cl,$index_target) = @_;
2414 return unless defined $index_target;
2415 $CPAN::Frontend->myprint("Going to read $index_target\n");
2416 my $fh = CPAN::Tarzip->TIEHANDLE($index_target);
2418 while ($_ = $fh->READLINE) {
2421 while ($_ = $fh->READLINE) {
2423 my($mod,$version,$dist) = split;
2424 ### $version =~ s/^\+//;
2426 # if it is a bundle, instatiate a bundle object
2427 my($bundle,$id,$userid);
2429 if ($mod eq 'CPAN' &&
2431 $CPAN::META->exists('CPAN::Queue','Bundle::CPAN') ||
2432 $CPAN::META->exists('CPAN::Queue','CPAN')
2436 if ($version > $CPAN::VERSION){
2437 $CPAN::Frontend->myprint(qq{
2438 There\'s a new CPAN.pm version (v$version) available!
2439 You might want to try
2440 install Bundle::CPAN
2442 without quitting the current session. It should be a seamless upgrade
2443 while we are running...
2446 $CPAN::Frontend->myprint(qq{\n});
2448 last if $CPAN::Signal;
2449 } elsif ($mod =~ /^Bundle::(.*)/) {
2454 $id = $CPAN::META->instance('CPAN::Bundle',$mod);
2455 # Let's make it a module too, because bundles have so much
2456 # in common with modules
2457 $CPAN::META->instance('CPAN::Module',$mod);
2459 # This "next" makes us faster but if the job is running long, we ignore
2460 # rereads which is bad. So we have to be a bit slower again.
2461 # } elsif ($CPAN::META->exists('CPAN::Module',$mod)) {
2466 # instantiate a module object
2467 $id = $CPAN::META->instance('CPAN::Module',$mod);
2470 if ($id->cpan_file ne $dist){
2471 $userid = $cl->userid($dist);
2473 'CPAN_USERID' => $userid,
2474 'CPAN_VERSION' => $version,
2475 'CPAN_FILE' => $dist
2479 # instantiate a distribution object
2480 unless ($CPAN::META->exists('CPAN::Distribution',$dist)) {
2481 $CPAN::META->instance(
2482 'CPAN::Distribution' => $dist
2484 'CPAN_USERID' => $userid
2488 return if $CPAN::Signal;
2493 #-> sub CPAN::Index::rd_modlist ;
2495 my($cl,$index_target) = @_;
2496 return unless defined $index_target;
2497 $CPAN::Frontend->myprint("Going to read $index_target\n");
2498 my $fh = CPAN::Tarzip->TIEHANDLE($index_target);
2501 while ($_ = $fh->READLINE) {
2502 if (/^Date:\s+(.*)/){
2503 return if $date_of_03 eq $1;
2508 push @eval, $_ while $_ = $fh->READLINE;
2510 push @eval, q{CPAN::Modulelist->data;};
2512 my($comp) = Safe->new("CPAN::Safe1");
2513 my($eval) = join("", @eval);
2514 my $ret = $comp->reval($eval);
2515 Carp::confess($@) if $@;
2516 return if $CPAN::Signal;
2518 my $obj = $CPAN::META->instance(CPAN::Module,$_);
2519 $obj->set(%{$ret->{$_}});
2520 return if $CPAN::Signal;
2524 package CPAN::InfoObj;
2526 #-> sub CPAN::InfoObj::new ;
2527 sub new { my $this = bless {}, shift; %$this = @_; $this }
2529 #-> sub CPAN::InfoObj::set ;
2531 my($self,%att) = @_;
2532 my(%oldatt) = %$self;
2533 %$self = (%oldatt, %att);
2536 #-> sub CPAN::InfoObj::id ;
2537 sub id { shift->{'ID'} }
2539 #-> sub CPAN::InfoObj::as_glimpse ;
2543 my $class = ref($self);
2544 $class =~ s/^CPAN:://;
2545 push @m, sprintf "%-15s %s\n", $class, $self->{ID};
2549 #-> sub CPAN::InfoObj::as_string ;
2553 my $class = ref($self);
2554 $class =~ s/^CPAN:://;
2555 push @m, $class, " id = $self->{ID}\n";
2556 for (sort keys %$self) {
2559 if ($_ eq "CPAN_USERID") {
2560 $extra .= " (".$self->author;
2561 my $email; # old perls!
2562 if ($email = $CPAN::META->instance(CPAN::Author,
2565 $extra .= " <$email>";
2567 $extra .= " <no email>";
2571 if (ref($self->{$_}) eq "ARRAY") { # language interface? XXX
2572 push @m, sprintf " %-12s %s%s\n", $_, "@{$self->{$_}}", $extra;
2574 push @m, sprintf " %-12s %s%s\n", $_, $self->{$_}, $extra;
2580 #-> sub CPAN::InfoObj::author ;
2583 $CPAN::META->instance(CPAN::Author,$self->{CPAN_USERID})->fullname;
2586 package CPAN::Author;
2588 #-> sub CPAN::Author::as_glimpse ;
2592 my $class = ref($self);
2593 $class =~ s/^CPAN:://;
2594 push @m, sprintf "%-15s %s (%s)\n", $class, $self->{ID}, $self->fullname;
2598 # Dead code, I would have liked to have,,, but it was never reached,,,
2601 # return "Don't be silly, you can't make $self->{FULLNAME} ;-)\n";
2604 #-> sub CPAN::Author::fullname ;
2605 sub fullname { shift->{'FULLNAME'} }
2607 #-> sub CPAN::Author::email ;
2608 sub email { shift->{'EMAIL'} }
2610 package CPAN::Distribution;
2612 #-> sub CPAN::Distribution::called_for ;
2615 $self->{'CALLED_FOR'} = $id if defined $id;
2616 return $self->{'CALLED_FOR'};
2619 #-> sub CPAN::Distribution::get ;
2624 exists $self->{'build_dir'} and push @e,
2625 "Unwrapped into directory $self->{'build_dir'}";
2626 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
2631 $CPAN::Config->{keep_source_where},
2634 split("/",$self->{ID})
2637 $self->debug("Doing localize") if $CPAN::DEBUG;
2639 CPAN::FTP->localize("authors/id/$self->{ID}", $local_wanted)
2640 or $CPAN::Frontend->mydie("Giving up on '$local_wanted'\n");
2641 $self->{localfile} = $local_file;
2642 my $builddir = $CPAN::META->{cachemgr}->dir;
2643 $self->debug("doing chdir $builddir") if $CPAN::DEBUG;
2644 chdir $builddir or Carp::croak("Couldn't chdir $builddir: $!");
2647 $self->debug("local_file[$local_file]") if $CPAN::DEBUG;
2648 if ($CPAN::META->has_inst('MD5')) {
2649 $self->debug("MD5 is installed, verifying");
2652 $self->debug("MD5 is NOT installed");
2654 $self->debug("Removing tmp") if $CPAN::DEBUG;
2655 File::Path::rmtree("tmp");
2656 mkdir "tmp", 0755 or Carp::croak "Couldn't mkdir tmp: $!";
2658 $self->debug("Changed directory to tmp") if $CPAN::DEBUG;
2659 if (! $local_file) {
2660 Carp::croak "bad download, can't do anything :-(\n";
2661 } elsif ($local_file =~ /(\.tar\.(gz|Z)|\.tgz)$/i){
2662 $self->untar_me($local_file);
2663 } elsif ( $local_file =~ /\.zip$/i ) {
2664 $self->unzip_me($local_file);
2665 } elsif ( $local_file =~ /\.pm\.(gz|Z)$/) {
2666 $self->pm2dir_me($local_file);
2668 $self->{archived} = "NO";
2671 if ($self->{archived} ne 'NO') {
2673 # Let's check if the package has its own directory.
2674 my $dh = DirHandle->new(".") or Carp::croak("Couldn't opendir .: $!");
2675 my @readdir = grep $_ !~ /^\.\.?$/, $dh->read; ### MAC??
2677 my ($distdir,$packagedir);
2678 if (@readdir == 1 && -d $readdir[0]) {
2679 $distdir = $readdir[0];
2680 $packagedir = MM->catdir($builddir,$distdir);
2681 -d $packagedir and $CPAN::Frontend->myprint("Removing previously used $packagedir\n");
2682 File::Path::rmtree($packagedir);
2683 rename($distdir,$packagedir) or Carp::confess("Couldn't rename $distdir to $packagedir: $!");
2685 my $pragmatic_dir = $self->{'CPAN_USERID'} . '000';
2686 $pragmatic_dir =~ s/\W_//g;
2687 $pragmatic_dir++ while -d "../$pragmatic_dir";
2688 $packagedir = MM->catdir($builddir,$pragmatic_dir);
2689 File::Path::mkpath($packagedir);
2691 for $f (@readdir) { # is already without "." and ".."
2692 my $to = MM->catdir($packagedir,$f);
2693 rename($f,$to) or Carp::confess("Couldn't rename $f to $to: $!");
2696 $self->{'build_dir'} = $packagedir;
2699 $self->debug("Changed directory to .. (self is $self [".$self->as_string."])")
2701 File::Path::rmtree("tmp");
2702 if ($CPAN::Config->{keep_source_where} =~ /^no/i ){
2703 $CPAN::Frontend->myprint("Going to unlink $local_file\n");
2704 unlink $local_file or Carp::carp "Couldn't unlink $local_file";
2706 my($makefilepl) = MM->catfile($packagedir,"Makefile.PL");
2707 unless (-f $makefilepl) {
2708 my($configure) = MM->catfile($packagedir,"Configure");
2709 if (-f $configure) {
2710 # do we have anything to do?
2711 $self->{'configure'} = $configure;
2712 } elsif (-f MM->catfile($packagedir,"Makefile")) {
2713 $CPAN::Frontend->myprint(qq{
2714 Package comes with a Makefile and without a Makefile.PL.
2715 We\'ll try to build it with that Makefile then.
2717 $self->{writemakefile} = "YES";
2720 my $fh = FileHandle->new(">$makefilepl")
2721 or Carp::croak("Could not open >$makefilepl");
2722 my $cf = $self->called_for || "unknown";
2724 qq{# This Makefile.PL has been autogenerated by the module CPAN.pm
2725 # because there was no Makefile.PL supplied.
2726 # Autogenerated on: }.scalar localtime().qq{
2728 use ExtUtils::MakeMaker;
2729 WriteMakefile(NAME => q[$cf]);
2732 $CPAN::Frontend->myprint(qq{Package comes without Makefile.PL.
2733 Writing one on our own (calling it $cf)\n});
2741 my($self,$local_file) = @_;
2742 $self->{archived} = "tar";
2743 if (CPAN::Tarzip->untar($local_file)) {
2744 $self->{unwrapped} = "YES";
2746 $self->{unwrapped} = "NO";
2751 my($self,$local_file) = @_;
2752 $self->{archived} = "zip";
2753 my $system = "$CPAN::Config->{unzip} $local_file";
2754 if (system($system) == 0) {
2755 $self->{unwrapped} = "YES";
2757 $self->{unwrapped} = "NO";
2762 my($self,$local_file) = @_;
2763 $self->{archived} = "pm";
2764 my $to = File::Basename::basename($local_file);
2765 $to =~ s/\.(gz|Z)$//;
2766 if (CPAN::Tarzip->gunzip($local_file,$to)) {
2767 $self->{unwrapped} = "YES";
2769 $self->{unwrapped} = "NO";
2773 #-> sub CPAN::Distribution::new ;
2775 my($class,%att) = @_;
2777 $CPAN::META->{cachemgr} ||= CPAN::CacheMgr->new();
2779 my $this = { %att };
2780 return bless $this, $class;
2783 #-> sub CPAN::Distribution::look ;
2786 if ( $CPAN::Config->{'shell'} ) {
2787 $CPAN::Frontend->myprint(qq{
2788 Trying to open a subshell in the build directory...
2791 $CPAN::Frontend->myprint(qq{
2792 Your configuration does not define a value for subshells.
2793 Please define it with "o conf shell <your shell>"
2797 my $dist = $self->id;
2798 my $dir = $self->dir or $self->get;
2801 $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
2802 my $pwd = CPAN->$getcwd();
2804 $CPAN::Frontend->myprint(qq{Working directory is $dir\n});
2805 system($CPAN::Config->{'shell'}) == 0
2806 or $CPAN::Frontend->mydie("Subprocess shell error");
2810 #-> sub CPAN::Distribution::readme ;
2813 my($dist) = $self->id;
2814 my($sans,$suffix) = $dist =~ /(.+)\.(tgz|tar[\._-]gz|tar\.Z|zip)$/;
2815 $self->debug("sans[$sans] suffix[$suffix]\n") if $CPAN::DEBUG;
2819 $CPAN::Config->{keep_source_where},
2822 split("/","$sans.readme"),
2824 $self->debug("Doing localize") if $CPAN::DEBUG;
2825 $local_file = CPAN::FTP->localize("authors/id/$sans.readme",
2827 or $CPAN::Frontend->mydie(qq{No $sans.readme found});;
2828 my $fh_pager = FileHandle->new;
2829 local($SIG{PIPE}) = "IGNORE";
2830 $fh_pager->open("|$CPAN::Config->{'pager'}")
2831 or die "Could not open pager $CPAN::Config->{'pager'}: $!";
2832 my $fh_readme = FileHandle->new;
2833 $fh_readme->open($local_file)
2834 or $CPAN::Frontend->mydie(qq{Could not open "$local_file": $!});
2835 $CPAN::Frontend->myprint(qq{
2838 with pager "$CPAN::Config->{'pager'}"
2841 $fh_pager->print(<$fh_readme>);
2844 #-> sub CPAN::Distribution::verifyMD5 ;
2849 $self->{MD5_STATUS} ||= "";
2850 $self->{MD5_STATUS} eq "OK" and push @e, "MD5 Checksum was ok";
2851 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
2853 my($lc_want,$lc_file,@local,$basename);
2854 @local = split("/",$self->{ID});
2856 push @local, "CHECKSUMS";
2858 MM->catfile($CPAN::Config->{keep_source_where},
2859 "authors", "id", @local);
2864 $self->MD5_check_file($lc_want)
2866 return $self->{MD5_STATUS} = "OK";
2868 $lc_file = CPAN::FTP->localize("authors/id/@local",
2871 $local[-1] .= ".gz";
2872 $lc_file = CPAN::FTP->localize("authors/id/@local",
2875 $lc_file =~ s/\.gz$//;
2876 CPAN::Tarzip->gunzip("$lc_file.gz",$lc_file);
2881 $self->MD5_check_file($lc_file);
2884 #-> sub CPAN::Distribution::MD5_check_file ;
2885 sub MD5_check_file {
2886 my($self,$chk_file) = @_;
2887 my($cksum,$file,$basename);
2888 $file = $self->{localfile};
2889 $basename = File::Basename::basename($file);
2890 my $fh = FileHandle->new;
2891 if (open $fh, $chk_file){
2895 my($comp) = Safe->new();
2896 $cksum = $comp->reval($eval);
2898 rename $chk_file, "$chk_file.bad";
2899 Carp::confess($@) if $@;
2902 Carp::carp "Could not open $chk_file for reading";
2905 if (exists $cksum->{$basename}{md5}) {
2906 $self->debug("Found checksum for $basename:" .
2907 "$cksum->{$basename}{md5}\n") if $CPAN::DEBUG;
2911 my $eq = $self->eq_MD5($fh,$cksum->{$basename}{'md5'});
2913 $fh = CPAN::Tarzip->TIEHANDLE($file);
2916 # had to inline it, when I tied it, the tiedness got lost on
2917 # the call to eq_MD5. (Jan 1998)
2921 while ($fh->READ($ref, 4096)){
2924 my $hexdigest = $md5->hexdigest;
2925 $eq += $hexdigest eq $cksum->{$basename}{'md5-ungz'};
2929 $CPAN::Frontend->myprint("Checksum for $file ok\n");
2930 return $self->{MD5_STATUS} = "OK";
2932 $CPAN::Frontend->myprint(qq{Checksum mismatch for }.
2933 qq{distribution file. }.
2934 qq{Please investigate.\n\n}.
2936 $CPAN::META->instance(
2938 $self->{CPAN_USERID}
2940 my $wrap = qq{I\'d recommend removing $file. It seems to
2941 be a bogus file. Maybe you have configured your \`urllist\' with a
2942 bad URL. Please check this array with \`o conf urllist\', and
2944 $CPAN::Frontend->myprint(Text::Wrap::wrap("","",$wrap));
2945 $CPAN::Frontend->myprint("\n\n");
2949 # close $fh if fileno($fh);
2951 $self->{MD5_STATUS} ||= "";
2952 if ($self->{MD5_STATUS} eq "NIL") {
2953 $CPAN::Frontend->myprint(qq{
2954 No md5 checksum for $basename in local $chk_file.
2957 unlink $chk_file or $CPAN::Frontend->myprint("Could not unlink: $!");
2960 $self->{MD5_STATUS} = "NIL";
2965 #-> sub CPAN::Distribution::eq_MD5 ;
2967 my($self,$fh,$expectMD5) = @_;
2970 while (read($fh, $data, 4096)){
2973 # $md5->addfile($fh);
2974 my $hexdigest = $md5->hexdigest;
2975 # warn "fh[$fh] hex[$hexdigest] aexp[$expectMD5]";
2976 $hexdigest eq $expectMD5;
2979 #-> sub CPAN::Distribution::force ;
2982 $self->{'force_update'}++;
2983 delete $self->{'MD5_STATUS'};
2984 delete $self->{'archived'};
2985 delete $self->{'build_dir'};
2986 delete $self->{'localfile'};
2987 delete $self->{'make'};
2988 delete $self->{'install'};
2989 delete $self->{'unwrapped'};
2990 delete $self->{'writemakefile'};
2995 my $file = File::Basename::basename($self->id);
2996 return unless $file =~ m{ ^ perl
2999 (\d{3}(_[0-4][0-9])?)
3006 #-> sub CPAN::Distribution::perl ;
3009 my($perl) = MM->file_name_is_absolute($^X) ? $^X : "";
3010 my $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
3011 my $pwd = CPAN->$getcwd();
3012 my $candidate = MM->catfile($pwd,$^X);
3013 $perl ||= $candidate if MM->maybe_command($candidate);
3015 my ($component,$perl_name);
3016 DIST_PERLNAME: foreach $perl_name ($^X, 'perl', 'perl5', "perl$]") {
3017 PATH_COMPONENT: foreach $component (MM->path(),
3018 $Config::Config{'binexp'}) {
3019 next unless defined($component) && $component;
3020 my($abs) = MM->catfile($component,$perl_name);
3021 if (MM->maybe_command($abs)) {
3031 #-> sub CPAN::Distribution::make ;
3034 $CPAN::Frontend->myprint(sprintf "Running make for %s\n", $self->id);
3035 # Emergency brake if they said install Pippi and get newest perl
3036 if ($self->isa_perl) {
3038 $self->called_for ne $self->id && ! $self->{'force_update'}
3040 $CPAN::Frontend->mydie(sprintf qq{
3041 The most recent version "%s" of the module "%s"
3042 comes with the current version of perl (%s).
3043 I\'ll build that only if you ask for something like
3048 $CPAN::META->instance(
3061 $self->{archived} eq "NO" and push @e,
3062 "Is neither a tar nor a zip archive.";
3064 $self->{unwrapped} eq "NO" and push @e,
3065 "had problems unarchiving. Please build manually";
3067 exists $self->{writemakefile} &&
3068 $self->{writemakefile} eq "NO" and push @e,
3069 "Had some problem writing Makefile";
3071 defined $self->{'make'} and push @e,
3072 "Has already been processed within this session";
3074 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
3076 $CPAN::Frontend->myprint("\n CPAN.pm: Going to build ".$self->id."\n\n");
3077 my $builddir = $self->dir;
3078 chdir $builddir or Carp::croak("Couldn't chdir $builddir: $!");
3079 $self->debug("Changed directory to $builddir") if $CPAN::DEBUG;
3082 if ($self->{'configure'}) {
3083 $system = $self->{'configure'};
3085 my($perl) = $self->perl or die "Couldn\'t find executable perl\n";
3087 # This needs a handler that can be turned on or off:
3088 # $switch = "-MExtUtils::MakeMaker ".
3089 # "-Mops=:default,:filesys_read,:filesys_open,require,chdir"
3091 $system = "$perl $switch Makefile.PL $CPAN::Config->{makepl_arg}";
3093 unless (exists $self->{writemakefile}) {
3094 local($SIG{ALRM}) = sub { die "inactivity_timeout reached\n" };
3097 if ($CPAN::Config->{inactivity_timeout}) {
3099 alarm $CPAN::Config->{inactivity_timeout};
3100 local $SIG{CHLD} = sub { wait };
3101 if (defined($pid = fork)) {
3105 # note, this exec isn't necessary if
3106 # inactivity_timeout is 0. On the Mac I'd
3107 # suggest, we set it always to 0.
3111 $CPAN::Frontend->myprint("Cannot fork: $!");
3119 $CPAN::Frontend->myprint($@);
3120 $self->{writemakefile} = "NO - $@";
3126 warn "Trying to intercept the output of 'perl Makefile.PL'";
3128 # my $fh = FileHandle->new("$system 2>&1 |") or
3129 my $fh = IO::File->new("$system 2>&1 |") or
3130 die "Couldn't run '$system': $!";
3132 while (length($_ = getc($fh))) {
3133 print $_; # we want to parse that some day!
3134 # unfortunately we have Makefile.PLs that want to talk
3135 # and we can't emulate that reliably. I think, we have
3136 # to parse Makefile.PL directly
3140 warn $! ? "Error during 'perl Makefile.PL' subprocess: $!" :
3141 "Exit status of 'perl Makefile.PL': $?";
3142 $self->{writemakefile} = "NO";
3146 $ret = system($system);
3148 $self->{writemakefile} = "NO";
3153 $self->{writemakefile} = "YES";
3155 return if $CPAN::Signal;
3156 $system = join " ", $CPAN::Config->{'make'}, $CPAN::Config->{make_arg};
3157 if (system($system) == 0) {
3158 $CPAN::Frontend->myprint(" $system -- OK\n");
3159 $self->{'make'} = "YES";
3161 $self->{writemakefile} = "YES";
3162 $self->{'make'} = "NO";
3163 $CPAN::Frontend->myprint(" $system -- NOT OK\n");
3167 #-> sub CPAN::Distribution::test ;
3171 return if $CPAN::Signal;
3172 $CPAN::Frontend->myprint("Running make test\n");
3175 exists $self->{'make'} or push @e,
3176 "Make had some problems, maybe interrupted? Won't test";
3178 exists $self->{'make'} and
3179 $self->{'make'} eq 'NO' and
3180 push @e, "Oops, make had returned bad status";
3182 exists $self->{'build_dir'} or push @e, "Has no own directory";
3183 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
3185 chdir $self->{'build_dir'} or
3186 Carp::croak("Couldn't chdir to $self->{'build_dir'}");
3187 $self->debug("Changed directory to $self->{'build_dir'}")
3189 my $system = join " ", $CPAN::Config->{'make'}, "test";
3190 if (system($system) == 0) {
3191 $CPAN::Frontend->myprint(" $system -- OK\n");
3192 $self->{'make_test'} = "YES";
3194 $self->{'make_test'} = "NO";
3195 $CPAN::Frontend->myprint(" $system -- NOT OK\n");
3199 #-> sub CPAN::Distribution::clean ;
3202 $CPAN::Frontend->myprint("Running make clean\n");
3205 exists $self->{'build_dir'} or push @e, "Has no own directory";
3206 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
3208 chdir $self->{'build_dir'} or
3209 Carp::croak("Couldn't chdir to $self->{'build_dir'}");
3210 $self->debug("Changed directory to $self->{'build_dir'}") if $CPAN::DEBUG;
3211 my $system = join " ", $CPAN::Config->{'make'}, "clean";
3212 if (system($system) == 0) {
3213 $CPAN::Frontend->myprint(" $system -- OK\n");
3216 # Hmmm, what to do if make clean failed?
3220 #-> sub CPAN::Distribution::install ;
3224 return if $CPAN::Signal;
3225 $CPAN::Frontend->myprint("Running make install\n");
3228 exists $self->{'build_dir'} or push @e, "Has no own directory";
3230 exists $self->{'make'} or push @e,
3231 "Make had some problems, maybe interrupted? Won't install";
3233 exists $self->{'make'} and
3234 $self->{'make'} eq 'NO' and
3235 push @e, "Oops, make had returned bad status";
3237 push @e, "make test had returned bad status, ".
3238 "won't install without force"
3239 if exists $self->{'make_test'} and
3240 $self->{'make_test'} eq 'NO' and
3241 ! $self->{'force_update'};
3243 exists $self->{'install'} and push @e,
3244 $self->{'install'} eq "YES" ?
3245 "Already done" : "Already tried without success";
3247 $CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
3249 chdir $self->{'build_dir'} or
3250 Carp::croak("Couldn't chdir to $self->{'build_dir'}");
3251 $self->debug("Changed directory to $self->{'build_dir'}")
3253 my $system = join(" ", $CPAN::Config->{'make'},
3254 "install", $CPAN::Config->{make_install_arg});
3255 my($pipe) = FileHandle->new("$system 2>&1 |");
3258 $CPAN::Frontend->myprint($_);
3263 $CPAN::Frontend->myprint(" $system -- OK\n");
3264 $self->{'install'} = "YES";
3266 $self->{'install'} = "NO";
3267 $CPAN::Frontend->myprint(" $system -- NOT OK\n");
3268 if ($makeout =~ /permission/s && $> > 0) {
3269 $CPAN::Frontend->myprint(qq{ You may have to su }.
3270 qq{to root to install the package\n});
3275 #-> sub CPAN::Distribution::dir ;
3277 shift->{'build_dir'};
3280 package CPAN::Bundle;
3282 #-> sub CPAN::Bundle::as_string ;
3286 $self->{INST_VERSION} = $self->inst_version;
3287 return $self->SUPER::as_string;
3290 #-> sub CPAN::Bundle::contains ;
3293 my($parsefile) = $self->inst_file;
3294 my($id) = $self->id;
3295 $self->debug("parsefile[$parsefile]id[$id]") if $CPAN::DEBUG;
3296 unless ($parsefile) {
3297 # Try to get at it in the cpan directory
3298 $self->debug("no parsefile") if $CPAN::DEBUG;
3299 Carp::confess "I don't know a $id" unless $self->{CPAN_FILE};
3300 my $dist = $CPAN::META->instance('CPAN::Distribution',
3301 $self->{CPAN_FILE});
3303 $self->debug($dist->as_string) if $CPAN::DEBUG;
3304 my($todir) = $CPAN::Config->{'cpan_home'};
3305 my(@me,$from,$to,$me);
3306 @me = split /::/, $self->id;
3308 $me = MM->catfile(@me);
3309 $from = $self->find_bundle_file($dist->{'build_dir'},$me);
3310 $to = MM->catfile($todir,$me);
3311 File::Path::mkpath(File::Basename::dirname($to));
3312 File::Copy::copy($from, $to)
3313 or Carp::confess("Couldn't copy $from to $to: $!");
3317 my $fh = FileHandle->new;
3319 open($fh,$parsefile) or die "Could not open '$parsefile': $!";
3321 $self->debug("parsefile[$parsefile]") if $CPAN::DEBUG;
3323 $inpod = /^=(?!head1\s+CONTENTS)/ ? 0 :
3324 /^=head1\s+CONTENTS/ ? 1 : $inpod;
3329 push @result, (split " ", $_, 2)[0];
3332 delete $self->{STATUS};
3333 $self->{CONTAINS} = join ", ", @result;
3334 $self->debug("CONTAINS[@result]") if $CPAN::DEBUG;
3338 #-> sub CPAN::Bundle::find_bundle_file
3339 sub find_bundle_file {
3340 my($self,$where,$what) = @_;
3341 $self->debug("where[$where]what[$what]") if $CPAN::DEBUG;
3342 my $bu = MM->catfile($where,$what);
3343 return $bu if -f $bu;
3344 my $manifest = MM->catfile($where,"MANIFEST");
3345 unless (-f $manifest) {
3346 require ExtUtils::Manifest;
3347 my $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
3348 my $cwd = CPAN->$getcwd();
3350 ExtUtils::Manifest::mkmanifest();
3353 my $fh = FileHandle->new($manifest)
3354 or Carp::croak("Couldn't open $manifest: $!");
3358 my($file) = /(\S+)/;
3359 if ($file =~ m|\Q$what\E$|) {
3361 return MM->catfile($where,$bu);
3362 } elsif ($what =~ s|Bundle/||) { # retry if she managed to
3363 # have no Bundle directory
3364 if ($file =~ m|\Q$what\E$|) {
3366 return MM->catfile($where,$bu);
3370 Carp::croak("Couldn't find a Bundle file in $where");
3373 #-> sub CPAN::Bundle::inst_file ;
3377 ($me = $self->id) =~ s/.*://;
3378 ## my(@me,$inst_file);
3379 ## @me = split /::/, $self->id;
3380 ## $me[-1] .= ".pm";
3381 $inst_file = MM->catfile($CPAN::Config->{'cpan_home'},
3382 "Bundle", "$me.pm");
3384 return $self->{'INST_FILE'} = $inst_file if -f $inst_file;
3386 $self->SUPER::inst_file;
3387 # return $self->{'INST_FILE'} = $inst_file if -f $inst_file;
3388 # return $self->{'INST_FILE'}; # even if undefined?
3391 #-> sub CPAN::Bundle::rematein ;
3393 my($self,$meth) = @_;
3394 $self->debug("self[$self] meth[$meth]") if $CPAN::DEBUG;
3395 my($id) = $self->id;
3396 Carp::croak "Can't $meth $id, don't have an associated bundle file. :-(\n"
3397 unless $self->inst_file || $self->{CPAN_FILE};
3399 for $s ($self->contains) {
3400 my($type) = $s =~ m|/| ? 'CPAN::Distribution' :
3401 $s =~ m|^Bundle::| ? 'CPAN::Bundle' : 'CPAN::Module';
3402 if ($type eq 'CPAN::Distribution') {
3403 $CPAN::Frontend->mywarn(qq{
3404 The Bundle }.$self->id.qq{ contains
3405 explicitly a file $s.
3409 $CPAN::META->instance($type,$s)->$meth();
3413 #sub CPAN::Bundle::xs_file
3415 # If a bundle contains another that contains an xs_file we have
3416 # here, we just don't bother I suppose
3420 #-> sub CPAN::Bundle::force ;
3421 sub force { shift->rematein('force',@_); }
3422 #-> sub CPAN::Bundle::get ;
3423 sub get { shift->rematein('get',@_); }
3424 #-> sub CPAN::Bundle::make ;
3425 sub make { shift->rematein('make',@_); }
3426 #-> sub CPAN::Bundle::test ;
3427 sub test { shift->rematein('test',@_); }
3428 #-> sub CPAN::Bundle::install ;
3431 $self->rematein('install',@_);
3432 $CPAN::META->delete('CPAN::Queue',$self->id);
3434 #-> sub CPAN::Bundle::clean ;
3435 sub clean { shift->rematein('clean',@_); }
3437 #-> sub CPAN::Bundle::readme ;
3440 my($file) = $self->cpan_file or $CPAN::Frontend->myprint(qq{
3441 No File found for bundle } . $self->id . qq{\n}), return;
3442 $self->debug("self[$self] file[$file]") if $CPAN::DEBUG;
3443 $CPAN::META->instance('CPAN::Distribution',$file)->readme;
3446 package CPAN::Module;
3448 #-> sub CPAN::Module::as_glimpse ;
3452 my $class = ref($self);
3453 $class =~ s/^CPAN:://;
3454 push @m, sprintf("%-15s %-15s (%s)\n", $class, $self->{ID},
3459 #-> sub CPAN::Module::as_string ;
3463 CPAN->debug($self) if $CPAN::DEBUG;
3464 my $class = ref($self);
3465 $class =~ s/^CPAN:://;
3467 push @m, $class, " id = $self->{ID}\n";
3468 my $sprintf = " %-12s %s\n";
3469 push @m, sprintf($sprintf, 'DESCRIPTION', $self->{description})
3470 if $self->{description};
3471 my $sprintf2 = " %-12s %s (%s)\n";
3473 if ($userid = $self->{'CPAN_USERID'} || $self->{'userid'}){
3475 if ($author = CPAN::Shell->expand('Author',$userid)) {
3478 if ($m = $author->email) {
3485 $author->fullname . $email
3489 push @m, sprintf($sprintf, 'CPAN_VERSION', $self->{CPAN_VERSION})
3490 if $self->{CPAN_VERSION};
3491 push @m, sprintf($sprintf, 'CPAN_FILE', $self->{CPAN_FILE})
3492 if $self->{CPAN_FILE};
3493 my $sprintf3 = " %-12s %1s%1s%1s%1s (%s,%s,%s,%s)\n";
3494 my(%statd,%stats,%statl,%stati);
3495 @statd{qw,? i c a b R M S,} = qw,unknown idea
3496 pre-alpha alpha beta released mature standard,;
3497 @stats{qw,? m d u n,} = qw,unknown mailing-list
3498 developer comp.lang.perl.* none,;
3499 @statl{qw,? p c + o,} = qw,unknown perl C C++ other,;
3500 @stati{qw,? f r O,} = qw,unknown functions
3501 references+ties object-oriented,;
3502 $statd{' '} = 'unknown';
3503 $stats{' '} = 'unknown';
3504 $statl{' '} = 'unknown';
3505 $stati{' '} = 'unknown';
3513 $statd{$self->{statd}},
3514 $stats{$self->{stats}},
3515 $statl{$self->{statl}},
3516 $stati{$self->{stati}}
3517 ) if $self->{statd};
3518 my $local_file = $self->inst_file;
3520 $self->{MANPAGE} ||= $self->manpage_headline($local_file);
3523 for $item (qw/MANPAGE CONTAINS/) {
3524 push @m, sprintf($sprintf, $item, $self->{$item})
3525 if exists $self->{$item};
3527 push @m, sprintf($sprintf, 'INST_FILE',
3528 $local_file || "(not installed)");
3529 push @m, sprintf($sprintf, 'INST_VERSION',
3530 $self->inst_version) if $local_file;
3534 sub manpage_headline {
3535 my($self,$local_file) = @_;
3536 my(@local_file) = $local_file;
3537 $local_file =~ s/\.pm$/.pod/;
3538 push @local_file, $local_file;
3540 for $locf (@local_file) {
3541 next unless -f $locf;
3542 my $fh = FileHandle->new($locf)
3543 or $Carp::Frontend->mydie("Couldn't open $locf: $!");
3547 $inpod = /^=(?!head1\s+NAME)/ ? 0 :
3548 /^=head1\s+NAME/ ? 1 : $inpod;
3561 #-> sub CPAN::Module::cpan_file ;
3564 CPAN->debug($self->id) if $CPAN::DEBUG;
3565 unless (defined $self->{'CPAN_FILE'}) {
3566 CPAN::Index->reload;
3568 if (exists $self->{'CPAN_FILE'} && defined $self->{'CPAN_FILE'}){
3569 return $self->{'CPAN_FILE'};
3570 } elsif (exists $self->{'userid'} && defined $self->{'userid'}) {
3571 my $fullname = $CPAN::META->instance(CPAN::Author,
3572 $self->{'userid'})->fullname;
3573 my $email = $CPAN::META->instance(CPAN::Author,
3574 $self->{'userid'})->email;
3575 unless (defined $fullname && defined $email) {
3576 return "Contact Author $self->{userid} (Try ``a $self->{userid}'')";
3578 return "Contact Author $fullname <$email>";
3584 *name = \&cpan_file;
3586 #-> sub CPAN::Module::cpan_version ;
3589 $self->{'CPAN_VERSION'} = 'undef'
3590 unless defined $self->{'CPAN_VERSION'}; # I believe this is
3591 # always a bug in the
3592 # index and should be
3594 # but usually I find
3596 # and do not want to
3599 $self->{'CPAN_VERSION'};
3602 #-> sub CPAN::Module::force ;
3605 $self->{'force_update'}++;
3608 #-> sub CPAN::Module::rematein ;
3610 my($self,$meth) = @_;
3611 $self->debug($self->id) if $CPAN::DEBUG;
3612 my $cpan_file = $self->cpan_file;
3613 if ($cpan_file eq "N/A" || $cpan_file =~ /^Contact Author/){
3614 $CPAN::Frontend->mywarn(sprintf qq{
3615 The module %s isn\'t available on CPAN.
3617 Either the module has not yet been uploaded to CPAN, or it is
3618 temporary unavailable. Please contact the author to find out
3619 more about the status. Try ``i %s''.
3626 my $pack = $CPAN::META->instance('CPAN::Distribution',$cpan_file);
3627 $pack->called_for($self->id);
3628 $pack->force if exists $self->{'force_update'};
3630 delete $self->{'force_update'};
3633 #-> sub CPAN::Module::readme ;
3634 sub readme { shift->rematein('readme') }
3635 #-> sub CPAN::Module::look ;
3636 sub look { shift->rematein('look') }
3637 #-> sub CPAN::Module::get ;
3638 sub get { shift->rematein('get',@_); }
3639 #-> sub CPAN::Module::make ;
3640 sub make { shift->rematein('make') }
3641 #-> sub CPAN::Module::test ;
3642 sub test { shift->rematein('test') }
3643 #-> sub CPAN::Module::install ;
3647 my($latest) = $self->cpan_version;
3649 my($inst_file) = $self->inst_file;
3651 if (defined $inst_file) {
3652 $have = $self->inst_version;
3654 if (1){ # A block for scoping $^W, the if is just for the visual
3661 not exists $self->{'force_update'}
3663 $CPAN::Frontend->myprint( $self->id. " is up to date.\n");
3668 $self->rematein('install') if $doit;
3669 $CPAN::META->delete('CPAN::Queue',$self->id);
3671 #-> sub CPAN::Module::clean ;
3672 sub clean { shift->rematein('clean') }
3674 #-> sub CPAN::Module::inst_file ;
3678 @packpath = split /::/, $self->{ID};
3679 $packpath[-1] .= ".pm";
3680 foreach $dir (@INC) {
3681 my $pmfile = MM->catfile($dir,@packpath);
3689 #-> sub CPAN::Module::xs_file ;
3693 @packpath = split /::/, $self->{ID};
3694 push @packpath, $packpath[-1];
3695 $packpath[-1] .= "." . $Config::Config{'dlext'};
3696 foreach $dir (@INC) {
3697 my $xsfile = MM->catfile($dir,'auto',@packpath);
3705 #-> sub CPAN::Module::inst_version ;
3708 my $parsefile = $self->inst_file or return;
3709 local($^W) = 0 if $] < 5.00303 && $ExtUtils::MakeMaker::VERSION < 5.38;
3710 my $have = MM->parse_version($parsefile) || "undef";
3715 package CPAN::Tarzip;
3718 my($class,$read,$write) = @_;
3719 if ($CPAN::META->has_inst("Compress::Zlib")) {
3721 $fhw = FileHandle->new($read)
3722 or $CPAN::Frontend->mydie("Could not open $read: $!");
3723 my $gz = Compress::Zlib::gzopen($write, "wb")
3724 or $CPAN::Frontend->mydie("Cannot gzopen $write: $!\n");
3725 $gz->gzwrite($buffer)
3726 while read($fhw,$buffer,4096) > 0 ;
3731 system("$CPAN::Config->{'gzip'} -c $read > $write")==0;
3736 my($class,$read,$write) = @_;
3737 if ($CPAN::META->has_inst("Compress::Zlib")) {
3739 $fhw = FileHandle->new(">$write")
3740 or $CPAN::Frontend->mydie("Could not open >$write: $!");
3741 my $gz = Compress::Zlib::gzopen($read, "rb")
3742 or $CPAN::Frontend->mydie("Cannot gzopen $read: $!\n");
3743 $fhw->print($buffer)
3744 while $gz->gzread($buffer) > 0 ;
3745 $CPAN::Frontend->mydie("Error reading from $read: $!\n")
3746 if $gz->gzerror != Compress::Zlib::Z_STREAM_END();
3751 system("$CPAN::Config->{'gzip'} -dc $read > $write")==0;
3756 my($class,$read) = @_;
3757 if ($CPAN::META->has_inst("Compress::Zlib")) {
3759 my $gz = Compress::Zlib::gzopen($read, "rb")
3760 or $CPAN::Frontend->mydie("Cannot open $read: $!\n");
3761 1 while $gz->gzread($buffer) > 0 ;
3762 $CPAN::Frontend->mydie("Error reading from $read: $!\n")
3763 if $gz->gzerror != Compress::Zlib::Z_STREAM_END();
3767 return system("$CPAN::Config->{'gzip'} -dt $read")==0;
3772 my($class,$file) = @_;
3774 $class->debug("file[$file]");
3775 if ($CPAN::META->has_inst("Compress::Zlib")) {
3776 my $gz = Compress::Zlib::gzopen($file,"rb") or
3777 die "Could not gzopen $file";
3778 $ret = bless {GZ => $gz}, $class;
3780 my $pipe = "$CPAN::Config->{'gzip'} --decompress --stdout $file |";
3781 my $fh = FileHandle->new($pipe) or die "Could pipe[$pipe]: $!";
3783 $ret = bless {FH => $fh}, $class;
3790 if (exists $self->{GZ}) {
3791 my $gz = $self->{GZ};
3792 my($line,$bytesread);
3793 $bytesread = $gz->gzreadline($line);
3794 return undef if $bytesread == 0;
3797 my $fh = $self->{FH};
3798 return scalar <$fh>;
3803 my($self,$ref,$length,$offset) = @_;
3804 die "read with offset not implemented" if defined $offset;
3805 if (exists $self->{GZ}) {
3806 my $gz = $self->{GZ};
3807 my $byteread = $gz->gzread($$ref,$length);# 30eaf79e8b446ef52464b5422da328a8
3810 my $fh = $self->{FH};
3811 return read($fh,$$ref,$length);
3817 if (exists $self->{GZ}) {
3818 my $gz = $self->{GZ};
3821 my $fh = $self->{FH};
3828 my($class,$file) = @_;
3829 # had to disable, because version 0.07 seems to be buggy
3830 if (MM->maybe_command($CPAN::Config->{'gzip'})
3832 MM->maybe_command($CPAN::Config->{'tar'})) {
3833 my $system = "$CPAN::Config->{'gzip'} --decompress --stdout " .
3834 "$file | $CPAN::Config->{tar} xvf -";
3835 return system($system) == 0;
3836 } elsif ($CPAN::META->has_inst("Archive::Tar")
3838 $CPAN::META->has_inst("Compress::Zlib") ) {
3839 my $tar = Archive::Tar->new($file,1);
3840 $tar->extract($tar->list_files); # I'm pretty sure we have nothing
3841 # that isn't compressed
3844 $CPAN::Frontend->mydie(qq{
3845 CPAN.pm needs either both external programs tar and gzip installed or
3846 both the modules Archive::Tar and Compress::Zlib. Neither prerequisite
3847 is available. Can\'t continue.
3860 CPAN - query, download and build perl modules from CPAN sites
3866 perl -MCPAN -e shell;
3872 autobundle, clean, install, make, recompile, test
3876 The CPAN module is designed to automate the make and install of perl
3877 modules and extensions. It includes some searching capabilities and
3878 knows how to use Net::FTP or LWP (or lynx or an external ftp client)
3879 to fetch the raw data from the net.
3881 Modules are fetched from one or more of the mirrored CPAN
3882 (Comprehensive Perl Archive Network) sites and unpacked in a dedicated
3885 The CPAN module also supports the concept of named and versioned
3886 'bundles' of modules. Bundles simplify the handling of sets of
3887 related modules. See BUNDLES below.
3889 The package contains a session manager and a cache manager. There is
3890 no status retained between sessions. The session manager keeps track
3891 of what has been fetched, built and installed in the current
3892 session. The cache manager keeps track of the disk space occupied by
3893 the make processes and deletes excess space according to a simple FIFO
3896 All methods provided are accessible in a programmer style and in an
3897 interactive shell style.
3899 =head2 Interactive Mode
3901 The interactive mode is entered by running
3903 perl -MCPAN -e shell
3905 which puts you into a readline interface. You will have the most fun if
3906 you install Term::ReadKey and Term::ReadLine to enjoy both history and
3909 Once you are on the command line, type 'h' and the rest should be
3912 The most common uses of the interactive modes are
3916 =item Searching for authors, bundles, distribution files and modules
3918 There are corresponding one-letter commands C<a>, C<b>, C<d>, and C<m>
3919 for each of the four categories and another, C<i> for any of the
3920 mentioned four. Each of the four entities is implemented as a class
3921 with slightly differing methods for displaying an object.
3923 Arguments you pass to these commands are either strings exactly matching
3924 the identification string of an object or regular expressions that are
3925 then matched case-insensitively against various attributes of the
3926 objects. The parser recognizes a regular expression only if you
3927 enclose it between two slashes.
3929 The principle is that the number of found objects influences how an
3930 item is displayed. If the search finds one item, the result is displayed
3931 as object-E<gt>as_string, but if we find more than one, we display
3932 each as object-E<gt>as_glimpse. E.g.
3936 EMAIL a.koenig@franz.ww.TU-Berlin.DE
3937 FULLNAME Andreas König
3942 EMAIL a.koenig@franz.ww.TU-Berlin.DE
3943 FULLNAME Andreas König
3947 Author ANDYD (Andy Dougherty)
3948 Author MERLYN (Randal L. Schwartz)
3950 =item make, test, install, clean modules or distributions
3952 These commands take any number of arguments and investigate what is
3953 necessary to perform the action. If the argument is a distribution
3954 file name (recognized by embedded slashes), it is processed. If it is a
3955 module, CPAN determines the distribution file in which this module is
3956 included and processes that.
3958 Any C<make> or C<test> are run unconditionally. An
3960 install <distribution_file>
3962 also is run unconditionally. But for
3966 CPAN checks if an install is actually needed for it and prints
3967 I<module up to date> in the case that the distribution file containing
3968 the module doesnE<39>t need to be updated.
3970 CPAN also keeps track of what it has done within the current session
3971 and doesnE<39>t try to build a package a second time regardless if it
3972 succeeded or not. The C<force> command takes as a first argument the
3973 method to invoke (currently: C<make>, C<test>, or C<install>) and executes the
3974 command from scratch.
3978 cpan> install OpenGL
3979 OpenGL is up to date.
3980 cpan> force install OpenGL
3983 OpenGL-0.4/COPYRIGHT
3986 A C<clean> command results in a
3990 being executed within the distribution file's working directory.
3992 =item readme, look module or distribution
3994 These two commands take only one argument, be it a module or a
3995 distribution file. C<readme> unconditionally runs, displaying the
3996 README of the associated distribution file. C<Look> gets and
3997 untars (if not yet done) the distribution file, changes to the
3998 appropriate directory and opens a subshell process in that directory.
4002 CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
4003 in the cpan-shell it is intended that you can press C<^C> anytime and
4004 return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
4005 to clean up and leave the shell loop. You can emulate the effect of a
4006 SIGTERM by sending two consecutive SIGINTs, which usually means by
4007 pressing C<^C> twice.
4009 CPAN.pm ignores a SIGPIPE. If the user sets inactivity_timeout, a
4010 SIGALRM is used during the run of the C<perl Makefile.PL> subprocess.
4016 The commands that are available in the shell interface are methods in
4017 the package CPAN::Shell. If you enter the shell command, all your
4018 input is split by the Text::ParseWords::shellwords() routine which
4019 acts like most shells do. The first word is being interpreted as the
4020 method to be called and the rest of the words are treated as arguments
4021 to this method. Continuation lines are supported if a line ends with a
4026 C<autobundle> writes a bundle file into the
4027 C<$CPAN::Config-E<gt>{cpan_home}/Bundle> directory. The file contains
4028 a list of all modules that are both available from CPAN and currently
4029 installed within @INC. The name of the bundle file is based on the
4030 current date and a counter.
4034 recompile() is a very special command in that it takes no argument and
4035 runs the make/test/install cycle with brute force over all installed
4036 dynamically loadable extensions (aka XS modules) with 'force' in
4037 effect. The primary purpose of this command is to finish a network
4038 installation. Imagine, you have a common source tree for two different
4039 architectures. You decide to do a completely independent fresh
4040 installation. You start on one architecture with the help of a Bundle
4041 file produced earlier. CPAN installs the whole Bundle for you, but
4042 when you try to repeat the job on the second architecture, CPAN
4043 responds with a C<"Foo up to date"> message for all modules. So you
4044 invoke CPAN's recompile on the second architecture and youE<39>re done.
4046 Another popular use for C<recompile> is to act as a rescue in case your
4047 perl breaks binary compatibility. If one of the modules that CPAN uses
4048 is in turn depending on binary compatibility (so you cannot run CPAN
4049 commands), then you should try the CPAN::Nox module for recovery.
4051 =head2 The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution
4053 Although it may be considered internal, the class hierarchy does matter
4054 for both users and programmer. CPAN.pm deals with above mentioned four
4055 classes, and all those classes share a set of methods. A classical
4056 single polymorphism is in effect. A metaclass object registers all
4057 objects of all kinds and indexes them with a string. The strings
4058 referencing objects have a separated namespace (well, not completely
4063 words containing a "/" (slash) Distribution
4064 words starting with Bundle:: Bundle
4065 everything else Module or Author
4067 Modules know their associated Distribution objects. They always refer
4068 to the most recent official release. Developers may mark their releases
4069 as unstable development versions (by inserting an underbar into the
4070 visible version number), so the really hottest and newest distribution
4071 file is not always the default. If a module Foo circulates on CPAN in
4072 both version 1.23 and 1.23_90, CPAN.pm offers a convenient way to
4073 install version 1.23 by saying
4077 This would install the complete distribution file (say
4078 BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
4079 like to install version 1.23_90, you need to know where the
4080 distribution file resides on CPAN relative to the authors/id/
4081 directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
4082 so you would have to say
4084 install BAR/Foo-1.23_90.tar.gz
4086 The first example will be driven by an object of the class
4087 CPAN::Module, the second by an object of class CPAN::Distribution.
4089 =head2 ProgrammerE<39>s interface
4091 If you do not enter the shell, the available shell commands are both
4092 available as methods (C<CPAN::Shell-E<gt>install(...)>) and as
4093 functions in the calling package (C<install(...)>).
4095 There's currently only one class that has a stable interface -
4096 CPAN::Shell. All commands that are available in the CPAN shell are
4097 methods of the class CPAN::Shell. Each of the commands that produce
4098 listings of modules (C<r>, C<autobundle>, C<u>) returns a list of the
4099 IDs of all modules within the list.
4103 =item expand($type,@things)
4105 The IDs of all objects available within a program are strings that can
4106 be expanded to the corresponding real objects with the
4107 C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a
4108 list of CPAN::Module objects according to the C<@things> arguments
4109 given. In scalar context it only returns the first element of the
4112 =item Programming Examples
4114 This enables the programmer to do operations that combine
4115 functionalities that are available in the shell.
4117 # install everything that is outdated on my disk:
4118 perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
4120 # install my favorite programs if necessary:
4121 for $mod (qw(Net::FTP MD5 Data::Dumper)){
4122 my $obj = CPAN::Shell->expand('Module',$mod);
4126 # list all modules on my disk that have no VERSION number
4127 for $mod (CPAN::Shell->expand("Module","/./")){
4128 next unless $mod->inst_file;
4129 # MakeMaker convention for undefined $VERSION:
4130 next unless $mod->inst_version eq "undef";
4131 print "No VERSION in ", $mod->id, "\n";
4136 =head2 Methods in the four
4138 =head2 Cache Manager
4140 Currently the cache manager only keeps track of the build directory
4141 ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
4142 deletes complete directories below C<build_dir> as soon as the size of
4143 all directories there gets bigger than $CPAN::Config->{build_cache}
4144 (in MB). The contents of this cache may be used for later
4145 re-installations that you intend to do manually, but will never be
4146 trusted by CPAN itself. This is due to the fact that the user might
4147 use these directories for building modules on different architectures.
4149 There is another directory ($CPAN::Config->{keep_source_where}) where
4150 the original distribution files are kept. This directory is not
4151 covered by the cache manager and must be controlled by the user. If
4152 you choose to have the same directory as build_dir and as
4153 keep_source_where directory, then your sources will be deleted with
4154 the same fifo mechanism.
4158 A bundle is just a perl module in the namespace Bundle:: that does not
4159 define any functions or methods. It usually only contains documentation.
4161 It starts like a perl module with a package declaration and a $VERSION
4162 variable. After that the pod section looks like any other pod with the
4163 only difference being that I<one special pod section> exists starting with
4168 In this pod section each line obeys the format
4170 Module_Name [Version_String] [- optional text]
4172 The only required part is the first field, the name of a module
4173 (e.g. Foo::Bar, ie. I<not> the name of the distribution file). The rest
4174 of the line is optional. The comment part is delimited by a dash just
4175 as in the man page header.
4177 The distribution of a bundle should follow the same convention as
4178 other distributions.
4180 Bundles are treated specially in the CPAN package. If you say 'install
4181 Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
4182 the modules in the CONTENTS section of the pod. You can install your
4183 own Bundles locally by placing a conformant Bundle file somewhere into
4184 your @INC path. The autobundle() command which is available in the
4185 shell interface does that for you by including all currently installed
4186 modules in a snapshot bundle file.
4188 =head2 Prerequisites
4190 If you have a local mirror of CPAN and can access all files with
4191 "file:" URLs, then you only need a perl better than perl5.003 to run
4192 this module. Otherwise Net::FTP is strongly recommended. LWP may be
4193 required for non-UNIX systems or if your nearest CPAN site is
4194 associated with an URL that is not C<ftp:>.
4196 If you have neither Net::FTP nor LWP, there is a fallback mechanism
4197 implemented for an external ftp command or for an external lynx
4200 =head2 Finding packages and VERSION
4202 This module presumes that all packages on CPAN
4208 declare their $VERSION variable in an easy to parse manner. This
4209 prerequisite can hardly be relaxed because it consumes far too much
4210 memory to load all packages into the running program just to determine
4211 the $VERSION variable. Currently all programs that are dealing with
4212 version use something like this
4214 perl -MExtUtils::MakeMaker -le \
4215 'print MM->parse_version($ARGV[0])' filename
4217 If you are author of a package and wonder if your $VERSION can be
4218 parsed, please try the above method.
4222 come as compressed or gzipped tarfiles or as zip files and contain a
4223 Makefile.PL (well, we try to handle a bit more, but without much
4230 The debugging of this module is pretty difficult, because we have
4231 interferences of the software producing the indices on CPAN, of the
4232 mirroring process on CPAN, of packaging, of configuration, of
4233 synchronicity, and of bugs within CPAN.pm.
4235 In interactive mode you can try "o debug" which will list options for
4236 debugging the various parts of the package. The output may not be very
4237 useful for you as it's just a by-product of my own testing, but if you
4238 have an idea which part of the package may have a bug, it's sometimes
4239 worth to give it a try and send me more specific output. You should
4240 know that "o debug" has built-in completion support.
4242 =head2 Floppy, Zip, and all that Jazz
4244 CPAN.pm works nicely without network too. If you maintain machines
4245 that are not networked at all, you should consider working with file:
4246 URLs. Of course, you have to collect your modules somewhere first. So
4247 you might use CPAN.pm to put together all you need on a networked
4248 machine. Then copy the $CPAN::Config->{keep_source_where} (but not
4249 $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
4250 of a personal CPAN. CPAN.pm on the non-networked machines works nicely
4253 =head1 CONFIGURATION
4255 When the CPAN module is installed, a site wide configuration file is
4256 created as CPAN/Config.pm. The default values defined there can be
4257 overridden in another configuration file: CPAN/MyConfig.pm. You can
4258 store this file in $HOME/.cpan/CPAN/MyConfig.pm if you want, because
4259 $HOME/.cpan is added to the search path of the CPAN module before the
4260 use() or require() statements.
4262 Currently the following keys in the hash reference $CPAN::Config are
4265 build_cache size of cache for directories to build modules
4266 build_dir locally accessible directory to build modules
4267 index_expire after this many days refetch index files
4268 cpan_home local directory reserved for this package
4269 gzip location of external program gzip
4270 inactivity_timeout breaks interactive Makefile.PLs after this
4271 many seconds inactivity. Set to 0 to never break.
4272 inhibit_startup_message
4273 if true, does not print the startup message
4274 keep_source keep the source in a local directory?
4275 keep_source_where directory in which to keep the source (if we do)
4276 make location of external make program
4277 make_arg arguments that should always be passed to 'make'
4278 make_install_arg same as make_arg for 'make install'
4279 makepl_arg arguments passed to 'perl Makefile.PL'
4280 pager location of external program more (or any pager)
4281 tar location of external program tar
4282 unzip location of external program unzip
4283 urllist arrayref to nearby CPAN sites (or equivalent locations)
4284 wait_list arrayref to a wait server to try (See CPAN::WAIT)
4286 You can set and query each of these options interactively in the cpan
4287 shell with the command set defined within the C<o conf> command:
4291 =item o conf E<lt>scalar optionE<gt>
4293 prints the current value of the I<scalar option>
4295 =item o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>
4297 Sets the value of the I<scalar option> to I<value>
4299 =item o conf E<lt>list optionE<gt>
4301 prints the current value of the I<list option> in MakeMaker's
4304 =item o conf E<lt>list optionE<gt> [shift|pop]
4306 shifts or pops the array in the I<list option> variable
4308 =item o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>
4310 works like the corresponding perl commands.
4314 =head2 CD-ROM support
4316 The C<urllist> parameter of the configuration table contains a list of
4317 URLs that are to be used for downloading. If the list contains any
4318 C<file> URLs, CPAN always tries to get files from there first. This
4319 feature is disabled for index files. So the recommendation for the
4320 owner of a CD-ROM with CPAN contents is: include your local, possibly
4321 outdated CD-ROM as a C<file> URL at the end of urllist, e.g.
4323 o conf urllist push file://localhost/CDROM/CPAN
4325 CPAN.pm will then fetch the index files from one of the CPAN sites
4326 that come at the beginning of urllist. It will later check for each
4327 module if there is a local copy of the most recent version.
4331 There's no strong security layer in CPAN.pm. CPAN.pm helps you to
4332 install foreign, unmasked, unsigned code on your machine. We compare
4333 to a checksum that comes from the net just as the distribution file
4334 itself. If somebody has managed to tamper with the distribution file,
4335 they may have as well tampered with the CHECKSUMS file. Future
4336 development will go towards strong authentification.
4340 Most functions in package CPAN are exported per default. The reason
4341 for this is that the primary use is intended for the cpan shell or for
4346 We should give coverage for _all_ of the CPAN and not just the PAUSE
4347 part, right? In this discussion CPAN and PAUSE have become equal --
4348 but they are not. PAUSE is authors/ and modules/. CPAN is PAUSE plus
4349 the clpa/, doc/, misc/, ports/, src/, scripts/.
4351 Future development should be directed towards a better integration of
4354 If a Makefile.PL requires special customization of libraries, prompts
4355 the user for special input, etc. then you may find CPAN is not able to
4356 build the distribution. In that case, you should attempt the
4357 traditional method of building a Perl module package from a shell.
4361 Andreas König E<lt>a.koenig@mind.deE<gt>
4365 perl(1), CPAN::Nox(3)