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