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