1 # -*- Mode: cperl; coding: utf-8; cperl-indent-level: 4 -*-
2 # vim: ts=4 sts=4 sw=4:
5 $CPAN::VERSION = '1.93_51';
6 $CPAN::VERSION =~ s/_//;
8 # we need to run chdir all over and we would get at wrong libraries
12 if (File::Spec->can("rel2abs")) {
14 $inc = File::Spec->rel2abs($inc) unless ref $inc;
19 use CPAN::HandleConfig;
25 use CPAN::Distribution;
26 use CPAN::Distrostatus;
35 use CPAN::DeferredCode;
37 use CPAN::LWP::UserAgent;
38 use CPAN::Exception::RecursiveDependency;
39 use CPAN::Exception::yaml_not_installed;
46 use ExtUtils::MakeMaker qw(prompt); # for some unknown reason,
47 # 5.005_04 does not work without
49 use File::Basename ();
56 use Sys::Hostname qw(hostname);
57 use Text::ParseWords ();
60 # protect against "called too early"
67 require Mac::BuildTools if $^O eq 'MacOS';
68 if ($ENV{PERL5_CPAN_IS_RUNNING} && $$ != $ENV{PERL5_CPAN_IS_RUNNING}) {
69 $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION} ||= $ENV{PERL5_CPAN_IS_RUNNING};
70 my @rec = _uniq split(/,/, $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION}), $$;
71 $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION} = join ",", @rec;
72 # warn "# Note: Recursive call of CPAN.pm detected\n";
73 my $w = sprintf "# Note: CPAN.pm is running in process %d now", pop @rec;
79 my $sleep = @rec > 7 ? 300 : ($sleep{scalar @rec}||0);
80 my $verbose = @rec >= 4;
82 $w .= sprintf " which has been called by process %d", pop @rec;
85 $w .= ".\n\n# Sleeping $sleep seconds to protect other processes\n";
92 printf "\r#%5d", --$sleep;
97 $ENV{PERL5_CPAN_IS_RUNNING}=$$;
98 $ENV{PERL5_CPANPLUS_IS_RUNNING}=$$; # https://rt.cpan.org/Ticket/Display.html?id=23735
100 END { $CPAN::End++; &cleanup; }
103 $CPAN::Frontend ||= "CPAN::Shell";
104 unless (@CPAN::Defaultsites) {
105 @CPAN::Defaultsites = map {
106 CPAN::URL->new(TEXT => $_, FROM => "DEF")
108 "http://www.perl.org/CPAN/",
109 "ftp://ftp.perl.org/pub/CPAN/";
111 # $CPAN::iCwd (i for initial)
112 $CPAN::iCwd ||= CPAN::anycwd();
113 $CPAN::Perl ||= CPAN::find_perl();
114 $CPAN::Defaultdocs ||= "http://search.cpan.org/perldoc?";
115 $CPAN::Defaultrecent ||= "http://search.cpan.org/uploads.rdf";
116 $CPAN::Defaultrecent ||= "http://cpan.uwinnipeg.ca/htdocs/cpan.xml";
118 # our globals are getting a mess
144 @CPAN::ISA = qw(CPAN::Debug Exporter);
146 # note that these functions live in CPAN::Shell and get executed via
147 # AUTOLOAD when called directly
174 sub soft_chdir_with_alternatives ($);
177 $autoload_recursion ||= 0;
179 #-> sub CPAN::AUTOLOAD ;
180 sub AUTOLOAD { ## no critic
181 $autoload_recursion++;
185 warn "Refusing to autoload '$l' while signal pending";
186 $autoload_recursion--;
189 if ($autoload_recursion > 1) {
190 my $fullcommand = join " ", map { "'$_'" } $l, @_;
191 warn "Refusing to autoload $fullcommand in recursion\n";
192 $autoload_recursion--;
196 @export{@EXPORT} = '';
197 CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
198 if (exists $export{$l}) {
201 die(qq{Unknown CPAN command "$AUTOLOAD". }.
202 qq{Type ? for help.\n});
204 $autoload_recursion--;
209 my $x = *SAVEOUT; # avoid warning
210 open($x,">&STDOUT") or die "dup failed";
216 while(defined($_=shift)) {
218 my ($m) = s/^>// ? ">" : "";
220 $_=shift unless length;
221 die "no dest" unless defined;
222 open(STDOUT,">$m$_") or die "open:$_:$!\n";
224 } elsif ( s/^\s*\|\s*// ) {
226 while(defined($_[0])){
227 $pipe .= ' ' . shift;
229 open(STDOUT,$pipe) or die "open:$pipe:$!\n";
238 return unless $redir;
240 ## redirect: unredirect and propagate errors. explicit close to wait for pipe.
242 open(STDOUT,">&SAVEOUT");
251 return map { !$seen{$_} } @list;
254 #-> sub CPAN::shell ;
257 $Suppress_readline = ! -t STDIN unless defined $Suppress_readline;
258 CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
260 my $oprompt = shift || CPAN::Prompt->new;
261 my $prompt = $oprompt;
262 my $commandline = shift || "";
263 $CPAN::CurrentCommandId ||= 1;
266 unless ($Suppress_readline) {
267 require Term::ReadLine;
270 $term->ReadLine eq "Term::ReadLine::Stub"
272 $term = Term::ReadLine->new('CPAN Monitor');
274 if ($term->ReadLine eq "Term::ReadLine::Gnu") {
275 my $attribs = $term->Attribs;
276 $attribs->{attempted_completion_function} = sub {
277 &CPAN::Complete::gnu_cpl;
280 $readline::rl_completion_function =
281 $readline::rl_completion_function = 'CPAN::Complete::cpl';
283 if (my $histfile = $CPAN::Config->{'histfile'}) {{
284 unless ($term->can("AddHistory")) {
285 $CPAN::Frontend->mywarn("Terminal does not support AddHistory.\n");
288 $META->readhist($term,$histfile);
290 for ($CPAN::Config->{term_ornaments}) { # alias
291 local $Term::ReadLine::termcap_nowarn = 1;
292 $term->ornaments($_) if defined;
294 # $term->OUT is autoflushed anyway
295 my $odef = select STDERR;
303 my @cwd = grep { defined $_ and length $_ }
305 File::Spec->can("tmpdir") ? File::Spec->tmpdir() : (),
306 File::Spec->rootdir();
307 my $try_detect_readline;
308 $try_detect_readline = $term->ReadLine eq "Term::ReadLine::Stub" if $term;
309 unless ($CPAN::Config->{inhibit_startup_message}) {
310 my $rl_avail = $Suppress_readline ? "suppressed" :
311 ($term->ReadLine ne "Term::ReadLine::Stub") ? "enabled" :
312 "available (maybe install Bundle::CPAN or Bundle::CPANxxl?)";
313 $CPAN::Frontend->myprint(
315 cpan shell -- CPAN exploration and modules installation (v%s)
323 my($continuation) = "";
324 my $last_term_ornaments;
325 SHELLCOMMAND: while () {
326 if ($Suppress_readline) {
327 if ($Echo_readline) {
331 last SHELLCOMMAND unless defined ($_ = <> );
332 if ($Echo_readline) {
333 # backdoor: I could not find a way to record sessions
338 last SHELLCOMMAND unless
339 defined ($_ = $term->readline($prompt, $commandline));
341 $_ = "$continuation$_" if $continuation;
343 next SHELLCOMMAND if /^$/;
345 if (/^(?:q(?:uit)?|bye|exit)$/i) {
356 use vars qw($import_done);
357 CPAN->import(':DEFAULT') unless $import_done++;
358 CPAN->debug("eval[$eval]") if $CPAN::DEBUG;
365 eval { @line = Text::ParseWords::shellwords($_) };
366 warn($@), next SHELLCOMMAND if $@;
367 warn("Text::Parsewords could not parse the line [$_]"),
368 next SHELLCOMMAND unless @line;
369 $CPAN::META->debug("line[".join("|",@line)."]") if $CPAN::DEBUG;
370 my $command = shift @line;
372 local (*STDOUT)=*STDOUT;
373 @line = _redirect(@line);
374 CPAN::Shell->$command(@line)
382 my $dv = Dumpvalue->new(tick => '"');
383 Carp::cluck(sprintf "Catching error: %s", $dv->stringify($err));
393 # pragmas for classic commands
402 # only commands that tell us something about failed distros
403 CPAN::Shell->failed($CPAN::CurrentCommandId,1);
405 soft_chdir_with_alternatives(\@cwd);
406 $CPAN::Frontend->myprint("\n");
408 $CPAN::CurrentCommandId++;
412 $commandline = ""; # I do want to be able to pass a default to
413 # shell, but on the second command I see no
416 CPAN::Queue->nullify_queue;
417 if ($try_detect_readline) {
418 if ($CPAN::META->has_inst("Term::ReadLine::Gnu")
420 $CPAN::META->has_inst("Term::ReadLine::Perl")
422 delete $INC{"Term/ReadLine.pm"};
424 local($SIG{__WARN__}) = CPAN::Shell::paintdots_onreload(\$redef);
425 require Term::ReadLine;
426 $CPAN::Frontend->myprint("\n$redef subroutines in ".
427 "Term::ReadLine redefined\n");
431 if ($term and $term->can("ornaments")) {
432 for ($CPAN::Config->{term_ornaments}) { # alias
434 if (not defined $last_term_ornaments
435 or $_ != $last_term_ornaments
437 local $Term::ReadLine::termcap_nowarn = 1;
438 $term->ornaments($_);
439 $last_term_ornaments = $_;
442 undef $last_term_ornaments;
446 for my $class (qw(Module Distribution)) {
447 # again unsafe meta access?
448 for my $dm (keys %{$CPAN::META->{readwrite}{"CPAN::$class"}}) {
449 next unless $CPAN::META->{readwrite}{"CPAN::$class"}{$dm}{incommandcolor};
450 CPAN->debug("BUG: $class '$dm' was in command state, resetting");
451 delete $CPAN::META->{readwrite}{"CPAN::$class"}{$dm}{incommandcolor};
455 $GOTOSHELL = 0; # not too often
456 $META->savehist if $CPAN::term && $CPAN::term->can("GetHistory");
461 soft_chdir_with_alternatives(\@cwd);
464 #-> CPAN::soft_chdir_with_alternatives ;
465 sub soft_chdir_with_alternatives ($) {
468 my $root = File::Spec->rootdir();
469 $CPAN::Frontend->mywarn(qq{Warning: no good directory to chdir to!
470 Trying '$root' as temporary haven.
475 if (chdir $cwd->[0]) {
479 $CPAN::Frontend->mywarn(qq{Could not chdir to "$cwd->[0]": $!
480 Trying to chdir to "$cwd->[1]" instead.
484 $CPAN::Frontend->mydie(qq{Could not chdir to "$cwd->[0]": $!});
492 if ( $Config::Config{d_flock} || $Config::Config{d_fcntl_can_lock} ) {
493 return flock $fh, $mode;
494 } elsif (!$Have_warned->{"d_flock"}++) {
495 $CPAN::Frontend->mywarn("Your OS does not seem to support locking; continuing and ignoring all locking issues\n");
496 $CPAN::Frontend->mysleep(5);
503 sub _yaml_module () {
504 my $yaml_module = $CPAN::Config->{yaml_module} || "YAML";
506 $yaml_module ne "YAML"
508 !$CPAN::META->has_inst($yaml_module)
510 # $CPAN::Frontend->mywarn("'$yaml_module' not installed, falling back to 'YAML'\n");
511 $yaml_module = "YAML";
513 if ($yaml_module eq "YAML"
515 $CPAN::META->has_inst($yaml_module)
517 $YAML::VERSION < 0.60
519 !$Have_warned->{"YAML"}++
521 $CPAN::Frontend->mywarn("Warning: YAML version '$YAML::VERSION' is too low, please upgrade!\n".
522 "I'll continue but problems are *very* likely to happen.\n"
524 $CPAN::Frontend->mysleep(5);
529 # CPAN::_yaml_loadfile
531 my($self,$local_file) = @_;
532 return +[] unless -s $local_file;
533 my $yaml_module = _yaml_module;
534 if ($CPAN::META->has_inst($yaml_module)) {
535 # temporarly enable yaml code deserialisation
537 # 5.6.2 could not do the local() with the reference
538 # so we do it manually instead
539 my $old_loadcode = ${"$yaml_module\::LoadCode"};
540 ${ "$yaml_module\::LoadCode" } = $CPAN::Config->{yaml_load_code} || 0;
543 if ($code = UNIVERSAL::can($yaml_module, "LoadFile")) {
544 eval { @yaml = $code->($local_file); };
546 # this shall not be done by the frontend
547 die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
549 } elsif ($code = UNIVERSAL::can($yaml_module, "Load")) {
551 open FH, $local_file or die "Could not open '$local_file': $!";
554 eval { @yaml = $code->($ystream); };
556 # this shall not be done by the frontend
557 die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
560 ${"$yaml_module\::LoadCode"} = $old_loadcode;
563 # this shall not be done by the frontend
564 die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "parse");
569 # CPAN::_yaml_dumpfile
571 my($self,$local_file,@what) = @_;
572 my $yaml_module = _yaml_module;
573 if ($CPAN::META->has_inst($yaml_module)) {
575 if (UNIVERSAL::isa($local_file, "FileHandle")) {
576 $code = UNIVERSAL::can($yaml_module, "Dump");
577 eval { print $local_file $code->(@what) };
578 } elsif ($code = UNIVERSAL::can($yaml_module, "DumpFile")) {
579 eval { $code->($local_file,@what); };
580 } elsif ($code = UNIVERSAL::can($yaml_module, "Dump")) {
582 open FH, ">$local_file" or die "Could not open '$local_file': $!";
583 print FH $code->(@what);
586 die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"dump",$@);
589 if (UNIVERSAL::isa($local_file, "FileHandle")) {
590 # I think this case does not justify a warning at all
592 die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "dump");
597 sub _init_sqlite () {
598 unless ($CPAN::META->has_inst("CPAN::SQLite")) {
599 $CPAN::Frontend->mywarn(qq{CPAN::SQLite not installed, trying to work without\n})
600 unless $Have_warned->{"CPAN::SQLite"}++;
603 require CPAN::SQLite::META; # not needed since CVS version of 2006-12-17
604 $CPAN::SQLite ||= CPAN::SQLite::META->new($CPAN::META);
608 my $negative_cache = {};
609 sub _sqlite_running {
610 if ($negative_cache->{time} && time < $negative_cache->{time} + 60) {
611 # need to cache the result, otherwise too slow
612 return $negative_cache->{fact};
614 $negative_cache = {}; # reset
616 my $ret = $CPAN::Config->{use_sqlite} && ($CPAN::SQLite || _init_sqlite());
617 return $ret if $ret; # fast anyway
618 $negative_cache->{time} = time;
619 return $negative_cache->{fact} = $ret;
623 $META ||= CPAN->new; # In case we re-eval ourselves we need the ||
625 # from here on only subs.
626 ################################################################################
628 sub _perl_fingerprint {
629 my($self,$other_fingerprint) = @_;
630 my $dll = eval {OS2::DLLname()};
633 $mtime_dll = (-f $dll ? (stat(_))[9] : '-1');
635 my $mtime_perl = (-f CPAN::find_perl ? (stat(_))[9] : '-1');
636 my $this_fingerprint = {
637 '$^X' => CPAN::find_perl,
638 sitearchexp => $Config::Config{sitearchexp},
639 'mtime_$^X' => $mtime_perl,
640 'mtime_dll' => $mtime_dll,
642 if ($other_fingerprint) {
643 if (exists $other_fingerprint->{'stat($^X)'}) { # repair fp from rev. 1.88_57
644 $other_fingerprint->{'mtime_$^X'} = $other_fingerprint->{'stat($^X)'}[9];
646 # mandatory keys since 1.88_57
647 for my $key (qw($^X sitearchexp mtime_dll mtime_$^X)) {
648 return unless $other_fingerprint->{$key} eq $this_fingerprint->{$key};
652 return $this_fingerprint;
656 sub suggest_myconfig () {
657 SUGGEST_MYCONFIG: if(!$INC{'CPAN/MyConfig.pm'}) {
658 $CPAN::Frontend->myprint("You don't seem to have a user ".
659 "configuration (MyConfig.pm) yet.\n");
660 my $new = CPAN::Shell::colorable_makemaker_prompt("Do you want to create a ".
661 "user configuration now? (Y/n)",
664 CPAN::Shell->mkmyconfig();
667 $CPAN::Frontend->mydie("OK, giving up.");
672 #-> sub CPAN::all_objects ;
674 my($mgr,$class) = @_;
675 CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
676 CPAN->debug("mgr[$mgr] class[$class]") if $CPAN::DEBUG;
678 values %{ $META->{readwrite}{$class} }; # unsafe meta access, ok
681 # Called by shell, not in batch mode. In batch mode I see no risk in
682 # having many processes updating something as installations are
683 # continually checked at runtime. In shell mode I suspect it is
684 # unintentional to open more than one shell at a time
686 #-> sub CPAN::checklock ;
689 my $lockfile = File::Spec->catfile($CPAN::Config->{cpan_home},".lock");
690 if (-f $lockfile && -M _ > 0) {
691 my $fh = FileHandle->new($lockfile) or
692 $CPAN::Frontend->mydie("Could not open lockfile '$lockfile': $!");
693 my $otherpid = <$fh>;
694 my $otherhost = <$fh>;
696 if (defined $otherpid && $otherpid) {
699 if (defined $otherhost && $otherhost) {
702 my $thishost = hostname();
703 if (defined $otherhost && defined $thishost &&
704 $otherhost ne '' && $thishost ne '' &&
705 $otherhost ne $thishost) {
706 $CPAN::Frontend->mydie(sprintf("CPAN.pm panic: Lockfile '$lockfile'\n".
707 "reports other host $otherhost and other ".
708 "process $otherpid.\n".
709 "Cannot proceed.\n"));
710 } elsif ($RUN_DEGRADED) {
711 $CPAN::Frontend->mywarn("Running in downgraded mode (experimental)\n");
712 } elsif (defined $otherpid && $otherpid) {
713 return if $$ == $otherpid; # should never happen
714 $CPAN::Frontend->mywarn(
716 There seems to be running another CPAN process (pid $otherpid). Contacting...
718 if (kill 0, $otherpid or $!{EPERM}) {
719 $CPAN::Frontend->mywarn(qq{Other job is running.\n});
721 CPAN::Shell::colorable_makemaker_prompt
722 (qq{Shall I try to run in downgraded }.
723 qq{mode? (Y/n)},"y");
725 $CPAN::Frontend->mywarn("Running in downgraded mode (experimental).
726 Please report if something unexpected happens\n");
728 for ($CPAN::Config) {
730 # $_->{build_dir_reuse} = 0; # 2006-11-17 akoenig Why was that?
731 $_->{commandnumber_in_prompt} = 0; # visibility
732 $_->{histfile} = ""; # who should win otherwise?
733 $_->{cache_metadata} = 0; # better would be a lock?
734 $_->{use_sqlite} = 0; # better would be a write lock!
735 $_->{auto_commit} = 0; # we are violent, do not persist
736 $_->{test_report} = 0; # Oliver Paukstadt had sent wrong reports in degraded mode
739 $CPAN::Frontend->mydie("
740 You may want to kill the other job and delete the lockfile. On UNIX try:
745 } elsif (-w $lockfile) {
747 CPAN::Shell::colorable_makemaker_prompt
748 (qq{Other job not responding. Shall I overwrite }.
749 qq{the lockfile '$lockfile'? (Y/n)},"y");
750 $CPAN::Frontend->myexit("Ok, bye\n")
751 unless $ans =~ /^y/i;
754 qq{Lockfile '$lockfile' not writable by you. }.
755 qq{Cannot proceed.\n}.
757 qq{ rm '$lockfile'\n}.
758 qq{ and then rerun us.\n}
762 $CPAN::Frontend->mydie(sprintf("CPAN.pm panic: Found invalid lockfile ".
763 "'$lockfile', please remove. Cannot proceed.\n"));
766 my $dotcpan = $CPAN::Config->{cpan_home};
767 eval { File::Path::mkpath($dotcpan);};
769 # A special case at least for Jarkko.
774 $symlinkcpan = readlink $dotcpan;
775 die "readlink $dotcpan failed: $!" unless defined $symlinkcpan;
776 eval { File::Path::mkpath($symlinkcpan); };
780 $CPAN::Frontend->mywarn(qq{
781 Working directory $symlinkcpan created.
785 unless (-d $dotcpan) {
787 Your configuration suggests "$dotcpan" as your
788 CPAN.pm working directory. I could not create this directory due
789 to this error: $firsterror\n};
791 As "$dotcpan" is a symlink to "$symlinkcpan",
792 I tried to create that, but I failed with this error: $seconderror
795 Please make sure the directory exists and is writable.
797 $CPAN::Frontend->mywarn($mess);
798 return suggest_myconfig;
800 } # $@ after eval mkpath $dotcpan
801 if (0) { # to test what happens when a race condition occurs
802 for (reverse 1..10) {
808 if (!$RUN_DEGRADED && !$self->{LOCKFH}) {
810 unless ($fh = FileHandle->new("+>>$lockfile")) {
811 if ($! =~ /Permission/) {
812 $CPAN::Frontend->mywarn(qq{
814 Your configuration suggests that CPAN.pm should use a working
816 $CPAN::Config->{cpan_home}
817 Unfortunately we could not create the lock file
819 due to permission problems.
821 Please make sure that the configuration variable
822 \$CPAN::Config->{cpan_home}
823 points to a directory where you can write a .lock file. You can set
824 this variable in either a CPAN/MyConfig.pm or a CPAN/Config.pm in your
827 return suggest_myconfig;
831 while (!CPAN::_flock($fh, LOCK_EX|LOCK_NB)) {
833 $CPAN::Frontend->mydie("Giving up\n");
835 $CPAN::Frontend->mysleep($sleep++);
836 $CPAN::Frontend->mywarn("Could not lock lockfile with flock: $!; retrying\n");
842 $fh->print($$, "\n");
843 $fh->print(hostname(), "\n");
844 $self->{LOCK} = $lockfile;
845 $self->{LOCKFH} = $fh;
850 $CPAN::Frontend->mydie("Got SIG$sig, leaving");
856 die "Got yet another signal" if $Signal > 1;
857 $CPAN::Frontend->mydie("Got another SIG$sig") if $Signal;
858 $CPAN::Frontend->mywarn("Caught SIG$sig, trying to continue\n");
862 # From: Larry Wall <larry@wall.org>
863 # Subject: Re: deprecating SIGDIE
864 # To: perl5-porters@perl.org
865 # Date: Thu, 30 Sep 1999 14:58:40 -0700 (PDT)
867 # The original intent of __DIE__ was only to allow you to substitute one
868 # kind of death for another on an application-wide basis without respect
869 # to whether you were in an eval or not. As a global backstop, it should
870 # not be used any more lightly (or any more heavily :-) than class
871 # UNIVERSAL. Any attempt to build a general exception model on it should
872 # be politely squashed. Any bug that causes every eval {} to have to be
873 # modified should be not so politely squashed.
875 # Those are my current opinions. It is also my optinion that polite
876 # arguments degenerate to personal arguments far too frequently, and that
877 # when they do, it's because both people wanted it to, or at least didn't
878 # sufficiently want it not to.
882 # global backstop to cleanup if we should really die
883 $SIG{__DIE__} = \&cleanup;
884 $self->debug("Signal handler set.") if $CPAN::DEBUG;
887 #-> sub CPAN::DESTROY ;
889 &cleanup; # need an eval?
892 #-> sub CPAN::anycwd ;
895 $getcwd = $CPAN::Config->{'getcwd'} || 'cwd';
900 sub cwd {Cwd::cwd();}
902 #-> sub CPAN::getcwd ;
903 sub getcwd {Cwd::getcwd();}
905 #-> sub CPAN::fastcwd ;
906 sub fastcwd {Cwd::fastcwd();}
908 #-> sub CPAN::backtickcwd ;
909 sub backtickcwd {my $cwd = `cwd`; chomp $cwd; $cwd}
911 #-> sub CPAN::find_perl ;
913 my($perl) = File::Spec->file_name_is_absolute($^X) ? $^X : "";
915 my $candidate = File::Spec->catfile($CPAN::iCwd,$^X);
916 $^X = $perl = $candidate if MM->maybe_command($candidate);
919 my ($component,$perl_name);
920 DIST_PERLNAME: foreach $perl_name ($^X, 'perl', 'perl5', "perl$]") {
921 PATH_COMPONENT: foreach $component (File::Spec->path(),
922 $Config::Config{'binexp'}) {
923 next unless defined($component) && $component;
924 my($abs) = File::Spec->catfile($component,$perl_name);
925 if (MM->maybe_command($abs)) {
936 #-> sub CPAN::exists ;
938 my($mgr,$class,$id) = @_;
939 CPAN::HandleConfig->load unless $CPAN::Config_loaded++;
941 ### Carp::croak "exists called without class argument" unless $class;
943 $id =~ s/:+/::/g if $class eq "CPAN::Module";
945 if (CPAN::_sqlite_running) {
946 $exists = (exists $META->{readonly}{$class}{$id} or
947 $CPAN::SQLite->set($class, $id));
949 $exists = exists $META->{readonly}{$class}{$id};
951 $exists ||= exists $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
954 #-> sub CPAN::delete ;
956 my($mgr,$class,$id) = @_;
957 delete $META->{readonly}{$class}{$id}; # unsafe meta access, ok
958 delete $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
961 #-> sub CPAN::has_usable
962 # has_inst is sometimes too optimistic, we should replace it with this
963 # has_usable whenever a case is given
965 my($self,$mod,$message) = @_;
966 return 1 if $HAS_USABLE->{$mod};
967 my $has_inst = $self->has_inst($mod,$message);
968 return unless $has_inst;
971 LWP => [ # we frequently had "Can't locate object
972 # method "new" via package "LWP::UserAgent" at
973 # (eval 69) line 2006
975 sub {require LWP::UserAgent},
976 sub {require HTTP::Request},
977 sub {require URI::URL},
980 sub {require Net::FTP},
981 sub {require Net::Config},
984 sub {require File::HomeDir;
985 unless (CPAN::Version->vge(File::HomeDir::->VERSION, 0.52)) {
986 for ("Will not use File::HomeDir, need 0.52\n") {
987 $CPAN::Frontend->mywarn($_);
994 sub {require Archive::Tar;
995 unless (CPAN::Version->vge(Archive::Tar::->VERSION, 1.00)) {
996 for ("Will not use Archive::Tar, need 1.00\n") {
997 $CPAN::Frontend->mywarn($_);
1004 # XXX we should probably delete from
1005 # %INC too so we can load after we
1006 # installed a new enough version --
1008 sub {require File::Temp;
1009 unless (CPAN::Version->vge(File::Temp::->VERSION,0.16)) {
1010 for ("Will not use File::Temp, need 0.16\n") {
1011 $CPAN::Frontend->mywarn($_);
1018 if ($usable->{$mod}) {
1019 for my $c (0..$#{$usable->{$mod}}) {
1020 my $code = $usable->{$mod}[$c];
1021 my $ret = eval { &$code() };
1022 $ret = "" unless defined $ret;
1024 # warn "DEBUG: c[$c]\$\@[$@]ret[$ret]";
1029 return $HAS_USABLE->{$mod} = 1;
1032 #-> sub CPAN::has_inst
1034 my($self,$mod,$message) = @_;
1035 Carp::croak("CPAN->has_inst() called without an argument")
1036 unless defined $mod;
1037 my %dont = map { $_ => 1 } keys %{$CPAN::META->{dontload_hash}||{}},
1038 keys %{$CPAN::Config->{dontload_hash}||{}},
1039 @{$CPAN::Config->{dontload_list}||[]};
1040 if (defined $message && $message eq "no" # afair only used by Nox
1044 $CPAN::META->{dontload_hash}{$mod}||=1; # unsafe meta access, ok
1052 # checking %INC is wrong, because $INC{LWP} may be true
1053 # although $INC{"URI/URL.pm"} may have failed. But as
1054 # I really want to say "bla loaded OK", I have to somehow
1056 ### warn "$file in %INC"; #debug
1058 } elsif (eval { require $file }) {
1059 # eval is good: if we haven't yet read the database it's
1060 # perfect and if we have installed the module in the meantime,
1061 # it tries again. The second require is only a NOOP returning
1062 # 1 if we had success, otherwise it's retrying
1064 my $mtime = (stat $INC{$file})[9];
1065 # privileged files loaded by has_inst; Note: we use $mtime
1066 # as a proxy for a checksum.
1067 $CPAN::Shell::reload->{$file} = $mtime;
1068 my $v = eval "\$$mod\::VERSION";
1069 $v = $v ? " (v$v)" : "";
1070 CPAN::Shell->optprint("load_module","CPAN: $mod loaded ok$v\n");
1071 if ($mod eq "CPAN::WAIT") {
1072 push @CPAN::Shell::ISA, 'CPAN::WAIT';
1075 } elsif ($mod eq "Net::FTP") {
1076 $CPAN::Frontend->mywarn(qq{
1077 Please, install Net::FTP as soon as possible. CPAN.pm installs it for you
1079 install Bundle::libnet
1081 }) unless $Have_warned->{"Net::FTP"}++;
1082 $CPAN::Frontend->mysleep(3);
1083 } elsif ($mod eq "Digest::SHA") {
1084 if ($Have_warned->{"Digest::SHA"}++) {
1085 $CPAN::Frontend->mywarn(qq{CPAN: checksum security checks disabled }.
1086 qq{because Digest::SHA not installed.\n});
1088 $CPAN::Frontend->mywarn(qq{
1089 CPAN: checksum security checks disabled because Digest::SHA not installed.
1090 Please consider installing the Digest::SHA module.
1093 $CPAN::Frontend->mysleep(2);
1095 } elsif ($mod eq "Module::Signature") {
1096 # NOT prefs_lookup, we are not a distro
1097 my $check_sigs = $CPAN::Config->{check_sigs};
1098 if (not $check_sigs) {
1099 # they do not want us:-(
1100 } elsif (not $Have_warned->{"Module::Signature"}++) {
1101 # No point in complaining unless the user can
1102 # reasonably install and use it.
1103 if (eval { require Crypt::OpenPGP; 1 } ||
1105 defined $CPAN::Config->{'gpg'}
1107 $CPAN::Config->{'gpg'} =~ /\S/
1110 $CPAN::Frontend->mywarn(qq{
1111 CPAN: Module::Signature security checks disabled because Module::Signature
1112 not installed. Please consider installing the Module::Signature module.
1113 You may also need to be able to connect over the Internet to the public
1114 keyservers like pgp.mit.edu (port 11371).
1117 $CPAN::Frontend->mysleep(2);
1121 delete $INC{$file}; # if it inc'd LWP but failed during, say, URI
1126 #-> sub CPAN::instance ;
1128 my($mgr,$class,$id) = @_;
1129 CPAN::Index->reload;
1131 # unsafe meta access, ok?
1132 return $META->{readwrite}{$class}{$id} if exists $META->{readwrite}{$class}{$id};
1133 $META->{readwrite}{$class}{$id} ||= $class->new(ID => $id);
1141 #-> sub CPAN::cleanup ;
1143 # warn "cleanup called with arg[@_] End[$CPAN::End] Signal[$Signal]";
1144 local $SIG{__DIE__} = '';
1149 while ((undef,undef,undef,$subroutine) = caller(++$i)) {
1150 $ineval = 1, last if
1151 $subroutine eq '(eval)';
1153 return if $ineval && !$CPAN::End;
1154 return unless defined $META->{LOCK};
1155 return unless -f $META->{LOCK};
1157 close $META->{LOCKFH};
1158 unlink $META->{LOCK};
1160 # Carp::cluck("DEBUGGING");
1161 if ( $CPAN::CONFIG_DIRTY ) {
1162 $CPAN::Frontend->mywarn("Warning: Configuration not saved.\n");
1164 $CPAN::Frontend->myprint("Lockfile removed.\n");
1167 #-> sub CPAN::readhist
1169 my($self,$term,$histfile) = @_;
1170 my $histsize = $CPAN::Config->{'histsize'} || 100;
1171 $term->Attribs->{'MaxHistorySize'} = $histsize if (defined($term->Attribs->{'MaxHistorySize'}));
1172 my($fh) = FileHandle->new;
1173 open $fh, "<$histfile" or return;
1177 $term->AddHistory($_);
1182 #-> sub CPAN::savehist
1185 my($histfile,$histsize);
1186 unless ($histfile = $CPAN::Config->{'histfile'}) {
1187 $CPAN::Frontend->mywarn("No history written (no histfile specified).\n");
1190 $histsize = $CPAN::Config->{'histsize'} || 100;
1192 unless ($CPAN::term->can("GetHistory")) {
1193 $CPAN::Frontend->mywarn("Terminal does not support GetHistory.\n");
1199 my @h = $CPAN::term->GetHistory;
1200 splice @h, 0, @h-$histsize if @h>$histsize;
1201 my($fh) = FileHandle->new;
1202 open $fh, ">$histfile" or $CPAN::Frontend->mydie("Couldn't open >$histfile: $!");
1203 local $\ = local $, = "\n";
1208 #-> sub CPAN::is_tested
1210 my($self,$what,$when) = @_;
1212 Carp::cluck("DEBUG: empty what");
1215 $self->{is_tested}{$what} = $when;
1218 #-> sub CPAN::reset_tested
1219 # forget all distributions tested -- resets what gets included in PERL5LIB
1222 $self->{is_tested} = {};
1225 #-> sub CPAN::is_installed
1226 # unsets the is_tested flag: as soon as the thing is installed, it is
1227 # not needed in set_perl5lib anymore
1229 my($self,$what) = @_;
1230 delete $self->{is_tested}{$what};
1233 sub _list_sorted_descending_is_tested {
1236 { ($self->{is_tested}{$b}||0) <=> ($self->{is_tested}{$a}||0) }
1237 keys %{$self->{is_tested}}
1240 #-> sub CPAN::set_perl5lib
1241 # Notes on max environment variable length:
1242 # - Win32 : XP or later, 8191; Win2000 or NT4, 2047
1246 my($self,$for) = @_;
1248 (undef,undef,undef,$for) = caller(1);
1251 $self->{is_tested} ||= {};
1252 return unless %{$self->{is_tested}};
1253 my $env = $ENV{PERL5LIB};
1254 $env = $ENV{PERLLIB} unless defined $env;
1256 push @env, split /\Q$Config::Config{path_sep}\E/, $env if defined $env and length $env;
1257 #my @dirs = map {("$_/blib/arch", "$_/blib/lib")} keys %{$self->{is_tested}};
1258 #$CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB.\n");
1260 my @dirs = map {("$_/blib/arch", "$_/blib/lib")} $self->_list_sorted_descending_is_tested;
1264 $CPAN::Frontend->optprint('perl5lib', "Prepending @dirs to PERL5LIB for '$for'\n");
1265 $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1266 } elsif (@dirs < 24 ) {
1267 my @d = map {my $cp = $_;
1268 $cp =~ s/^\Q$CPAN::Config->{build_dir}\E/%BUILDDIR%/;
1271 $CPAN::Frontend->optprint('perl5lib', "Prepending @d to PERL5LIB; ".
1272 "%BUILDDIR%=$CPAN::Config->{build_dir} ".
1275 $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1277 my $cnt = keys %{$self->{is_tested}};
1278 $CPAN::Frontend->optprint('perl5lib', "Prepending blib/arch and blib/lib of ".
1279 "$cnt build dirs to PERL5LIB; ".
1282 $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env;
1294 CPAN - query, download and build perl modules from CPAN sites
1300 perl -MCPAN -e shell
1310 cpan> install Acme::Meta # in the shell
1312 CPAN::Shell->install("Acme::Meta"); # in perl
1316 cpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell
1319 install("NWCLARK/Acme-Meta-0.02.tar.gz"); # in perl
1323 $mo = CPAN::Shell->expandany($mod);
1324 $mo = CPAN::Shell->expand("Module",$mod); # same thing
1326 # distribution objects:
1328 $do = CPAN::Shell->expand("Module",$mod)->distribution;
1329 $do = CPAN::Shell->expandany($distro); # same thing
1330 $do = CPAN::Shell->expand("Distribution",
1331 $distro); # same thing
1335 The CPAN module automates or at least simplifies the make and install
1336 of perl modules and extensions. It includes some primitive searching
1337 capabilities and knows how to use Net::FTP, LWP, and certain external
1338 download clients to fetch distributions from the net.
1340 These are fetched from one or more mirrored CPAN (Comprehensive
1341 Perl Archive Network) sites and unpacked in a dedicated directory.
1343 The CPAN module also supports named and versioned
1344 I<bundles> of modules. Bundles simplify handling of sets of
1345 related modules. See Bundles below.
1347 The package contains a session manager and a cache manager. The
1348 session manager keeps track of what has been fetched, built, and
1349 installed in the current session. The cache manager keeps track of the
1350 disk space occupied by the make processes and deletes excess space
1351 using a simple FIFO mechanism.
1353 All methods provided are accessible in a programmer style and in an
1354 interactive shell style.
1356 =head2 CPAN::shell([$prompt, $command]) Starting Interactive Mode
1358 Enter interactive mode by running
1360 perl -MCPAN -e shell
1366 which puts you into a readline interface. If C<Term::ReadKey> and
1367 either of C<Term::ReadLine::Perl> or C<Term::ReadLine::Gnu> are installed,
1368 history and command completion are supported.
1370 Once at the command line, type C<h> for one-page help
1371 screen; the rest should be self-explanatory.
1373 The function call C<shell> takes two optional arguments: one the
1374 prompt, the second the default initial command line (the latter
1375 only works if a real ReadLine interface module is installed).
1377 The most common uses of the interactive modes are
1381 =item Searching for authors, bundles, distribution files and modules
1383 There are corresponding one-letter commands C<a>, C<b>, C<d>, and C<m>
1384 for each of the four categories and another, C<i> for any of the
1385 mentioned four. Each of the four entities is implemented as a class
1386 with slightly differing methods for displaying an object.
1388 Arguments to these commands are either strings exactly matching
1389 the identification string of an object, or regular expressions
1390 matched case-insensitively against various attributes of the
1391 objects. The parser only recognizes a regular expression when you
1392 enclose it with slashes.
1394 The principle is that the number of objects found influences how an
1395 item is displayed. If the search finds one item, the result is
1396 displayed with the rather verbose method C<as_string>, but if
1397 more than one is found, each object is displayed with the terse method
1402 cpan> m Acme::MetaSyntactic
1403 Module id = Acme::MetaSyntactic
1404 CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
1406 CPAN_FILE B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
1407 UPLOAD_DATE 2006-11-06
1408 MANPAGE Acme::MetaSyntactic - Themed metasyntactic variables names
1409 INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
1414 FULLNAME Philippe Bruhat (BooK)
1415 cpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz
1416 Distribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
1417 CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
1418 CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
1419 UPLOAD_DATE 2006-11-06
1421 Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz)
1422 Module Text::Lorem (ADEOLA/Text-Lorem-0.3.tar.gz)
1423 Module Text::Lorem::More (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
1424 Module Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
1426 Distribution BEATNIK/Filter-NumberLines-0.02.tar.gz
1427 Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz)
1428 Module Filter::NumberLines (BEATNIK/Filter-NumberLines-0.02.tar.gz)
1431 The examples illustrate several aspects: the first three queries
1432 target modules, authors, or distros directly and yield exactly one
1433 result. The last two use regular expressions and yield several
1434 results. The last one targets all of bundles, modules, authors, and
1435 distros simultaneously. When more than one result is available, they
1436 are printed in one-line format.
1438 =item C<get>, C<make>, C<test>, C<install>, C<clean> modules or distributions
1440 These commands take any number of arguments and investigate what is
1441 necessary to perform the action. If the argument is a distribution
1442 file name (recognized by embedded slashes), it is processed. If it is
1443 a module, CPAN determines the distribution file in which this module
1444 is included and processes that, following any dependencies named in
1445 the module's META.yml or Makefile.PL (this behavior is controlled by
1446 the configuration parameter C<prerequisites_policy>.)
1448 C<get> downloads a distribution file and untars or unzips it, C<make>
1449 builds it, C<test> runs the test suite, and C<install> installs it.
1451 Any C<make> or C<test> is run unconditionally. An
1453 install <distribution_file>
1455 is also run unconditionally. But for
1459 CPAN checks whether an install is needed and prints
1460 I<module up to date> if the distribution file containing
1461 the module doesn't need updating.
1463 CPAN also keeps track of what it has done within the current session
1464 and doesn't try to build a package a second time regardless of whether it
1465 succeeded or not. It does not repeat a test run if the test
1466 has been run successfully before. Same for install runs.
1468 The C<force> pragma may precede another command (currently: C<get>,
1469 C<make>, C<test>, or C<install>) to execute the command from scratch
1470 and attempt to continue past certain errors. See the section below on
1471 the C<force> and the C<fforce> pragma.
1473 The C<notest> pragma skips the test part in the build
1478 cpan> notest install Tk
1480 A C<clean> command results in a
1484 being executed within the distribution file's working directory.
1486 =item C<readme>, C<perldoc>, C<look> module or distribution
1488 C<readme> displays the README file of the associated distribution.
1489 C<Look> gets and untars (if not yet done) the distribution file,
1490 changes to the appropriate directory and opens a subshell process in
1491 that directory. C<perldoc> displays the module's pod documentation
1492 in html or plain text format.
1496 =item C<ls> globbing_expression
1498 The first form lists all distribution files in and below an author's
1499 CPAN directory as stored in the CHECKUMS files distributed on
1500 CPAN. The listing recurses into subdirectories.
1502 The second form limits or expands the output with shell
1503 globbing as in the following examples:
1509 The last example is very slow and outputs extra progress indicators
1510 that break the alignment of the result.
1512 Note that globbing only lists directories explicitly asked for, for
1513 example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be
1514 regarded as a bug that may be changed in some future version.
1518 The C<failed> command reports all distributions that failed on one of
1519 C<make>, C<test> or C<install> for some reason in the currently
1520 running shell session.
1522 =item Persistence between sessions
1524 If the C<YAML> or the C<YAML::Syck> module is installed a record of
1525 the internal state of all modules is written to disk after each step.
1526 The files contain a signature of the currently running perl version
1529 If the configurations variable C<build_dir_reuse> is set to a true
1530 value, then CPAN.pm reads the collected YAML files. If the stored
1531 signature matches the currently running perl, the stored state is
1532 loaded into memory such that persistence between sessions
1533 is effectively established.
1535 =item The C<force> and the C<fforce> pragma
1537 To speed things up in complex installation scenarios, CPAN.pm keeps
1538 track of what it has already done and refuses to do some things a
1539 second time. A C<get>, a C<make>, and an C<install> are not repeated.
1540 A C<test> is repeated only if the previous test was unsuccessful. The
1541 diagnostic message when CPAN.pm refuses to do something a second time
1542 is one of I<Has already been >C<unwrapped|made|tested successfully> or
1543 something similar. Another situation where CPAN refuses to act is an
1544 C<install> if the corresponding C<test> was not successful.
1546 In all these cases, the user can override this stubborn behaviour by
1547 prepending the command with the word force, for example:
1550 cpan> force make AUTHOR/Bar-3.14.tar.gz
1551 cpan> force test Baz
1552 cpan> force install Acme::Meta
1554 Each I<forced> command is executed with the corresponding part of its
1557 The C<fforce> pragma is a variant that emulates a C<force get> which
1558 erases the entire memory followed by the action specified, effectively
1559 restarting the whole get/make/test/install procedure from scratch.
1563 Interactive sessions maintain a lockfile, by default C<~/.cpan/.lock>.
1564 Batch jobs can run without a lockfile and not disturb each other.
1566 The shell offers to run in I<downgraded mode> when another process is
1567 holding the lockfile. This is an experimental feature that is not yet
1568 tested very well. This second shell then does not write the history
1569 file, does not use the metadata file, and has a different prompt.
1573 CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
1574 in the cpan-shell, it is intended that you can press C<^C> anytime and
1575 return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
1576 to clean up and leave the shell loop. You can emulate the effect of a
1577 SIGTERM by sending two consecutive SIGINTs, which usually means by
1578 pressing C<^C> twice.
1580 CPAN.pm ignores SIGPIPE. If the user sets C<inactivity_timeout>, a
1581 SIGALRM is used during the run of the C<perl Makefile.PL> or C<perl
1582 Build.PL> subprocess.
1588 The commands available in the shell interface are methods in
1589 the package CPAN::Shell. If you enter the shell command, your
1590 input is split by the Text::ParseWords::shellwords() routine, which
1591 acts like most shells do. The first word is interpreted as the
1592 method to be invoked, and the rest of the words are treated as the method's arguments.
1593 Continuation lines are supported by ending a line with a
1598 C<autobundle> writes a bundle file into the
1599 C<$CPAN::Config-E<gt>{cpan_home}/Bundle> directory. The file contains
1600 a list of all modules that are both available from CPAN and currently
1601 installed within @INC. The name of the bundle file is based on the
1602 current date and a counter.
1606 Note: this feature is still in alpha state and may change in future
1609 This commands provides a statistical overview over recent download
1610 activities. The data for this is collected in the YAML file
1611 C<FTPstats.yml> in your C<cpan_home> directory. If no YAML module is
1612 configured or YAML not installed, no stats are provided.
1616 mkmyconfig() writes your own CPAN::MyConfig file into your C<~/.cpan/>
1617 directory so that you can save your own preferences instead of the
1620 =head2 recent ***EXPERIMENTAL COMMAND***
1622 The C<recent> command downloads a list of recent uploads to CPAN and
1623 displays them I<slowly>. While the command is running, a $SIG{INT}
1624 exits the loop after displaying the current item.
1626 B<Note>: This command requires XML::LibXML installed.
1628 B<Note>: This whole command currently is just a hack and will
1629 probably change in future versions of CPAN.pm, but the general
1630 approach will likely remain.
1632 B<Note>: See also L<smoke>
1636 recompile() is a special command that takes no argument and
1637 runs the make/test/install cycle with brute force over all installed
1638 dynamically loadable extensions (aka XS modules) with 'force' in
1639 effect. The primary purpose of this command is to finish a network
1640 installation. Imagine you have a common source tree for two different
1641 architectures. You decide to do a completely independent fresh
1642 installation. You start on one architecture with the help of a Bundle
1643 file produced earlier. CPAN installs the whole Bundle for you, but
1644 when you try to repeat the job on the second architecture, CPAN
1645 responds with a C<"Foo up to date"> message for all modules. So you
1646 invoke CPAN's recompile on the second architecture and you're done.
1648 Another popular use for C<recompile> is to act as a rescue in case your
1649 perl breaks binary compatibility. If one of the modules that CPAN uses
1650 is in turn depending on binary compatibility (so you cannot run CPAN
1651 commands), then you should try the CPAN::Nox module for recovery.
1653 =head2 report Bundle|Distribution|Module
1655 The C<report> command temporarily turns on the C<test_report> config
1656 variable, then runs the C<force test> command with the given
1657 arguments. The C<force> pragma reruns the tests and repeats
1658 every step that might have failed before.
1660 =head2 smoke ***EXPERIMENTAL COMMAND***
1662 B<*** WARNING: this command downloads and executes software from CPAN to
1663 your computer of completely unknown status. You should never do
1664 this with your normal account and better have a dedicated well
1665 separated and secured machine to do this. ***>
1667 The C<smoke> command takes the list of recent uploads to CPAN as
1668 provided by the C<recent> command and tests them all. While the
1669 command is running $SIG{INT} is defined to mean that the current item
1672 B<Note>: This whole command currently is just a hack and will
1673 probably change in future versions of CPAN.pm, but the general
1674 approach will likely remain.
1676 B<Note>: See also L<recent>
1678 =head2 upgrade [Module|/Regex/]...
1680 The C<upgrade> command first runs an C<r> command with the given
1681 arguments and then installs the newest versions of all modules that
1682 were listed by that.
1684 =head2 The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution
1686 Although it may be considered internal, the class hierarchy does matter
1687 for both users and programmer. CPAN.pm deals with the four
1688 classes mentioned above, and those classes all share a set of methods. Classical
1689 single polymorphism is in effect. A metaclass object registers all
1690 objects of all kinds and indexes them with a string. The strings
1691 referencing objects have a separated namespace (well, not completely
1696 words containing a "/" (slash) Distribution
1697 words starting with Bundle:: Bundle
1698 everything else Module or Author
1700 Modules know their associated Distribution objects. They always refer
1701 to the most recent official release. Developers may mark their releases
1702 as unstable development versions (by inserting an underbar into the
1703 module version number which will also be reflected in the distribution
1704 name when you run 'make dist'), so the really hottest and newest
1705 distribution is not always the default. If a module Foo circulates
1706 on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
1707 way to install version 1.23 by saying
1711 This would install the complete distribution file (say
1712 BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would
1713 like to install version 1.23_90, you need to know where the
1714 distribution file resides on CPAN relative to the authors/id/
1715 directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz;
1716 so you would have to say
1718 install BAR/Foo-1.23_90.tar.gz
1720 The first example will be driven by an object of the class
1721 CPAN::Module, the second by an object of class CPAN::Distribution.
1723 =head2 Integrating local directories
1725 Note: this feature is still in alpha state and may change in future
1728 Distribution objects are normally distributions from the CPAN, but
1729 there is a slightly degenerate case for Distribution objects, too, of
1730 projects held on the local disk. These distribution objects have the
1731 same name as the local directory and end with a dot. A dot by itself
1732 is also allowed for the current directory at the time CPAN.pm was
1733 used. All actions such as C<make>, C<test>, and C<install> are applied
1734 directly to that directory. This gives the command C<cpan .> an
1735 interesting touch: while the normal mantra of installing a CPAN module
1736 without CPAN.pm is one of
1738 perl Makefile.PL perl Build.PL
1739 ( go and get prerequisites )
1741 make test ./Build test
1742 make install ./Build install
1744 the command C<cpan .> does all of this at once. It figures out which
1745 of the two mantras is appropriate, fetches and installs all
1746 prerequisites, takes care of them recursively, and finally finishes the
1747 installation of the module in the current directory, be it a CPAN
1750 The typical usage case is for private modules or working copies of
1751 projects from remote repositories on the local disk.
1755 The usual shell redirection symbols C< | > and C<< > >> are recognized
1756 by the cpan shell B<only when surrounded by whitespace>. So piping to
1757 pager or redirecting output into a file works somewhat as in a normal
1758 shell, with the stipulation that you must type extra spaces.
1760 =head1 CONFIGURATION
1762 When the CPAN module is used for the first time, a configuration
1763 dialogue tries to determine a couple of site specific options. The
1764 result of the dialog is stored in a hash reference C< $CPAN::Config >
1765 in a file CPAN/Config.pm.
1767 Default values defined in the CPAN/Config.pm file can be
1768 overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
1769 best placed in C<$HOME/.cpan/CPAN/MyConfig.pm>, because C<$HOME/.cpan> is
1770 added to the search path of the CPAN module before the use() or
1771 require() statements. The mkmyconfig command writes this file for you.
1773 The C<o conf> command has various bells and whistles:
1777 =item completion support
1779 If you have a ReadLine module installed, you can hit TAB at any point
1780 of the commandline and C<o conf> will offer you completion for the
1781 built-in subcommands and/or config variable names.
1783 =item displaying some help: o conf help
1785 Displays a short help
1787 =item displaying current values: o conf [KEY]
1789 Displays the current value(s) for this config variable. Without KEY,
1790 displays all subcommands and config variables.
1796 If KEY starts and ends with a slash, the string in between is
1797 treated as a regular expression and only keys matching this regex
1804 =item changing of scalar values: o conf KEY VALUE
1806 Sets the config variable KEY to VALUE. The empty string can be
1807 specified as usual in shells, with C<''> or C<"">
1811 o conf wget /usr/bin/wget
1813 =item changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
1815 If a config variable name ends with C<list>, it is a list. C<o conf
1816 KEY shift> removes the first element of the list, C<o conf KEY pop>
1817 removes the last element of the list. C<o conf KEYS unshift LIST>
1818 prepends a list of values to the list, C<o conf KEYS push LIST>
1819 appends a list of valued to the list.
1821 Likewise, C<o conf KEY splice LIST> passes the LIST to the corresponding
1824 Finally, any other list of arguments is taken as a new list value for
1825 the KEY variable discarding the previous value.
1829 o conf urllist unshift http://cpan.dev.local/CPAN
1830 o conf urllist splice 3 1
1831 o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
1833 =item reverting to saved: o conf defaults
1835 Reverts all config variables to the state in the saved config file.
1837 =item saving the config: o conf commit
1839 Saves all config variables to the current config file (CPAN/Config.pm
1840 or CPAN/MyConfig.pm that was loaded at start).
1844 The configuration dialog can be started any time later again by
1845 issuing the command C< o conf init > in the CPAN shell. A subset of
1846 the configuration dialog can be run by issuing C<o conf init WORD>
1847 where WORD is any valid config variable or a regular expression.
1849 =head2 Config Variables
1851 The following keys in the hash reference $CPAN::Config are
1854 applypatch path to external prg
1855 auto_commit commit all changes to config variables to disk
1856 build_cache size of cache for directories to build modules
1857 build_dir locally accessible directory to build modules
1858 build_dir_reuse boolean if distros in build_dir are persistent
1859 build_requires_install_policy
1860 to install or not to install when a module is
1861 only needed for building. yes|no|ask/yes|ask/no
1862 bzip2 path to external prg
1863 cache_metadata use serializer to cache metadata
1864 check_sigs if signatures should be verified
1865 colorize_debug Term::ANSIColor attributes for debugging output
1866 colorize_output boolean if Term::ANSIColor should colorize output
1867 colorize_print Term::ANSIColor attributes for normal output
1868 colorize_warn Term::ANSIColor attributes for warnings
1869 commandnumber_in_prompt
1870 boolean if you want to see current command number
1871 commands_quote preferred character to use for quoting external
1872 commands when running them. Defaults to double
1873 quote on Windows, single tick everywhere else;
1874 can be set to space to disable quoting
1875 connect_to_internet_ok
1876 whether to ask if opening a connection is ok before
1877 urllist is specified
1878 cpan_home local directory reserved for this package
1879 curl path to external prg
1880 dontload_hash DEPRECATED
1881 dontload_list arrayref: modules in the list will not be
1882 loaded by the CPAN::has_inst() routine
1883 ftp path to external prg
1884 ftp_passive if set, the envariable FTP_PASSIVE is set for downloads
1885 ftp_proxy proxy host for ftp requests
1886 ftpstats_period max number of days to keep download statistics
1887 ftpstats_size max number of items to keep in the download statistics
1889 gpg path to external prg
1890 gzip location of external program gzip
1891 halt_on_failure stop processing after the first failure of queued
1892 items or dependencies
1893 histfile file to maintain history between sessions
1894 histsize maximum number of lines to keep in histfile
1895 http_proxy proxy host for http requests
1896 inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
1897 after this many seconds inactivity. Set to 0 to
1899 index_expire refetch index files after this many days
1900 inhibit_startup_message
1901 if true, suppress the startup message
1902 keep_source_where directory in which to keep the source (if we do)
1903 load_module_verbosity
1904 report loading of optional modules used by CPAN.pm
1905 lynx path to external prg
1906 make location of external make program
1907 make_arg arguments that should always be passed to 'make'
1908 make_install_make_command
1909 the make command for running 'make install', for
1911 make_install_arg same as make_arg for 'make install'
1912 makepl_arg arguments passed to 'perl Makefile.PL'
1913 mbuild_arg arguments passed to './Build'
1914 mbuild_install_arg arguments passed to './Build install'
1915 mbuild_install_build_command
1916 command to use instead of './Build' when we are
1917 in the install stage, for example 'sudo ./Build'
1918 mbuildpl_arg arguments passed to 'perl Build.PL'
1919 ncftp path to external prg
1920 ncftpget path to external prg
1921 no_proxy don't proxy to these hosts/domains (comma separated list)
1922 pager location of external program more (or any pager)
1923 password your password if you CPAN server wants one
1924 patch path to external prg
1925 patches_dir local directory containing patch files
1926 perl5lib_verbosity verbosity level for PERL5LIB additions
1927 prefer_installer legal values are MB and EUMM: if a module comes
1928 with both a Makefile.PL and a Build.PL, use the
1929 former (EUMM) or the latter (MB); if the module
1930 comes with only one of the two, that one will be
1931 used no matter the setting
1932 prerequisites_policy
1933 what to do if you are missing module prerequisites
1934 ('follow' automatically, 'ask' me, or 'ignore')
1935 prefs_dir local directory to store per-distro build options
1936 proxy_user username for accessing an authenticating proxy
1937 proxy_pass password for accessing an authenticating proxy
1938 randomize_urllist add some randomness to the sequence of the urllist
1939 scan_cache controls scanning of cache ('atstart' or 'never')
1940 shell your favorite shell
1941 show_unparsable_versions
1942 boolean if r command tells which modules are versionless
1943 show_upload_date boolean if commands should try to determine upload date
1944 show_zero_versions boolean if r command tells for which modules $version==0
1945 tar location of external program tar
1946 tar_verbosity verbosity level for the tar command
1947 term_is_latin deprecated: if true Unicode is translated to ISO-8859-1
1948 (and nonsense for characters outside latin range)
1949 term_ornaments boolean to turn ReadLine ornamenting on/off
1950 test_report email test reports (if CPAN::Reporter is installed)
1951 trust_test_report_history
1952 skip testing when previously tested ok (according to
1953 CPAN::Reporter history)
1954 unzip location of external program unzip
1955 urllist arrayref to nearby CPAN sites (or equivalent locations)
1956 use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
1957 username your username if you CPAN server wants one
1958 wait_list arrayref to a wait server to try (See CPAN::WAIT)
1959 wget path to external prg
1960 yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
1961 yaml_module which module to use to read/write YAML files
1963 You can set and query each of these options interactively in the cpan
1964 shell with the C<o conf> or the C<o conf init> command as specified below.
1968 =item C<o conf E<lt>scalar optionE<gt>>
1970 prints the current value of the I<scalar option>
1972 =item C<o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>>
1974 Sets the value of the I<scalar option> to I<value>
1976 =item C<o conf E<lt>list optionE<gt>>
1978 prints the current value of the I<list option> in MakeMaker's
1981 =item C<o conf E<lt>list optionE<gt> [shift|pop]>
1983 shifts or pops the array in the I<list option> variable
1985 =item C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>>
1987 works like the corresponding perl commands.
1989 =item interactive editing: o conf init [MATCH|LIST]
1991 Runs an interactive configuration dialog for matching variables.
1992 Without argument runs the dialog over all supported config variables.
1993 To specify a MATCH the argument must be enclosed by slashes.
1997 o conf init ftp_passive ftp_proxy
2000 Note: this method of setting config variables often provides more
2001 explanation about the functioning of a variable than the manpage.
2005 =head2 CPAN::anycwd($path): Note on config variable getcwd
2007 CPAN.pm changes the current working directory often and needs to
2008 determine its own current working directory. By default it uses
2009 Cwd::cwd, but if for some reason this doesn't work on your system,
2010 configure alternatives according to the following table:
2028 Calls the external command cwd.
2032 =head2 Note on the format of the urllist parameter
2034 urllist parameters are URLs according to RFC 1738. We do a little
2035 guessing if your URL is not compliant, but if you have problems with
2036 C<file> URLs, please try the correct format. Either:
2038 file://localhost/whatever/ftp/pub/CPAN/
2042 file:///home/ftp/pub/CPAN/
2044 =head2 The urllist parameter has CD-ROM support
2046 The C<urllist> parameter of the configuration table contains a list of
2047 URLs used for downloading. If the list contains any
2048 C<file> URLs, CPAN always tries there first. This
2049 feature is disabled for index files. So the recommendation for the
2050 owner of a CD-ROM with CPAN contents is: include your local, possibly
2051 outdated CD-ROM as a C<file> URL at the end of urllist, e.g.
2053 o conf urllist push file://localhost/CDROM/CPAN
2055 CPAN.pm will then fetch the index files from one of the CPAN sites
2056 that come at the beginning of urllist. It will later check for each
2057 module to see whether there is a local copy of the most recent version.
2059 Another peculiarity of urllist is that the site that we could
2060 successfully fetch the last file from automatically gets a preference
2061 token and is tried as the first site for the next request. So if you
2062 add a new site at runtime it may happen that the previously preferred
2063 site will be tried another time. This means that if you want to disallow
2064 a site for the next transfer, it must be explicitly removed from
2067 =head2 Maintaining the urllist parameter
2069 If you have YAML.pm (or some other YAML module configured in
2070 C<yaml_module>) installed, CPAN.pm collects a few statistical data
2071 about recent downloads. You can view the statistics with the C<hosts>
2072 command or inspect them directly by looking into the C<FTPstats.yml>
2073 file in your C<cpan_home> directory.
2075 To get some interesting statistics, it is recommended that
2076 C<randomize_urllist> be set; this introduces some amount of
2077 randomness into the URL selection.
2079 =head2 The C<requires> and C<build_requires> dependency declarations
2081 Since CPAN.pm version 1.88_51 modules declared as C<build_requires> by
2082 a distribution are treated differently depending on the config
2083 variable C<build_requires_install_policy>. By setting
2084 C<build_requires_install_policy> to C<no>, such a module is not
2085 installed. It is only built and tested, and then kept in the list of
2086 tested but uninstalled modules. As such, it is available during the
2087 build of the dependent module by integrating the path to the
2088 C<blib/arch> and C<blib/lib> directories in the environment variable
2089 PERL5LIB. If C<build_requires_install_policy> is set ti C<yes>, then
2090 both modules declared as C<requires> and those declared as
2091 C<build_requires> are treated alike. By setting to C<ask/yes> or
2092 C<ask/no>, CPAN.pm asks the user and sets the default accordingly.
2094 =head2 Configuration for individual distributions (I<Distroprefs>)
2096 (B<Note:> This feature has been introduced in CPAN.pm 1.8854 and is
2097 still considered beta quality)
2099 Distributions on CPAN usually behave according to what we call the
2100 CPAN mantra. Or since the event of Module::Build, we should talk about
2103 perl Makefile.PL perl Build.PL
2105 make test ./Build test
2106 make install ./Build install
2108 But some modules cannot be built with this mantra. They try to get
2109 some extra data from the user via the environment, extra arguments, or
2110 interactively--thus disturbing the installation of large bundles like
2111 Phalanx100 or modules with many dependencies like Plagger.
2113 The distroprefs system of C<CPAN.pm> addresses this problem by
2114 allowing the user to specify extra informations and recipes in YAML
2121 pass additional arguments to one of the four commands,
2125 set environment variables
2129 instantiate an Expect object that reads from the console, waits for
2130 some regular expressions and enters some answers
2134 temporarily override assorted C<CPAN.pm> configuration variables
2138 specify dependencies the original maintainer forgot
2142 disable the installation of an object altogether
2146 See the YAML and Data::Dumper files that come with the C<CPAN.pm>
2147 distribution in the C<distroprefs/> directory for examples.
2151 The YAML files themselves must have the C<.yml> extension; all other
2152 files are ignored (for two exceptions see I<Fallback Data::Dumper and
2153 Storable> below). The containing directory can be specified in
2154 C<CPAN.pm> in the C<prefs_dir> config variable. Try C<o conf init
2155 prefs_dir> in the CPAN shell to set and activate the distroprefs
2158 Every YAML file may contain arbitrary documents according to the YAML
2159 specification, and every document is treated as an entity that
2160 can specify the treatment of a single distribution.
2162 Filenames can be picked arbitrarily; C<CPAN.pm> always reads
2163 all files (in alphabetical order) and takes the key C<match> (see
2164 below in I<Language Specs>) as a hashref containing match criteria
2165 that determine if the current distribution matches the YAML document
2168 =head2 Fallback Data::Dumper and Storable
2170 If neither your configured C<yaml_module> nor YAML.pm is installed,
2171 CPAN.pm falls back to using Data::Dumper and Storable and looks for
2172 files with the extensions C<.dd> or C<.st> in the C<prefs_dir>
2173 directory. These files are expected to contain one or more hashrefs.
2174 For Data::Dumper generated files, this is expected to be done with by
2175 defining C<$VAR1>, C<$VAR2>, etc. The YAML shell would produce these
2178 ysh < somefile.yml > somefile.dd
2180 For Storable files the rule is that they must be constructed such that
2181 C<Storable::retrieve(file)> returns an array reference and the array
2182 elements represent one distropref object each. The conversion from
2183 YAML would look like so:
2185 perl -MYAML=LoadFile -MStorable=nstore -e '
2187 nstore(\@y, shift)' somefile.yml somefile.st
2189 In bootstrapping situations it is usually sufficient to translate only
2190 a few YAML files to Data::Dumper for crucial modules like
2191 C<YAML::Syck>, C<YAML.pm> and C<Expect.pm>. If you prefer Storable
2192 over Data::Dumper, remember to pull out a Storable version that writes
2193 an older format than all the other Storable versions that will need to
2198 The following example contains all supported keywords and structures
2199 with the exception of C<eexpect> which can be used instead of
2205 module: "Dancing::Queen"
2206 distribution: "^CHACHACHA/Dancing-"
2207 not_distribution: "\.zip$"
2208 perl: "/usr/local/cariba-perl/bin/perl"
2213 DANCING_FLOOR: "Shubiduh"
2219 - "--somearg=specialcase"
2224 - "Which is your favorite fruit"
2236 commendline: "echo SKIPPING make"
2249 WANT_TO_INSTALL: YES
2252 - "Do you really want to install"
2256 - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
2262 Test::Exception: 0.25
2267 =head2 Language Specs
2269 Every YAML document represents a single hash reference. The valid keys
2270 in this hash are as follows:
2274 =item comment [scalar]
2278 =item cpanconfig [hash]
2280 Temporarily override assorted C<CPAN.pm> configuration variables.
2282 Supported are: C<build_requires_install_policy>, C<check_sigs>,
2283 C<make>, C<make_install_make_command>, C<prefer_installer>,
2284 C<test_report>. Please report as a bug when you need another one
2287 =item depends [hash] *** EXPERIMENTAL FEATURE ***
2289 All three types, namely C<configure_requires>, C<build_requires>, and
2290 C<requires> are supported in the way specified in the META.yml
2291 specification. The current implementation I<merges> the specified
2292 dependencies with those declared by the package maintainer. In a
2293 future implementation this may be changed to override the original
2296 =item disabled [boolean]
2298 Specifies that this distribution shall not be processed at all.
2300 =item features [array] *** EXPERIMENTAL FEATURE ***
2302 Experimental implementation to deal with optional_features from
2303 META.yml. Still needs coordination with installer software and
2304 currently works only for META.yml declaring C<dynamic_config=0>. Use
2309 The canonical name of a delegate distribution to install
2310 instead. Useful when a new version, although it tests OK itself,
2311 breaks something else or a developer release or a fork is already
2312 uploaded that is better than the last released version.
2314 =item install [hash]
2316 Processing instructions for the C<make install> or C<./Build install>
2317 phase of the CPAN mantra. See below under I<Processing Instructions>.
2321 Processing instructions for the C<make> or C<./Build> phase of the
2322 CPAN mantra. See below under I<Processing Instructions>.
2326 A hashref with one or more of the keys C<distribution>, C<modules>,
2327 C<perl>, C<perlconfig>, and C<env> that specify whether a document is
2328 targeted at a specific CPAN distribution or installation.
2329 Keys prefixed with C<not_> negates the corresponding match.
2331 The corresponding values are interpreted as regular expressions. The
2332 C<distribution> related one will be matched against the canonical
2333 distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
2335 The C<module> related one will be matched against I<all> modules
2336 contained in the distribution until one module matches.
2338 The C<perl> related one will be matched against C<$^X> (but with the
2341 The value associated with C<perlconfig> is itself a hashref that is
2342 matched against corresponding values in the C<%Config::Config> hash
2343 living in the C<Config.pm> module.
2344 Keys prefixed with C<not_> negates the corresponding match.
2346 The value associated with C<env> is itself a hashref that is
2347 matched against corresponding values in the C<%ENV> hash.
2348 Keys prefixed with C<not_> negates the corresponding match.
2350 If more than one restriction of C<module>, C<distribution>, etc. is
2351 specified, the results of the separately computed match values must
2352 all match. If so, the hashref represented by the
2353 YAML document is returned as the preference structure for the current
2356 =item patches [array]
2358 An array of patches on CPAN or on the local disk to be applied in
2359 order via an external patch program. If the value for the C<-p>
2360 parameter is C<0> or C<1> is determined by reading the patch
2361 beforehand. The path to each patch is either an absolute path on the
2362 local filesystem or relative to a patch directory specified in the
2363 C<patches_dir> configuration variable or in the format of a canonical
2364 distroname. For examples please consult the distroprefs/ directory in
2365 the CPAN.pm distribution (these examples are not installed by
2368 Note: if the C<applypatch> program is installed and C<CPAN::Config>
2369 knows about it B<and> a patch is written by the C<makepatch> program,
2370 then C<CPAN.pm> lets C<applypatch> apply the patch. Both C<makepatch>
2371 and C<applypatch> are available from CPAN in the C<JV/makepatch-*>
2376 Processing instructions for the C<perl Makefile.PL> or C<perl
2377 Build.PL> phase of the CPAN mantra. See below under I<Processing
2382 Processing instructions for the C<make test> or C<./Build test> phase
2383 of the CPAN mantra. See below under I<Processing Instructions>.
2387 =head2 Processing Instructions
2393 Arguments to be added to the command line
2397 A full commandline to run via C<system()>.
2398 During execution, the environment variable PERL is set
2399 to $^X (but with an absolute path). If C<commandline> is specified,
2400 C<args> is not used.
2402 =item eexpect [hash]
2404 Extended C<expect>. This is a hash reference with four allowed keys,
2405 C<mode>, C<timeout>, C<reuse>, and C<talk>.
2407 C<mode> may have the values C<deterministic> for the case where all
2408 questions come in the order written down and C<anyorder> for the case
2409 where the questions may come in any order. The default mode is
2412 C<timeout> denotes a timeout in seconds. Floating-point timeouts are
2413 OK. With C<mode=deterministic>, the timeout denotes the
2414 timeout per question; with C<mode=anyorder> it denotes the
2415 timeout per byte received from the stream or questions.
2417 C<talk> is a reference to an array that contains alternating questions
2418 and answers. Questions are regular expressions and answers are literal
2419 strings. The Expect module watches the stream from the
2420 execution of the external program (C<perl Makefile.PL>, C<perl
2421 Build.PL>, C<make>, etc.).
2423 For C<mode=deterministic>, the CPAN.pm injects the
2424 corresponding answer as soon as the stream matches the regular expression.
2426 For C<mode=anyorder> CPAN.pm answers a question as soon
2427 as the timeout is reached for the next byte in the input stream. In
2428 this mode you can use the C<reuse> parameter to decide what will
2429 happen with a question-answer pair after it has been used. In the
2430 default case (reuse=0) it is removed from the array, avoiding being
2431 used again accidentally. If you want to answer the
2432 question C<Do you really want to do that> several times, then it must
2433 be included in the array at least as often as you want this answer to
2434 be given. Setting the parameter C<reuse> to 1 makes this repetition
2439 Environment variables to be set during the command
2441 =item expect [array]
2443 C<< expect: <array> >> is a short notation for
2452 =head2 Schema verification with C<Kwalify>
2454 If you have the C<Kwalify> module installed (which is part of the
2455 Bundle::CPANxxl), then all your distroprefs files are checked for
2456 syntactic correctness.
2458 =head2 Example Distroprefs Files
2460 C<CPAN.pm> comes with a collection of example YAML files. Note that these
2461 are really just examples and should not be used without care because
2462 they cannot fit everybody's purpose. After all, the authors of the
2463 packages that ask questions had a need to ask, so you should watch
2464 their questions and adjust the examples to your environment and your
2465 needs. You have been warned:-)
2467 =head1 PROGRAMMER'S INTERFACE
2469 If you do not enter the shell, shell commands are
2470 available both as methods (C<CPAN::Shell-E<gt>install(...)>) and as
2471 functions in the calling package (C<install(...)>). Before calling low-level
2472 commands, it makes sense to initialize components of CPAN you need, e.g.:
2474 CPAN::HandleConfig->load;
2475 CPAN::Shell::setup_output;
2476 CPAN::Index->reload;
2478 High-level commands do such initializations automatically.
2480 There's currently only one class that has a stable interface -
2481 CPAN::Shell. All commands that are available in the CPAN shell are
2482 methods of the class CPAN::Shell. Each of the commands that produce
2483 listings of modules (C<r>, C<autobundle>, C<u>) also return a list of
2484 the IDs of all modules within the list.
2488 =item expand($type,@things)
2490 The IDs of all objects available within a program are strings that can
2491 be expanded to the corresponding real objects with the
2492 C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a
2493 list of CPAN::Module objects according to the C<@things> arguments
2494 given. In scalar context, it returns only the first element of the
2497 =item expandany(@things)
2499 Like expand, but returns objects of the appropriate type, i.e.
2500 CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and
2501 CPAN::Distribution objects for distributions. Note: it does not expand
2502 to CPAN::Author objects.
2504 =item Programming Examples
2506 This enables the programmer to do operations that combine
2507 functionalities that are available in the shell.
2509 # install everything that is outdated on my disk:
2510 perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
2512 # install my favorite programs if necessary:
2513 for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
2514 CPAN::Shell->install($mod);
2517 # list all modules on my disk that have no VERSION number
2518 for $mod (CPAN::Shell->expand("Module","/./")) {
2519 next unless $mod->inst_file;
2520 # MakeMaker convention for undefined $VERSION:
2521 next unless $mod->inst_version eq "undef";
2522 print "No VERSION in ", $mod->id, "\n";
2525 # find out which distribution on CPAN contains a module:
2526 print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
2528 Or if you want to schedule a I<cron> job to watch CPAN, you could list
2529 all modules that need updating. First a quick and dirty way:
2531 perl -e 'use CPAN; CPAN::Shell->r;'
2533 If you don't want any output should all modules be
2534 up to date, parse the output of above command for the regular
2535 expression C</modules are up to date/> and decide to mail the output
2536 only if it doesn't match.
2538 If you prefer to do it more in a programmerish style in one single
2539 process, something like this may better suit you:
2541 # list all modules on my disk that have newer versions on CPAN
2542 for $mod (CPAN::Shell->expand("Module","/./")) {
2543 next unless $mod->inst_file;
2544 next if $mod->uptodate;
2545 printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
2546 $mod->id, $mod->inst_version, $mod->cpan_version;
2549 If that gives too much output every day, you may want to
2550 watch only for three modules. You can write
2552 for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {
2554 as the first line instead. Or you can combine some of the above
2557 # watch only for a new mod_perl module
2558 $mod = CPAN::Shell->expand("Module","mod_perl");
2559 exit if $mod->uptodate;
2560 # new mod_perl arrived, let me know all update recommendations
2565 =head2 Methods in the other Classes
2569 =item CPAN::Author::as_glimpse()
2571 Returns a one-line description of the author
2573 =item CPAN::Author::as_string()
2575 Returns a multi-line description of the author
2577 =item CPAN::Author::email()
2579 Returns the author's email address
2581 =item CPAN::Author::fullname()
2583 Returns the author's name
2585 =item CPAN::Author::name()
2587 An alias for fullname
2589 =item CPAN::Bundle::as_glimpse()
2591 Returns a one-line description of the bundle
2593 =item CPAN::Bundle::as_string()
2595 Returns a multi-line description of the bundle
2597 =item CPAN::Bundle::clean()
2599 Recursively runs the C<clean> method on all items contained in the bundle.
2601 =item CPAN::Bundle::contains()
2603 Returns a list of objects' IDs contained in a bundle. The associated
2604 objects may be bundles, modules or distributions.
2606 =item CPAN::Bundle::force($method,@args)
2608 Forces CPAN to perform a task that it normally would have refused to
2609 do. Force takes as arguments a method name to be called and any number
2610 of additional arguments that should be passed to the called method.
2611 The internals of the object get the needed changes so that CPAN.pm
2612 does not refuse to take the action. The C<force> is passed recursively
2613 to all contained objects. See also the section above on the C<force>
2614 and the C<fforce> pragma.
2616 =item CPAN::Bundle::get()
2618 Recursively runs the C<get> method on all items contained in the bundle
2620 =item CPAN::Bundle::inst_file()
2622 Returns the highest installed version of the bundle in either @INC or
2623 C<$CPAN::Config->{cpan_home}>. Note that this is different from
2624 CPAN::Module::inst_file.
2626 =item CPAN::Bundle::inst_version()
2628 Like CPAN::Bundle::inst_file, but returns the $VERSION
2630 =item CPAN::Bundle::uptodate()
2632 Returns 1 if the bundle itself and all its members are uptodate.
2634 =item CPAN::Bundle::install()
2636 Recursively runs the C<install> method on all items contained in the bundle
2638 =item CPAN::Bundle::make()
2640 Recursively runs the C<make> method on all items contained in the bundle
2642 =item CPAN::Bundle::readme()
2644 Recursively runs the C<readme> method on all items contained in the bundle
2646 =item CPAN::Bundle::test()
2648 Recursively runs the C<test> method on all items contained in the bundle
2650 =item CPAN::Distribution::as_glimpse()
2652 Returns a one-line description of the distribution
2654 =item CPAN::Distribution::as_string()
2656 Returns a multi-line description of the distribution
2658 =item CPAN::Distribution::author
2660 Returns the CPAN::Author object of the maintainer who uploaded this
2663 =item CPAN::Distribution::pretty_id()
2665 Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is the
2666 author's PAUSE ID and TARBALL is the distribution filename.
2668 =item CPAN::Distribution::base_id()
2670 Returns the distribution filename without any archive suffix. E.g
2673 =item CPAN::Distribution::clean()
2675 Changes to the directory where the distribution has been unpacked and
2676 runs C<make clean> there.
2678 =item CPAN::Distribution::containsmods()
2680 Returns a list of IDs of modules contained in a distribution file.
2681 Works only for distributions listed in the 02packages.details.txt.gz
2682 file. This typically means that just most recent version of a
2683 distribution is covered.
2685 =item CPAN::Distribution::cvs_import()
2687 Changes to the directory where the distribution has been unpacked and
2690 cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
2694 =item CPAN::Distribution::dir()
2696 Returns the directory into which this distribution has been unpacked.
2698 =item CPAN::Distribution::force($method,@args)
2700 Forces CPAN to perform a task that it normally would have refused to
2701 do. Force takes as arguments a method name to be called and any number
2702 of additional arguments that should be passed to the called method.
2703 The internals of the object get the needed changes so that CPAN.pm
2704 does not refuse to take the action. See also the section above on the
2705 C<force> and the C<fforce> pragma.
2707 =item CPAN::Distribution::get()
2709 Downloads the distribution from CPAN and unpacks it. Does nothing if
2710 the distribution has already been downloaded and unpacked within the
2713 =item CPAN::Distribution::install()
2715 Changes to the directory where the distribution has been unpacked and
2716 runs the external command C<make install> there. If C<make> has not
2717 yet been run, it will be run first. A C<make test> is issued in
2718 any case and if this fails, the install is cancelled. The
2719 cancellation can be avoided by letting C<force> run the C<install> for
2722 This install method only has the power to install the distribution if
2723 there are no dependencies in the way. To install an object along with all
2724 its dependencies, use CPAN::Shell->install.
2726 Note that install() gives no meaningful return value. See uptodate().
2728 =item CPAN::Distribution::install_tested()
2730 Install all distributions that have tested sucessfully but
2731 not yet installed. See also C<is_tested>.
2733 =item CPAN::Distribution::isa_perl()
2735 Returns 1 if this distribution file seems to be a perl distribution.
2736 Normally this is derived from the file name only, but the index from
2737 CPAN can contain a hint to achieve a return value of true for other
2740 =item CPAN::Distribution::look()
2742 Changes to the directory where the distribution has been unpacked and
2743 opens a subshell there. Exiting the subshell returns.
2745 =item CPAN::Distribution::make()
2747 First runs the C<get> method to make sure the distribution is
2748 downloaded and unpacked. Changes to the directory where the
2749 distribution has been unpacked and runs the external commands C<perl
2750 Makefile.PL> or C<perl Build.PL> and C<make> there.
2752 =item CPAN::Distribution::perldoc()
2754 Downloads the pod documentation of the file associated with a
2755 distribution (in HTML format) and runs it through the external
2756 command I<lynx> specified in C<$CPAN::Config->{lynx}>. If I<lynx>
2757 isn't available, it converts it to plain text with the external
2758 command I<html2text> and runs it through the pager specified
2759 in C<$CPAN::Config->{pager}>
2761 =item CPAN::Distribution::prefs()
2763 Returns the hash reference from the first matching YAML file that the
2764 user has deposited in the C<prefs_dir/> directory. The first
2765 succeeding match wins. The files in the C<prefs_dir/> are processed
2766 alphabetically, and the canonical distroname (e.g.
2767 AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions
2768 stored in the $root->{match}{distribution} attribute value.
2769 Additionally all module names contained in a distribution are matched
2770 against the regular expressions in the $root->{match}{module} attribute
2771 value. The two match values are ANDed together. Each of the two
2772 attributes are optional.
2774 =item CPAN::Distribution::prereq_pm()
2776 Returns the hash reference that has been announced by a distribution
2777 as the C<requires> and C<build_requires> elements. These can be
2778 declared either by the C<META.yml> (if authoritative) or can be
2779 deposited after the run of C<Build.PL> in the file C<./_build/prereqs>
2780 or after the run of C<Makfile.PL> written as the C<PREREQ_PM> hash in
2781 a comment in the produced C<Makefile>. I<Note>: this method only works
2782 after an attempt has been made to C<make> the distribution. Returns
2785 =item CPAN::Distribution::readme()
2787 Downloads the README file associated with a distribution and runs it
2788 through the pager specified in C<$CPAN::Config->{pager}>.
2790 =item CPAN::Distribution::reports()
2792 Downloads report data for this distribution from www.cpantesters.org
2793 and displays a subset of them.
2795 =item CPAN::Distribution::read_yaml()
2797 Returns the content of the META.yml of this distro as a hashref. Note:
2798 works only after an attempt has been made to C<make> the distribution.
2799 Returns undef otherwise. Also returns undef if the content of META.yml
2800 is not authoritative. (The rules about what exactly makes the content
2801 authoritative are still in flux.)
2803 =item CPAN::Distribution::test()
2805 Changes to the directory where the distribution has been unpacked and
2806 runs C<make test> there.
2808 =item CPAN::Distribution::uptodate()
2810 Returns 1 if all the modules contained in the distribution are
2811 uptodate. Relies on containsmods.
2813 =item CPAN::Index::force_reload()
2815 Forces a reload of all indices.
2817 =item CPAN::Index::reload()
2819 Reloads all indices if they have not been read for more than
2820 C<$CPAN::Config->{index_expire}> days.
2822 =item CPAN::InfoObj::dump()
2824 CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
2825 inherit this method. It prints the data structure associated with an
2826 object. Useful for debugging. Note: the data structure is considered
2827 internal and thus subject to change without notice.
2829 =item CPAN::Module::as_glimpse()
2831 Returns a one-line description of the module in four columns: The
2832 first column contains the word C<Module>, the second column consists
2833 of one character: an equals sign if this module is already installed
2834 and uptodate, a less-than sign if this module is installed but can be
2835 upgraded, and a space if the module is not installed. The third column
2836 is the name of the module and the fourth column gives maintainer or
2837 distribution information.
2839 =item CPAN::Module::as_string()
2841 Returns a multi-line description of the module
2843 =item CPAN::Module::clean()
2845 Runs a clean on the distribution associated with this module.
2847 =item CPAN::Module::cpan_file()
2849 Returns the filename on CPAN that is associated with the module.
2851 =item CPAN::Module::cpan_version()
2853 Returns the latest version of this module available on CPAN.
2855 =item CPAN::Module::cvs_import()
2857 Runs a cvs_import on the distribution associated with this module.
2859 =item CPAN::Module::description()
2861 Returns a 44 character description of this module. Only available for
2862 modules listed in The Module List (CPAN/modules/00modlist.long.html
2863 or 00modlist.long.txt.gz)
2865 =item CPAN::Module::distribution()
2867 Returns the CPAN::Distribution object that contains the current
2868 version of this module.
2870 =item CPAN::Module::dslip_status()
2872 Returns a hash reference. The keys of the hash are the letters C<D>,
2873 C<S>, C<L>, C<I>, and <P>, for development status, support level,
2874 language, interface and public licence respectively. The data for the
2875 DSLIP status are collected by pause.perl.org when authors register
2876 their namespaces. The values of the 5 hash elements are one-character
2877 words whose meaning is described in the table below. There are also 5
2878 hash elements C<DV>, C<SV>, C<LV>, C<IV>, and <PV> that carry a more
2879 verbose value of the 5 status variables.
2881 Where the 'DSLIP' characters have the following meanings:
2883 D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
2884 i - Idea, listed to gain consensus or as a placeholder
2885 c - under construction but pre-alpha (not yet released)
2886 a/b - Alpha/Beta testing
2888 M - Mature (no rigorous definition)
2889 S - Standard, supplied with Perl 5
2894 u - Usenet newsgroup comp.lang.perl.modules
2895 n - None known, try comp.lang.perl.modules
2896 a - abandoned; volunteers welcome to take over maintainance
2899 p - Perl-only, no compiler needed, should be platform independent
2900 c - C and perl, a C compiler will be needed
2901 h - Hybrid, written in perl with optional C code, no compiler needed
2902 + - C++ and perl, a C++ compiler will be needed
2903 o - perl and another language other than C or C++
2906 f - plain Functions, no references used
2907 h - hybrid, object and function interfaces available
2908 n - no interface at all (huh?)
2909 r - some use of unblessed References or ties
2910 O - Object oriented using blessed references and/or inheritance
2913 p - Standard-Perl: user may choose between GPL and Artistic
2914 g - GPL: GNU General Public License
2915 l - LGPL: "GNU Lesser General Public License" (previously known as
2916 "GNU Library General Public License")
2917 b - BSD: The BSD License
2918 a - Artistic license alone
2919 2 - Artistic license 2.0 or later
2920 o - open source: appoved by www.opensource.org
2921 d - allows distribution without restrictions
2922 r - restricted distribtion
2923 n - no license at all
2925 =item CPAN::Module::force($method,@args)
2927 Forces CPAN to perform a task it would normally refuse to
2928 do. Force takes as arguments a method name to be invoked and any number
2929 of additional arguments to pass that method.
2930 The internals of the object get the needed changes so that CPAN.pm
2931 does not refuse to take the action. See also the section above on the
2932 C<force> and the C<fforce> pragma.
2934 =item CPAN::Module::get()
2936 Runs a get on the distribution associated with this module.
2938 =item CPAN::Module::inst_file()
2940 Returns the filename of the module found in @INC. The first file found
2941 is reported, just as perl itself stops searching @INC once it finds a
2944 =item CPAN::Module::available_file()
2946 Returns the filename of the module found in PERL5LIB or @INC. The
2947 first file found is reported. The advantage of this method over
2948 C<inst_file> is that modules that have been tested but not yet
2949 installed are included because PERL5LIB keeps track of tested modules.
2951 =item CPAN::Module::inst_version()
2953 Returns the version number of the installed module in readable format.
2955 =item CPAN::Module::available_version()
2957 Returns the version number of the available module in readable format.
2959 =item CPAN::Module::install()
2961 Runs an C<install> on the distribution associated with this module.
2963 =item CPAN::Module::look()
2965 Changes to the directory where the distribution associated with this
2966 module has been unpacked and opens a subshell there. Exiting the
2969 =item CPAN::Module::make()
2971 Runs a C<make> on the distribution associated with this module.
2973 =item CPAN::Module::manpage_headline()
2975 If module is installed, peeks into the module's manpage, reads the
2976 headline, and returns it. Moreover, if the module has been downloaded
2977 within this session, does the equivalent on the downloaded module even
2978 if it hasn't been installed yet.
2980 =item CPAN::Module::perldoc()
2982 Runs a C<perldoc> on this module.
2984 =item CPAN::Module::readme()
2986 Runs a C<readme> on the distribution associated with this module.
2988 =item CPAN::Module::reports()
2990 Calls the reports() method on the associated distribution object.
2992 =item CPAN::Module::test()
2994 Runs a C<test> on the distribution associated with this module.
2996 =item CPAN::Module::uptodate()
2998 Returns 1 if the module is installed and up-to-date.
3000 =item CPAN::Module::userid()
3002 Returns the author's ID of the module.
3006 =head2 Cache Manager
3008 Currently the cache manager only keeps track of the build directory
3009 ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
3010 deletes complete directories below C<build_dir> as soon as the size of
3011 all directories there gets bigger than $CPAN::Config->{build_cache}
3012 (in MB). The contents of this cache may be used for later
3013 re-installations that you intend to do manually, but will never be
3014 trusted by CPAN itself. This is due to the fact that the user might
3015 use these directories for building modules on different architectures.
3017 There is another directory ($CPAN::Config->{keep_source_where}) where
3018 the original distribution files are kept. This directory is not
3019 covered by the cache manager and must be controlled by the user. If
3020 you choose to have the same directory as build_dir and as
3021 keep_source_where directory, then your sources will be deleted with
3022 the same fifo mechanism.
3026 A bundle is just a perl module in the namespace Bundle:: that does not
3027 define any functions or methods. It usually only contains documentation.
3029 It starts like a perl module with a package declaration and a $VERSION
3030 variable. After that the pod section looks like any other pod with the
3031 only difference being that I<one special pod section> exists starting with
3036 In this pod section each line obeys the format
3038 Module_Name [Version_String] [- optional text]
3040 The only required part is the first field, the name of a module
3041 (e.g. Foo::Bar, ie. I<not> the name of the distribution file). The rest
3042 of the line is optional. The comment part is delimited by a dash just
3043 as in the man page header.
3045 The distribution of a bundle should follow the same convention as
3046 other distributions.
3048 Bundles are treated specially in the CPAN package. If you say 'install
3049 Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
3050 the modules in the CONTENTS section of the pod. You can install your
3051 own Bundles locally by placing a conformant Bundle file somewhere into
3052 your @INC path. The autobundle() command which is available in the
3053 shell interface does that for you by including all currently installed
3054 modules in a snapshot bundle file.
3056 =head1 PREREQUISITES
3058 If you have a local mirror of CPAN and can access all files with
3059 "file:" URLs, then you only need a perl later than perl5.003 to run
3060 this module. Otherwise Net::FTP is strongly recommended. LWP may be
3061 required for non-UNIX systems, or if your nearest CPAN site is
3062 associated with a URL that is not C<ftp:>.
3064 If you have neither Net::FTP nor LWP, there is a fallback mechanism
3065 implemented for an external ftp command or for an external lynx
3070 =head2 Finding packages and VERSION
3072 This module presumes that all packages on CPAN
3078 declare their $VERSION variable in an easy to parse manner. This
3079 prerequisite can hardly be relaxed because it consumes far too much
3080 memory to load all packages into the running program just to determine
3081 the $VERSION variable. Currently all programs that are dealing with
3082 version use something like this
3084 perl -MExtUtils::MakeMaker -le \
3085 'print MM->parse_version(shift)' filename
3087 If you are author of a package and wonder if your $VERSION can be
3088 parsed, please try the above method.
3092 come as compressed or gzipped tarfiles or as zip files and contain a
3093 C<Makefile.PL> or C<Build.PL> (well, we try to handle a bit more, but
3094 with little enthusiasm).
3100 Debugging this module is more than a bit complex due to interference from
3101 the software producing the indices on CPAN, the mirroring process on CPAN,
3102 packaging, configuration, synchronicity, and even (gasp!) due to bugs
3103 within the CPAN.pm module itself.
3105 For debugging the code of CPAN.pm itself in interactive mode, some
3106 debugging aid can be turned on for most packages within
3111 =item o debug package...
3113 sets debug mode for packages.
3115 =item o debug -package...
3117 unsets debug mode for packages.
3121 turns debugging on for all packages.
3123 =item o debug number
3127 which sets the debugging packages directly. Note that C<o debug 0>
3128 turns debugging off.
3130 What seems a successful strategy is the combination of C<reload
3131 cpan> and the debugging switches. Add a new debug statement while
3132 running in the shell and then issue a C<reload cpan> and see the new
3133 debugging messages immediately without losing the current context.
3135 C<o debug> without an argument lists the valid package names and the
3136 current set of packages in debugging mode. C<o debug> has built-in
3139 For debugging of CPAN data there is the C<dump> command which takes
3140 the same arguments as make/test/install and outputs each object's
3141 Data::Dumper dump. If an argument looks like a perl variable and
3142 contains one of C<$>, C<@> or C<%>, it is eval()ed and fed to
3143 Data::Dumper directly.
3145 =head2 Floppy, Zip, Offline Mode
3147 CPAN.pm works nicely without network access, too. If you maintain machines
3148 that are not networked at all, you should consider working with C<file:>
3149 URLs. You'll have to collect your modules somewhere first. So
3150 you might use CPAN.pm to put together all you need on a networked
3151 machine. Then copy the $CPAN::Config->{keep_source_where} (but not
3152 $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
3153 of a personal CPAN. CPAN.pm on the non-networked machines works nicely
3154 with this floppy. See also below the paragraph about CD-ROM support.
3156 =head2 Basic Utilities for Programmers
3160 =item has_inst($module)
3162 Returns true if the module is installed. Used to load all modules into
3163 the running CPAN.pm that are considered optional. The config variable
3164 C<dontload_list> intercepts the C<has_inst()> call such
3165 that an optional module is not loaded despite being available. For
3166 example, the following command will prevent C<YAML.pm> from being
3169 cpan> o conf dontload_list push YAML
3171 See the source for details.
3173 =item has_usable($module)
3175 Returns true if the module is installed and in a usable state. Only
3176 useful for a handful of modules that are used internally. See the
3179 =item instance($module)
3181 The constructor for all the singletons used to represent modules,
3182 distributions, authors, and bundles. If the object already exists, this
3183 method returns the object; otherwise, it calls the constructor.
3189 There's no strong security layer in CPAN.pm. CPAN.pm helps you to
3190 install foreign, unmasked, unsigned code on your machine. We compare
3191 to a checksum that comes from the net just as the distribution file
3192 itself. But we try to make it easy to add security on demand:
3194 =head2 Cryptographically signed modules
3196 Since release 1.77, CPAN.pm has been able to verify cryptographically
3197 signed module distributions using Module::Signature. The CPAN modules
3198 can be signed by their authors, thus giving more security. The simple
3199 unsigned MD5 checksums that were used before by CPAN protect mainly
3200 against accidental file corruption.
3202 You will need to have Module::Signature installed, which in turn
3203 requires that you have at least one of Crypt::OpenPGP module or the
3204 command-line F<gpg> tool installed.
3206 You will also need to be able to connect over the Internet to the public
3207 keyservers, like pgp.mit.edu, and their port 11731 (the HKP protocol).
3209 The configuration parameter check_sigs is there to turn signature
3214 Most functions in package CPAN are exported by default. The reason
3215 for this is that the primary use is intended for the cpan shell or for
3220 When the CPAN shell enters a subshell via the look command, it sets
3221 the environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
3224 When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
3225 to the ID of the running process. It also sets
3226 PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
3227 happen with older versions of Module::Install.
3229 When running C<perl Makefile.PL>, the environment variable
3230 C<PERL5_CPAN_IS_EXECUTING> is set to the full path of the
3231 C<Makefile.PL> that is being executed. This prevents runaway processes
3232 with newer versions of Module::Install.
3234 When the config variable ftp_passive is set, all downloads will be run
3235 with the environment variable FTP_PASSIVE set to this value. This is
3236 in general a good idea as it influences both Net::FTP and LWP based
3237 connections. The same effect can be achieved by starting the cpan
3238 shell with this environment variable set. For Net::FTP alone, one can
3239 also always set passive mode by running libnetcfg.
3241 =head1 POPULATE AN INSTALLATION WITH LOTS OF MODULES
3243 Populating a freshly installed perl with one's favorite modules is pretty
3244 easy if you maintain a private bundle definition file. To get a useful
3245 blueprint of a bundle definition file, the command autobundle can be used
3246 on the CPAN shell command line. This command writes a bundle definition
3247 file for all modules installed for the current perl
3248 interpreter. It's recommended to run this command once only, and from then
3249 on maintain the file manually under a private name, say
3250 Bundle/my_bundle.pm. With a clever bundle file you can then simply say
3252 cpan> install Bundle::my_bundle
3254 then answer a few questions and go out for coffee (possibly
3255 even in a different city).
3257 Maintaining a bundle definition file means keeping track of two
3258 things: dependencies and interactivity. CPAN.pm sometimes fails on
3259 calculating dependencies because not all modules define all MakeMaker
3260 attributes correctly, so a bundle definition file should specify
3261 prerequisites as early as possible. On the other hand, it's
3262 annoying that so many distributions need some interactive configuring. So
3263 what you can try to accomplish in your private bundle file is to have the
3264 packages that need to be configured early in the file and the gentle
3265 ones later, so you can go out for cofeee after a few minutes and leave CPAN.pm
3266 to churn away untended.
3268 =head1 WORKING WITH CPAN.pm BEHIND FIREWALLS
3270 Thanks to Graham Barr for contributing the following paragraphs about
3271 the interaction between perl, and various firewall configurations. For
3272 further information on firewalls, it is recommended to consult the
3273 documentation that comes with the I<ncftp> program. If you are unable to
3274 go through the firewall with a simple Perl setup, it is likely
3275 that you can configure I<ncftp> so that it works through your firewall.
3277 =head2 Three basic types of firewalls
3279 Firewalls can be categorized into three basic types.
3285 This is when the firewall machine runs a web server, and to access the
3286 outside world, you must do so via that web server. If you set environment
3287 variables like http_proxy or ftp_proxy to values beginning with http://,
3288 or in your web browser you've proxy information set, then you know
3289 you are running behind an http firewall.
3291 To access servers outside these types of firewalls with perl (even for
3296 This where the firewall machine runs an ftp server. This kind of
3297 firewall will only let you access ftp servers outside the firewall.
3298 This is usually done by connecting to the firewall with ftp, then
3299 entering a username like "user@outside.host.com".
3301 To access servers outside these type of firewalls with perl, you
3304 =item One-way visibility
3306 One-way visibility means these firewalls try to make themselves
3307 invisible to users inside the firewall. An FTP data connection is
3308 normally created by sending your IP address to the remote server and then
3309 listening for the return connection. But the remote server will not be able to
3310 connect to you because of the firewall. For these types of firewall,
3311 FTP connections need to be done in a passive mode.
3313 There are two that I can think off.
3319 If you are using a SOCKS firewall, you will need to compile perl and link
3320 it with the SOCKS library. This is what is normally called a 'socksified'
3321 perl. With this executable you will be able to connect to servers outside
3322 the firewall as if it were not there.
3326 This is when the firewall implemented in the kernel (via NAT, or networking
3327 address translation), it allows you to hide a complete network behind one
3328 IP address. With this firewall no special compiling is needed as you can
3329 access hosts directly.
3331 For accessing ftp servers behind such firewalls you usually need to
3332 set the environment variable C<FTP_PASSIVE> or the config variable
3333 ftp_passive to a true value.
3339 =head2 Configuring lynx or ncftp for going through a firewall
3341 If you can go through your firewall with e.g. lynx, presumably with a
3344 /usr/local/bin/lynx -pscott:tiger
3346 then you would configure CPAN.pm with the command
3348 o conf lynx "/usr/local/bin/lynx -pscott:tiger"
3350 That's all. Similarly for ncftp or ftp, you would configure something
3353 o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"
3355 Your mileage may vary...
3363 I installed a new version of module X but CPAN keeps saying,
3364 I have the old version installed
3366 Probably you B<do> have the old version installed. This can
3367 happen if a module installs itself into a different directory in the
3368 @INC path than it was previously installed. This is not really a
3369 CPAN.pm problem, you would have the same problem when installing the
3370 module manually. The easiest way to prevent this behaviour is to add
3371 the argument C<UNINST=1> to the C<make install> call, and that is why
3372 many people add this argument permanently by configuring
3374 o conf make_install_arg UNINST=1
3378 So why is UNINST=1 not the default?
3380 Because there are people who have their precise expectations about who
3381 may install where in the @INC path and who uses which @INC array. In
3382 fine tuned environments C<UNINST=1> can cause damage.
3386 I want to clean up my mess, and install a new perl along with
3387 all modules I have. How do I go about it?
3389 Run the autobundle command for your old perl and optionally rename the
3390 resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
3391 with the Configure option prefix, e.g.
3393 ./Configure -Dprefix=/usr/local/perl-5.6.78.9
3395 Install the bundle file you produced in the first step with something like
3397 cpan> install Bundle::mybundle
3403 When I install bundles or multiple modules with one command
3404 there is too much output to keep track of.
3406 You may want to configure something like
3408 o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
3409 o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"
3411 so that STDOUT is captured in a file for later inspection.
3416 I am not root, how can I install a module in a personal directory?
3418 First of all, you will want to use your own configuration, not the one
3419 that your root user installed. If you do not have permission to write
3420 in the cpan directory that root has configured, you will be asked if
3421 you want to create your own config. Answering "yes" will bring you into
3422 CPAN's configuration stage, using the system config for all defaults except
3423 things that have to do with CPAN's work directory, saving your choices to
3424 your MyConfig.pm file.
3426 You can also manually initiate this process with the following command:
3428 % perl -MCPAN -e 'mkmyconfig'
3434 from the CPAN shell.
3436 You will most probably also want to configure something like this:
3438 o conf makepl_arg "LIB=~/myperl/lib \
3439 INSTALLMAN1DIR=~/myperl/man/man1 \
3440 INSTALLMAN3DIR=~/myperl/man/man3 \
3441 INSTALLSCRIPT=~/myperl/bin \
3442 INSTALLBIN=~/myperl/bin"
3444 and then (oh joy) the equivalent command for Module::Build. That would
3447 o conf mbuildpl_arg "--lib=~/myperl/lib \
3448 --installman1dir=~/myperl/man/man1 \
3449 --installman3dir=~/myperl/man/man3 \
3450 --installscript=~/myperl/bin \
3451 --installbin=~/myperl/bin"
3453 You can make this setting permanent like all C<o conf> settings with
3454 C<o conf commit> or by setting C<auto_commit> beforehand.
3456 You will have to add ~/myperl/man to the MANPATH environment variable
3457 and also tell your perl programs to look into ~/myperl/lib, e.g. by
3460 use lib "$ENV{HOME}/myperl/lib";
3462 or setting the PERL5LIB environment variable.
3464 While we're speaking about $ENV{HOME}, it might be worth mentioning,
3465 that for Windows we use the File::HomeDir module that provides an
3466 equivalent to the concept of the home directory on Unix.
3468 Another thing you should bear in mind is that the UNINST parameter can
3469 be dangerous when you are installing into a private area because you
3470 might accidentally remove modules that other people depend on that are
3471 not using the private area.
3475 How to get a package, unwrap it, and make a change before building it?
3477 Have a look at the C<look> (!) command.
3481 I installed a Bundle and had a couple of fails. When I
3482 retried, everything resolved nicely. Can this be fixed to work
3485 The reason for this is that CPAN does not know the dependencies of all
3486 modules when it starts out. To decide about the additional items to
3487 install, it just uses data found in the META.yml file or the generated
3488 Makefile. An undetected missing piece breaks the process. But it may
3489 well be that your Bundle installs some prerequisite later than some
3490 depending item and thus your second try is able to resolve everything.
3491 Please note, CPAN.pm does not know the dependency tree in advance and
3492 cannot sort the queue of things to install in a topologically correct
3493 order. It resolves perfectly well B<if> all modules declare the
3494 prerequisites correctly with the PREREQ_PM attribute to MakeMaker or
3495 the C<requires> stanza of Module::Build. For bundles which fail and
3496 you need to install often, it is recommended to sort the Bundle
3497 definition file manually.
3501 In our intranet, we have many modules for internal use. How
3502 can I integrate these modules with CPAN.pm but without uploading
3503 the modules to CPAN?
3505 Have a look at the CPAN::Site module.
3509 When I run CPAN's shell, I get an error message about things in my
3510 C</etc/inputrc> (or C<~/.inputrc>) file.
3512 These are readline issues and can only be fixed by studying readline
3513 configuration on your architecture and adjusting the referenced file
3514 accordingly. Please make a backup of the C</etc/inputrc> or C<~/.inputrc>
3515 and edit them. Quite often harmless changes like uppercasing or
3516 lowercasing some arguments solves the problem.
3520 Some authors have strange characters in their names.
3522 Internally CPAN.pm uses the UTF-8 charset. If your terminal is
3523 expecting ISO-8859-1 charset, a converter can be activated by setting
3524 term_is_latin to a true value in your config file. One way of doing so
3527 cpan> o conf term_is_latin 1
3529 If other charset support is needed, please file a bugreport against
3530 CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend
3531 the support or maybe UTF-8 terminals become widely available.
3533 Note: this config variable is deprecated and will be removed in a
3534 future version of CPAN.pm. It will be replaced with the conventions
3535 around the family of $LANG and $LC_* environment variables.
3539 When an install fails for some reason and then I correct the error
3540 condition and retry, CPAN.pm refuses to install the module, saying
3541 C<Already tried without success>.
3543 Use the force pragma like so
3545 force install Foo::Bar
3551 and then C<make install> directly in the subshell.
3555 How do I install a "DEVELOPER RELEASE" of a module?
3557 By default, CPAN will install the latest non-developer release of a
3558 module. If you want to install a dev release, you have to specify the
3559 partial path starting with the author id to the tarball you wish to
3562 cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
3564 Note that you can use the C<ls> command to get this path listed.
3568 How do I install a module and all its dependencies from the commandline,
3569 without being prompted for anything, despite my CPAN configuration
3572 CPAN uses ExtUtils::MakeMaker's prompt() function to ask its questions, so
3573 if you set the PERL_MM_USE_DEFAULT environment variable, you shouldn't be
3574 asked any questions at all (assuming the modules you are installing are
3575 nice about obeying that variable as well):
3577 % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'
3581 How do I create a Module::Build based Build.PL derived from an
3582 ExtUtils::MakeMaker focused Makefile.PL?
3584 http://search.cpan.org/search?query=Module::Build::Convert
3586 http://www.refcnt.org/papers/module-build-convert
3590 I'm frequently irritated with the CPAN shell's inability to help me
3591 select a good mirror.
3593 The urllist config parameter is yours. You can add and remove sites at
3594 will. You should find out which sites have the best uptodateness,
3595 bandwidth, reliability, etc. and are topologically close to you. Some
3596 people prefer fast downloads, others uptodateness, others reliability.
3597 You decide which to try in which order.
3599 Henk P. Penning maintains a site that collects data about CPAN sites:
3601 http://www.cs.uu.nl/people/henkp/mirmon/cpan.html
3603 Also, feel free to play with experimental features. Run
3605 o conf init randomize_urllist ftpstats_period ftpstats_size
3607 and choose your favorite parameters. After a few downloads running the
3608 C<hosts> command will probably assist you in choosing the best mirror
3613 Why do I get asked the same questions every time I start the shell?
3615 You can make your configuration changes permanent by calling the
3616 command C<o conf commit>. Alternatively set the C<auto_commit>
3617 variable to true by running C<o conf init auto_commit> and answering
3618 the following question with yes.
3622 Older versions of CPAN.pm had the original root directory of all
3623 tarballs in the build directory. Now there are always random
3624 characters appended to these directory names. Why was this done?
3626 The random characters are provided by File::Temp and ensure that each
3627 module's individual build directory is unique. This makes running
3628 CPAN.pm in concurrent processes simultaneously safe.
3632 Speaking of the build directory. Do I have to clean it up myself?
3634 You have the choice to set the config variable C<scan_cache> to
3635 C<never>. Then you must clean it up yourself. The other possible
3636 value, C<atstart> only cleans up the build directory when you start
3637 the CPAN shell. If you never start up the CPAN shell, you probably
3638 also have to clean up the build directory yourself.
3642 =head1 COMPATIBILITY
3644 =head2 OLD PERL VERSIONS
3646 CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted
3647 newer versions. It is getting more and more difficult to get the
3648 minimal prerequisites working on older perls. It is close to
3649 impossible to get the whole Bundle::CPAN working there. If you're in
3650 the position to have only these old versions, be advised that CPAN is
3651 designed to work fine without the Bundle::CPAN installed.
3653 To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
3654 compatible with ancient perls and that File::Temp is listed as a
3655 prerequisite but CPAN has reasonable workarounds if it is missing.
3659 This module and its competitor, the CPANPLUS module, are both much
3660 cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
3661 more modular, but it was never intended to be compatible with CPAN.pm.
3663 =head1 SECURITY ADVICE
3665 This software enables you to upgrade software on your computer and so
3666 is inherently dangerous because the newly installed software may
3667 contain bugs and may alter the way your computer works or even make it
3668 unusable. Please consider backing up your data before every upgrade.
3672 Please report bugs via L<http://rt.cpan.org/>
3674 Before submitting a bug, please make sure that the traditional method
3675 of building a Perl module package from a shell by following the
3676 installation instructions of that package still works in your
3681 Andreas Koenig C<< <andk@cpan.org> >>
3685 This program is free software; you can redistribute it and/or
3686 modify it under the same terms as Perl itself.
3688 See L<http://www.perl.com/perl/misc/Artistic.html>
3692 Kawai,Takanori provides a Japanese translation of this manpage at
3693 L<http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
3697 L<cpan>, L<CPAN::Nox>, L<CPAN::Version>