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