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