Commit | Line | Data |
---|---|---|
44d21104 | 1 | # -*- Mode: cperl; coding: utf-8; cperl-indent-level: 4 -*- |
5254b38e | 2 | # vim: ts=4 sts=4 sw=4: |
e82b9348 | 3 | use strict; |
8962fc49 | 4 | package CPAN; |
5930c76e | 5 | $CPAN::VERSION = '1.9600'; |
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 | |
10 | use File::Spec (); | |
11 | BEGIN { | |
12 | if (File::Spec->can("rel2abs")) { | |
13 | for my $inc (@INC) { | |
14 | $inc = File::Spec->rel2abs($inc) unless ref $inc; | |
15 | } | |
16 | } | |
17 | } | |
f9916dde | 18 | use CPAN::Author; |
e82b9348 | 19 | use CPAN::HandleConfig; |
554a9ef5 | 20 | use CPAN::Version; |
f9916dde A |
21 | use CPAN::Bundle; |
22 | use CPAN::CacheMgr; | |
23 | use CPAN::Complete; | |
e82b9348 | 24 | use CPAN::Debug; |
f9916dde A |
25 | use CPAN::Distribution; |
26 | use CPAN::Distrostatus; | |
27 | use CPAN::FTP; | |
2f2071b1 | 28 | use CPAN::Index 1.93; # https://rt.cpan.org/Ticket/Display.html?id=43349 |
f9916dde A |
29 | use CPAN::InfoObj; |
30 | use CPAN::Module; | |
31 | use CPAN::Prompt; | |
32 | use CPAN::URL; | |
135a59c2 | 33 | use CPAN::Queue; |
e82b9348 | 34 | use CPAN::Tarzip; |
f9916dde A |
35 | use CPAN::DeferredCode; |
36 | use CPAN::Shell; | |
37 | use CPAN::LWP::UserAgent; | |
38 | use CPAN::Exception::RecursiveDependency; | |
39 | use CPAN::Exception::yaml_not_installed; | |
40 | ||
5f05dabc | 41 | use Carp (); |
42 | use Config (); | |
5254b38e | 43 | use Cwd qw(chdir); |
0cf35e6a | 44 | use DirHandle (); |
5f05dabc | 45 | use Exporter (); |
b96578bb SP |
46 | use ExtUtils::MakeMaker qw(prompt); # for some unknown reason, |
47 | # 5.005_04 does not work without | |
48 | # this | |
5f05dabc | 49 | use File::Basename (); |
10b2abe6 | 50 | use File::Copy (); |
5f05dabc | 51 | use File::Find; |
52 | use File::Path (); | |
da199366 | 53 | use FileHandle (); |
05bab18e | 54 | use Fcntl qw(:flock); |
5f05dabc | 55 | use Safe (); |
0cf35e6a | 56 | use Sys::Hostname qw(hostname); |
10b2abe6 | 57 | use Text::ParseWords (); |
0cf35e6a | 58 | use Text::Wrap (); |
8962fc49 | 59 | |
5254b38e | 60 | # protect against "called too early" |
b03f445c | 61 | sub find_perl (); |
5254b38e | 62 | sub anycwd (); |
f9916dde | 63 | sub _uniq; |
b03f445c | 64 | |
8962fc49 | 65 | no lib "."; |
5f05dabc | 66 | |
be708cc0 | 67 | require Mac::BuildTools if $^O eq 'MacOS'; |
5254b38e SP |
68 | if ($ENV{PERL5_CPAN_IS_RUNNING} && $$ != $ENV{PERL5_CPAN_IS_RUNNING}) { |
69 | $ENV{PERL5_CPAN_IS_RUNNING_IN_RECURSION} ||= $ENV{PERL5_CPAN_IS_RUNNING}; | |
f9916dde A |
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 |
100 | END { $CPAN::End++; &cleanup; } |
101 | ||
da199366 | 102 | $CPAN::Signal ||= 0; |
c356248b | 103 | $CPAN::Frontend ||= "CPAN::Shell"; |
f04ea8d1 | 104 | unless (@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 |
119 | use 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 |
174 | sub 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 A |
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 A |
248 | sub _uniq { |
249 | my(@list) = @_; | |
250 | my %seen; | |
2f2071b1 | 251 | return grep { !$seen{$_}++ } @list; |
f9916dde A |
252 | } |
253 | ||
55e314ee A |
254 | #-> sub CPAN::shell ; |
255 | sub 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 A |
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 A |
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 | 315 | cpan shell -- CPAN exploration and modules installation (v%s) |
6b1bef9a | 316 | Enter '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 A |
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 A |
380 | if ($command_error) { |
381 | my $err = $command_error; | |
2f2071b1 A |
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 A |
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 A |
477 | } |
478 | ||
ecc7fca0 | 479 | #-> CPAN::soft_chdir_with_alternatives ; |
0cf35e6a SP |
480 | sub 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! | |
485 | Trying '$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]": $! | |
495 | Trying 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 |
505 | sub _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 | 518 | sub _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 |
545 | sub _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)) { |
12ad1f85 | 550 | # temporarily enable yaml code deserialisation |
f04ea8d1 SP |
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 |
585 | sub _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 | 612 | sub _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 |
643 | sub _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 |
671 | sub 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 | 688 | sub all_objects { |
5f05dabc | 689 | my($mgr,$class) = @_; |
e82b9348 | 690 | CPAN::HandleConfig->load unless $CPAN::Config_loaded++; |
5f05dabc | 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 | 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 | 702 | sub 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 | 731 | There 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 |
741 | Please 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 A |
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(" | |
755 | You 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 |
796 | Working directory $symlinkcpan created. |
797 | }); | |
ed84aac9 A |
798 | } |
799 | } | |
800 | unless (-d $dotcpan) { | |
801 | my $mess = qq{ | |
36263cb3 GS |
802 | Your configuration suggests "$dotcpan" as your |
803 | CPAN.pm working directory. I could not create this directory due | |
804 | to this error: $firsterror\n}; | |
ed84aac9 | 805 | $mess .= qq{ |
36263cb3 GS |
806 | As "$dotcpan" is a symlink to "$symlinkcpan", |
807 | I tried to create that, but I failed with this error: $seconderror | |
808 | } if $seconderror; | |
ed84aac9 | 809 | $mess .= qq{ |
36263cb3 GS |
810 | Please 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 | 827 | |
828 | Your configuration suggests that CPAN.pm should use a working | |
829 | directory of | |
830 | $CPAN::Config->{cpan_home} | |
831 | Unfortunately we could not create the lock file | |
832 | $lockfile | |
0f848f67 | 833 | due to '$!'. |
5f05dabc | 834 | |
835 | Please make sure that the configuration variable | |
836 | \$CPAN::Config->{cpan_home} | |
837 | points to a directory where you can write a .lock file. You can set | |
87892b73 RGS |
838 | this 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 | 898 | } |
899 | ||
10b2abe6 | 900 | #-> sub CPAN::DESTROY ; |
5f05dabc | 901 | sub DESTROY { |
902 | &cleanup; # need an eval? | |
903 | } | |
904 | ||
9d61fa1d A |
905 | #-> sub CPAN::anycwd ; |
906 | sub anycwd () { | |
907 | my $getcwd; | |
908 | $getcwd = $CPAN::Config->{'getcwd'} || 'cwd'; | |
909 | CPAN->$getcwd(); | |
910 | } | |
911 | ||
55e314ee A |
912 | #-> sub CPAN::cwd ; |
913 | sub cwd {Cwd::cwd();} | |
914 | ||
915 | #-> sub CPAN::getcwd ; | |
916 | sub getcwd {Cwd::getcwd();} | |
917 | ||
ca79d794 SP |
918 | #-> sub CPAN::fastcwd ; |
919 | sub fastcwd {Cwd::fastcwd();} | |
920 | ||
921 | #-> sub CPAN::backtickcwd ; | |
922 | sub backtickcwd {my $cwd = `cwd`; chomp $cwd; $cwd} | |
923 | ||
0f848f67 CBW |
924 | # Adapted from Probe::Perl |
925 | #-> sub CPAN::_perl_is_same | |
926 | sub _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 | 934 | sub 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 | 972 | sub 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 | 987 | } |
988 | ||
09d9d230 A |
989 | #-> sub CPAN::delete ; |
990 | sub 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 | |
999 | sub 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 | # | |
12ad1f85 DG |
1010 | 'CPAN::Meta' => [ |
1011 | sub { | |
1012 | require CPAN::Meta; | |
1013 | unless (CPAN::Version->vge(CPAN::Meta->VERSION, 2.110350)) { | |
1014 | for ("Will not use CPAN::Meta, need version 2.110350\n") { | |
1015 | $CPAN::Frontend->mywarn($_); | |
1016 | die $_; | |
1017 | } | |
1018 | } | |
1019 | }, | |
1020 | ], | |
7b8f75d3 | 1021 | |
6d29edf5 JH |
1022 | LWP => [ # we frequently had "Can't locate object |
1023 | # method "new" via package "LWP::UserAgent" at | |
1024 | # (eval 69) line 2006 | |
1025 | sub {require LWP}, | |
1026 | sub {require LWP::UserAgent}, | |
1027 | sub {require HTTP::Request}, | |
7b8f75d3 JV |
1028 | sub {require URI::URL; |
1029 | unless (CPAN::Version->vge(URI::URL::->VERSION,0.08)) { | |
1030 | for ("Will not use URI::URL, need 0.08\n") { | |
1031 | $CPAN::Frontend->mywarn($_); | |
1032 | die $_; | |
1033 | } | |
1034 | } | |
1035 | }, | |
6d29edf5 | 1036 | ], |
ec5fee46 | 1037 | 'Net::FTP' => [ |
6d29edf5 JH |
1038 | sub {require Net::FTP}, |
1039 | sub {require Net::Config}, | |
87892b73 | 1040 | ], |
a52237f3 DG |
1041 | 'HTTP::Tiny' => [ |
1042 | sub { | |
1043 | require HTTP::Tiny; | |
1044 | unless (CPAN::Version->vge(HTTP::Tiny->VERSION, 0.005)) { | |
1045 | for ("Will not use HTTP::Tiny, need version 0.005\n") { | |
1046 | $CPAN::Frontend->mywarn($_); | |
1047 | die $_; | |
1048 | } | |
1049 | } | |
1050 | }, | |
1051 | ], | |
87892b73 RGS |
1052 | 'File::HomeDir' => [ |
1053 | sub {require File::HomeDir; | |
64a589f6 DG |
1054 | unless (CPAN::Version->vge(File::HomeDir::->VERSION, 0.52)) { |
1055 | for ("Will not use File::HomeDir, need 0.52\n") { | |
ed84aac9 | 1056 | $CPAN::Frontend->mywarn($_); |
87892b73 RGS |
1057 | die $_; |
1058 | } | |
1059 | } | |
1060 | }, | |
1061 | ], | |
f20de9f0 SP |
1062 | 'Archive::Tar' => [ |
1063 | sub {require Archive::Tar; | |
7b8f75d3 JV |
1064 | my $demand = "1.50"; |
1065 | unless (CPAN::Version->vge(Archive::Tar::->VERSION, $demand)) { | |
1066 | my $atv = Archive::Tar->VERSION; | |
1067 | for ("You have Archive::Tar $atv, but $demand or later is recommended. Please upgrade.\n") { | |
f20de9f0 | 1068 | $CPAN::Frontend->mywarn($_); |
0124e695 JV |
1069 | # don't die, because we may need |
1070 | # Archive::Tar to upgrade | |
f20de9f0 | 1071 | } |
7b8f75d3 | 1072 | |
6b1bef9a | 1073 | } |
f20de9f0 SP |
1074 | }, |
1075 | ], | |
b03f445c RGS |
1076 | 'File::Temp' => [ |
1077 | # XXX we should probably delete from | |
1078 | # %INC too so we can load after we | |
1079 | # installed a new enough version -- | |
1080 | # I'm not sure. | |
1081 | sub {require File::Temp; | |
1082 | unless (CPAN::Version->vge(File::Temp::->VERSION,0.16)) { | |
1083 | for ("Will not use File::Temp, need 0.16\n") { | |
1084 | $CPAN::Frontend->mywarn($_); | |
1085 | die $_; | |
1086 | } | |
1087 | } | |
1088 | }, | |
1089 | ] | |
6d29edf5 JH |
1090 | }; |
1091 | if ($usable->{$mod}) { | |
87892b73 RGS |
1092 | for my $c (0..$#{$usable->{$mod}}) { |
1093 | my $code = $usable->{$mod}[$c]; | |
1094 | my $ret = eval { &$code() }; | |
1095 | $ret = "" unless defined $ret; | |
1096 | if ($@) { | |
1097 | # warn "DEBUG: c[$c]\$\@[$@]ret[$ret]"; | |
1098 | return; | |
1099 | } | |
de34a54b | 1100 | } |
de34a54b JH |
1101 | } |
1102 | return $HAS_USABLE->{$mod} = 1; | |
1103 | } | |
1104 | ||
55e314ee A |
1105 | #-> sub CPAN::has_inst |
1106 | sub has_inst { | |
1107 | my($self,$mod,$message) = @_; | |
1108 | Carp::croak("CPAN->has_inst() called without an argument") | |
f04ea8d1 | 1109 | unless defined $mod; |
4d1321a7 A |
1110 | my %dont = map { $_ => 1 } keys %{$CPAN::META->{dontload_hash}||{}}, |
1111 | keys %{$CPAN::Config->{dontload_hash}||{}}, | |
1112 | @{$CPAN::Config->{dontload_list}||[]}; | |
1113 | if (defined $message && $message eq "no" # afair only used by Nox | |
de34a54b | 1114 | || |
4d1321a7 | 1115 | $dont{$mod} |
de34a54b | 1116 | ) { |
6d29edf5 | 1117 | $CPAN::META->{dontload_hash}{$mod}||=1; # unsafe meta access, ok |
de34a54b | 1118 | return 0; |
55e314ee A |
1119 | } |
1120 | my $file = $mod; | |
c356248b | 1121 | my $obj; |
55e314ee | 1122 | $file =~ s|::|/|g; |
55e314ee | 1123 | $file .= ".pm"; |
c356248b | 1124 | if ($INC{$file}) { |
f04ea8d1 SP |
1125 | # checking %INC is wrong, because $INC{LWP} may be true |
1126 | # although $INC{"URI/URL.pm"} may have failed. But as | |
1127 | # I really want to say "bla loaded OK", I have to somehow | |
1128 | # cache results. | |
1129 | ### warn "$file in %INC"; #debug | |
1130 | return 1; | |
55e314ee | 1131 | } elsif (eval { require $file }) { |
f04ea8d1 SP |
1132 | # eval is good: if we haven't yet read the database it's |
1133 | # perfect and if we have installed the module in the meantime, | |
1134 | # it tries again. The second require is only a NOOP returning | |
1135 | # 1 if we had success, otherwise it's retrying | |
1136 | ||
1137 | my $mtime = (stat $INC{$file})[9]; | |
1138 | # privileged files loaded by has_inst; Note: we use $mtime | |
1139 | # as a proxy for a checksum. | |
1140 | $CPAN::Shell::reload->{$file} = $mtime; | |
6a935156 SP |
1141 | my $v = eval "\$$mod\::VERSION"; |
1142 | $v = $v ? " (v$v)" : ""; | |
f9916dde A |
1143 | CPAN::Shell->optprint("load_module","CPAN: $mod loaded ok$v\n"); |
1144 | if ($mod eq "CPAN::WAIT") { | |
1145 | push @CPAN::Shell::ISA, 'CPAN::WAIT'; | |
554a9ef5 | 1146 | } |
f9916dde A |
1147 | return 1; |
1148 | } elsif ($mod eq "Net::FTP") { | |
1149 | $CPAN::Frontend->mywarn(qq{ | |
1150 | Please, install Net::FTP as soon as possible. CPAN.pm installs it for you | |
1151 | if you just type | |
1152 | install Bundle::libnet | |
1153 | ||
1154 | }) unless $Have_warned->{"Net::FTP"}++; | |
1155 | $CPAN::Frontend->mysleep(3); | |
1156 | } elsif ($mod eq "Digest::SHA") { | |
1157 | if ($Have_warned->{"Digest::SHA"}++) { | |
1158 | $CPAN::Frontend->mywarn(qq{CPAN: checksum security checks disabled }. | |
1159 | qq{because Digest::SHA not installed.\n}); | |
9d61fa1d | 1160 | } else { |
f9916dde A |
1161 | $CPAN::Frontend->mywarn(qq{ |
1162 | CPAN: checksum security checks disabled because Digest::SHA not installed. | |
1163 | Please consider installing the Digest::SHA module. | |
5f05dabc | 1164 | |
f9916dde A |
1165 | }); |
1166 | $CPAN::Frontend->mysleep(2); | |
f04ea8d1 | 1167 | } |
f9916dde A |
1168 | } elsif ($mod eq "Module::Signature") { |
1169 | # NOT prefs_lookup, we are not a distro | |
1170 | my $check_sigs = $CPAN::Config->{check_sigs}; | |
1171 | if (not $check_sigs) { | |
1172 | # they do not want us:-( | |
1173 | } elsif (not $Have_warned->{"Module::Signature"}++) { | |
1174 | # No point in complaining unless the user can | |
1175 | # reasonably install and use it. | |
1176 | if (eval { require Crypt::OpenPGP; 1 } || | |
1177 | ( | |
1178 | defined $CPAN::Config->{'gpg'} | |
1179 | && | |
1180 | $CPAN::Config->{'gpg'} =~ /\S/ | |
1181 | ) | |
1182 | ) { | |
1183 | $CPAN::Frontend->mywarn(qq{ | |
1184 | CPAN: Module::Signature security checks disabled because Module::Signature | |
1185 | not installed. Please consider installing the Module::Signature module. | |
1186 | You may also need to be able to connect over the Internet to the public | |
12ad1f85 | 1187 | key servers like pool.sks-keyservers.net or pgp.mit.edu. |
09d9d230 | 1188 | |
f9916dde A |
1189 | }); |
1190 | $CPAN::Frontend->mysleep(2); | |
8d97e4a1 | 1191 | } |
8d97e4a1 | 1192 | } |
f9916dde A |
1193 | } else { |
1194 | delete $INC{$file}; # if it inc'd LWP but failed during, say, URI | |
5f05dabc | 1195 | } |
f9916dde | 1196 | return 0; |
5f05dabc | 1197 | } |
1198 | ||
f9916dde A |
1199 | #-> sub CPAN::instance ; |
1200 | sub instance { | |
1201 | my($mgr,$class,$id) = @_; | |
1202 | CPAN::Index->reload; | |
1203 | $id ||= ""; | |
1204 | # unsafe meta access, ok? | |
1205 | return $META->{readwrite}{$class}{$id} if exists $META->{readwrite}{$class}{$id}; | |
1206 | $META->{readwrite}{$class}{$id} ||= $class->new(ID => $id); | |
c356248b | 1207 | } |
5f05dabc | 1208 | |
f9916dde A |
1209 | #-> sub CPAN::new ; |
1210 | sub new { | |
1211 | bless {}, shift; | |
b72dd56f SP |
1212 | } |
1213 | ||
a52237f3 DG |
1214 | #-> sub CPAN::_exit_messages ; |
1215 | sub _exit_messages { | |
1216 | my ($self) = @_; | |
1217 | $self->{exit_messages} ||= []; | |
1218 | } | |
1219 | ||
f9916dde A |
1220 | #-> sub CPAN::cleanup ; |
1221 | sub cleanup { | |
1222 | # warn "cleanup called with arg[@_] End[$CPAN::End] Signal[$Signal]"; | |
1223 | local $SIG{__DIE__} = ''; | |
1224 | my($message) = @_; | |
1225 | my $i = 0; | |
1226 | my $ineval = 0; | |
1227 | my($subroutine); | |
1228 | while ((undef,undef,undef,$subroutine) = caller(++$i)) { | |
1229 | $ineval = 1, last if | |
1230 | $subroutine eq '(eval)'; | |
1231 | } | |
1232 | return if $ineval && !$CPAN::End; | |
1233 | return unless defined $META->{LOCK}; | |
1234 | return unless -f $META->{LOCK}; | |
1235 | $META->savehist; | |
a52237f3 | 1236 | $META->{cachemgr} ||= CPAN::CacheMgr->new('atexit'); |
f9916dde A |
1237 | close $META->{LOCKFH}; |
1238 | unlink $META->{LOCK}; | |
1239 | # require Carp; | |
1240 | # Carp::cluck("DEBUGGING"); | |
1241 | if ( $CPAN::CONFIG_DIRTY ) { | |
1242 | $CPAN::Frontend->mywarn("Warning: Configuration not saved.\n"); | |
1243 | } | |
1244 | $CPAN::Frontend->myprint("Lockfile removed.\n"); | |
a52237f3 DG |
1245 | for my $msg ( @{ $META->_exit_messages } ) { |
1246 | $CPAN::Frontend->myprint($msg); | |
1247 | } | |
5f05dabc | 1248 | } |
1249 | ||
f9916dde A |
1250 | #-> sub CPAN::readhist |
1251 | sub readhist { | |
1252 | my($self,$term,$histfile) = @_; | |
1253 | my $histsize = $CPAN::Config->{'histsize'} || 100; | |
1254 | $term->Attribs->{'MaxHistorySize'} = $histsize if (defined($term->Attribs->{'MaxHistorySize'})); | |
1255 | my($fh) = FileHandle->new; | |
1256 | open $fh, "<$histfile" or return; | |
1257 | local $/ = "\n"; | |
1258 | while (<$fh>) { | |
1259 | chomp; | |
1260 | $term->AddHistory($_); | |
1261 | } | |
1262 | close $fh; | |
554a9ef5 SP |
1263 | } |
1264 | ||
f9916dde A |
1265 | #-> sub CPAN::savehist |
1266 | sub savehist { | |
1267 | my($self) = @_; | |
1268 | my($histfile,$histsize); | |
1269 | unless ($histfile = $CPAN::Config->{'histfile'}) { | |
1270 | $CPAN::Frontend->mywarn("No history written (no histfile specified).\n"); | |
f04ea8d1 | 1271 | return; |
09d9d230 | 1272 | } |
f9916dde A |
1273 | $histsize = $CPAN::Config->{'histsize'} || 100; |
1274 | if ($CPAN::term) { | |
1275 | unless ($CPAN::term->can("GetHistory")) { | |
1276 | $CPAN::Frontend->mywarn("Terminal does not support GetHistory.\n"); | |
1277 | return; | |
135a59c2 | 1278 | } |
f610777f | 1279 | } else { |
f9916dde | 1280 | return; |
5254b38e | 1281 | } |
f9916dde A |
1282 | my @h = $CPAN::term->GetHistory; |
1283 | splice @h, 0, @h-$histsize if @h>$histsize; | |
1284 | my($fh) = FileHandle->new; | |
1285 | open $fh, ">$histfile" or $CPAN::Frontend->mydie("Couldn't open >$histfile: $!"); | |
1286 | local $\ = local $, = "\n"; | |
1287 | print $fh @h; | |
1288 | close $fh; | |
810a0276 SP |
1289 | } |
1290 | ||
f9916dde A |
1291 | #-> sub CPAN::is_tested |
1292 | sub is_tested { | |
1293 | my($self,$what,$when) = @_; | |
1294 | unless ($what) { | |
1295 | Carp::cluck("DEBUG: empty what"); | |
1296 | return; | |
5f05dabc | 1297 | } |
f9916dde | 1298 | $self->{is_tested}{$what} = $when; |
5f05dabc | 1299 | } |
1300 | ||
f9916dde A |
1301 | #-> sub CPAN::reset_tested |
1302 | # forget all distributions tested -- resets what gets included in PERL5LIB | |
1303 | sub reset_tested { | |
1304 | my ($self) = @_; | |
1305 | $self->{is_tested} = {}; | |
5f05dabc | 1306 | } |
1307 | ||
f9916dde A |
1308 | #-> sub CPAN::is_installed |
1309 | # unsets the is_tested flag: as soon as the thing is installed, it is | |
1310 | # not needed in set_perl5lib anymore | |
1311 | sub is_installed { | |
1312 | my($self,$what) = @_; | |
1313 | delete $self->{is_tested}{$what}; | |
810a0276 SP |
1314 | } |
1315 | ||
f9916dde | 1316 | sub _list_sorted_descending_is_tested { |
810a0276 | 1317 | my($self) = @_; |
f9916dde A |
1318 | sort |
1319 | { ($self->{is_tested}{$b}||0) <=> ($self->{is_tested}{$a}||0) } | |
1320 | keys %{$self->{is_tested}} | |
810a0276 | 1321 | } |
de34a54b | 1322 | |
f9916dde A |
1323 | #-> sub CPAN::set_perl5lib |
1324 | # Notes on max environment variable length: | |
1325 | # - Win32 : XP or later, 8191; Win2000 or NT4, 2047 | |
1326 | { | |
1327 | my $fh; | |
1328 | sub set_perl5lib { | |
1329 | my($self,$for) = @_; | |
1330 | unless ($for) { | |
1331 | (undef,undef,undef,$for) = caller(1); | |
1332 | $for =~ s/.*://; | |
5254b38e | 1333 | } |
f9916dde A |
1334 | $self->{is_tested} ||= {}; |
1335 | return unless %{$self->{is_tested}}; | |
1336 | my $env = $ENV{PERL5LIB}; | |
1337 | $env = $ENV{PERLLIB} unless defined $env; | |
1338 | my @env; | |
1339 | push @env, split /\Q$Config::Config{path_sep}\E/, $env if defined $env and length $env; | |
1340 | #my @dirs = map {("$_/blib/arch", "$_/blib/lib")} keys %{$self->{is_tested}}; | |
1341 | #$CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB.\n"); | |
c4d24d4c | 1342 | |
f9916dde A |
1343 | my @dirs = map {("$_/blib/arch", "$_/blib/lib")} $self->_list_sorted_descending_is_tested; |
1344 | return if !@dirs; | |
5f05dabc | 1345 | |
f9916dde A |
1346 | if (@dirs < 12) { |
1347 | $CPAN::Frontend->optprint('perl5lib', "Prepending @dirs to PERL5LIB for '$for'\n"); | |
1348 | $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env; | |
1349 | } elsif (@dirs < 24 ) { | |
1350 | my @d = map {my $cp = $_; | |
1351 | $cp =~ s/^\Q$CPAN::Config->{build_dir}\E/%BUILDDIR%/; | |
1352 | $cp | |
1353 | } @dirs; | |
1354 | $CPAN::Frontend->optprint('perl5lib', "Prepending @d to PERL5LIB; ". | |
1355 | "%BUILDDIR%=$CPAN::Config->{build_dir} ". | |
1356 | "for '$for'\n" | |
1357 | ); | |
1358 | $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env; | |
1359 | } else { | |
1360 | my $cnt = keys %{$self->{is_tested}}; | |
1361 | $CPAN::Frontend->optprint('perl5lib', "Prepending blib/arch and blib/lib of ". | |
1362 | "$cnt build dirs to PERL5LIB; ". | |
1363 | "for '$for'\n" | |
1364 | ); | |
1365 | $ENV{PERL5LIB} = join $Config::Config{path_sep}, @dirs, @env; | |
1366 | } | |
1367 | }} | |
dc053c64 | 1368 | |
d4fd5c69 | 1369 | |
5f05dabc | 1370 | 1; |
55e314ee | 1371 | |
ed84aac9 | 1372 | |
e50380aa | 1373 | __END__ |
5f05dabc | 1374 | |
1375 | =head1 NAME | |
1376 | ||
1377 | CPAN - query, download and build perl modules from CPAN sites | |
1378 | ||
1379 | =head1 SYNOPSIS | |
1380 | ||
1381 | Interactive mode: | |
1382 | ||
f20de9f0 | 1383 | perl -MCPAN -e shell |
5f05dabc | 1384 | |
f20de9f0 | 1385 | --or-- |
5f05dabc | 1386 | |
f20de9f0 SP |
1387 | cpan |
1388 | ||
1389 | Basic commands: | |
5f05dabc | 1390 | |
1e8f9a0a SP |
1391 | # Modules: |
1392 | ||
1393 | cpan> install Acme::Meta # in the shell | |
1394 | ||
1395 | CPAN::Shell->install("Acme::Meta"); # in perl | |
1396 | ||
1397 | # Distributions: | |
1398 | ||
1399 | cpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell | |
1400 | ||
1401 | CPAN::Shell-> | |
1402 | install("NWCLARK/Acme-Meta-0.02.tar.gz"); # in perl | |
1403 | ||
1404 | # module objects: | |
c9869e1c | 1405 | |
1e8f9a0a SP |
1406 | $mo = CPAN::Shell->expandany($mod); |
1407 | $mo = CPAN::Shell->expand("Module",$mod); # same thing | |
c9869e1c | 1408 | |
1e8f9a0a | 1409 | # distribution objects: |
c9869e1c | 1410 | |
1e8f9a0a SP |
1411 | $do = CPAN::Shell->expand("Module",$mod)->distribution; |
1412 | $do = CPAN::Shell->expandany($distro); # same thing | |
1413 | $do = CPAN::Shell->expand("Distribution", | |
1414 | $distro); # same thing | |
5f05dabc | 1415 | |
1416 | =head1 DESCRIPTION | |
1417 | ||
f20de9f0 SP |
1418 | The CPAN module automates or at least simplifies the make and install |
1419 | of perl modules and extensions. It includes some primitive searching | |
a52237f3 DG |
1420 | capabilities and knows how to use LWP, HTTP::Tiny, Net::FTP and certain |
1421 | external download clients to fetch distributions from the net. | |
5f05dabc | 1422 | |
f9916dde | 1423 | These are fetched from one or more mirrored CPAN (Comprehensive |
f20de9f0 | 1424 | Perl Archive Network) sites and unpacked in a dedicated directory. |
5f05dabc | 1425 | |
f9916dde A |
1426 | The CPAN module also supports named and versioned |
1427 | I<bundles> of modules. Bundles simplify handling of sets of | |
911a92db | 1428 | related modules. See Bundles below. |
5f05dabc | 1429 | |
b72dd56f | 1430 | The package contains a session manager and a cache manager. The |
f9916dde | 1431 | session manager keeps track of what has been fetched, built, and |
b72dd56f SP |
1432 | installed in the current session. The cache manager keeps track of the |
1433 | disk space occupied by the make processes and deletes excess space | |
f9916dde | 1434 | using a simple FIFO mechanism. |
5f05dabc | 1435 | |
c9869e1c | 1436 | All methods provided are accessible in a programmer style and in an |
10b2abe6 CS |
1437 | interactive shell style. |
1438 | ||
2ccf00a7 | 1439 | =head2 CPAN::shell([$prompt, $command]) Starting Interactive Mode |
5f05dabc | 1440 | |
f9916dde | 1441 | Enter interactive mode by running |
5f05dabc | 1442 | |
1443 | perl -MCPAN -e shell | |
1444 | ||
f20de9f0 SP |
1445 | or |
1446 | ||
1447 | cpan | |
1448 | ||
1449 | which puts you into a readline interface. If C<Term::ReadKey> and | |
f9916dde A |
1450 | either of C<Term::ReadLine::Perl> or C<Term::ReadLine::Gnu> are installed, |
1451 | history and command completion are supported. | |
5f05dabc | 1452 | |
f9916dde A |
1453 | Once at the command line, type C<h> for one-page help |
1454 | screen; the rest should be self-explanatory. | |
5f05dabc | 1455 | |
f9916dde A |
1456 | The function call C<shell> takes two optional arguments: one the |
1457 | prompt, the second the default initial command line (the latter | |
9d61fa1d A |
1458 | only works if a real ReadLine interface module is installed). |
1459 | ||
10b2abe6 CS |
1460 | The most common uses of the interactive modes are |
1461 | ||
1462 | =over 2 | |
1463 | ||
1464 | =item Searching for authors, bundles, distribution files and modules | |
1465 | ||
1466 | There are corresponding one-letter commands C<a>, C<b>, C<d>, and C<m> | |
42d3b621 A |
1467 | for each of the four categories and another, C<i> for any of the |
1468 | mentioned four. Each of the four entities is implemented as a class | |
1469 | with slightly differing methods for displaying an object. | |
10b2abe6 | 1470 | |
f9916dde A |
1471 | Arguments to these commands are either strings exactly matching |
1472 | the identification string of an object, or regular expressions | |
1473 | matched case-insensitively against various attributes of the | |
1474 | objects. The parser only recognizes a regular expression when you | |
1475 | enclose it with slashes. | |
10b2abe6 | 1476 | |
f9916dde | 1477 | The principle is that the number of objects found influences how an |
911a92db | 1478 | item is displayed. If the search finds one item, the result is |
f9916dde A |
1479 | displayed with the rather verbose method C<as_string>, but if |
1480 | more than one is found, each object is displayed with the terse method | |
c9869e1c | 1481 | C<as_glimpse>. |
10b2abe6 | 1482 | |
5254b38e SP |
1483 | Examples: |
1484 | ||
1485 | cpan> m Acme::MetaSyntactic | |
1486 | Module id = Acme::MetaSyntactic | |
1487 | CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>) | |
1488 | CPAN_VERSION 0.99 | |
1489 | CPAN_FILE B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz | |
1490 | UPLOAD_DATE 2006-11-06 | |
1491 | MANPAGE Acme::MetaSyntactic - Themed metasyntactic variables names | |
1492 | INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm | |
1493 | INST_VERSION 0.99 | |
1494 | cpan> a BOOK | |
1495 | Author id = BOOK | |
1496 | EMAIL [...] | |
1497 | FULLNAME Philippe Bruhat (BooK) | |
1498 | cpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz | |
1499 | Distribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz | |
1500 | CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>) | |
1501 | CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...] | |
1502 | UPLOAD_DATE 2006-11-06 | |
1503 | cpan> m /lorem/ | |
1504 | Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz) | |
1505 | Module Text::Lorem (ADEOLA/Text-Lorem-0.3.tar.gz) | |
1506 | Module Text::Lorem::More (RKRIMEN/Text-Lorem-More-0.12.tar.gz) | |
1507 | Module Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz) | |
1508 | cpan> i /berlin/ | |
1509 | Distribution BEATNIK/Filter-NumberLines-0.02.tar.gz | |
1510 | Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz) | |
1511 | Module Filter::NumberLines (BEATNIK/Filter-NumberLines-0.02.tar.gz) | |
1512 | Author [...] | |
1513 | ||
1514 | The examples illustrate several aspects: the first three queries | |
1515 | target modules, authors, or distros directly and yield exactly one | |
1516 | result. The last two use regular expressions and yield several | |
1517 | results. The last one targets all of bundles, modules, authors, and | |
1518 | distros simultaneously. When more than one result is available, they | |
1519 | are printed in one-line format. | |
1520 | ||
f20de9f0 | 1521 | =item C<get>, C<make>, C<test>, C<install>, C<clean> modules or distributions |
10b2abe6 | 1522 | |
911a92db | 1523 | These commands take any number of arguments and investigate what is |
0124e695 JV |
1524 | necessary to perform the action. Argument processing is as follows: |
1525 | ||
1526 | known module name in format Foo/Bar.pm module | |
1527 | other embedded slash distribution | |
1528 | - with trailing slash dot directory | |
1529 | enclosing slashes regexp | |
1530 | known module name in format Foo::Bar module | |
1531 | ||
1532 | If the argument is a distribution file name (recognized by embedded | |
1533 | slashes), it is processed. If it is a module, CPAN determines the | |
1534 | distribution file in which this module is included and processes that, | |
1535 | following any dependencies named in the module's META.yml or | |
1536 | Makefile.PL (this behavior is controlled by the configuration | |
1537 | parameter C<prerequisites_policy>). If an argument is enclosed in | |
1538 | slashes it is treated as a regular expression: it is expanded and if | |
1539 | the result is a single object (distribution, bundle or module), this | |
1540 | object is processed. | |
1541 | ||
1542 | Example: | |
1543 | ||
1544 | install Dummy::Perl # installs the module | |
1545 | install AUXXX/Dummy-Perl-3.14.tar.gz # installs that distribution | |
1546 | install /Dummy-Perl-3.14/ # same if the regexp is unambiguous | |
10b2abe6 | 1547 | |
b72dd56f SP |
1548 | C<get> downloads a distribution file and untars or unzips it, C<make> |
1549 | builds it, C<test> runs the test suite, and C<install> installs it. | |
1550 | ||
f9916dde | 1551 | Any C<make> or C<test> is run unconditionally. An |
42d3b621 | 1552 | |
05454584 | 1553 | install <distribution_file> |
42d3b621 | 1554 | |
f9916dde | 1555 | is also run unconditionally. But for |
42d3b621 | 1556 | |
05454584 | 1557 | install <module> |
42d3b621 | 1558 | |
f9916dde A |
1559 | CPAN checks whether an install is needed and prints |
1560 | I<module up to date> if the distribution file containing | |
1561 | the module doesn't need updating. | |
10b2abe6 CS |
1562 | |
1563 | CPAN also keeps track of what it has done within the current session | |
f9916dde | 1564 | and doesn't try to build a package a second time regardless of whether it |
b72dd56f SP |
1565 | succeeded or not. It does not repeat a test run if the test |
1566 | has been run successfully before. Same for install runs. | |
10b2abe6 | 1567 | |
b72dd56f | 1568 | The C<force> pragma may precede another command (currently: C<get>, |
f9916dde A |
1569 | C<make>, C<test>, or C<install>) to execute the command from scratch |
1570 | and attempt to continue past certain errors. See the section below on | |
f20de9f0 | 1571 | the C<force> and the C<fforce> pragma. |
10b2abe6 | 1572 | |
f9916dde | 1573 | The C<notest> pragma skips the test part in the build |
554a9ef5 SP |
1574 | process. |
1575 | ||
1576 | Example: | |
1577 | ||
1578 | cpan> notest install Tk | |
1579 | ||
f610777f | 1580 | A C<clean> command results in a |
09d9d230 A |
1581 | |
1582 | make clean | |
1583 | ||
1584 | being executed within the distribution file's working directory. | |
1585 | ||
f20de9f0 | 1586 | =item C<readme>, C<perldoc>, C<look> module or distribution |
da199366 | 1587 | |
b72dd56f SP |
1588 | C<readme> displays the README file of the associated distribution. |
1589 | C<Look> gets and untars (if not yet done) the distribution file, | |
1590 | changes to the appropriate directory and opens a subshell process in | |
f9916dde A |
1591 | that directory. C<perldoc> displays the module's pod documentation |
1592 | in html or plain text format. | |
09d9d230 | 1593 | |
f20de9f0 | 1594 | =item C<ls> author |
c049f953 | 1595 | |
f20de9f0 | 1596 | =item C<ls> globbing_expression |
e82b9348 SP |
1597 | |
1598 | The first form lists all distribution files in and below an author's | |
f9916dde A |
1599 | CPAN directory as stored in the CHECKUMS files distributed on |
1600 | CPAN. The listing recurses into subdirectories. | |
e82b9348 | 1601 | |
f9916dde | 1602 | The second form limits or expands the output with shell |
e82b9348 SP |
1603 | globbing as in the following examples: |
1604 | ||
f04ea8d1 SP |
1605 | ls JV/make* |
1606 | ls GSAR/*make* | |
1607 | ls */*make* | |
e82b9348 SP |
1608 | |
1609 | The last example is very slow and outputs extra progress indicators | |
1610 | that break the alignment of the result. | |
c049f953 | 1611 | |
ca79d794 SP |
1612 | Note that globbing only lists directories explicitly asked for, for |
1613 | example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be | |
f9916dde | 1614 | regarded as a bug that may be changed in some future version. |
ca79d794 | 1615 | |
f20de9f0 | 1616 | =item C<failed> |
9ddc4ed0 A |
1617 | |
1618 | The C<failed> command reports all distributions that failed on one of | |
1619 | C<make>, C<test> or C<install> for some reason in the currently | |
1620 | running shell session. | |
1621 | ||
b72dd56f SP |
1622 | =item Persistence between sessions |
1623 | ||
b03f445c | 1624 | If the C<YAML> or the C<YAML::Syck> module is installed a record of |
b72dd56f SP |
1625 | the internal state of all modules is written to disk after each step. |
1626 | The files contain a signature of the currently running perl version | |
1627 | for later perusal. | |
1628 | ||
1629 | If the configurations variable C<build_dir_reuse> is set to a true | |
1630 | value, then CPAN.pm reads the collected YAML files. If the stored | |
f9916dde A |
1631 | signature matches the currently running perl, the stored state is |
1632 | loaded into memory such that persistence between sessions | |
1633 | is effectively established. | |
b72dd56f SP |
1634 | |
1635 | =item The C<force> and the C<fforce> pragma | |
1636 | ||
1637 | To speed things up in complex installation scenarios, CPAN.pm keeps | |
1638 | track of what it has already done and refuses to do some things a | |
1639 | second time. A C<get>, a C<make>, and an C<install> are not repeated. | |
f9916dde | 1640 | A C<test> is repeated only if the previous test was unsuccessful. The |
b72dd56f SP |
1641 | diagnostic message when CPAN.pm refuses to do something a second time |
1642 | is one of I<Has already been >C<unwrapped|made|tested successfully> or | |
1643 | something similar. Another situation where CPAN refuses to act is an | |
f9916dde | 1644 | C<install> if the corresponding C<test> was not successful. |
b72dd56f | 1645 | |
f9916dde | 1646 | In all these cases, the user can override this stubborn behaviour by |
b72dd56f SP |
1647 | prepending the command with the word force, for example: |
1648 | ||
1649 | cpan> force get Foo | |
1650 | cpan> force make AUTHOR/Bar-3.14.tar.gz | |
1651 | cpan> force test Baz | |
1652 | cpan> force install Acme::Meta | |
1653 | ||
f9916dde | 1654 | Each I<forced> command is executed with the corresponding part of its |
b72dd56f SP |
1655 | memory erased. |
1656 | ||
1657 | The C<fforce> pragma is a variant that emulates a C<force get> which | |
1658 | erases the entire memory followed by the action specified, effectively | |
1659 | restarting the whole get/make/test/install procedure from scratch. | |
1660 | ||
c9869e1c SP |
1661 | =item Lockfile |
1662 | ||
f9916dde A |
1663 | Interactive sessions maintain a lockfile, by default C<~/.cpan/.lock>. |
1664 | Batch jobs can run without a lockfile and not disturb each other. | |
c9869e1c | 1665 | |
f9916dde | 1666 | The shell offers to run in I<downgraded mode> when another process is |
be34b10d SP |
1667 | holding the lockfile. This is an experimental feature that is not yet |
1668 | tested very well. This second shell then does not write the history | |
f9916dde | 1669 | file, does not use the metadata file, and has a different prompt. |
c9869e1c | 1670 | |
09d9d230 A |
1671 | =item Signals |
1672 | ||
1673 | CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are | |
f9916dde | 1674 | in the cpan-shell, it is intended that you can press C<^C> anytime and |
09d9d230 A |
1675 | return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell |
1676 | to clean up and leave the shell loop. You can emulate the effect of a | |
1677 | SIGTERM by sending two consecutive SIGINTs, which usually means by | |
1678 | pressing C<^C> twice. | |
1679 | ||
f9916dde | 1680 | CPAN.pm ignores SIGPIPE. If the user sets C<inactivity_timeout>, a |
e82b9348 | 1681 | SIGALRM is used during the run of the C<perl Makefile.PL> or C<perl |
0124e695 JV |
1682 | Build.PL> subprocess. A SIGALRM is also used during module version |
1683 | parsing, and is controlled by C<version_timeout>. | |
da199366 | 1684 | |
10b2abe6 CS |
1685 | =back |
1686 | ||
5f05dabc | 1687 | =head2 CPAN::Shell |
1688 | ||
f9916dde A |
1689 | The commands available in the shell interface are methods in |
1690 | the package CPAN::Shell. If you enter the shell command, your | |
1691 | input is split by the Text::ParseWords::shellwords() routine, which | |
1692 | acts like most shells do. The first word is interpreted as the | |
1693 | method to be invoked, and the rest of the words are treated as the method's arguments. | |
1694 | Continuation lines are supported by ending a line with a | |
c356248b | 1695 | literal backslash. |
10b2abe6 | 1696 | |
da199366 A |
1697 | =head2 autobundle |
1698 | ||
1699 | C<autobundle> writes a bundle file into the | |
1700 | C<$CPAN::Config-E<gt>{cpan_home}/Bundle> directory. The file contains | |
1701 | a list of all modules that are both available from CPAN and currently | |
1702 | installed within @INC. The name of the bundle file is based on the | |
1703 | current date and a counter. | |
1704 | ||
05bab18e SP |
1705 | =head2 hosts |
1706 | ||
ed756621 SP |
1707 | Note: this feature is still in alpha state and may change in future |
1708 | versions of CPAN.pm | |
1709 | ||
05bab18e SP |
1710 | This commands provides a statistical overview over recent download |
1711 | activities. The data for this is collected in the YAML file | |
1712 | C<FTPstats.yml> in your C<cpan_home> directory. If no YAML module is | |
f9916dde | 1713 | configured or YAML not installed, no stats are provided. |
05bab18e SP |
1714 | |
1715 | =head2 mkmyconfig | |
1716 | ||
f9916dde | 1717 | mkmyconfig() writes your own CPAN::MyConfig file into your C<~/.cpan/> |
05bab18e | 1718 | directory so that you can save your own preferences instead of the |
f9916dde | 1719 | system-wide ones. |
05bab18e | 1720 | |
f04ea8d1 SP |
1721 | =head2 recent ***EXPERIMENTAL COMMAND*** |
1722 | ||
1723 | The C<recent> command downloads a list of recent uploads to CPAN and | |
f9916dde A |
1724 | displays them I<slowly>. While the command is running, a $SIG{INT} |
1725 | exits the loop after displaying the current item. | |
f04ea8d1 SP |
1726 | |
1727 | B<Note>: This command requires XML::LibXML installed. | |
1728 | ||
5254b38e | 1729 | B<Note>: This whole command currently is just a hack and will |
f9916dde A |
1730 | probably change in future versions of CPAN.pm, but the general |
1731 | approach will likely remain. | |
f04ea8d1 SP |
1732 | |
1733 | B<Note>: See also L<smoke> | |
1734 | ||
da199366 A |
1735 | =head2 recompile |
1736 | ||
f9916dde | 1737 | recompile() is a special command that takes no argument and |
da199366 | 1738 | runs the make/test/install cycle with brute force over all installed |
12ad1f85 | 1739 | dynamically loadable extensions (a.k.a. XS modules) with 'force' in |
09d9d230 | 1740 | effect. The primary purpose of this command is to finish a network |
f9916dde | 1741 | installation. Imagine you have a common source tree for two different |
da199366 A |
1742 | architectures. You decide to do a completely independent fresh |
1743 | installation. You start on one architecture with the help of a Bundle | |
1744 | file produced earlier. CPAN installs the whole Bundle for you, but | |
1745 | when you try to repeat the job on the second architecture, CPAN | |
1746 | responds with a C<"Foo up to date"> message for all modules. So you | |
de34a54b | 1747 | invoke CPAN's recompile on the second architecture and you're done. |
da199366 A |
1748 | |
1749 | Another popular use for C<recompile> is to act as a rescue in case your | |
1750 | perl breaks binary compatibility. If one of the modules that CPAN uses | |
1751 | is in turn depending on binary compatibility (so you cannot run CPAN | |
1752 | commands), then you should try the CPAN::Nox module for recovery. | |
1753 | ||
8fc516fe SP |
1754 | =head2 report Bundle|Distribution|Module |
1755 | ||
1756 | The C<report> command temporarily turns on the C<test_report> config | |
6658a91b | 1757 | variable, then runs the C<force test> command with the given |
f9916dde | 1758 | arguments. The C<force> pragma reruns the tests and repeats |
6658a91b | 1759 | every step that might have failed before. |
8fc516fe | 1760 | |
f04ea8d1 SP |
1761 | =head2 smoke ***EXPERIMENTAL COMMAND*** |
1762 | ||
1763 | B<*** WARNING: this command downloads and executes software from CPAN to | |
b03f445c RGS |
1764 | your computer of completely unknown status. You should never do |
1765 | this with your normal account and better have a dedicated well | |
1766 | separated and secured machine to do this. ***> | |
f04ea8d1 SP |
1767 | |
1768 | The C<smoke> command takes the list of recent uploads to CPAN as | |
1769 | provided by the C<recent> command and tests them all. While the | |
1770 | command is running $SIG{INT} is defined to mean that the current item | |
1771 | shall be skipped. | |
1772 | ||
5254b38e | 1773 | B<Note>: This whole command currently is just a hack and will |
f9916dde A |
1774 | probably change in future versions of CPAN.pm, but the general |
1775 | approach will likely remain. | |
f04ea8d1 SP |
1776 | |
1777 | B<Note>: See also L<recent> | |
1778 | ||
135a59c2 | 1779 | =head2 upgrade [Module|/Regex/]... |
ed84aac9 | 1780 | |
135a59c2 A |
1781 | The C<upgrade> command first runs an C<r> command with the given |
1782 | arguments and then installs the newest versions of all modules that | |
1783 | were listed by that. | |
ed84aac9 | 1784 | |
c356248b | 1785 | =head2 The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution |
e50380aa | 1786 | |
09d9d230 | 1787 | Although it may be considered internal, the class hierarchy does matter |
f9916dde A |
1788 | for both users and programmer. CPAN.pm deals with the four |
1789 | classes mentioned above, and those classes all share a set of methods. Classical | |
09d9d230 A |
1790 | single polymorphism is in effect. A metaclass object registers all |
1791 | objects of all kinds and indexes them with a string. The strings | |
1792 | referencing objects have a separated namespace (well, not completely | |
1793 | separated): | |
e50380aa A |
1794 | |
1795 | Namespace Class | |
1796 | ||
1797 | words containing a "/" (slash) Distribution | |
1798 | words starting with Bundle:: Bundle | |
1799 | everything else Module or Author | |
1800 | ||
1801 | Modules know their associated Distribution objects. They always refer | |
09d9d230 A |
1802 | to the most recent official release. Developers may mark their releases |
1803 | as unstable development versions (by inserting an underbar into the | |
16703a00 | 1804 | module version number which will also be reflected in the distribution |
6658a91b SP |
1805 | name when you run 'make dist'), so the really hottest and newest |
1806 | distribution is not always the default. If a module Foo circulates | |
1807 | on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient | |
16703a00 | 1808 | way to install version 1.23 by saying |
e50380aa A |
1809 | |
1810 | install Foo | |
1811 | ||
1812 | This would install the complete distribution file (say | |
09d9d230 A |
1813 | BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would |
1814 | like to install version 1.23_90, you need to know where the | |
e50380aa | 1815 | distribution file resides on CPAN relative to the authors/id/ |
09d9d230 | 1816 | directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz; |
c356248b | 1817 | so you would have to say |
e50380aa A |
1818 | |
1819 | install BAR/Foo-1.23_90.tar.gz | |
1820 | ||
1821 | The first example will be driven by an object of the class | |
c356248b | 1822 | CPAN::Module, the second by an object of class CPAN::Distribution. |
e50380aa | 1823 | |
6658a91b SP |
1824 | =head2 Integrating local directories |
1825 | ||
ed756621 SP |
1826 | Note: this feature is still in alpha state and may change in future |
1827 | versions of CPAN.pm | |
1828 | ||
6658a91b | 1829 | Distribution objects are normally distributions from the CPAN, but |
b72dd56f SP |
1830 | there is a slightly degenerate case for Distribution objects, too, of |
1831 | projects held on the local disk. These distribution objects have the | |
1832 | same name as the local directory and end with a dot. A dot by itself | |
1833 | is also allowed for the current directory at the time CPAN.pm was | |
1834 | used. All actions such as C<make>, C<test>, and C<install> are applied | |
6658a91b SP |
1835 | directly to that directory. This gives the command C<cpan .> an |
1836 | interesting touch: while the normal mantra of installing a CPAN module | |
1837 | without CPAN.pm is one of | |
1838 | ||
1839 | perl Makefile.PL perl Build.PL | |
1840 | ( go and get prerequisites ) | |
1841 | make ./Build | |
1842 | make test ./Build test | |
1843 | make install ./Build install | |
1844 | ||
1845 | the command C<cpan .> does all of this at once. It figures out which | |
1846 | of the two mantras is appropriate, fetches and installs all | |
f9916dde | 1847 | prerequisites, takes care of them recursively, and finally finishes the |
6658a91b SP |
1848 | installation of the module in the current directory, be it a CPAN |
1849 | module or not. | |
1850 | ||
b72dd56f SP |
1851 | The typical usage case is for private modules or working copies of |
1852 | projects from remote repositories on the local disk. | |
1853 | ||
5254b38e SP |
1854 | =head2 Redirection |
1855 | ||
1856 | The usual shell redirection symbols C< | > and C<< > >> are recognized | |
f9916dde A |
1857 | by the cpan shell B<only when surrounded by whitespace>. So piping to |
1858 | pager or redirecting output into a file works somewhat as in a normal | |
1859 | shell, with the stipulation that you must type extra spaces. | |
5254b38e | 1860 | |
f20de9f0 | 1861 | =head1 CONFIGURATION |
55e314ee | 1862 | |
f20de9f0 | 1863 | When the CPAN module is used for the first time, a configuration |
f9916dde | 1864 | dialogue tries to determine a couple of site specific options. The |
f20de9f0 SP |
1865 | result of the dialog is stored in a hash reference C< $CPAN::Config > |
1866 | in a file CPAN/Config.pm. | |
de34a54b | 1867 | |
f9916dde | 1868 | Default values defined in the CPAN/Config.pm file can be |
f20de9f0 | 1869 | overridden in a user specific file: CPAN/MyConfig.pm. Such a file is |
f9916dde | 1870 | best placed in C<$HOME/.cpan/CPAN/MyConfig.pm>, because C<$HOME/.cpan> is |
f20de9f0 SP |
1871 | added to the search path of the CPAN module before the use() or |
1872 | require() statements. The mkmyconfig command writes this file for you. | |
36263cb3 | 1873 | |
f20de9f0 | 1874 | The C<o conf> command has various bells and whistles: |
36263cb3 | 1875 | |
f20de9f0 | 1876 | =over |
36263cb3 | 1877 | |
f20de9f0 | 1878 | =item completion support |
36263cb3 | 1879 | |
f20de9f0 SP |
1880 | If you have a ReadLine module installed, you can hit TAB at any point |
1881 | of the commandline and C<o conf> will offer you completion for the | |
1882 | built-in subcommands and/or config variable names. | |
36263cb3 | 1883 | |
f20de9f0 | 1884 | =item displaying some help: o conf help |
36263cb3 | 1885 | |
f20de9f0 | 1886 | Displays a short help |
36263cb3 | 1887 | |
f20de9f0 | 1888 | =item displaying current values: o conf [KEY] |
36263cb3 | 1889 | |
f9916dde | 1890 | Displays the current value(s) for this config variable. Without KEY, |
f20de9f0 | 1891 | displays all subcommands and config variables. |
36263cb3 | 1892 | |
f20de9f0 | 1893 | Example: |
5f05dabc | 1894 | |
f20de9f0 | 1895 | o conf shell |
d8773709 | 1896 | |
f9916dde A |
1897 | If KEY starts and ends with a slash, the string in between is |
1898 | treated as a regular expression and only keys matching this regex | |
f04ea8d1 SP |
1899 | are displayed |
1900 | ||
1901 | Example: | |
1902 | ||
1903 | o conf /color/ | |
1904 | ||
f20de9f0 | 1905 | =item changing of scalar values: o conf KEY VALUE |
d8773709 | 1906 | |
f20de9f0 SP |
1907 | Sets the config variable KEY to VALUE. The empty string can be |
1908 | specified as usual in shells, with C<''> or C<""> | |
d8773709 | 1909 | |
f20de9f0 | 1910 | Example: |
d8773709 | 1911 | |
f20de9f0 | 1912 | o conf wget /usr/bin/wget |
d8773709 | 1913 | |
f20de9f0 | 1914 | =item changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST |
d8773709 | 1915 | |
f20de9f0 SP |
1916 | If a config variable name ends with C<list>, it is a list. C<o conf |
1917 | KEY shift> removes the first element of the list, C<o conf KEY pop> | |
1918 | removes the last element of the list. C<o conf KEYS unshift LIST> | |
1919 | prepends a list of values to the list, C<o conf KEYS push LIST> | |
1920 | appends a list of valued to the list. | |
d8773709 | 1921 | |
f9916dde | 1922 | Likewise, C<o conf KEY splice LIST> passes the LIST to the corresponding |
f20de9f0 | 1923 | splice command. |
d8773709 | 1924 | |
f20de9f0 SP |
1925 | Finally, any other list of arguments is taken as a new list value for |
1926 | the KEY variable discarding the previous value. | |
d8773709 | 1927 | |
f20de9f0 | 1928 | Examples: |
d8773709 | 1929 | |
f20de9f0 SP |
1930 | o conf urllist unshift http://cpan.dev.local/CPAN |
1931 | o conf urllist splice 3 1 | |
1932 | o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org | |
d8773709 | 1933 | |
f20de9f0 | 1934 | =item reverting to saved: o conf defaults |
d8773709 | 1935 | |
f20de9f0 | 1936 | Reverts all config variables to the state in the saved config file. |
d8773709 | 1937 | |
f20de9f0 | 1938 | =item saving the config: o conf commit |
d8773709 | 1939 | |
f20de9f0 SP |
1940 | Saves all config variables to the current config file (CPAN/Config.pm |
1941 | or CPAN/MyConfig.pm that was loaded at start). | |
d8773709 | 1942 | |
f20de9f0 | 1943 | =back |
d8773709 | 1944 | |
f20de9f0 SP |
1945 | The configuration dialog can be started any time later again by |
1946 | issuing the command C< o conf init > in the CPAN shell. A subset of | |
1947 | the configuration dialog can be run by issuing C<o conf init WORD> | |
1948 | where WORD is any valid config variable or a regular expression. | |
d8773709 | 1949 | |
f20de9f0 | 1950 | =head2 Config Variables |
d8773709 | 1951 | |
f9916dde A |
1952 | The following keys in the hash reference $CPAN::Config are |
1953 | currently defined: | |
d8773709 | 1954 | |
f20de9f0 SP |
1955 | applypatch path to external prg |
1956 | auto_commit commit all changes to config variables to disk | |
1957 | build_cache size of cache for directories to build modules | |
1958 | build_dir locally accessible directory to build modules | |
1959 | build_dir_reuse boolean if distros in build_dir are persistent | |
1960 | build_requires_install_policy | |
1961 | to install or not to install when a module is | |
1962 | only needed for building. yes|no|ask/yes|ask/no | |
1963 | bzip2 path to external prg | |
1964 | cache_metadata use serializer to cache metadata | |
f20de9f0 SP |
1965 | check_sigs if signatures should be verified |
1966 | colorize_debug Term::ANSIColor attributes for debugging output | |
1967 | colorize_output boolean if Term::ANSIColor should colorize output | |
1968 | colorize_print Term::ANSIColor attributes for normal output | |
1969 | colorize_warn Term::ANSIColor attributes for warnings | |
1970 | commandnumber_in_prompt | |
1971 | boolean if you want to see current command number | |
f9916dde | 1972 | commands_quote preferred character to use for quoting external |
5254b38e SP |
1973 | commands when running them. Defaults to double |
1974 | quote on Windows, single tick everywhere else; | |
1975 | can be set to space to disable quoting | |
1976 | connect_to_internet_ok | |
f9916dde | 1977 | whether to ask if opening a connection is ok before |
5254b38e | 1978 | urllist is specified |
f20de9f0 SP |
1979 | cpan_home local directory reserved for this package |
1980 | curl path to external prg | |
1981 | dontload_hash DEPRECATED | |
1982 | dontload_list arrayref: modules in the list will not be | |
1983 | loaded by the CPAN::has_inst() routine | |
1984 | ftp path to external prg | |
12ad1f85 DG |
1985 | ftp_passive if set, the environment variable FTP_PASSIVE is set |
1986 | for downloads | |
f20de9f0 | 1987 | ftp_proxy proxy host for ftp requests |
5254b38e SP |
1988 | ftpstats_period max number of days to keep download statistics |
1989 | ftpstats_size max number of items to keep in the download statistics | |
f20de9f0 SP |
1990 | getcwd see below |
1991 | gpg path to external prg | |
f04ea8d1 | 1992 | gzip location of external program gzip |
5254b38e SP |
1993 | halt_on_failure stop processing after the first failure of queued |
1994 | items or dependencies | |
f20de9f0 SP |
1995 | histfile file to maintain history between sessions |
1996 | histsize maximum number of lines to keep in histfile | |
1997 | http_proxy proxy host for http requests | |
1998 | inactivity_timeout breaks interactive Makefile.PLs or Build.PLs | |
1999 | after this many seconds inactivity. Set to 0 to | |
f9916dde A |
2000 | disable timeouts. |
2001 | index_expire refetch index files after this many days | |
f20de9f0 | 2002 | inhibit_startup_message |
f9916dde | 2003 | if true, suppress the startup message |
f20de9f0 | 2004 | keep_source_where directory in which to keep the source (if we do) |
f04ea8d1 SP |
2005 | load_module_verbosity |
2006 | report loading of optional modules used by CPAN.pm | |
f20de9f0 SP |
2007 | lynx path to external prg |
2008 | make location of external make program | |
f04ea8d1 | 2009 | make_arg arguments that should always be passed to 'make' |
f20de9f0 SP |
2010 | make_install_make_command |
2011 | the make command for running 'make install', for | |
2012 | example 'sudo make' | |
2013 | make_install_arg same as make_arg for 'make install' | |
f04ea8d1 SP |
2014 | makepl_arg arguments passed to 'perl Makefile.PL' |
2015 | mbuild_arg arguments passed to './Build' | |
f20de9f0 SP |
2016 | mbuild_install_arg arguments passed to './Build install' |
2017 | mbuild_install_build_command | |
2018 | command to use instead of './Build' when we are | |
2019 | in the install stage, for example 'sudo ./Build' | |
2020 | mbuildpl_arg arguments passed to 'perl Build.PL' | |
2021 | ncftp path to external prg | |
2022 | ncftpget path to external prg | |
2023 | no_proxy don't proxy to these hosts/domains (comma separated list) | |
2024 | pager location of external program more (or any pager) | |
2025 | password your password if you CPAN server wants one | |
2026 | patch path to external prg | |
f9916dde | 2027 | patches_dir local directory containing patch files |
5254b38e | 2028 | perl5lib_verbosity verbosity level for PERL5LIB additions |
a52237f3 DG |
2029 | prefer_external_tar |
2030 | per default all untar operations are done with | |
2031 | Archive::Tar; by setting this variable to true | |
2032 | the external tar command is used if available | |
f20de9f0 SP |
2033 | prefer_installer legal values are MB and EUMM: if a module comes |
2034 | with both a Makefile.PL and a Build.PL, use the | |
2035 | former (EUMM) or the latter (MB); if the module | |
2036 | comes with only one of the two, that one will be | |
f9916dde | 2037 | used no matter the setting |
f20de9f0 SP |
2038 | prerequisites_policy |
2039 | what to do if you are missing module prerequisites | |
2040 | ('follow' automatically, 'ask' me, or 'ignore') | |
23d72198 S |
2041 | For 'follow', also sets PERL_AUTOINSTALL and |
2042 | PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if | |
2043 | not already set | |
f20de9f0 SP |
2044 | prefs_dir local directory to store per-distro build options |
2045 | proxy_user username for accessing an authenticating proxy | |
2046 | proxy_pass password for accessing an authenticating proxy | |
2047 | randomize_urllist add some randomness to the sequence of the urllist | |
a52237f3 | 2048 | scan_cache controls scanning of cache ('atstart', 'atexit' or 'never') |
f20de9f0 | 2049 | shell your favorite shell |
f04ea8d1 SP |
2050 | show_unparsable_versions |
2051 | boolean if r command tells which modules are versionless | |
f20de9f0 | 2052 | show_upload_date boolean if commands should try to determine upload date |
f04ea8d1 | 2053 | show_zero_versions boolean if r command tells for which modules $version==0 |
f20de9f0 | 2054 | tar location of external program tar |
f04ea8d1 SP |
2055 | tar_verbosity verbosity level for the tar command |
2056 | term_is_latin deprecated: if true Unicode is translated to ISO-8859-1 | |
f20de9f0 SP |
2057 | (and nonsense for characters outside latin range) |
2058 | term_ornaments boolean to turn ReadLine ornamenting on/off | |
2059 | test_report email test reports (if CPAN::Reporter is installed) | |
5254b38e SP |
2060 | trust_test_report_history |
2061 | skip testing when previously tested ok (according to | |
2062 | CPAN::Reporter history) | |
f20de9f0 | 2063 | unzip location of external program unzip |
f04ea8d1 | 2064 | urllist arrayref to nearby CPAN sites (or equivalent locations) |
f20de9f0 SP |
2065 | use_sqlite use CPAN::SQLite for metadata storage (fast and lean) |
2066 | username your username if you CPAN server wants one | |
0124e695 JV |
2067 | version_timeout stops version parsing after this many seconds. |
2068 | Default is 15 secs. Set to 0 to disable. | |
f20de9f0 SP |
2069 | wait_list arrayref to a wait server to try (See CPAN::WAIT) |
2070 | wget path to external prg | |
f9916dde | 2071 | yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode |
f20de9f0 | 2072 | yaml_module which module to use to read/write YAML files |
d8773709 | 2073 | |
f20de9f0 SP |
2074 | You can set and query each of these options interactively in the cpan |
2075 | shell with the C<o conf> or the C<o conf init> command as specified below. | |
d8773709 | 2076 | |
f20de9f0 | 2077 | =over 2 |
d8773709 | 2078 | |
f20de9f0 | 2079 | =item C<o conf E<lt>scalar optionE<gt>> |
d8773709 | 2080 | |
f20de9f0 | 2081 | prints the current value of the I<scalar option> |
d8773709 | 2082 | |
f20de9f0 | 2083 | =item C<o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>> |
d8773709 | 2084 | |
f20de9f0 | 2085 | Sets the value of the I<scalar option> to I<value> |
d8773709 | 2086 | |
f20de9f0 | 2087 | =item C<o conf E<lt>list optionE<gt>> |
d8773709 | 2088 | |
f20de9f0 SP |
2089 | prints the current value of the I<list option> in MakeMaker's |
2090 | neatvalue format. | |
d8773709 | 2091 | |
f20de9f0 | 2092 | =item C<o conf E<lt>list optionE<gt> [shift|pop]> |
d8773709 | 2093 | |
f20de9f0 | 2094 | shifts or pops the array in the I<list option> variable |
d8773709 | 2095 | |
f20de9f0 | 2096 | =item C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>> |
d8773709 | 2097 | |
f20de9f0 | 2098 | works like the corresponding perl commands. |
d8773709 | 2099 | |
f20de9f0 | 2100 | =item interactive editing: o conf init [MATCH|LIST] |
d8773709 | 2101 | |
f20de9f0 SP |
2102 | Runs an interactive configuration dialog for matching variables. |
2103 | Without argument runs the dialog over all supported config variables. | |
2104 | To specify a MATCH the argument must be enclosed by slashes. | |
d8773709 | 2105 | |
f20de9f0 | 2106 | Examples: |
d8773709 | 2107 | |
f20de9f0 SP |
2108 | o conf init ftp_passive ftp_proxy |
2109 | o conf init /color/ | |
d8773709 | 2110 | |
f20de9f0 SP |
2111 | Note: this method of setting config variables often provides more |
2112 | explanation about the functioning of a variable than the manpage. | |
d8773709 | 2113 | |
f20de9f0 | 2114 | =back |
d8773709 | 2115 | |
f20de9f0 | 2116 | =head2 CPAN::anycwd($path): Note on config variable getcwd |
d8773709 | 2117 | |
f20de9f0 | 2118 | CPAN.pm changes the current working directory often and needs to |
f9916dde A |
2119 | determine its own current working directory. By default it uses |
2120 | Cwd::cwd, but if for some reason this doesn't work on your system, | |
2121 | configure alternatives according to the following table: | |
d8773709 | 2122 | |
f20de9f0 | 2123 | =over 4 |
d8773709 | 2124 | |
f20de9f0 | 2125 | =item cwd |
d8773709 | 2126 | |
f20de9f0 | 2127 | Calls Cwd::cwd |
4d1321a7 | 2128 | |
f20de9f0 | 2129 | =item getcwd |
4d1321a7 | 2130 | |
f20de9f0 | 2131 | Calls Cwd::getcwd |
d8773709 | 2132 | |
f20de9f0 | 2133 | =item fastcwd |
d8773709 | 2134 | |
f20de9f0 | 2135 | Calls Cwd::fastcwd |
d8773709 | 2136 | |
f20de9f0 | 2137 | =item backtickcwd |
d8773709 | 2138 | |
f20de9f0 | 2139 | Calls the external command cwd. |
d8773709 | 2140 | |
f20de9f0 | 2141 | =back |
d8773709 | 2142 | |
f20de9f0 | 2143 | =head2 Note on the format of the urllist parameter |
d8773709 | 2144 | |
f20de9f0 SP |
2145 | urllist parameters are URLs according to RFC 1738. We do a little |
2146 | guessing if your URL is not compliant, but if you have problems with | |
2147 | C<file> URLs, please try the correct format. Either: | |
d8773709 | 2148 | |
f20de9f0 | 2149 | file://localhost/whatever/ftp/pub/CPAN/ |
d8773709 | 2150 | |
f20de9f0 | 2151 | or |
d8773709 | 2152 | |
f20de9f0 | 2153 | file:///home/ftp/pub/CPAN/ |
d8773709 | 2154 | |
f20de9f0 | 2155 | =head2 The urllist parameter has CD-ROM support |
d8773709 | 2156 | |
f20de9f0 | 2157 | The C<urllist> parameter of the configuration table contains a list of |
f9916dde A |
2158 | URLs used for downloading. If the list contains any |
2159 | C<file> URLs, CPAN always tries there first. This | |
f20de9f0 SP |
2160 | feature is disabled for index files. So the recommendation for the |
2161 | owner of a CD-ROM with CPAN contents is: include your local, possibly | |
2162 | outdated CD-ROM as a C<file> URL at the end of urllist, e.g. | |
d8773709 | 2163 | |
f20de9f0 | 2164 | o conf urllist push file://localhost/CDROM/CPAN |
d8773709 | 2165 | |
f20de9f0 SP |
2166 | CPAN.pm will then fetch the index files from one of the CPAN sites |
2167 | that come at the beginning of urllist. It will later check for each | |
f9916dde | 2168 | module to see whether there is a local copy of the most recent version. |
d8773709 | 2169 | |
f20de9f0 SP |
2170 | Another peculiarity of urllist is that the site that we could |
2171 | successfully fetch the last file from automatically gets a preference | |
2172 | token and is tried as the first site for the next request. So if you | |
2173 | add a new site at runtime it may happen that the previously preferred | |
2174 | site will be tried another time. This means that if you want to disallow | |
2175 | a site for the next transfer, it must be explicitly removed from | |
2176 | urllist. | |
d8773709 | 2177 | |
f20de9f0 | 2178 | =head2 Maintaining the urllist parameter |
1e8f9a0a | 2179 | |
f20de9f0 SP |
2180 | If you have YAML.pm (or some other YAML module configured in |
2181 | C<yaml_module>) installed, CPAN.pm collects a few statistical data | |
2182 | about recent downloads. You can view the statistics with the C<hosts> | |
2183 | command or inspect them directly by looking into the C<FTPstats.yml> | |
2184 | file in your C<cpan_home> directory. | |
8962fc49 | 2185 | |
f9916dde A |
2186 | To get some interesting statistics, it is recommended that |
2187 | C<randomize_urllist> be set; this introduces some amount of | |
f20de9f0 | 2188 | randomness into the URL selection. |
d8773709 | 2189 | |
f20de9f0 | 2190 | =head2 The C<requires> and C<build_requires> dependency declarations |
d8773709 | 2191 | |
f20de9f0 SP |
2192 | Since CPAN.pm version 1.88_51 modules declared as C<build_requires> by |
2193 | a distribution are treated differently depending on the config | |
2194 | variable C<build_requires_install_policy>. By setting | |
f9916dde A |
2195 | C<build_requires_install_policy> to C<no>, such a module is not |
2196 | installed. It is only built and tested, and then kept in the list of | |
2197 | tested but uninstalled modules. As such, it is available during the | |
f20de9f0 SP |
2198 | build of the dependent module by integrating the path to the |
2199 | C<blib/arch> and C<blib/lib> directories in the environment variable | |
2200 | PERL5LIB. If C<build_requires_install_policy> is set ti C<yes>, then | |
2201 | both modules declared as C<requires> and those declared as | |
2202 | C<build_requires> are treated alike. By setting to C<ask/yes> or | |
2203 | C<ask/no>, CPAN.pm asks the user and sets the default accordingly. | |
d8773709 | 2204 | |
f20de9f0 | 2205 | =head2 Configuration for individual distributions (I<Distroprefs>) |
d8773709 | 2206 | |
f20de9f0 SP |
2207 | (B<Note:> This feature has been introduced in CPAN.pm 1.8854 and is |
2208 | still considered beta quality) | |
d8773709 | 2209 | |
f9916dde | 2210 | Distributions on CPAN usually behave according to what we call the |
6b1bef9a | 2211 | CPAN mantra. Or since the advent of Module::Build we should talk about |
f20de9f0 | 2212 | two mantras: |
d8773709 | 2213 | |
f20de9f0 SP |
2214 | perl Makefile.PL perl Build.PL |
2215 | make ./Build | |
2216 | make test ./Build test | |
2217 | make install ./Build install | |
4d1321a7 | 2218 | |
f20de9f0 | 2219 | But some modules cannot be built with this mantra. They try to get |
f9916dde A |
2220 | some extra data from the user via the environment, extra arguments, or |
2221 | interactively--thus disturbing the installation of large bundles like | |
f20de9f0 | 2222 | Phalanx100 or modules with many dependencies like Plagger. |
4d1321a7 | 2223 | |
f20de9f0 SP |
2224 | The distroprefs system of C<CPAN.pm> addresses this problem by |
2225 | allowing the user to specify extra informations and recipes in YAML | |
2226 | files to either | |
1e8f9a0a | 2227 | |
f20de9f0 | 2228 | =over |
d8773709 | 2229 | |
f20de9f0 | 2230 | =item |
d8773709 | 2231 | |
f20de9f0 | 2232 | pass additional arguments to one of the four commands, |
d8773709 | 2233 | |
f20de9f0 | 2234 | =item |
554a9ef5 | 2235 | |
f20de9f0 | 2236 | set environment variables |
554a9ef5 | 2237 | |
f20de9f0 | 2238 | =item |
d8773709 | 2239 | |
f20de9f0 SP |
2240 | instantiate an Expect object that reads from the console, waits for |
2241 | some regular expressions and enters some answers | |
d8773709 | 2242 | |
f20de9f0 | 2243 | =item |
d8773709 | 2244 | |
f20de9f0 | 2245 | temporarily override assorted C<CPAN.pm> configuration variables |
d8773709 | 2246 | |
f20de9f0 | 2247 | =item |
d8773709 | 2248 | |
f9916dde | 2249 | specify dependencies the original maintainer forgot |
f04ea8d1 SP |
2250 | |
2251 | =item | |
2252 | ||
f20de9f0 | 2253 | disable the installation of an object altogether |
d8773709 | 2254 | |
f20de9f0 | 2255 | =back |
d8773709 | 2256 | |
f20de9f0 SP |
2257 | See the YAML and Data::Dumper files that come with the C<CPAN.pm> |
2258 | distribution in the C<distroprefs/> directory for examples. | |
d8773709 | 2259 | |
f20de9f0 | 2260 | =head2 Filenames |
d8773709 | 2261 | |
f9916dde | 2262 | The YAML files themselves must have the C<.yml> extension; all other |
f20de9f0 SP |
2263 | files are ignored (for two exceptions see I<Fallback Data::Dumper and |
2264 | Storable> below). The containing directory can be specified in | |
2265 | C<CPAN.pm> in the C<prefs_dir> config variable. Try C<o conf init | |
2266 | prefs_dir> in the CPAN shell to set and activate the distroprefs | |
2267 | system. | |
d8773709 | 2268 | |
f20de9f0 | 2269 | Every YAML file may contain arbitrary documents according to the YAML |
f9916dde | 2270 | specification, and every document is treated as an entity that |
f20de9f0 | 2271 | can specify the treatment of a single distribution. |
d8773709 | 2272 | |
f9916dde | 2273 | Filenames can be picked arbitrarily; C<CPAN.pm> always reads |
f20de9f0 SP |
2274 | all files (in alphabetical order) and takes the key C<match> (see |
2275 | below in I<Language Specs>) as a hashref containing match criteria | |
2276 | that determine if the current distribution matches the YAML document | |
2277 | or not. | |
d8773709 | 2278 | |
f20de9f0 | 2279 | =head2 Fallback Data::Dumper and Storable |
d8773709 | 2280 | |
f9916dde | 2281 | If neither your configured C<yaml_module> nor YAML.pm is installed, |
f20de9f0 SP |
2282 | CPAN.pm falls back to using Data::Dumper and Storable and looks for |
2283 | files with the extensions C<.dd> or C<.st> in the C<prefs_dir> | |
2284 | directory. These files are expected to contain one or more hashrefs. | |
2285 | For Data::Dumper generated files, this is expected to be done with by | |
2286 | defining C<$VAR1>, C<$VAR2>, etc. The YAML shell would produce these | |
2287 | with the command | |
d8773709 | 2288 | |
f20de9f0 | 2289 | ysh < somefile.yml > somefile.dd |
d8773709 | 2290 | |
f20de9f0 SP |
2291 | For Storable files the rule is that they must be constructed such that |
2292 | C<Storable::retrieve(file)> returns an array reference and the array | |
2293 | elements represent one distropref object each. The conversion from | |
2294 | YAML would look like so: | |
d8773709 | 2295 | |
f20de9f0 SP |
2296 | perl -MYAML=LoadFile -MStorable=nstore -e ' |
2297 | @y=LoadFile(shift); | |
2298 | nstore(\@y, shift)' somefile.yml somefile.st | |
d8773709 | 2299 | |
f20de9f0 | 2300 | In bootstrapping situations it is usually sufficient to translate only |
f9916dde | 2301 | a few YAML files to Data::Dumper for crucial modules like |
f20de9f0 SP |
2302 | C<YAML::Syck>, C<YAML.pm> and C<Expect.pm>. If you prefer Storable |
2303 | over Data::Dumper, remember to pull out a Storable version that writes | |
2304 | an older format than all the other Storable versions that will need to | |
2305 | read them. | |
d8773709 | 2306 | |
f20de9f0 | 2307 | =head2 Blueprint |
d8773709 | 2308 | |
f20de9f0 SP |
2309 | The following example contains all supported keywords and structures |
2310 | with the exception of C<eexpect> which can be used instead of | |
2311 | C<expect>. | |
d8773709 | 2312 | |
f20de9f0 SP |
2313 | --- |
2314 | comment: "Demo" | |
2315 | match: | |
2316 | module: "Dancing::Queen" | |
2317 | distribution: "^CHACHACHA/Dancing-" | |
f9916dde | 2318 | not_distribution: "\.zip$" |
f20de9f0 | 2319 | perl: "/usr/local/cariba-perl/bin/perl" |
2b3bde2a SP |
2320 | perlconfig: |
2321 | archname: "freebsd" | |
f9916dde | 2322 | not_cc: "gcc" |
5254b38e SP |
2323 | env: |
2324 | DANCING_FLOOR: "Shubiduh" | |
f20de9f0 SP |
2325 | disabled: 1 |
2326 | cpanconfig: | |
2327 | make: gmake | |
2328 | pl: | |
2329 | args: | |
2330 | - "--somearg=specialcase" | |
d8773709 | 2331 | |
f20de9f0 | 2332 | env: {} |
d8773709 | 2333 | |
f20de9f0 SP |
2334 | expect: |
2335 | - "Which is your favorite fruit" | |
2336 | - "apple\n" | |
d8773709 | 2337 | |
f20de9f0 SP |
2338 | make: |
2339 | args: | |
2340 | - all | |
2341 | - extra-all | |
d8773709 | 2342 | |
f20de9f0 | 2343 | env: {} |
4d1321a7 | 2344 | |
f20de9f0 | 2345 | expect: [] |
4d1321a7 | 2346 | |
0124e695 | 2347 | commandline: "echo SKIPPING make" |
87892b73 | 2348 | |
f20de9f0 SP |
2349 | test: |
2350 | args: [] | |
87892b73 | 2351 | |
f20de9f0 | 2352 | env: {} |
87892b73 | 2353 | |
f20de9f0 | 2354 | expect: [] |
87892b73 | 2355 | |
f20de9f0 SP |
2356 | install: |
2357 | args: [] | |
87892b73 | 2358 | |
f20de9f0 SP |
2359 | env: |
2360 | WANT_TO_INSTALL: YES | |
87892b73 | 2361 | |
f20de9f0 SP |
2362 | expect: |
2363 | - "Do you really want to install" | |
2364 | - "y\n" | |
87892b73 | 2365 | |
f20de9f0 SP |
2366 | patches: |
2367 | - "ABCDE/Fedcba-3.14-ABCDE-01.patch" | |
87892b73 | 2368 | |
f04ea8d1 SP |
2369 | depends: |
2370 | configure_requires: | |
2371 | LWP: 5.8 | |
2372 | build_requires: | |
2373 | Test::Exception: 0.25 | |
2374 | requires: | |
2375 | Spiffy: 0.30 | |
2376 | ||
d8773709 | 2377 | |
f20de9f0 | 2378 | =head2 Language Specs |
d8773709 | 2379 | |
f20de9f0 SP |
2380 | Every YAML document represents a single hash reference. The valid keys |
2381 | in this hash are as follows: | |
d8773709 | 2382 | |
f20de9f0 | 2383 | =over |
d8773709 | 2384 | |
f20de9f0 | 2385 | =item comment [scalar] |
d8773709 | 2386 | |
f20de9f0 | 2387 | A comment |
d8773709 | 2388 | |
f20de9f0 | 2389 | =item cpanconfig [hash] |
810a0276 | 2390 | |
f20de9f0 | 2391 | Temporarily override assorted C<CPAN.pm> configuration variables. |
810a0276 | 2392 | |
f20de9f0 SP |
2393 | Supported are: C<build_requires_install_policy>, C<check_sigs>, |
2394 | C<make>, C<make_install_make_command>, C<prefer_installer>, | |
2395 | C<test_report>. Please report as a bug when you need another one | |
2396 | supported. | |
d8773709 | 2397 | |
f04ea8d1 SP |
2398 | =item depends [hash] *** EXPERIMENTAL FEATURE *** |
2399 | ||
2400 | All three types, namely C<configure_requires>, C<build_requires>, and | |
2401 | C<requires> are supported in the way specified in the META.yml | |
2402 | specification. The current implementation I<merges> the specified | |
2403 | dependencies with those declared by the package maintainer. In a | |
2404 | future implementation this may be changed to override the original | |
2405 | declaration. | |
2406 | ||
f20de9f0 | 2407 | =item disabled [boolean] |
810a0276 | 2408 | |
f20de9f0 | 2409 | Specifies that this distribution shall not be processed at all. |
810a0276 | 2410 | |
5254b38e SP |
2411 | =item features [array] *** EXPERIMENTAL FEATURE *** |
2412 | ||
2413 | Experimental implementation to deal with optional_features from | |
2414 | META.yml. Still needs coordination with installer software and | |
f9916dde | 2415 | currently works only for META.yml declaring C<dynamic_config=0>. Use |
5254b38e SP |
2416 | with caution. |
2417 | ||
f20de9f0 | 2418 | =item goto [string] |
d8773709 | 2419 | |
f9916dde | 2420 | The canonical name of a delegate distribution to install |
f20de9f0 SP |
2421 | instead. Useful when a new version, although it tests OK itself, |
2422 | breaks something else or a developer release or a fork is already | |
2423 | uploaded that is better than the last released version. | |
d8773709 | 2424 | |
f20de9f0 | 2425 | =item install [hash] |
d8773709 | 2426 | |
f20de9f0 | 2427 | Processing instructions for the C<make install> or C<./Build install> |
5254b38e | 2428 | phase of the CPAN mantra. See below under I<Processing Instructions>. |
d8773709 | 2429 | |
f20de9f0 | 2430 | =item make [hash] |
d8773709 | 2431 | |
f20de9f0 | 2432 | Processing instructions for the C<make> or C<./Build> phase of the |
5254b38e | 2433 | CPAN mantra. See below under I<Processing Instructions>. |
d8773709 | 2434 | |
f20de9f0 | 2435 | =item match [hash] |
d8773709 | 2436 | |
2b3bde2a | 2437 | A hashref with one or more of the keys C<distribution>, C<modules>, |
f9916dde | 2438 | C<perl>, C<perlconfig>, and C<env> that specify whether a document is |
5254b38e | 2439 | targeted at a specific CPAN distribution or installation. |
f9916dde | 2440 | Keys prefixed with C<not_> negates the corresponding match. |
d8773709 | 2441 | |
f20de9f0 SP |
2442 | The corresponding values are interpreted as regular expressions. The |
2443 | C<distribution> related one will be matched against the canonical | |
2444 | distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz". | |
d8773709 | 2445 | |
f20de9f0 SP |
2446 | The C<module> related one will be matched against I<all> modules |
2447 | contained in the distribution until one module matches. | |
554a9ef5 | 2448 | |
b03f445c RGS |
2449 | The C<perl> related one will be matched against C<$^X> (but with the |
2450 | absolute path). | |
554a9ef5 | 2451 | |
2b3bde2a SP |
2452 | The value associated with C<perlconfig> is itself a hashref that is |
2453 | matched against corresponding values in the C<%Config::Config> hash | |
5254b38e | 2454 | living in the C<Config.pm> module. |
f9916dde | 2455 | Keys prefixed with C<not_> negates the corresponding match. |
2b3bde2a | 2456 | |
5254b38e SP |
2457 | The value associated with C<env> is itself a hashref that is |
2458 | matched against corresponding values in the C<%ENV> hash. | |
f9916dde | 2459 | Keys prefixed with C<not_> negates the corresponding match. |
5254b38e SP |
2460 | |
2461 | If more than one restriction of C<module>, C<distribution>, etc. is | |
2462 | specified, the results of the separately computed match values must | |
f9916dde | 2463 | all match. If so, the hashref represented by the |
5254b38e SP |
2464 | YAML document is returned as the preference structure for the current |
2465 | distribution. | |
4d1321a7 | 2466 | |
f20de9f0 | 2467 | =item patches [array] |
4d1321a7 | 2468 | |
f20de9f0 | 2469 | An array of patches on CPAN or on the local disk to be applied in |
f9916dde | 2470 | order via an external patch program. If the value for the C<-p> |
f20de9f0 | 2471 | parameter is C<0> or C<1> is determined by reading the patch |
f9916dde A |
2472 | beforehand. The path to each patch is either an absolute path on the |
2473 | local filesystem or relative to a patch directory specified in the | |
2474 | C<patches_dir> configuration variable or in the format of a canonical | |
12ad1f85 | 2475 | distro name. For examples please consult the distroprefs/ directory in |
f9916dde A |
2476 | the CPAN.pm distribution (these examples are not installed by |
2477 | default). | |
d8773709 | 2478 | |
f20de9f0 SP |
2479 | Note: if the C<applypatch> program is installed and C<CPAN::Config> |
2480 | knows about it B<and> a patch is written by the C<makepatch> program, | |
2481 | then C<CPAN.pm> lets C<applypatch> apply the patch. Both C<makepatch> | |
2482 | and C<applypatch> are available from CPAN in the C<JV/makepatch-*> | |
2483 | distribution. | |
d8773709 | 2484 | |
f20de9f0 | 2485 | =item pl [hash] |
d8773709 | 2486 | |
f20de9f0 | 2487 | Processing instructions for the C<perl Makefile.PL> or C<perl |
5254b38e | 2488 | Build.PL> phase of the CPAN mantra. See below under I<Processing |
f20de9f0 | 2489 | Instructions>. |
d8773709 | 2490 | |
f20de9f0 | 2491 | =item test [hash] |
d8773709 | 2492 | |
f20de9f0 | 2493 | Processing instructions for the C<make test> or C<./Build test> phase |
5254b38e | 2494 | of the CPAN mantra. See below under I<Processing Instructions>. |
d8773709 | 2495 | |
d8773709 | 2496 | =back |
55e314ee | 2497 | |
f20de9f0 | 2498 | =head2 Processing Instructions |
5f05dabc | 2499 | |
f20de9f0 | 2500 | =over |
5f05dabc | 2501 | |
f20de9f0 | 2502 | =item args [array] |
5f05dabc | 2503 | |
f20de9f0 | 2504 | Arguments to be added to the command line |
5f05dabc | 2505 | |
f20de9f0 | 2506 | =item commandline |
5f05dabc | 2507 | |
f9916dde A |
2508 | A full commandline to run via C<system()>. |
2509 | During execution, the environment variable PERL is set | |
b03f445c | 2510 | to $^X (but with an absolute path). If C<commandline> is specified, |
f9916dde | 2511 | C<args> is not used. |
5f05dabc | 2512 | |
f20de9f0 | 2513 | =item eexpect [hash] |
5f05dabc | 2514 | |
f04ea8d1 SP |
2515 | Extended C<expect>. This is a hash reference with four allowed keys, |
2516 | C<mode>, C<timeout>, C<reuse>, and C<talk>. | |
5f05dabc | 2517 | |
0124e695 JV |
2518 | You must install the C<Expect> module to use C<eexpect>. CPAN.pm |
2519 | does not install it for you. | |
2520 | ||
f20de9f0 SP |
2521 | C<mode> may have the values C<deterministic> for the case where all |
2522 | questions come in the order written down and C<anyorder> for the case | |
2523 | where the questions may come in any order. The default mode is | |
2524 | C<deterministic>. | |
5f05dabc | 2525 | |
f9916dde A |
2526 | C<timeout> denotes a timeout in seconds. Floating-point timeouts are |
2527 | OK. With C<mode=deterministic>, the timeout denotes the | |
2528 | timeout per question; with C<mode=anyorder> it denotes the | |
f20de9f0 | 2529 | timeout per byte received from the stream or questions. |
5f05dabc | 2530 | |
f20de9f0 SP |
2531 | C<talk> is a reference to an array that contains alternating questions |
2532 | and answers. Questions are regular expressions and answers are literal | |
f9916dde | 2533 | strings. The Expect module watches the stream from the |
f20de9f0 SP |
2534 | execution of the external program (C<perl Makefile.PL>, C<perl |
2535 | Build.PL>, C<make>, etc.). | |
5f05dabc | 2536 | |
f9916dde A |
2537 | For C<mode=deterministic>, the CPAN.pm injects the |
2538 | corresponding answer as soon as the stream matches the regular expression. | |
f04ea8d1 | 2539 | |
f9916dde | 2540 | For C<mode=anyorder> CPAN.pm answers a question as soon |
f04ea8d1 | 2541 | as the timeout is reached for the next byte in the input stream. In |
f9916dde | 2542 | this mode you can use the C<reuse> parameter to decide what will |
f04ea8d1 | 2543 | happen with a question-answer pair after it has been used. In the |
f9916dde A |
2544 | default case (reuse=0) it is removed from the array, avoiding being |
2545 | used again accidentally. If you want to answer the | |
f04ea8d1 SP |
2546 | question C<Do you really want to do that> several times, then it must |
2547 | be included in the array at least as often as you want this answer to | |
2548 | be given. Setting the parameter C<reuse> to 1 makes this repetition | |
2549 | unnecessary. | |
5f05dabc | 2550 | |
f20de9f0 | 2551 | =item env [hash] |
5f05dabc | 2552 | |
f20de9f0 | 2553 | Environment variables to be set during the command |
2ccf00a7 | 2554 | |
f20de9f0 | 2555 | =item expect [array] |
09d9d230 | 2556 | |
0124e695 JV |
2557 | You must install the C<Expect> module to use C<expect>. CPAN.pm |
2558 | does not install it for you. | |
2559 | ||
2560 | C<< expect: <array> >> is a short notation for this C<eexpect>: | |
5f05dabc | 2561 | |
0124e695 JV |
2562 | eexpect: |
2563 | mode: deterministic | |
2564 | timeout: 15 | |
2565 | talk: <array> | |
da199366 | 2566 | |
f20de9f0 | 2567 | =back |
da199366 | 2568 | |
f20de9f0 | 2569 | =head2 Schema verification with C<Kwalify> |
da199366 | 2570 | |
f20de9f0 SP |
2571 | If you have the C<Kwalify> module installed (which is part of the |
2572 | Bundle::CPANxxl), then all your distroprefs files are checked for | |
f9916dde | 2573 | syntactic correctness. |
da199366 | 2574 | |
f20de9f0 | 2575 | =head2 Example Distroprefs Files |
da199366 | 2576 | |
f20de9f0 SP |
2577 | C<CPAN.pm> comes with a collection of example YAML files. Note that these |
2578 | are really just examples and should not be used without care because | |
f9916dde | 2579 | they cannot fit everybody's purpose. After all, the authors of the |
f20de9f0 SP |
2580 | packages that ask questions had a need to ask, so you should watch |
2581 | their questions and adjust the examples to your environment and your | |
f9916dde | 2582 | needs. You have been warned:-) |
da199366 | 2583 | |
f20de9f0 | 2584 | =head1 PROGRAMMER'S INTERFACE |
da199366 | 2585 | |
f9916dde A |
2586 | If you do not enter the shell, shell commands are |
2587 | available both as methods (C<CPAN::Shell-E<gt>install(...)>) and as | |
f20de9f0 | 2588 | functions in the calling package (C<install(...)>). Before calling low-level |
f9916dde | 2589 | commands, it makes sense to initialize components of CPAN you need, e.g.: |
da199366 | 2590 | |
f20de9f0 SP |
2591 | CPAN::HandleConfig->load; |
2592 | CPAN::Shell::setup_output; | |
2593 | CPAN::Index->reload; | |
da199366 | 2594 | |
f20de9f0 | 2595 | High-level commands do such initializations automatically. |
da199366 | 2596 | |
f20de9f0 SP |
2597 | There's currently only one class that has a stable interface - |
2598 | CPAN::Shell. All commands that are available in the CPAN shell are | |
2599 | methods of the class CPAN::Shell. Each of the commands that produce | |
2600 | listings of modules (C<r>, C<autobundle>, C<u>) also return a list of | |
2601 | the IDs of all modules within the list. | |
7d97ad34 SP |
2602 | |
2603 | =over 2 | |
2604 | ||
f20de9f0 | 2605 | =item expand($type,@things) |
7d97ad34 | 2606 | |
f20de9f0 SP |
2607 | The IDs of all objects available within a program are strings that can |
2608 | be expanded to the corresponding real objects with the | |
2609 | C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a | |
2610 | list of CPAN::Module objects according to the C<@things> arguments | |
f9916dde | 2611 | given. In scalar context, it returns only the first element of the |
f20de9f0 | 2612 | list. |
7d97ad34 | 2613 | |
f20de9f0 | 2614 | =item expandany(@things) |
7d97ad34 | 2615 | |
f20de9f0 | 2616 | Like expand, but returns objects of the appropriate type, i.e. |
f9916dde | 2617 | CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and |
f20de9f0 SP |
2618 | CPAN::Distribution objects for distributions. Note: it does not expand |
2619 | to CPAN::Author objects. | |
7d97ad34 | 2620 | |
f20de9f0 SP |
2621 | =item Programming Examples |
2622 | ||
2623 | This enables the programmer to do operations that combine | |
2624 | functionalities that are available in the shell. | |
2625 | ||
2626 | # install everything that is outdated on my disk: | |
2627 | perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)' | |
2628 | ||
2629 | # install my favorite programs if necessary: | |
f04ea8d1 | 2630 | for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) { |
f20de9f0 SP |
2631 | CPAN::Shell->install($mod); |
2632 | } | |
2633 | ||
2634 | # list all modules on my disk that have no VERSION number | |
f04ea8d1 SP |
2635 | for $mod (CPAN::Shell->expand("Module","/./")) { |
2636 | next unless $mod->inst_file; | |
f20de9f0 | 2637 | # MakeMaker convention for undefined $VERSION: |
f04ea8d1 SP |
2638 | next unless $mod->inst_version eq "undef"; |
2639 | print "No VERSION in ", $mod->id, "\n"; | |
f20de9f0 SP |
2640 | } |
2641 | ||
2642 | # find out which distribution on CPAN contains a module: | |
2643 | print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file | |
2644 | ||
f9916dde | 2645 | Or if you want to schedule a I<cron> job to watch CPAN, you could list |
f20de9f0 SP |
2646 | all modules that need updating. First a quick and dirty way: |
2647 | ||
2648 | perl -e 'use CPAN; CPAN::Shell->r;' | |
2649 | ||
f9916dde A |
2650 | If you don't want any output should all modules be |
2651 | up to date, parse the output of above command for the regular | |
2652 | expression C</modules are up to date/> and decide to mail the output | |
2653 | only if it doesn't match. | |
f20de9f0 | 2654 | |
f9916dde A |
2655 | If you prefer to do it more in a programmerish style in one single |
2656 | process, something like this may better suit you: | |
f20de9f0 SP |
2657 | |
2658 | # list all modules on my disk that have newer versions on CPAN | |
f04ea8d1 | 2659 | for $mod (CPAN::Shell->expand("Module","/./")) { |
f20de9f0 SP |
2660 | next unless $mod->inst_file; |
2661 | next if $mod->uptodate; | |
2662 | printf "Module %s is installed as %s, could be updated to %s from CPAN\n", | |
2663 | $mod->id, $mod->inst_version, $mod->cpan_version; | |
2664 | } | |
2665 | ||
f9916dde A |
2666 | If that gives too much output every day, you may want to |
2667 | watch only for three modules. You can write | |
f20de9f0 | 2668 | |
f04ea8d1 | 2669 | for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) { |
f20de9f0 SP |
2670 | |
2671 | as the first line instead. Or you can combine some of the above | |
2672 | tricks: | |
2673 | ||
2674 | # watch only for a new mod_perl module | |
2675 | $mod = CPAN::Shell->expand("Module","mod_perl"); | |
2676 | exit if $mod->uptodate; | |
2677 | # new mod_perl arrived, let me know all update recommendations | |
2678 | CPAN::Shell->r; | |
7d97ad34 SP |
2679 | |
2680 | =back | |
2681 | ||
f20de9f0 | 2682 | =head2 Methods in the other Classes |
7d97ad34 | 2683 | |
f20de9f0 | 2684 | =over 4 |
7d97ad34 | 2685 | |
f20de9f0 | 2686 | =item CPAN::Author::as_glimpse() |
6d29edf5 | 2687 | |
f20de9f0 | 2688 | Returns a one-line description of the author |
da199366 | 2689 | |
f20de9f0 | 2690 | =item CPAN::Author::as_string() |
da199366 | 2691 | |
f20de9f0 | 2692 | Returns a multi-line description of the author |
10b2abe6 | 2693 | |
f20de9f0 | 2694 | =item CPAN::Author::email() |
2ccf00a7 | 2695 | |
f20de9f0 | 2696 | Returns the author's email address |
2ccf00a7 | 2697 | |
f20de9f0 | 2698 | =item CPAN::Author::fullname() |
2ccf00a7 | 2699 | |
f20de9f0 | 2700 | Returns the author's name |
2ccf00a7 | 2701 | |
f20de9f0 | 2702 | =item CPAN::Author::name() |
2ccf00a7 | 2703 | |
f20de9f0 | 2704 | An alias for fullname |
2ccf00a7 | 2705 | |
f20de9f0 | 2706 | =item CPAN::Bundle::as_glimpse() |
b72dd56f | 2707 | |
f20de9f0 | 2708 | Returns a one-line description of the bundle |
b72dd56f | 2709 | |
f20de9f0 | 2710 | =item CPAN::Bundle::as_string() |
2ccf00a7 | 2711 | |
f20de9f0 | 2712 | Returns a multi-line description of the bundle |
2ccf00a7 | 2713 | |
f20de9f0 | 2714 | =item CPAN::Bundle::clean() |
2ccf00a7 | 2715 | |
f20de9f0 | 2716 | Recursively runs the C<clean> method on all items contained in the bundle. |
5f05dabc | 2717 | |
f20de9f0 | 2718 | =item CPAN::Bundle::contains() |
35576f8c | 2719 | |
f20de9f0 SP |
2720 | Returns a list of objects' IDs contained in a bundle. The associated |
2721 | objects may be bundles, modules or distributions. | |
05bab18e | 2722 | |
f20de9f0 | 2723 | =item CPAN::Bundle::force($method,@args) |
05bab18e | 2724 | |
f20de9f0 SP |
2725 | Forces CPAN to perform a task that it normally would have refused to |
2726 | do. Force takes as arguments a method name to be called and any number | |
2727 | of additional arguments that should be passed to the called method. | |
2728 | The internals of the object get the needed changes so that CPAN.pm | |
2729 | does not refuse to take the action. The C<force> is passed recursively | |
2730 | to all contained objects. See also the section above on the C<force> | |
2731 | and the C<fforce> pragma. | |
05bab18e | 2732 | |
f20de9f0 | 2733 | =item CPAN::Bundle::get() |
05bab18e | 2734 | |
f20de9f0 | 2735 | Recursively runs the C<get> method on all items contained in the bundle |
05bab18e | 2736 | |
f20de9f0 | 2737 | =item CPAN::Bundle::inst_file() |
05bab18e | 2738 | |
f20de9f0 | 2739 | Returns the highest installed version of the bundle in either @INC or |
0124e695 | 2740 | C<< $CPAN::Config->{cpan_home} >>. Note that this is different from |
f20de9f0 | 2741 | CPAN::Module::inst_file. |
05bab18e | 2742 | |
f20de9f0 | 2743 | =item CPAN::Bundle::inst_version() |
05bab18e | 2744 | |
f20de9f0 | 2745 | Like CPAN::Bundle::inst_file, but returns the $VERSION |
05bab18e | 2746 | |
f20de9f0 | 2747 | =item CPAN::Bundle::uptodate() |
05bab18e | 2748 | |
12ad1f85 | 2749 | Returns 1 if the bundle itself and all its members are up-to-date. |
05bab18e | 2750 | |
f20de9f0 | 2751 | =item CPAN::Bundle::install() |
05bab18e | 2752 | |
f20de9f0 | 2753 | Recursively runs the C<install> method on all items contained in the bundle |
05bab18e | 2754 | |
f20de9f0 | 2755 | =item CPAN::Bundle::make() |
05bab18e | 2756 | |
f20de9f0 | 2757 | Recursively runs the C<make> method on all items contained in the bundle |
05bab18e | 2758 | |
f20de9f0 | 2759 | =item CPAN::Bundle::readme() |
05bab18e | 2760 | |
f20de9f0 | 2761 | Recursively runs the C<readme> method on all items contained in the bundle |
05bab18e | 2762 | |
f20de9f0 | 2763 | =item CPAN::Bundle::test() |
05bab18e | 2764 | |
f20de9f0 | 2765 | Recursively runs the C<test> method on all items contained in the bundle |
05bab18e | 2766 | |
f20de9f0 | 2767 | =item CPAN::Distribution::as_glimpse() |
05bab18e | 2768 | |
f20de9f0 | 2769 | Returns a one-line description of the distribution |
05bab18e | 2770 | |
f20de9f0 | 2771 | =item CPAN::Distribution::as_string() |
05bab18e | 2772 | |
f20de9f0 | 2773 | Returns a multi-line description of the distribution |
05bab18e | 2774 | |
f20de9f0 | 2775 | =item CPAN::Distribution::author |
05bab18e | 2776 | |
f20de9f0 SP |
2777 | Returns the CPAN::Author object of the maintainer who uploaded this |
2778 | distribution | |
05bab18e | 2779 | |
f04ea8d1 SP |
2780 | =item CPAN::Distribution::pretty_id() |
2781 | ||
2782 | Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is the | |
2783 | author's PAUSE ID and TARBALL is the distribution filename. | |
2784 | ||
2785 | =item CPAN::Distribution::base_id() | |
2786 | ||
2787 | Returns the distribution filename without any archive suffix. E.g | |
2788 | "Foo-Bar-0.01" | |
2789 | ||
f20de9f0 | 2790 | =item CPAN::Distribution::clean() |
05bab18e | 2791 | |
f20de9f0 SP |
2792 | Changes to the directory where the distribution has been unpacked and |
2793 | runs C<make clean> there. | |
05bab18e | 2794 | |
f20de9f0 | 2795 | =item CPAN::Distribution::containsmods() |
05bab18e | 2796 | |
f20de9f0 | 2797 | Returns a list of IDs of modules contained in a distribution file. |
f9916dde A |
2798 | Works only for distributions listed in the 02packages.details.txt.gz |
2799 | file. This typically means that just most recent version of a | |
f20de9f0 | 2800 | distribution is covered. |
05bab18e | 2801 | |
f20de9f0 | 2802 | =item CPAN::Distribution::cvs_import() |
35576f8c | 2803 | |
f20de9f0 SP |
2804 | Changes to the directory where the distribution has been unpacked and |
2805 | runs something like | |
5f05dabc | 2806 | |
f20de9f0 | 2807 | cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version |
05bab18e | 2808 | |
f20de9f0 | 2809 | there. |
5f05dabc | 2810 | |
f20de9f0 SP |
2811 | =item CPAN::Distribution::dir() |
2812 | ||
2813 | Returns the directory into which this distribution has been unpacked. | |
2814 | ||
2815 | =item CPAN::Distribution::force($method,@args) | |
2816 | ||
2817 | Forces CPAN to perform a task that it normally would have refused to | |
2818 | do. Force takes as arguments a method name to be called and any number | |
2819 | of additional arguments that should be passed to the called method. | |
2820 | The internals of the object get the needed changes so that CPAN.pm | |
2821 | does not refuse to take the action. See also the section above on the | |
2822 | C<force> and the C<fforce> pragma. | |
2823 | ||
2824 | =item CPAN::Distribution::get() | |
2825 | ||
2826 | Downloads the distribution from CPAN and unpacks it. Does nothing if | |
2827 | the distribution has already been downloaded and unpacked within the | |
2828 | current session. | |
2829 | ||
2830 | =item CPAN::Distribution::install() | |
2831 | ||
2832 | Changes to the directory where the distribution has been unpacked and | |
2833 | runs the external command C<make install> there. If C<make> has not | |
f9916dde A |
2834 | yet been run, it will be run first. A C<make test> is issued in |
2835 | any case and if this fails, the install is cancelled. The | |
f20de9f0 SP |
2836 | cancellation can be avoided by letting C<force> run the C<install> for |
2837 | you. | |
2838 | ||
f9916dde A |
2839 | This install method only has the power to install the distribution if |
2840 | there are no dependencies in the way. To install an object along with all | |
f20de9f0 SP |
2841 | its dependencies, use CPAN::Shell->install. |
2842 | ||
2843 | Note that install() gives no meaningful return value. See uptodate(). | |
2844 | ||
2845 | =item CPAN::Distribution::install_tested() | |
2846 | ||
12ad1f85 | 2847 | Install all distributions that have tested successfully but |
f20de9f0 SP |
2848 | not yet installed. See also C<is_tested>. |
2849 | ||
2850 | =item CPAN::Distribution::isa_perl() | |
2851 | ||
2852 | Returns 1 if this distribution file seems to be a perl distribution. | |
2853 | Normally this is derived from the file name only, but the index from | |
2854 | CPAN can contain a hint to achieve a return value of true for other | |
2855 | filenames too. | |
2856 | ||
f20de9f0 SP |
2857 | =item CPAN::Distribution::look() |
2858 | ||
2859 | Changes to the directory where the distribution has been unpacked and | |
2860 | opens a subshell there. Exiting the subshell returns. | |
2861 | ||
2862 | =item CPAN::Distribution::make() | |
2863 | ||
2864 | First runs the C<get> method to make sure the distribution is | |
2865 | downloaded and unpacked. Changes to the directory where the | |
2866 | distribution has been unpacked and runs the external commands C<perl | |
2867 | Makefile.PL> or C<perl Build.PL> and C<make> there. | |
2868 | ||
2869 | =item CPAN::Distribution::perldoc() | |
2870 | ||
2871 | Downloads the pod documentation of the file associated with a | |
f9916dde | 2872 | distribution (in HTML format) and runs it through the external |
0124e695 | 2873 | command I<lynx> specified in C<< $CPAN::Config->{lynx} >>. If I<lynx> |
f9916dde A |
2874 | isn't available, it converts it to plain text with the external |
2875 | command I<html2text> and runs it through the pager specified | |
0124e695 | 2876 | in C<< $CPAN::Config->{pager} >>. |
f20de9f0 SP |
2877 | |
2878 | =item CPAN::Distribution::prefs() | |
2879 | ||
2880 | Returns the hash reference from the first matching YAML file that the | |
2881 | user has deposited in the C<prefs_dir/> directory. The first | |
2882 | succeeding match wins. The files in the C<prefs_dir/> are processed | |
12ad1f85 | 2883 | alphabetically, and the canonical distro name (e.g. |
f20de9f0 SP |
2884 | AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions |
2885 | stored in the $root->{match}{distribution} attribute value. | |
2886 | Additionally all module names contained in a distribution are matched | |
f9916dde | 2887 | against the regular expressions in the $root->{match}{module} attribute |
f20de9f0 SP |
2888 | value. The two match values are ANDed together. Each of the two |
2889 | attributes are optional. | |
2890 | ||
2891 | =item CPAN::Distribution::prereq_pm() | |
2892 | ||
2893 | Returns the hash reference that has been announced by a distribution | |
f9916dde | 2894 | as the C<requires> and C<build_requires> elements. These can be |
f20de9f0 SP |
2895 | declared either by the C<META.yml> (if authoritative) or can be |
2896 | deposited after the run of C<Build.PL> in the file C<./_build/prereqs> | |
2897 | or after the run of C<Makfile.PL> written as the C<PREREQ_PM> hash in | |
2898 | a comment in the produced C<Makefile>. I<Note>: this method only works | |
2899 | after an attempt has been made to C<make> the distribution. Returns | |
2900 | undef otherwise. | |
2901 | ||
2902 | =item CPAN::Distribution::readme() | |
2903 | ||
2904 | Downloads the README file associated with a distribution and runs it | |
0124e695 | 2905 | through the pager specified in C<< $CPAN::Config->{pager} >>. |
f20de9f0 | 2906 | |
dc053c64 SP |
2907 | =item CPAN::Distribution::reports() |
2908 | ||
a7f1e69b | 2909 | Downloads report data for this distribution from www.cpantesters.org |
dc053c64 SP |
2910 | and displays a subset of them. |
2911 | ||
f20de9f0 SP |
2912 | =item CPAN::Distribution::read_yaml() |
2913 | ||
2914 | Returns the content of the META.yml of this distro as a hashref. Note: | |
2915 | works only after an attempt has been made to C<make> the distribution. | |
2916 | Returns undef otherwise. Also returns undef if the content of META.yml | |
2917 | is not authoritative. (The rules about what exactly makes the content | |
2918 | authoritative are still in flux.) | |
2919 | ||
2920 | =item CPAN::Distribution::test() | |
2921 | ||
2922 | Changes to the directory where the distribution has been unpacked and | |
2923 | runs C<make test> there. | |
2924 | ||
2925 | =item CPAN::Distribution::uptodate() | |
2926 | ||
2927 | Returns 1 if all the modules contained in the distribution are | |
12ad1f85 | 2928 | up-to-date. Relies on containsmods. |
f20de9f0 SP |
2929 | |
2930 | =item CPAN::Index::force_reload() | |
2931 | ||
2932 | Forces a reload of all indices. | |
2933 | ||
2934 | =item CPAN::Index::reload() | |
2935 | ||
2936 | Reloads all indices if they have not been read for more than | |
0124e695 | 2937 | C<< $CPAN::Config->{index_expire} >> days. |
f20de9f0 SP |
2938 | |
2939 | =item CPAN::InfoObj::dump() | |
2940 | ||
2941 | CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution | |
2942 | inherit this method. It prints the data structure associated with an | |
2943 | object. Useful for debugging. Note: the data structure is considered | |
2944 | internal and thus subject to change without notice. | |
2945 | ||
2946 | =item CPAN::Module::as_glimpse() | |
2947 | ||
2948 | Returns a one-line description of the module in four columns: The | |
2949 | first column contains the word C<Module>, the second column consists | |
2950 | of one character: an equals sign if this module is already installed | |
12ad1f85 | 2951 | and up-to-date, a less-than sign if this module is installed but can be |
f20de9f0 SP |
2952 | upgraded, and a space if the module is not installed. The third column |
2953 | is the name of the module and the fourth column gives maintainer or | |
2954 | distribution information. | |
2955 | ||
2956 | =item CPAN::Module::as_string() | |
2957 | ||
2958 | Returns a multi-line description of the module | |
2959 | ||
2960 | =item CPAN::Module::clean() | |
2961 | ||
2962 | Runs a clean on the distribution associated with this module. | |
2963 | ||
2964 | =item CPAN::Module::cpan_file() | |
2965 | ||
2966 | Returns the filename on CPAN that is associated with the module. | |
2967 | ||
2968 | =item CPAN::Module::cpan_version() | |
2969 | ||
2970 | Returns the latest version of this module available on CPAN. | |
2971 | ||
2972 | =item CPAN::Module::cvs_import() | |
2973 | ||
2974 | Runs a cvs_import on the distribution associated with this module. | |
2975 | ||
2976 | =item CPAN::Module::description() | |
2977 | ||
2978 | Returns a 44 character description of this module. Only available for | |
2979 | modules listed in The Module List (CPAN/modules/00modlist.long.html | |
2980 | or 00modlist.long.txt.gz) | |
2981 | ||
2982 | =item CPAN::Module::distribution() | |
2983 | ||
2984 | Returns the CPAN::Distribution object that contains the current | |
2985 | version of this module. | |
2986 | ||
2987 | =item CPAN::Module::dslip_status() | |
2988 | ||
2989 | Returns a hash reference. The keys of the hash are the letters C<D>, | |
2990 | C<S>, C<L>, C<I>, and <P>, for development status, support level, | |
2991 | language, interface and public licence respectively. The data for the | |
2992 | DSLIP status are collected by pause.perl.org when authors register | |
2993 | their namespaces. The values of the 5 hash elements are one-character | |
2994 | words whose meaning is described in the table below. There are also 5 | |
2995 | hash elements C<DV>, C<SV>, C<LV>, C<IV>, and <PV> that carry a more | |
2996 | verbose value of the 5 status variables. | |
2997 | ||
2998 | Where the 'DSLIP' characters have the following meanings: | |
2999 | ||
3000 | D - Development Stage (Note: *NO IMPLIED TIMESCALES*): | |
3001 | i - Idea, listed to gain consensus or as a placeholder | |
3002 | c - under construction but pre-alpha (not yet released) | |
3003 | a/b - Alpha/Beta testing | |
3004 | R - Released | |
3005 | M - Mature (no rigorous definition) | |
3006 | S - Standard, supplied with Perl 5 | |
3007 | ||
3008 | S - Support Level: | |
3009 | m - Mailing-list | |
3010 | d - Developer | |
3011 | u - Usenet newsgroup comp.lang.perl.modules | |
3012 | n - None known, try comp.lang.perl.modules | |
12ad1f85 | 3013 | a - abandoned; volunteers welcome to take over maintenance |
f20de9f0 SP |
3014 | |
3015 | L - Language Used: | |
3016 | p - Perl-only, no compiler needed, should be platform independent | |
3017 | c - C and perl, a C compiler will be needed | |
3018 | h - Hybrid, written in perl with optional C code, no compiler needed | |
3019 | + - C++ and perl, a C++ compiler will be needed | |
3020 | o - perl and another language other than C or C++ | |
3021 | ||
3022 | I - Interface Style | |
3023 | f - plain Functions, no references used | |
3024 | h - hybrid, object and function interfaces available | |
3025 | n - no interface at all (huh?) | |
3026 | r - some use of unblessed References or ties | |
3027 | O - Object oriented using blessed references and/or inheritance | |
3028 | ||
3029 | P - Public License | |
3030 | p - Standard-Perl: user may choose between GPL and Artistic | |
3031 | g - GPL: GNU General Public License | |
3032 | l - LGPL: "GNU Lesser General Public License" (previously known as | |
3033 | "GNU Library General Public License") | |
3034 | b - BSD: The BSD License | |
3035 | a - Artistic license alone | |
f04ea8d1 | 3036 | 2 - Artistic license 2.0 or later |
12ad1f85 | 3037 | o - open source: approved by www.opensource.org |
f20de9f0 | 3038 | d - allows distribution without restrictions |
12ad1f85 | 3039 | r - restricted distribution |
f20de9f0 SP |
3040 | n - no license at all |
3041 | ||
3042 | =item CPAN::Module::force($method,@args) | |
3043 | ||
f9916dde A |
3044 | Forces CPAN to perform a task it would normally refuse to |
3045 | do. Force takes as arguments a method name to be invoked and any number | |
3046 | of additional arguments to pass that method. | |
f20de9f0 SP |
3047 | The internals of the object get the needed changes so that CPAN.pm |
3048 | does not refuse to take the action. See also the section above on the | |
3049 | C<force> and the C<fforce> pragma. | |
3050 | ||
3051 | =item CPAN::Module::get() | |
3052 | ||
3053 | Runs a get on the distribution associated with this module. | |
3054 | ||
3055 | =item CPAN::Module::inst_file() | |
3056 | ||
3057 | Returns the filename of the module found in @INC. The first file found | |
f9916dde | 3058 | is reported, just as perl itself stops searching @INC once it finds a |
f20de9f0 | 3059 | module. |
5f05dabc | 3060 | |
f20de9f0 | 3061 | =item CPAN::Module::available_file() |
5f05dabc | 3062 | |
f20de9f0 SP |
3063 | Returns the filename of the module found in PERL5LIB or @INC. The |
3064 | first file found is reported. The advantage of this method over | |
3065 | C<inst_file> is that modules that have been tested but not yet | |
3066 | installed are included because PERL5LIB keeps track of tested modules. | |
5f05dabc | 3067 | |
f20de9f0 | 3068 | =item CPAN::Module::inst_version() |
5f05dabc | 3069 | |
f20de9f0 | 3070 | Returns the version number of the installed module in readable format. |
5f05dabc | 3071 | |
f20de9f0 | 3072 | =item CPAN::Module::available_version() |
5f05dabc | 3073 | |
f20de9f0 | 3074 | Returns the version number of the available module in readable format. |
5f05dabc | 3075 | |
f20de9f0 | 3076 | =item CPAN::Module::install() |
5f05dabc | 3077 | |
f20de9f0 | 3078 | Runs an C<install> on the distribution associated with this module. |
5f05dabc | 3079 | |
f20de9f0 | 3080 | =item CPAN::Module::look() |
5f05dabc | 3081 | |
f20de9f0 SP |
3082 | Changes to the directory where the distribution associated with this |
3083 | module has been unpacked and opens a subshell there. Exiting the | |
3084 | subshell returns. | |
5f05dabc | 3085 | |
f20de9f0 | 3086 | =item CPAN::Module::make() |
5f05dabc | 3087 | |
f20de9f0 SP |
3088 | Runs a C<make> on the distribution associated with this module. |
3089 | ||
3090 | =item CPAN::Module::manpage_headline() | |
3091 | ||
3092 | If module is installed, peeks into the module's manpage, reads the | |
f9916dde | 3093 | headline, and returns it. Moreover, if the module has been downloaded |
f20de9f0 | 3094 | within this session, does the equivalent on the downloaded module even |
f9916dde | 3095 | if it hasn't been installed yet. |
f20de9f0 SP |
3096 | |
3097 | =item CPAN::Module::perldoc() | |
3098 | ||
3099 | Runs a C<perldoc> on this module. | |
3100 | ||
3101 | =item CPAN::Module::readme() | |
3102 | ||
3103 | Runs a C<readme> on the distribution associated with this module. | |
3104 | ||
dc053c64 SP |
3105 | =item CPAN::Module::reports() |
3106 | ||
3107 | Calls the reports() method on the associated distribution object. | |
3108 | ||
f20de9f0 SP |
3109 | =item CPAN::Module::test() |
3110 | ||
3111 | Runs a C<test> on the distribution associated with this module. | |
3112 | ||
3113 | =item CPAN::Module::uptodate() | |
3114 | ||
3115 | Returns 1 if the module is installed and up-to-date. | |
3116 | ||
3117 | =item CPAN::Module::userid() | |
3118 | ||
3119 | Returns the author's ID of the module. | |
5f05dabc | 3120 | |
3121 | =back | |
3122 | ||
f20de9f0 | 3123 | =head2 Cache Manager |
ca79d794 | 3124 | |
f20de9f0 SP |
3125 | Currently the cache manager only keeps track of the build directory |
3126 | ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that | |
3127 | deletes complete directories below C<build_dir> as soon as the size of | |
3128 | all directories there gets bigger than $CPAN::Config->{build_cache} | |
3129 | (in MB). The contents of this cache may be used for later | |
3130 | re-installations that you intend to do manually, but will never be | |
3131 | trusted by CPAN itself. This is due to the fact that the user might | |
3132 | use these directories for building modules on different architectures. | |
3133 | ||
3134 | There is another directory ($CPAN::Config->{keep_source_where}) where | |
3135 | the original distribution files are kept. This directory is not | |
3136 | covered by the cache manager and must be controlled by the user. If | |
3137 | you choose to have the same directory as build_dir and as | |
3138 | keep_source_where directory, then your sources will be deleted with | |
3139 | the same fifo mechanism. | |
3140 | ||
3141 | =head2 Bundles | |
3142 | ||
3143 | A bundle is just a perl module in the namespace Bundle:: that does not | |
3144 | define any functions or methods. It usually only contains documentation. | |
3145 | ||
3146 | It starts like a perl module with a package declaration and a $VERSION | |
3147 | variable. After that the pod section looks like any other pod with the | |
3148 | only difference being that I<one special pod section> exists starting with | |
3149 | (verbatim): | |
3150 | ||
f04ea8d1 | 3151 | =head1 CONTENTS |
f20de9f0 SP |
3152 | |
3153 | In this pod section each line obeys the format | |
3154 | ||
3155 | Module_Name [Version_String] [- optional text] | |
3156 | ||
3157 | The only required part is the first field, the name of a module | |
12ad1f85 | 3158 | (e.g. Foo::Bar, i.e. I<not> the name of the distribution file). The rest |
f20de9f0 SP |
3159 | of the line is optional. The comment part is delimited by a dash just |
3160 | as in the man page header. | |
3161 | ||
3162 | The distribution of a bundle should follow the same convention as | |
3163 | other distributions. | |
3164 | ||
3165 | Bundles are treated specially in the CPAN package. If you say 'install | |
3166 | Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all | |
3167 | the modules in the CONTENTS section of the pod. You can install your | |
3168 | own Bundles locally by placing a conformant Bundle file somewhere into | |
3169 | your @INC path. The autobundle() command which is available in the | |
3170 | shell interface does that for you by including all currently installed | |
3171 | modules in a snapshot bundle file. | |
3172 | ||
3173 | =head1 PREREQUISITES | |
3174 | ||
d1f5653b | 3175 | The CPAN program is trying to depend on as little as possible so the |
12ad1f85 | 3176 | user can use it in hostile environment. It works better the more goodies |
d1f5653b RGS |
3177 | the environment provides. For example if you try in the CPAN shell |
3178 | ||
3179 | install Bundle::CPAN | |
3180 | ||
3181 | or | |
3182 | ||
3183 | install Bundle::CPANxxl | |
3184 | ||
3185 | you will find the shell more convenient than the bare shell before. | |
3186 | ||
f20de9f0 | 3187 | If you have a local mirror of CPAN and can access all files with |
f9916dde | 3188 | "file:" URLs, then you only need a perl later than perl5.003 to run |
f20de9f0 | 3189 | this module. Otherwise Net::FTP is strongly recommended. LWP may be |
f9916dde | 3190 | required for non-UNIX systems, or if your nearest CPAN site is |
f20de9f0 SP |
3191 | associated with a URL that is not C<ftp:>. |
3192 | ||
3193 | If you have neither Net::FTP nor LWP, there is a fallback mechanism | |
3194 | implemented for an external ftp command or for an external lynx | |
3195 | command. | |
3196 | ||
3197 | =head1 UTILITIES | |
3198 | ||
3199 | =head2 Finding packages and VERSION | |
3200 | ||
3201 | This module presumes that all packages on CPAN | |
ca79d794 | 3202 | |
2ccf00a7 SP |
3203 | =over 2 |
3204 | ||
f20de9f0 | 3205 | =item * |
2ccf00a7 | 3206 | |
f20de9f0 SP |
3207 | declare their $VERSION variable in an easy to parse manner. This |
3208 | prerequisite can hardly be relaxed because it consumes far too much | |
3209 | memory to load all packages into the running program just to determine | |
3210 | the $VERSION variable. Currently all programs that are dealing with | |
3211 | version use something like this | |
2ccf00a7 | 3212 | |
f20de9f0 SP |
3213 | perl -MExtUtils::MakeMaker -le \ |
3214 | 'print MM->parse_version(shift)' filename | |
2ccf00a7 | 3215 | |
f20de9f0 SP |
3216 | If you are author of a package and wonder if your $VERSION can be |
3217 | parsed, please try the above method. | |
2ccf00a7 | 3218 | |
f20de9f0 | 3219 | =item * |
2ccf00a7 | 3220 | |
f20de9f0 SP |
3221 | come as compressed or gzipped tarfiles or as zip files and contain a |
3222 | C<Makefile.PL> or C<Build.PL> (well, we try to handle a bit more, but | |
f9916dde | 3223 | with little enthusiasm). |
2ccf00a7 | 3224 | |
f20de9f0 | 3225 | =back |
2ccf00a7 | 3226 | |
f20de9f0 SP |
3227 | =head2 Debugging |
3228 | ||
f9916dde A |
3229 | Debugging this module is more than a bit complex due to interference from |
3230 | the software producing the indices on CPAN, the mirroring process on CPAN, | |
3231 | packaging, configuration, synchronicity, and even (gasp!) due to bugs | |
3232 | within the CPAN.pm module itself. | |
f20de9f0 | 3233 | |
f9916dde A |
3234 | For debugging the code of CPAN.pm itself in interactive mode, some |
3235 | debugging aid can be turned on for most packages within | |
f20de9f0 SP |
3236 | CPAN.pm with one of |
3237 | ||
3238 | =over 2 | |
3239 | ||
3240 | =item o debug package... | |
3241 | ||
3242 | sets debug mode for packages. | |
3243 | ||
3244 | =item o debug -package... | |
3245 | ||
3246 | unsets debug mode for packages. | |
3247 | ||
3248 | =item o debug all | |
3249 | ||
3250 | turns debugging on for all packages. | |
3251 | ||
3252 | =item o debug number | |
2ccf00a7 SP |
3253 | |
3254 | =back | |
ca79d794 | 3255 | |
f20de9f0 SP |
3256 | which sets the debugging packages directly. Note that C<o debug 0> |
3257 | turns debugging off. | |
36263cb3 | 3258 | |
f9916dde | 3259 | What seems a successful strategy is the combination of C<reload |
f20de9f0 SP |
3260 | cpan> and the debugging switches. Add a new debug statement while |
3261 | running in the shell and then issue a C<reload cpan> and see the new | |
3262 | debugging messages immediately without losing the current context. | |
36263cb3 | 3263 | |
f20de9f0 SP |
3264 | C<o debug> without an argument lists the valid package names and the |
3265 | current set of packages in debugging mode. C<o debug> has built-in | |
3266 | completion support. | |
36263cb3 | 3267 | |
f20de9f0 SP |
3268 | For debugging of CPAN data there is the C<dump> command which takes |
3269 | the same arguments as make/test/install and outputs each object's | |
3270 | Data::Dumper dump. If an argument looks like a perl variable and | |
3271 | contains one of C<$>, C<@> or C<%>, it is eval()ed and fed to | |
3272 | Data::Dumper directly. | |
36263cb3 | 3273 | |
f20de9f0 | 3274 | =head2 Floppy, Zip, Offline Mode |
36263cb3 | 3275 | |
f9916dde A |
3276 | CPAN.pm works nicely without network access, too. If you maintain machines |
3277 | that are not networked at all, you should consider working with C<file:> | |
3278 | URLs. You'll have to collect your modules somewhere first. So | |
f20de9f0 SP |
3279 | you might use CPAN.pm to put together all you need on a networked |
3280 | machine. Then copy the $CPAN::Config->{keep_source_where} (but not | |
3281 | $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind | |
3282 | of a personal CPAN. CPAN.pm on the non-networked machines works nicely | |
3283 | with this floppy. See also below the paragraph about CD-ROM support. | |
c356248b | 3284 | |
f20de9f0 | 3285 | =head2 Basic Utilities for Programmers |
c356248b | 3286 | |
f20de9f0 | 3287 | =over 2 |
c356248b | 3288 | |
f20de9f0 | 3289 | =item has_inst($module) |
c356248b | 3290 | |
f20de9f0 | 3291 | Returns true if the module is installed. Used to load all modules into |
f9916dde A |
3292 | the running CPAN.pm that are considered optional. The config variable |
3293 | C<dontload_list> intercepts the C<has_inst()> call such | |
f20de9f0 | 3294 | that an optional module is not loaded despite being available. For |
f9916dde | 3295 | example, the following command will prevent C<YAML.pm> from being |
f20de9f0 | 3296 | loaded: |
2e2b7522 | 3297 | |
f20de9f0 | 3298 | cpan> o conf dontload_list push YAML |
05bab18e | 3299 | |
f20de9f0 | 3300 | See the source for details. |
05bab18e | 3301 | |
f20de9f0 SP |
3302 | =item has_usable($module) |
3303 | ||
f9916dde | 3304 | Returns true if the module is installed and in a usable state. Only |
f20de9f0 SP |
3305 | useful for a handful of modules that are used internally. See the |
3306 | source for details. | |
05bab18e | 3307 | |
f20de9f0 | 3308 | =item instance($module) |
1e8f9a0a | 3309 | |
f20de9f0 | 3310 | The constructor for all the singletons used to represent modules, |
f9916dde A |
3311 | distributions, authors, and bundles. If the object already exists, this |
3312 | method returns the object; otherwise, it calls the constructor. | |
f20de9f0 SP |
3313 | |
3314 | =back | |
1e8f9a0a | 3315 | |
5f05dabc | 3316 | =head1 SECURITY |
3317 | ||
3318 | There's no strong security layer in CPAN.pm. CPAN.pm helps you to | |
3319 | install foreign, unmasked, unsigned code on your machine. We compare | |
3320 | to a checksum that comes from the net just as the distribution file | |
0cf35e6a SP |
3321 | itself. But we try to make it easy to add security on demand: |
3322 | ||
3323 | =head2 Cryptographically signed modules | |
3324 | ||
f9916dde | 3325 | Since release 1.77, CPAN.pm has been able to verify cryptographically |
0cf35e6a SP |
3326 | signed module distributions using Module::Signature. The CPAN modules |
3327 | can be signed by their authors, thus giving more security. The simple | |
3328 | unsigned MD5 checksums that were used before by CPAN protect mainly | |
3329 | against accidental file corruption. | |
3330 | ||
3331 | You will need to have Module::Signature installed, which in turn | |
3332 | requires that you have at least one of Crypt::OpenPGP module or the | |
3333 | command-line F<gpg> tool installed. | |
3334 | ||
3335 | You will also need to be able to connect over the Internet to the public | |
12ad1f85 | 3336 | key servers, like pgp.mit.edu, and their port 11731 (the HKP protocol). |
5f05dabc | 3337 | |
ed84aac9 A |
3338 | The configuration parameter check_sigs is there to turn signature |
3339 | checking on or off. | |
3340 | ||
5f05dabc | 3341 | =head1 EXPORT |
3342 | ||
f9916dde | 3343 | Most functions in package CPAN are exported by default. The reason |
5f05dabc | 3344 | for this is that the primary use is intended for the cpan shell or for |
d1be9408 | 3345 | one-liners. |
5f05dabc | 3346 | |
9ddc4ed0 A |
3347 | =head1 ENVIRONMENT |
3348 | ||
3349 | When the CPAN shell enters a subshell via the look command, it sets | |
f9916dde | 3350 | the environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is |
9ddc4ed0 A |
3351 | already set. |
3352 | ||
f04ea8d1 SP |
3353 | When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING |
3354 | to the ID of the running process. It also sets | |
3355 | PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could | |
3356 | happen with older versions of Module::Install. | |
3357 | ||
3358 | When running C<perl Makefile.PL>, the environment variable | |
3359 | C<PERL5_CPAN_IS_EXECUTING> is set to the full path of the | |
3360 | C<Makefile.PL> that is being executed. This prevents runaway processes | |
3361 | with newer versions of Module::Install. | |
be34b10d | 3362 | |
44d21104 A |
3363 | When the config variable ftp_passive is set, all downloads will be run |
3364 | with the environment variable FTP_PASSIVE set to this value. This is | |
4d1321a7 A |
3365 | in general a good idea as it influences both Net::FTP and LWP based |
3366 | connections. The same effect can be achieved by starting the cpan | |
3367 | shell with this environment variable set. For Net::FTP alone, one can | |
3368 | also always set passive mode by running libnetcfg. | |
44d21104 | 3369 | |
f610777f A |
3370 | =head1 POPULATE AN INSTALLATION WITH LOTS OF MODULES |
3371 | ||
f9916dde | 3372 | Populating a freshly installed perl with one's favorite modules is pretty |
8b3ad137 | 3373 | easy if you maintain a private bundle definition file. To get a useful |
f610777f A |
3374 | blueprint of a bundle definition file, the command autobundle can be used |
3375 | on the CPAN shell command line. This command writes a bundle definition | |
f9916dde A |
3376 | file for all modules installed for the current perl |
3377 | interpreter. It's recommended to run this command once only, and from then | |
f610777f A |
3378 | on maintain the file manually under a private name, say |
3379 | Bundle/my_bundle.pm. With a clever bundle file you can then simply say | |
3380 | ||
3381 | cpan> install Bundle::my_bundle | |
3382 | ||
f9916dde A |
3383 | then answer a few questions and go out for coffee (possibly |
3384 | even in a different city). | |
f610777f | 3385 | |
8b3ad137 | 3386 | Maintaining a bundle definition file means keeping track of two |
36263cb3 GS |
3387 | things: dependencies and interactivity. CPAN.pm sometimes fails on |
3388 | calculating dependencies because not all modules define all MakeMaker | |
3389 | attributes correctly, so a bundle definition file should specify | |
f9916dde A |
3390 | prerequisites as early as possible. On the other hand, it's |
3391 | annoying that so many distributions need some interactive configuring. So | |
3392 | what you can try to accomplish in your private bundle file is to have the | |
36263cb3 | 3393 | packages that need to be configured early in the file and the gentle |
12ad1f85 | 3394 | ones later, so you can go out for coffee after a few minutes and leave CPAN.pm |
f9916dde | 3395 | to churn away untended. |
f610777f A |
3396 | |
3397 | =head1 WORKING WITH CPAN.pm BEHIND FIREWALLS | |
3398 | ||
36263cb3 | 3399 | Thanks to Graham Barr for contributing the following paragraphs about |
de34a54b | 3400 | the interaction between perl, and various firewall configurations. For |
3c4b39be | 3401 | further information on firewalls, it is recommended to consult the |
f9916dde A |
3402 | documentation that comes with the I<ncftp> program. If you are unable to |
3403 | go through the firewall with a simple Perl setup, it is likely | |
3404 | that you can configure I<ncftp> so that it works through your firewall. | |
de34a54b JH |
3405 | |
3406 | =head2 Three basic types of firewalls | |
f610777f A |
3407 | |
3408 | Firewalls can be categorized into three basic types. | |
3409 | ||
bbc7dcd2 | 3410 | =over 4 |
f610777f A |
3411 | |
3412 | =item http firewall | |
3413 | ||
f9916dde A |
3414 | This is when the firewall machine runs a web server, and to access the |
3415 | outside world, you must do so via that web server. If you set environment | |
3416 | variables like http_proxy or ftp_proxy to values beginning with http://, | |
3417 | or in your web browser you've proxy information set, then you know | |
3418 | you are running behind an http firewall. | |
f610777f A |
3419 | |
3420 | To access servers outside these types of firewalls with perl (even for | |
a52237f3 | 3421 | ftp), you need LWP or HTTP::Tiny. |
f610777f A |
3422 | |
3423 | =item ftp firewall | |
3424 | ||
d1be9408 | 3425 | This where the firewall machine runs an ftp server. This kind of |
911a92db GS |
3426 | firewall will only let you access ftp servers outside the firewall. |
3427 | This is usually done by connecting to the firewall with ftp, then | |
f9916dde | 3428 | entering a username like "user@outside.host.com". |
f610777f | 3429 | |
f9916dde A |
3430 | To access servers outside these type of firewalls with perl, you |
3431 | need Net::FTP. | |
f610777f | 3432 | |
f9916dde | 3433 | =item One-way visibility |
f610777f | 3434 | |
f9916dde A |
3435 | One-way visibility means these firewalls try to make themselves |
3436 | invisible to users inside the firewall. An FTP data connection is | |
3437 | normally created by sending your IP address to the remote server and then | |
3438 | listening for the return connection. But the remote server will not be able to | |
3439 | connect to you because of the firewall. For these types of firewall, | |
f610777f A |
3440 | FTP connections need to be done in a passive mode. |
3441 | ||
3442 | There are two that I can think off. | |
3443 | ||
bbc7dcd2 | 3444 | =over 4 |
f610777f A |
3445 | |
3446 | =item SOCKS | |
3447 | ||
f9916dde A |
3448 | If you are using a SOCKS firewall, you will need to compile perl and link |
3449 | it with the SOCKS library. This is what is normally called a 'socksified' | |
f610777f | 3450 | perl. With this executable you will be able to connect to servers outside |
f9916dde | 3451 | the firewall as if it were not there. |
f610777f A |
3452 | |
3453 | =item IP Masquerade | |
3454 | ||
f9916dde A |
3455 | This is when the firewall implemented in the kernel (via NAT, or networking |
3456 | address translation), it allows you to hide a complete network behind one | |
3457 | IP address. With this firewall no special compiling is needed as you can | |
3458 | access hosts directly. | |
f610777f | 3459 | |
4d1321a7 A |
3460 | For accessing ftp servers behind such firewalls you usually need to |
3461 | set the environment variable C<FTP_PASSIVE> or the config variable | |
3462 | ftp_passive to a true value. | |
5fc0f0f6 | 3463 | |
f610777f A |
3464 | =back |
3465 | ||
3466 | =back | |
3467 | ||
c4d24d4c | 3468 | =head2 Configuring lynx or ncftp for going through a firewall |
de34a54b JH |
3469 | |
3470 | If you can go through your firewall with e.g. lynx, presumably with a | |
3471 | command such as | |
3472 | ||
3473 | /usr/local/bin/lynx -pscott:tiger | |
3474 | ||
3475 | then you would configure CPAN.pm with the command | |
3476 | ||
3477 | o conf lynx "/usr/local/bin/lynx -pscott:tiger" | |
3478 | ||
3479 | That's all. Similarly for ncftp or ftp, you would configure something | |
3480 | like | |
3481 | ||
3482 | o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg" | |
3483 | ||
d1be9408 | 3484 | Your mileage may vary... |
de34a54b JH |
3485 | |
3486 | =head1 FAQ | |
3487 | ||
bbc7dcd2 | 3488 | =over 4 |
de34a54b | 3489 | |
551e1d92 RB |
3490 | =item 1) |
3491 | ||
3492 | I installed a new version of module X but CPAN keeps saying, | |
3493 | I have the old version installed | |
de34a54b | 3494 | |
f9916dde | 3495 | Probably you B<do> have the old version installed. This can |
de34a54b JH |
3496 | happen if a module installs itself into a different directory in the |
3497 | @INC path than it was previously installed. This is not really a | |
3498 | CPAN.pm problem, you would have the same problem when installing the | |
3499 | module manually. The easiest way to prevent this behaviour is to add | |
3500 | the argument C<UNINST=1> to the C<make install> call, and that is why | |
3501 | many people add this argument permanently by configuring | |
3502 | ||
3503 | o conf make_install_arg UNINST=1 | |
3504 | ||
551e1d92 RB |
3505 | =item 2) |
3506 | ||
3507 | So why is UNINST=1 not the default? | |
de34a54b JH |
3508 | |
3509 | Because there are people who have their precise expectations about who | |
3510 | may install where in the @INC path and who uses which @INC array. In | |
3511 | fine tuned environments C<UNINST=1> can cause damage. | |
3512 | ||
551e1d92 RB |
3513 | =item 3) |
3514 | ||
3515 | I want to clean up my mess, and install a new perl along with | |
3516 | all modules I have. How do I go about it? | |
9d61fa1d A |
3517 | |
3518 | Run the autobundle command for your old perl and optionally rename the | |
3519 | resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl | |
3520 | with the Configure option prefix, e.g. | |
3521 | ||
3522 | ./Configure -Dprefix=/usr/local/perl-5.6.78.9 | |
3523 | ||
3524 | Install the bundle file you produced in the first step with something like | |
3525 | ||
3526 | cpan> install Bundle::mybundle | |
3527 | ||
3528 | and you're done. | |
3529 | ||
551e1d92 RB |
3530 | =item 4) |
3531 | ||
3532 | When I install bundles or multiple modules with one command | |
3533 | there is too much output to keep track of. | |
de34a54b JH |
3534 | |
3535 | You may want to configure something like | |
3536 | ||
3537 | o conf make_arg "| tee -ai /root/.cpan/logs/make.out" | |
3538 | o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out" | |
3539 | ||
3540 | so that STDOUT is captured in a file for later inspection. | |
3541 | ||
c4d24d4c | 3542 | |
551e1d92 RB |
3543 | =item 5) |
3544 | ||
3545 | I am not root, how can I install a module in a personal directory? | |
c4d24d4c | 3546 | |
64a589f6 DG |
3547 | As of CPAN 1.9463, if you do not have permission to write the default perl |
3548 | library directories, CPAN's configuration process will ask you whether | |
3549 | you want to bootstrap <local::lib>, which makes keeping a personal | |
3550 | perl library directory easy. | |
87892b73 | 3551 | |
4d1321a7 | 3552 | Another thing you should bear in mind is that the UNINST parameter can |
f04ea8d1 | 3553 | be dangerous when you are installing into a private area because you |
4d1321a7 A |
3554 | might accidentally remove modules that other people depend on that are |
3555 | not using the private area. | |
c4d24d4c | 3556 | |
551e1d92 RB |
3557 | =item 6) |
3558 | ||
3559 | How to get a package, unwrap it, and make a change before building it? | |
c4d24d4c | 3560 | |
8962fc49 | 3561 | Have a look at the C<look> (!) command. |
c4d24d4c | 3562 | |
551e1d92 RB |
3563 | =item 7) |
3564 | ||
3565 | I installed a Bundle and had a couple of fails. When I | |
3566 | retried, everything resolved nicely. Can this be fixed to work | |
3567 | on first try? | |
c4d24d4c A |
3568 | |
3569 | The reason for this is that CPAN does not know the dependencies of all | |
3570 | modules when it starts out. To decide about the additional items to | |
44d21104 A |
3571 | install, it just uses data found in the META.yml file or the generated |
3572 | Makefile. An undetected missing piece breaks the process. But it may | |
3573 | well be that your Bundle installs some prerequisite later than some | |
3574 | depending item and thus your second try is able to resolve everything. | |
3575 | Please note, CPAN.pm does not know the dependency tree in advance and | |
3576 | cannot sort the queue of things to install in a topologically correct | |
f9916dde | 3577 | order. It resolves perfectly well B<if> all modules declare the |
44d21104 A |
3578 | prerequisites correctly with the PREREQ_PM attribute to MakeMaker or |
3579 | the C<requires> stanza of Module::Build. For bundles which fail and | |
3580 | you need to install often, it is recommended to sort the Bundle | |
3581 | definition file manually. | |
5a5fac02 | 3582 | |
551e1d92 RB |
3583 | =item 8) |
3584 | ||
f9916dde | 3585 | In our intranet, we have many modules for internal use. How |
551e1d92 RB |
3586 | can I integrate these modules with CPAN.pm but without uploading |
3587 | the modules to CPAN? | |
5a5fac02 JH |
3588 | |
3589 | Have a look at the CPAN::Site module. | |
c4d24d4c | 3590 | |
551e1d92 RB |
3591 | =item 9) |
3592 | ||
44d21104 | 3593 | When I run CPAN's shell, I get an error message about things in my |
f9916dde | 3594 | C</etc/inputrc> (or C<~/.inputrc>) file. |
9d61fa1d | 3595 | |
44d21104 A |
3596 | These are readline issues and can only be fixed by studying readline |
3597 | configuration on your architecture and adjusting the referenced file | |
f9916dde | 3598 | accordingly. Please make a backup of the C</etc/inputrc> or C<~/.inputrc> |
44d21104 A |
3599 | and edit them. Quite often harmless changes like uppercasing or |
3600 | lowercasing some arguments solves the problem. | |
8d97e4a1 | 3601 | |
551e1d92 RB |
3602 | =item 10) |
3603 | ||
3604 | Some authors have strange characters in their names. | |
8d97e4a1 JH |
3605 | |
3606 | Internally CPAN.pm uses the UTF-8 charset. If your terminal is | |
3607 | expecting ISO-8859-1 charset, a converter can be activated by setting | |
3608 | term_is_latin to a true value in your config file. One way of doing so | |
3609 | would be | |
3610 | ||
44d21104 | 3611 | cpan> o conf term_is_latin 1 |
8d97e4a1 | 3612 | |
12ad1f85 | 3613 | If other charset support is needed, please file a bug report against |
44d21104 A |
3614 | CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend |
3615 | the support or maybe UTF-8 terminals become widely available. | |
9d61fa1d | 3616 | |
f04ea8d1 SP |
3617 | Note: this config variable is deprecated and will be removed in a |
3618 | future version of CPAN.pm. It will be replaced with the conventions | |
3619 | around the family of $LANG and $LC_* environment variables. | |
3620 | ||
554a9ef5 SP |
3621 | =item 11) |
3622 | ||
3623 | When an install fails for some reason and then I correct the error | |
3624 | condition and retry, CPAN.pm refuses to install the module, saying | |
3625 | C<Already tried without success>. | |
3626 | ||
3627 | Use the force pragma like so | |
3628 | ||
3629 | force install Foo::Bar | |
3630 | ||
554a9ef5 SP |
3631 | Or you can use |
3632 | ||
3633 | look Foo::Bar | |
3634 | ||
f9916dde | 3635 | and then C<make install> directly in the subshell. |
554a9ef5 | 3636 | |
44d21104 A |
3637 | =item 12) |
3638 | ||
3639 | How do I install a "DEVELOPER RELEASE" of a module? | |
3640 | ||
8962fc49 SP |
3641 | By default, CPAN will install the latest non-developer release of a |
3642 | module. If you want to install a dev release, you have to specify the | |
3643 | partial path starting with the author id to the tarball you wish to | |
3644 | install, like so: | |
44d21104 | 3645 | |
4d1321a7 | 3646 | cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz |
44d21104 | 3647 | |
8962fc49 SP |
3648 | Note that you can use the C<ls> command to get this path listed. |
3649 | ||
44d21104 A |
3650 | =item 13) |
3651 | ||
4d1321a7 | 3652 | How do I install a module and all its dependencies from the commandline, |
44d21104 A |
3653 | without being prompted for anything, despite my CPAN configuration |
3654 | (or lack thereof)? | |
3655 | ||
4d1321a7 | 3656 | CPAN uses ExtUtils::MakeMaker's prompt() function to ask its questions, so |
44d21104 A |
3657 | if you set the PERL_MM_USE_DEFAULT environment variable, you shouldn't be |
3658 | asked any questions at all (assuming the modules you are installing are | |
3659 | nice about obeying that variable as well): | |
3660 | ||
3661 | % PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module' | |
3662 | ||
b96578bb SP |
3663 | =item 14) |
3664 | ||
05bab18e | 3665 | How do I create a Module::Build based Build.PL derived from an |
ed84aac9 | 3666 | ExtUtils::MakeMaker focused Makefile.PL? |
b96578bb | 3667 | |
0124e695 | 3668 | http://search.cpan.org/dist/Module-Build-Convert/ |
b96578bb | 3669 | |
05bab18e SP |
3670 | =item 15) |
3671 | ||
5254b38e SP |
3672 | I'm frequently irritated with the CPAN shell's inability to help me |
3673 | select a good mirror. | |
05bab18e | 3674 | |
a52237f3 DG |
3675 | CPAN can now help you select a "good" mirror, based on which ones have the |
3676 | lowest 'ping' round-trip times. From the shell, use the command 'o conf init | |
3677 | urllist' and allow CPAN to automatically select mirrors for you. | |
3678 | ||
3679 | Beyond that help, the urllist config parameter is yours. You can add and remove | |
12ad1f85 | 3680 | sites at will. You should find out which sites have the best up-to-dateness, |
a52237f3 | 3681 | bandwidth, reliability, etc. and are topologically close to you. Some people |
12ad1f85 | 3682 | prefer fast downloads, others up-to-dateness, others reliability. You decide |
a52237f3 | 3683 | which to try in which order. |
05bab18e SP |
3684 | |
3685 | Henk P. Penning maintains a site that collects data about CPAN sites: | |
3686 | ||
3687 | http://www.cs.uu.nl/people/henkp/mirmon/cpan.html | |
b96578bb | 3688 | |
5254b38e SP |
3689 | Also, feel free to play with experimental features. Run |
3690 | ||
3691 | o conf init randomize_urllist ftpstats_period ftpstats_size | |
3692 | ||
3693 | and choose your favorite parameters. After a few downloads running the | |
3694 | C<hosts> command will probably assist you in choosing the best mirror | |
3695 | sites. | |
3696 | ||
f04ea8d1 SP |
3697 | =item 16) |
3698 | ||
3699 | Why do I get asked the same questions every time I start the shell? | |
3700 | ||
3701 | You can make your configuration changes permanent by calling the | |
3702 | command C<o conf commit>. Alternatively set the C<auto_commit> | |
3703 | variable to true by running C<o conf init auto_commit> and answering | |
3704 | the following question with yes. | |
3705 | ||
5254b38e SP |
3706 | =item 17) |
3707 | ||
3708 | Older versions of CPAN.pm had the original root directory of all | |
3709 | tarballs in the build directory. Now there are always random | |
3710 | characters appended to these directory names. Why was this done? | |
3711 | ||
3712 | The random characters are provided by File::Temp and ensure that each | |
3713 | module's individual build directory is unique. This makes running | |
3714 | CPAN.pm in concurrent processes simultaneously safe. | |
3715 | ||
3716 | =item 18) | |
3717 | ||
3718 | Speaking of the build directory. Do I have to clean it up myself? | |
3719 | ||
3720 | You have the choice to set the config variable C<scan_cache> to | |
3721 | C<never>. Then you must clean it up yourself. The other possible | |
64a589f6 DG |
3722 | values, C<atstart> and C<atexit> clean up the build directory when you |
3723 | start or exit the CPAN shell, respectively. If you never start up the | |
3724 | CPAN shell, you probably also have to clean up the build directory | |
3725 | yourself. | |
5254b38e | 3726 | |
de34a54b JH |
3727 | =back |
3728 | ||
b72dd56f | 3729 | =head1 COMPATIBILITY |
5f05dabc | 3730 | |
b72dd56f | 3731 | =head2 OLD PERL VERSIONS |
4d1321a7 | 3732 | |
b72dd56f SP |
3733 | CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted |
3734 | newer versions. It is getting more and more difficult to get the | |
3735 | minimal prerequisites working on older perls. It is close to | |
3736 | impossible to get the whole Bundle::CPAN working there. If you're in | |
3737 | the position to have only these old versions, be advised that CPAN is | |
3738 | designed to work fine without the Bundle::CPAN installed. | |
3739 | ||
3740 | To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is | |
3741 | compatible with ancient perls and that File::Temp is listed as a | |
3742 | prerequisite but CPAN has reasonable workarounds if it is missing. | |
3743 | ||
3744 | =head2 CPANPLUS | |
3745 | ||
3746 | This module and its competitor, the CPANPLUS module, are both much | |
3747 | cooler than the other. CPAN.pm is older. CPANPLUS was designed to be | |
f9916dde | 3748 | more modular, but it was never intended to be compatible with CPAN.pm. |
09d9d230 | 3749 | |
742adbff A |
3750 | =head2 CPANMINUS |
3751 | ||
3752 | In the year 2010 App::cpanminus was launched as a new approach to a | |
3753 | cpan shell with a considerably smaller footprint. Very cool stuff. | |
3754 | ||
ed84aac9 A |
3755 | =head1 SECURITY ADVICE |
3756 | ||
3757 | This software enables you to upgrade software on your computer and so | |
3758 | is inherently dangerous because the newly installed software may | |
3759 | contain bugs and may alter the way your computer works or even make it | |
3760 | unusable. Please consider backing up your data before every upgrade. | |
3761 | ||
b72dd56f SP |
3762 | =head1 BUGS |
3763 | ||
b03f445c | 3764 | Please report bugs via L<http://rt.cpan.org/> |
b72dd56f SP |
3765 | |
3766 | Before submitting a bug, please make sure that the traditional method | |
3767 | of building a Perl module package from a shell by following the | |
3768 | installation instructions of that package still works in your | |
3769 | environment. | |
3770 | ||
5f05dabc | 3771 | =head1 AUTHOR |
3772 | ||
e82b9348 | 3773 | Andreas Koenig C<< <andk@cpan.org> >> |
5f05dabc | 3774 | |
2ccf00a7 SP |
3775 | =head1 LICENSE |
3776 | ||
3777 | This program is free software; you can redistribute it and/or | |
3778 | modify it under the same terms as Perl itself. | |
3779 | ||
3780 | See L<http://www.perl.com/perl/misc/Artistic.html> | |
3781 | ||
c049f953 JH |
3782 | =head1 TRANSLATIONS |
3783 | ||
d1f5653b RGS |
3784 | Kawai,Takanori provides a Japanese translation of a very old version |
3785 | of this manpage at | |
b03f445c | 3786 | L<http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm> |
c049f953 | 3787 | |
5f05dabc | 3788 | =head1 SEE ALSO |
3789 | ||
d1f5653b RGS |
3790 | Many people enter the CPAN shell by running the L<cpan> utility |
3791 | program which is installed in the same directory as perl itself. So if | |
3792 | you have this directory in your PATH variable (or some equivalent in | |
3793 | your operating system) then typing C<cpan> in a console window will | |
3794 | work for you as well. Above that the utility provides several | |
3795 | commandline shortcuts. | |
5f05dabc | 3796 | |
3797 | =cut |