# -*- Mode: cperl; coding: utf-8; cperl-indent-level: 4 -*-
use strict;
package CPAN;
-$CPAN::VERSION = '1.88_62';
+$CPAN::VERSION = '1.88_78';
$CPAN::VERSION = eval $CPAN::VERSION;
use CPAN::HandleConfig;
BEGIN {
if (File::Spec->can("rel2abs")) {
for my $inc (@INC) {
- $inc = File::Spec->rel2abs($inc);
+ $inc = File::Spec->rel2abs($inc) unless ref $inc;
}
}
}
no lib ".";
require Mac::BuildTools if $^O eq 'MacOS';
+$ENV{PERL5_CPAN_IS_RUNNING}=1;
+$ENV{PERL5_CPANPLUS_IS_RUNNING}=1; # https://rt.cpan.org/Ticket/Display.html?id=23735
END { $CPAN::End++; &cleanup; }
$AUTOLOAD
$Be_Silent
$CONFIG_DIRTY
- $DEBUG
$Defaultdocs
$Defaultrecent
+ $Echo_readline
$Frontend
$GOTOSHELL
$HAS_USABLE
$Have_warned
+ $MAX_RECURSION
$META
$RUN_DEGRADED
$Signal
+ $SQLite
$Suppress_readline
$VERSION
$autoload_recursion
@EXPORT
);
+$MAX_RECURSION = 32;
+
@CPAN::ISA = qw(CPAN::Debug Exporter);
# note that these functions live in CPAN::Shell and get executed via
cvs_import
expand
force
+ fforce
get
install
install_tested
+ is_tested
make
mkmyconfig
notest
$CPAN::Frontend->mywarn("Terminal does not support AddHistory.\n");
last;
}
- my($fh) = FileHandle->new;
- open $fh, "<$histfile" or last;
- local $/ = "\n";
- while (<$fh>) {
- chomp;
- $term->AddHistory($_);
- }
- close $fh;
+ $META->readhist($term,$histfile);
}}
for ($CPAN::Config->{term_ornaments}) { # alias
local $Term::ReadLine::termcap_nowarn = 1;
select $odef;
}
- # no strict; # I do not recall why no strict was here (2000-09-03)
$META->checklock();
my @cwd = grep { defined $_ and length $_ }
CPAN::anycwd(),
my $last_term_ornaments;
SHELLCOMMAND: while () {
if ($Suppress_readline) {
+ if ($Echo_readline) {
+ $|=1;
+ }
print $prompt;
last SHELLCOMMAND unless defined ($_ = <> );
+ if ($Echo_readline) {
+ # backdoor: I could not find a way to record sessions
+ print $_;
+ }
chomp;
} else {
last SHELLCOMMAND unless
$CPAN::META->debug("line[".join("|",@line)."]") if $CPAN::DEBUG;
my $command = shift @line;
eval { CPAN::Shell->$command(@line) };
- if ($@){
+ if ($@ && "$@" =~ /\S/){
require Carp;
- Carp::cluck($@);
+ Carp::cluck("Catching error: '$@'");
}
- if ($command =~ /^(make|test|install|force|notest|clean|report|upgrade)$/) {
+ if ($command =~ /^(make|test|install|ff?orce|notest|clean|report|upgrade)$/) {
CPAN::Shell->failed($CPAN::CurrentCommandId,1);
}
soft_chdir_with_alternatives(\@cwd);
}
}
-sub _yaml_module {
+sub _yaml_module () {
my $yaml_module = $CPAN::Config->{yaml_module} || "YAML";
if (
$yaml_module ne "YAML"
sub _yaml_loadfile {
my($self,$local_file) = @_;
return +[] unless -s $local_file;
- my $yaml_module = $self->_yaml_module;
+ my $yaml_module = _yaml_module;
if ($CPAN::META->has_inst($yaml_module)) {
- my $code = UNIVERSAL::can($yaml_module, "LoadFile");
- my @yaml;
- eval { @yaml = $code->($local_file); };
- if ($@) {
- $CPAN::Frontend->mydie("Alert: While trying to parse YAML file\n".
- " $local_file\n".
- "with $yaml_module the following error was encountered:\n".
- " $@\n"
- );
+ my $code;
+ if ($code = UNIVERSAL::can($yaml_module, "LoadFile")) {
+ my @yaml;
+ eval { @yaml = $code->($local_file); };
+ if ($@) {
+ # this shall not be done by the frontend
+ die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
+ }
+ return \@yaml;
+ } elsif ($code = UNIVERSAL::can($yaml_module, "Load")) {
+ local *FH;
+ open FH, $local_file or die "Could not open '$local_file': $!";
+ local $/;
+ my $ystream = <FH>;
+ my @yaml;
+ eval { @yaml = $code->($ystream); };
+ if ($@) {
+ # this shall not be done by the frontend
+ die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"parse",$@);
+ }
+ return \@yaml;
}
- return \@yaml;
} else {
- $CPAN::Frontend->mywarn("'$yaml_module' not installed, cannot parse '$local_file'\n");
+ # this shall not be done by the frontend
+ die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "parse");
}
return +[];
}
# CPAN::_yaml_dumpfile
sub _yaml_dumpfile {
- my($self,$to_local_file,@what) = @_;
- my $yaml_module = $self->_yaml_module;
+ my($self,$local_file,@what) = @_;
+ my $yaml_module = _yaml_module;
if ($CPAN::META->has_inst($yaml_module)) {
- if (UNIVERSAL::isa($to_local_file, "FileHandle")) {
- my $code = UNIVERSAL::can($yaml_module, "Dump");
- eval { print $to_local_file $code->(@what) };
- } else {
- my $code = UNIVERSAL::can($yaml_module, "DumpFile");
- eval { $code->($to_local_file,@what); };
+ my $code;
+ if (UNIVERSAL::isa($local_file, "FileHandle")) {
+ $code = UNIVERSAL::can($yaml_module, "Dump");
+ eval { print $local_file $code->(@what) };
+ } elsif ($code = UNIVERSAL::can($yaml_module, "DumpFile")) {
+ eval { $code->($local_file,@what); };
+ } elsif ($code = UNIVERSAL::can($yaml_module, "Dump")) {
+ local *FH;
+ open FH, ">$local_file" or die "Could not open '$local_file': $!";
+ print FH $code->(@what);
}
if ($@) {
- $CPAN::Frontend->mydie("Alert: While trying to dump YAML file\n".
- " $to_local_file\n".
- "with $yaml_module the following error was encountered:\n".
- " $@\n"
- );
+ die CPAN::Exception::yaml_process_error->new($yaml_module,$local_file,"dump",$@);
}
} else {
- $CPAN::Frontend->myprint("Note (usually harmless): '$yaml_module' not installed, not dumping to '$to_local_file'\n");
+ if (UNIVERSAL::isa($local_file, "FileHandle")) {
+ # I think this case does not justify a warning at all
+ } else {
+ die CPAN::Exception::yaml_not_installed->new($yaml_module, $local_file, "dump");
+ }
+ }
+}
+
+sub _init_sqlite () {
+ unless ($CPAN::META->has_inst("CPAN::SQLite")) {
+ $CPAN::Frontend->mywarn(qq{CPAN::SQLite not installed, trying to work without\n})
+ unless $Have_warned->{"CPAN::SQLite"}++;
+ return;
+ }
+ require CPAN::SQLite::META; # not needed since CVS version of 2006-12-17
+ $CPAN::SQLite ||= CPAN::SQLite::META->new($CPAN::META);
+}
+
+{
+ my $negative_cache = {};
+ sub _sqlite_running {
+ if ($negative_cache->{time} && time < $negative_cache->{time} + 60) {
+ # need to cache the result, otherwise too slow
+ return $negative_cache->{fact};
+ } else {
+ $negative_cache = {}; # reset
+ }
+ my $ret = $CPAN::Config->{use_sqlite} && ($CPAN::SQLite || _init_sqlite());
+ return $ret if $ret; # fast anyway
+ $negative_cache->{time} = time;
+ return $negative_cache->{fact} = $ret;
}
}
clean
cvs_import
dump
+ failed
force
+ fforce
hosts
install
install_tested
+ is_tested
look
ls
make
use strict;
use overload '""' => "as_string";
+# a module sees its distribution (no version)
+# a distribution sees its prereqs (which are module names) (usually with versions)
+# a bundle sees its module names and/or its distributions (no version)
+
sub new {
my($class) = shift;
my($deps) = shift;
".\nCannot continue.\n";
}
+package CPAN::Exception::yaml_not_installed;
+use strict;
+use overload '""' => "as_string";
+
+sub new {
+ my($class,$module,$file,$during) = @_;
+ bless { module => $module, file => $file, during => $during }, $class;
+}
+
+sub as_string {
+ my($self) = shift;
+ "'$self->{module}' not installed, cannot $self->{during} '$self->{file}'\n";
+}
+
+package CPAN::Exception::yaml_process_error;
+use strict;
+use overload '""' => "as_string";
+
+sub new {
+ my($class,$module,$file,$during,$error) = shift;
+ bless { module => $module,
+ file => $file,
+ during => $during,
+ error => $error }, $class;
+}
+
+sub as_string {
+ my($self) = shift;
+ "Alert: While trying to $self->{during} YAML file\n".
+ " $self->{file}\n".
+ "with '$self->{module}' the following error was encountered:\n".
+ " $self->{error}\n";
+}
+
package CPAN::Prompt; use overload '""' => "as_string";
use vars qw($prompt);
$prompt = "cpan> ";
TEXT => $arg,
FAILED => substr($arg,0,2) eq "NO",
COMMANDID => $CPAN::CurrentCommandId,
+ TIME => time,
}, $class;
}
sub commandid { shift->{COMMANDID} }
if (defined $dll) {
$mtime_dll = (-f $dll ? (stat(_))[9] : '-1');
}
+ my $mtime_perl = (-f $^X ? (stat(_))[9] : '-1');
my $this_fingerprint = {
'$^X' => $^X,
sitearchexp => $Config::Config{sitearchexp},
- 'mtime_$^X' => (stat $^X)[9],
+ 'mtime_$^X' => $mtime_perl,
'mtime_dll' => $mtime_dll,
};
if ($other_fingerprint) {
Please report if something unexpected happens\n");
$RUN_DEGRADED = 1;
for ($CPAN::Config) {
- $_->{build_dir_reuse} = 0;
- $_->{commandnumber_in_prompt} = 0;
- $_->{histfile} = "";
- $_->{cache_metadata} = 0;
+ # XXX
+ # $_->{build_dir_reuse} = 0; # 2006-11-17 akoenig Why was that?
+ $_->{commandnumber_in_prompt} = 0; # visibility
+ $_->{histfile} = ""; # who should win otherwise?
+ $_->{cache_metadata} = 0; # better would be a lock?
+ $_->{use_sqlite} = 0; # better would be a write lock!
}
} else {
$CPAN::Frontend->mydie("
### Carp::croak "exists called without class argument" unless $class;
$id ||= "";
$id =~ s/:+/::/g if $class eq "CPAN::Module";
- exists $META->{readonly}{$class}{$id} or
- exists $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
+ my $exists;
+ if (CPAN::_sqlite_running) {
+ $exists = (exists $META->{readonly}{$class}{$id} or
+ $CPAN::SQLite->set($class, $id));
+ } else {
+ $exists = exists $META->{readonly}{$class}{$id};
+ }
+ $exists ||= exists $META->{readwrite}{$class}{$id}; # unsafe meta access, ok
}
#-> sub CPAN::delete ;
}
},
],
+ 'Archive::Tar' => [
+ sub {require Archive::Tar;
+ unless (Archive::Tar::->VERSION >= 1.00) {
+ for ("Will not use Archive::Tar, need 1.00\n") {
+ $CPAN::Frontend->mywarn($_);
+ die $_;
+ }
+ }
+ },
+ ],
};
if ($usable->{$mod}) {
for my $c (0..$#{$usable->{$mod}}) {
$CPAN::Frontend->mysleep(3);
} elsif ($mod eq "Digest::SHA"){
if ($Have_warned->{"Digest::SHA"}++) {
- $CPAN::Frontend->myprint(qq{CPAN: checksum security checks disabled}.
+ $CPAN::Frontend->myprint(qq{CPAN: checksum security checks disabled }.
qq{because Digest::SHA not installed.\n});
} else {
$CPAN::Frontend->mywarn(qq{
$CPAN::Frontend->mysleep(2);
}
} elsif ($mod eq "Module::Signature"){
- if (not $CPAN::Config->{check_sigs}) {
+ # NOT prefs_lookup, we are not a distro
+ my $check_sigs = $CPAN::Config->{check_sigs};
+ if (not $check_sigs) {
# they do not want us:-(
} elsif (not $Have_warned->{"Module::Signature"}++) {
# No point in complaining unless the user can
return unless defined $META->{LOCK};
return unless -f $META->{LOCK};
$META->savehist;
+ close $META->{LOCKFH};
unlink $META->{LOCK};
# require Carp;
# Carp::cluck("DEBUGGING");
$CPAN::Frontend->myprint("Lockfile removed.\n");
}
+#-> sub CPAN::readhist
+sub readhist {
+ my($self,$term,$histfile) = @_;
+ my($fh) = FileHandle->new;
+ open $fh, "<$histfile" or last;
+ local $/ = "\n";
+ while (<$fh>) {
+ chomp;
+ $term->AddHistory($_);
+ }
+ close $fh;
+}
+
#-> sub CPAN::savehist
sub savehist {
my($self) = @_;
#-> sub CPAN::is_tested
sub is_tested {
- my($self,$what) = @_;
- $self->{is_tested}{$what} = 1;
+ my($self,$what,$when) = @_;
+ unless ($what) {
+ Carp::cluck("DEBUG: empty what");
+ return;
+ }
+ $self->{is_tested}{$what} = $when;
}
#-> sub CPAN::is_installed
delete $self->{is_tested}{$what};
}
+sub _list_sorted_descending_is_tested {
+ my($self) = @_;
+ sort
+ { ($self->{is_tested}{$b}||0) <=> ($self->{is_tested}{$a}||0) }
+ keys %{$self->{is_tested}}
+}
+
#-> sub CPAN::set_perl5lib
sub set_perl5lib {
my($self,$for) = @_;
push @env, $env if defined $env and length $env;
#my @dirs = map {("$_/blib/arch", "$_/blib/lib")} keys %{$self->{is_tested}};
#$CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB.\n");
- my @dirs = map {("$_/blib/arch", "$_/blib/lib")} sort keys %{$self->{is_tested}};
- if (@dirs < 15) {
- $CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB for $for\n");
+
+ my @dirs = map {("$_/blib/arch", "$_/blib/lib")} $self->_list_sorted_descending_is_tested;
+ if (@dirs < 12) {
+ $CPAN::Frontend->myprint("Prepending @dirs to PERL5LIB for '$for'\n");
+ } elsif (@dirs < 24) {
+ my @d = map {my $cp = $_;
+ $cp =~ s/^\Q$CPAN::Config->{build_dir}\E/%BUILDDIR%/;
+ $cp
+ } @dirs;
+ $CPAN::Frontend->myprint("Prepending @d to PERL5LIB; ".
+ "%BUILDDIR%=$CPAN::Config->{build_dir} ".
+ "for '$for'\n"
+ );
} else {
- my @d = map {s/^\Q$CPAN::Config->{'build_dir'}/%BUILDDIR%/; $_ }
- sort keys %{$self->{is_tested}};
- $CPAN::Frontend->myprint("Prepending blib/arch and blib/lib subdirs of ".
- "@d to PERL5LIB; ".
- "%BUILDDIR%=$CPAN::Config->{'build_dir'} ".
- "for $for\n"
+ my $cnt = keys %{$self->{is_tested}};
+ $CPAN::Frontend->myprint("Prepending blib/arch and blib/lib of ".
+ "$cnt build dirs to PERL5LIB; ".
+ "for '$for'\n"
);
}
#-> sub CPAN::CacheMgr::tidyup ;
sub tidyup {
my($self) = @_;
+ return unless $CPAN::META->{LOCK};
return unless -d $self->{ID};
while ($self->{DU} > $self->{'MAX'} ) {
my($toremove) = shift @{$self->{FIFO}};
- $CPAN::Frontend->myprint(sprintf(
- "Deleting from cache".
- ": $toremove (%.1f>%.1f MB)\n",
- $self->{DU}, $self->{'MAX'})
- );
+ unless ($toremove =~ /\.yml$/) {
+ $CPAN::Frontend->myprint(sprintf(
+ "DEL(%.1f>%.1fMB): %s \n",
+ $self->{DU},
+ $self->{MAX},
+ $toremove,
+ )
+ );
+ }
return if $CPAN::Signal;
- $self->force_clean_cache($toremove);
+ $self->_clean_cache($toremove);
return if $CPAN::Signal;
}
}
return if $CPAN::Signal;
my($Du) = 0;
if (-e $dir) {
- unless (-x $dir) {
- unless (chmod 0755, $dir) {
- $CPAN::Frontend->mywarn("I have neither the -x permission nor the ".
- "permission to change the permission; cannot ".
- "estimate disk usage of '$dir'\n");
- $CPAN::Frontend->mysleep(5);
- return;
+ if (-d $dir) {
+ unless (-x $dir) {
+ unless (chmod 0755, $dir) {
+ $CPAN::Frontend->mywarn("I have neither the -x permission nor the ".
+ "permission to change the permission; cannot ".
+ "estimate disk usage of '$dir'\n");
+ $CPAN::Frontend->mysleep(5);
+ return;
+ }
}
+ } elsif (-f $dir) {
+ # nothing to say, no matter what the permissions
}
} else {
- $CPAN::Frontend->mywarn("Directory '$dir' has gone. Cannot continue.\n");
+ $CPAN::Frontend->mywarn("File or directory '$dir' has gone, ignoring\n");
return;
}
find(
$self->{DU};
}
-#-> sub CPAN::CacheMgr::force_clean_cache ;
-sub force_clean_cache {
+#-> sub CPAN::CacheMgr::_clean_cache ;
+sub _clean_cache {
my($self,$dir) = @_;
return unless -e $dir;
+ unless (File::Spec->canonpath(File::Basename::dirname($dir))
+ eq File::Spec->canonpath($CPAN::Config->{build_dir})) {
+ $CPAN::Frontend->mywarn("Directory '$dir' not below $CPAN::Config->{build_dir}, ".
+ "will not remove\n");
+ $CPAN::Frontend->mysleep(5);
+ return;
+ }
$self->debug("have to rmtree $dir, will free $self->{SIZE}{$dir}")
if $CPAN::DEBUG;
File::Path::rmtree($dir);
- unlink "$dir.yml"; # may fail
+ my $id_deleted = 0;
+ if ($dir !~ /\.yml$/ && -f "$dir.yml") {
+ my $yaml_module = CPAN::_yaml_module;
+ if ($CPAN::META->has_inst($yaml_module)) {
+ my($peek_yaml) = CPAN->_yaml_loadfile("$dir.yml");
+ if (my $id = $peek_yaml->[0]{distribution}{ID}) {
+ $CPAN::META->delete("CPAN::Distribution", $id);
+ # $CPAN::Frontend->mywarn (" +++\n");
+ $id_deleted++;
+ }
+ }
+ unlink "$dir.yml"; # may fail
+ unless ($id_deleted) {
+ CPAN->debug("no distro found associated with '$dir'");
+ }
+ }
$self->{DU} -= $self->{SIZE}{$dir};
delete $self->{SIZE}{$dir};
}
my($debug,$t2);
$debug = "";
my $self = {
- ID => $CPAN::Config->{'build_dir'},
+ ID => $CPAN::Config->{build_dir},
MAX => $CPAN::Config->{'build_cache'},
SCAN => $CPAN::Config->{'scan_cache'} || 'atstart',
DU => 0
return if $self->{SCAN} eq 'never';
$CPAN::Frontend->mydie("Unknown scan_cache argument: $self->{SCAN}")
unless $self->{SCAN} eq 'atstart';
+ return unless $CPAN::META->{LOCK};
$CPAN::Frontend->myprint(
sprintf("Scanning cache %s for sizes\n",
$self->{ID}));
my $e;
- for $e ($self->entries($self->{ID})) {
- next if $e eq ".." || $e eq ".";
+ my @entries = grep { !/^\.\.?$/ } $self->entries($self->{ID});
+ my $i = 0;
+ my $painted = 0;
+ for $e (@entries) {
+ # next if $e eq ".." || $e eq ".";
$self->disk_usage($e);
+ $i++;
+ while (($painted/76) < ($i/@entries)) {
+ $CPAN::Frontend->myprint(".");
+ $painted++;
+ }
return if $CPAN::Signal;
}
+ $CPAN::Frontend->myprint("DONE\n");
$self->tidyup;
}
upgrade WORDs or /REGEXP/ or NONE upgrade some/matching/all modules
Pragmas
- force COMMAND unconditionally do command
- notest COMMAND skip testing
+ force CMD try hard to do command fforce CMD try harder
+ notest CMD skip testing
Other
h,? display this menu ! perl-code eval a perl command
$pathglob = $2;
$author = CPAN::Shell->expand_by_method('CPAN::Author',
['id'],
- $a2) or die "No author found for $a2";
+ $a2)
+ or $CPAN::Frontend->mydie("No author found for $a2\n");
} else {
$author = CPAN::Shell->expand_by_method('CPAN::Author',
['id'],
- $a) or die "No author found for $a";
+ $a)
+ or $CPAN::Frontend->mydie("No author found for $a\n");
}
if ($silent) {
my $alpha = substr $author->id, 0, 1;
CPAN::HandleConfig->prettyprint($k);
}
$CPAN::Frontend->myprint("\n");
- } else {
+ } else {
if (CPAN::HandleConfig->edit(@o_what)) {
- unless ($o_what[0] eq "init") {
- $CPAN::Frontend->myprint("Please use 'o conf commit' to ".
- "make the config permanent!\n\n");
- }
} else {
$CPAN::Frontend->myprint(qq{Type 'o conf' to view all configuration }.
qq{items\n\n});
$S{end} ||= $last->{end};
my $dltime = $last->{end} - $start;
my $dlsize = $last->{filesize} || 0;
- my $url = $last->{thesiteurl}->text;
+ my $url = ref $last->{thesiteurl} ? $last->{thesiteurl}->text : $last->{thesiteurl};
my $s = $S{ok}{$url} ||= {};
$s->{n}++;
$s->{dlsize} ||= 0;
];
}
my $R = ""; # report
- $R .= sprintf "Log starts: %s\n", scalar(localtime $S{start}) || "unknown";
- $R .= sprintf "Log ends : %s\n", scalar(localtime $S{end}) || "unknown";
+ if ($S{start} && $S{end}) {
+ $R .= sprintf "Log starts: %s\n", $S{start} ? scalar(localtime $S{start}) : "unknown";
+ $R .= sprintf "Log ends : %s\n", $S{end} ? scalar(localtime $S{end}) : "unknown";
+ }
if ($res->{ok} && @{$res->{ok}}) {
$R .= sprintf "\nSuccessful downloads:
N kB secs kB/s url\n";
+ my $i = 20;
for (sort { $b->[3] <=> $a->[3] } @{$res->{ok}}) {
$R .= sprintf "%4d %8d %5d %9.1f %s\n", @$_;
+ last if --$i<=0;
}
}
if ($res->{no} && @{$res->{no}}) {
$R .= sprintf "\nUnsuccessful downloads:\n";
+ my $i = 20;
for (sort { $b->[0] <=> $a->[0] } @{$res->{no}}) {
$R .= sprintf "%4d %s\n", @$_;
+ last if --$i<=0;
}
}
$CPAN::Frontend->myprint($R);
my $failed;
my @relo = (
"CPAN.pm",
- "CPAN/HandleConfig.pm",
- "CPAN/FirstTime.pm",
- "CPAN/Tarzip.pm",
"CPAN/Debug.pm",
- "CPAN/Version.pm",
+ "CPAN/FirstTime.pm",
+ "CPAN/HandleConfig.pm",
+ "CPAN/Kwalify.pm",
"CPAN/Queue.pm",
"CPAN/Reporter.pm",
+ "CPAN/SQLite.pm",
+ "CPAN/Tarzip.pm",
+ "CPAN/Version.pm",
);
MFILE: for my $f (@relo) {
next unless exists $INC{$f};
$p =~ s|/|::|g;
$CPAN::Frontend->myprint("($p");
local($SIG{__WARN__}) = paintdots_onreload(\$redef);
- $self->reload_this($f) or $failed++;
+ $self->_reload_this($f) or $failed++;
my $v = eval "$p\::->VERSION";
$CPAN::Frontend->myprint("v$v)");
}
}
# reload means only load again what we have loaded before
-#-> sub CPAN::Shell::reload_this ;
-sub reload_this {
+#-> sub CPAN::Shell::_reload_this ;
+sub _reload_this {
my($self,$f,$args) = @_;
CPAN->debug("f[$f]") if $CPAN::DEBUG;
return 1 unless $INC{$f}; # we never loaded this, so we do not
$reload->{$f} ||= $^T;
my $must_reload = $mtime > $reload->{$f};
$args ||= {};
- $must_reload ||= $args->{force};
+ $must_reload ||= $args->{reloforce};
if ($must_reload) {
my $fh = FileHandle->new($file) or
$CPAN::Frontend->mydie("Could not open $file: $!");
# don't do it twice
$cpan_file = $module->cpan_file;
my $pack = $CPAN::META->instance('CPAN::Distribution',$cpan_file);
- $pack->force;
+ $pack->force; #
$dist{$cpan_file}++;
}
for $cpan_file (sort keys %dist) {
# re-run (as documented)
}
+# compare with is_tested
#-> sub CPAN::Shell::install_tested
sub install_tested {
my($self,@some) = @_;
- $CPAN::Frontend->mywarn("install_tested() requires no arguments.\n"),
+ $CPAN::Frontend->mywarn("install_tested() must not be called with arguments.\n"),
return if @some;
CPAN::Index->reload;
- for my $d (%{$CPAN::META->{readwrite}{'CPAN::Distribution'}}) {
- my $do = CPAN::Shell->expandany($d);
- next unless $do->{build_dir};
+ for my $b (reverse $CPAN::META->_list_sorted_descending_is_tested) {
+ my $yaml = "$b.yml";
+ unless (-f $yaml){
+ $CPAN::Frontend->mywarn("No YAML file for $b available, skipping\n");
+ next;
+ }
+ my $yaml_content = CPAN->_yaml_loadfile($yaml);
+ my $id = $yaml_content->[0]{distribution}{ID};
+ unless ($id){
+ $CPAN::Frontend->mywarn("No ID found in '$yaml', skipping\n");
+ next;
+ }
+ my $do = CPAN::Shell->expandany($id);
+ unless ($do){
+ $CPAN::Frontend->mywarn("Could not expand ID '$id', skipping\n");
+ next;
+ }
+ unless ($do->{build_dir}) {
+ $CPAN::Frontend->mywarn("Distro '$id' has no build_dir, skipping\n");
+ next;
+ }
+ unless ($do->{build_dir} eq $b) {
+ $CPAN::Frontend->mywarn("Distro '$id' has build_dir '$do->{build_dir}' but expected '$b', skipping\n");
+ next;
+ }
push @some, $do;
}
$CPAN::Frontend->mywarn("No distributions tested with this build of perl found.\n"),
return unless @some;
- @some = grep { not $_->uptodate } @some;
- $CPAN::Frontend->mywarn("No non-uptodate distributions tested with this build of perl found.\n"),
- return unless @some;
+ # @some = grep { not $_->uptodate } @some;
+ # $CPAN::Frontend->mywarn("No non-uptodate distributions tested with this build of perl found.\n"),
+ # return unless @some;
CPAN->debug("some[@some]");
for my $d (@some) {
my $id = $d->can("pretty_id") ? $d->pretty_id : $d->id;
$CPAN::Frontend->myprint("install_tested: Running for $id\n");
- $CPAN::Frontend->sleep(1);
+ $CPAN::Frontend->mysleep(1);
$self->install($d);
}
}
my @failed;
DIST: for my $d ($CPAN::META->all_objects("CPAN::Distribution")) {
my $failed = "";
- NAY: for my $nosayer (
+ NAY: for my $nosayer ( # order matters!
"unwrapped",
"writemakefile",
"signature_verify",
"make_clean",
) {
next unless exists $d->{$nosayer};
+ next unless defined $d->{$nosayer};
next unless (
- $d->{$nosayer}->can("failed") ?
+ UNIVERSAL::can($d->{$nosayer},"failed") ?
$d->{$nosayer}->failed :
$d->{$nosayer} =~ /^NO/
);
next NAY if $only_id && $only_id != (
- $d->{$nosayer}->can("commandid")
+ UNIVERSAL::can($d->{$nosayer},"commandid")
?
$d->{$nosayer}->commandid
:
# " %-45s: %s %s\n",
push @failed,
(
- $d->{$failed}->can("failed") ?
+ UNIVERSAL::can($d->{$failed},"failed") ?
[
$d->{$failed}->commandid,
$id,
$failed,
$d->{$failed}->text,
+ $d->{$failed}{TIME}||0,
] :
[
1,
$id,
$failed,
$d->{$failed},
+ 0,
]
);
}
- my $scope = $only_id ? "command" : "session";
+ my $scope;
+ if ($only_id) {
+ $scope = "this command";
+ } elsif ($CPAN::Index::HAVE_REANIMATED) {
+ $scope = "this or a previous session";
+ # it might be nice to have a section for previous session and
+ # a second for this
+ } else {
+ $scope = "this session";
+ }
if (@failed) {
- my $print = join "",
- map { sprintf " %-45s: %s %s\n", @$_[1,2,3] }
- sort { $a->[0] <=> $b->[0] } @failed;
- $CPAN::Frontend->myprint("Failed during this $scope:\n$print");
+ my $print;
+ my $debug = 0;
+ if ($debug) {
+ $print = join "",
+ map { sprintf "%5d %-45s: %s %s\n", @$_ }
+ sort { $a->[0] <=> $b->[0] } @failed;
+ } else {
+ $print = join "",
+ map { sprintf " %-45s: %s %s\n", @$_[1..3] }
+ sort {
+ $a->[0] <=> $b->[0]
+ ||
+ $a->[4] <=> $b->[4]
+ } @failed;
+ }
+ $CPAN::Frontend->myprint("Failed during $scope:\n$print");
} elsif (!$only_id || !$silent) {
- $CPAN::Frontend->myprint("Nothing failed in this $scope\n");
+ $CPAN::Frontend->myprint("Nothing failed in $scope\n");
}
}
}
}
+# compare with install_tested
+#-> sub CPAN::Shell::is_tested
+sub is_tested {
+ my($self) = @_;
+ CPAN::Index->reload;
+ for my $b (reverse $CPAN::META->_list_sorted_descending_is_tested) {
+ my $time;
+ if ($CPAN::META->{is_tested}{$b}) {
+ $time = scalar(localtime $CPAN::META->{is_tested}{$b});
+ } else {
+ $time = scalar localtime;
+ $time =~ s/\S/?/g;
+ }
+ $CPAN::Frontend->myprint(sprintf "%s %s\n", $time, $b);
+ }
+}
+
#-> sub CPAN::Shell::autobundle ;
sub autobundle {
my($self) = shift;
my $class = "CPAN::$type";
my $methods = ['id'];
for my $meth (qw(name)) {
- next if $] < 5.00303; # no "can"
next unless $class->can($meth);
push @$methods, $meth;
}
defined $command ? $command : "UNDEFINED",
) if $CPAN::DEBUG;
if (defined $regex) {
+ if (CPAN::_sqlite_running) {
+ $CPAN::SQLite->search($class, $regex);
+ }
for $obj (
$CPAN::META->all_objects($class)
) {
- unless ($obj->id){
+ unless ($obj && UNIVERSAL::can($obj,"id") && $obj->id){
# BUG, we got an empty object somewhere
require Data::Dumper;
CPAN->debug(sprintf(
if ($self->colorize_output) {
if ( $CPAN::DEBUG && $swhat =~ /^Debug\(/ ) {
# if you want to have this configurable, please file a bugreport
- $ornament = "black on_cyan";
+ $ornament = $CPAN::Config->{colorize_debug} || "black on_cyan";
}
my $color_on = eval { Term::ANSIColor::color($ornament) } || "";
if ($@) {
print "Term::ANSIColor rejects color[$ornament]: $@\n
-Please choose a different color (Hint: try 'o conf init color.*')\n";
+Please choose a different color (Hint: try 'o conf init /color/')\n";
}
print $color_on,
$swhat,
#-> sub CPAN::Shell::mysleep ;
sub mysleep {
my($self, $sleep) = @_;
+ use Time::HiRes qw(sleep);
sleep $sleep;
}
}
#-> sub CPAN::Shell::rematein ;
-# RE-adme||MA-ke||TE-st||IN-stall
+# RE-adme||MA-ke||TE-st||IN-stall : nearly everything runs through here
sub rematein {
my $self = shift;
my($meth,@some) = @_;
my @pragma;
- while($meth =~ /^(force|notest)$/) {
+ while($meth =~ /^(ff?orce|notest)$/) {
push @pragma, $meth;
$meth = shift @some or
$CPAN::Frontend->mydie("Pragma $pragma[-1] used without method: ".
# enter the queue but not its copy. How do they get a sensible
# test_count?
+ my $needs_recursion_protection = "make|test|install";
+
# construct the queue
my($s,@s,@qcopy);
STHING: foreach $s (@some) {
}
if (0) {
} elsif (ref $obj) {
- $obj->color_cmd_tmps(0,1);
+ if ($meth =~ /^($needs_recursion_protection)$/) {
+ # silly for look or dump
+ $obj->color_cmd_tmps(0,1);
+ }
CPAN::Queue->new(qmod => $obj->id, reqtype => "c");
push @qcopy, $obj;
} elsif ($CPAN::META->exists('CPAN::Author',uc($s))) {
my $s = $q->as_string;
my $reqtype = $q->reqtype || "";
$obj = CPAN::Shell->expandany($s);
+ unless ($obj) {
+ # don't know how this can happen, maybe we should panic,
+ # but maybe we get a solution from the first user who hits
+ # this unfortunate exception?
+ $CPAN::Frontend->mywarn("Warning: Could not expand string '$s' ".
+ "to an object. Skipping.\n");
+ $CPAN::Frontend->mysleep(5);
+ CPAN::Queue->delete_first($s);
+ next;
+ }
$obj->{reqtype} ||= "";
- CPAN->debug("obj-reqtype[$obj->{reqtype}]".
- "q-reqtype[$reqtype]") if $CPAN::DEBUG;
+ {
+ # force debugging because CPAN::SQLite somehow delivers us
+ # an empty object;
+
+ # local $CPAN::DEBUG = 1024; # Shell; probably fixed now
+
+ CPAN->debug("s[$s]obj-reqtype[$obj->{reqtype}]".
+ "q-reqtype[$reqtype]") if $CPAN::DEBUG;
+ }
if ($obj->{reqtype}) {
if ($obj->{reqtype} eq "b" && $reqtype =~ /^[rc]$/) {
$obj->{reqtype} = $reqtype;
exists $obj->{install}
&&
(
- $obj->{install}->can("failed") ?
+ UNIVERSAL::can($obj->{install},"failed") ?
$obj->{install}->failed :
$obj->{install} =~ /^NO/
)
$obj->$pragma($meth);
}
}
- if ($obj->can('called_for')) {
+ if (UNIVERSAL::can($obj, 'called_for')) {
$obj->called_for($s);
}
CPAN->debug(qq{pragma[@pragma]meth[$meth]}.
qq{ID[$obj->{ID}]}) if $CPAN::DEBUG;
push @qcopy, $obj;
- if ($obj->$meth()){
+ if (! UNIVERSAL::can($obj,$meth)) {
+ # Must never happen
+ my $serialized = "";
+ if (0) {
+ } elsif ($CPAN::META->has_inst("YAML::Syck")) {
+ $serialized = YAML::Syck::Dump($obj);
+ } elsif ($CPAN::META->has_inst("YAML")) {
+ $serialized = YAML::Dump($obj);
+ } elsif ($CPAN::META->has_inst("Data::Dumper")) {
+ $serialized = Data::Dumper::Dumper($obj);
+ } else {
+ require overload;
+ $serialized = overload::StrVal($obj);
+ }
+ $CPAN::Frontend->mydie("Panic: obj[$serialized] cannot meth[$meth]");
+ } elsif ($obj->$meth()){
CPAN::Queue->delete($s);
} else {
CPAN->debug("failed");
}
CPAN::Queue->delete_first($s);
}
- for my $obj (@qcopy) {
- $obj->color_cmd_tmps(0,0);
+ if ($meth =~ /^($needs_recursion_protection)$/) {
+ for my $obj (@qcopy) {
+ $obj->color_cmd_tmps(0,0);
+ }
}
}
cvs_import
dump
force
+ fforce
get
install
look
my $file = File::Spec->catfile($CPAN::Config->{cpan_home},"FTPstats.yml");
open $fh, "+>>$file" or $CPAN::Frontend->mydie("Could not open '$file': $!");
my $sleep = 1;
+ my $waitstart;
while (!flock $fh, $locktype|LOCK_NB) {
+ $waitstart ||= localtime();
if ($sleep>3) {
- die;
+ $CPAN::Frontend->mywarn("Waiting for a read lock on '$file' (since $waitstart)\n");
+ }
+ $CPAN::Frontend->mysleep($sleep);
+ if ($sleep <= 3) {
+ $sleep+=0.33;
+ } elsif ($sleep <=6) {
+ $sleep+=0.11;
}
- $CPAN::Frontend->mysleep($sleep++);
}
- my $stats = CPAN->_yaml_loadfile($file);
- if ($locktype == LOCK_SH) {
- } else {
- seek $fh, 0, 0;
- if (@$stats){ # no yaml no write
- truncate $fh, 0;
+ my $stats = eval { CPAN->_yaml_loadfile($file); };
+ if ($@) {
+ if (ref $@) {
+ if (ref $@ eq "CPAN::Exception::yaml_not_installed") {
+ $CPAN::Frontend->myprint("Warning (usually harmless): $@");
+ return;
+ } elsif (ref $@ eq "CPAN::Exception::yaml_process_error") {
+ $CPAN::Frontend->mydie($@);
+ }
+ } else {
+ $CPAN::Frontend->mydie($@);
}
}
return $stats->[0];
}
+#-> sub CPAN::FTP::_mytime
sub _mytime () {
if (CPAN->has_inst("Time::HiRes")) {
return Time::HiRes::time();
}
}
+#-> sub CPAN::FTP::_new_stats
sub _new_stats {
my($self,$file) = @_;
my $ret = {
$ret;
}
+#-> sub CPAN::FTP::_add_to_statistics
sub _add_to_statistics {
my($self,$stats) = @_;
- $stats->{thesiteurl} = $ThesiteURL;
- if (CPAN->has_inst("Time::HiRes")) {
- $stats->{end} = Time::HiRes::time();
- } else {
- $stats->{end} = time;
+ my $yaml_module = CPAN::_yaml_module;
+ $self->debug("yaml_module[$yaml_module]") if $CPAN::DEBUG;
+ if ($CPAN::META->has_inst($yaml_module)) {
+ $stats->{thesiteurl} = $ThesiteURL;
+ if (CPAN->has_inst("Time::HiRes")) {
+ $stats->{end} = Time::HiRes::time();
+ } else {
+ $stats->{end} = time;
+ }
+ my $fh = FileHandle->new;
+ my $time = time;
+ my $sdebug = 0;
+ my @debug;
+ @debug = $time if $sdebug;
+ my $fullstats = $self->_ftp_statistics($fh);
+ close $fh;
+ $fullstats->{history} ||= [];
+ push @debug, scalar @{$fullstats->{history}} if $sdebug;
+ push @debug, time if $sdebug;
+ push @{$fullstats->{history}}, $stats;
+ # arbitrary hardcoded constants until somebody demands to have
+ # them settable; YAML.pm 0.62 is unacceptably slow with 999;
+ # YAML::Syck 0.82 has no noticable performance problem with 999;
+ while (
+ @{$fullstats->{history}} > 99
+ || $time - $fullstats->{history}[0]{start} > 14*86400
+ ) {
+ shift @{$fullstats->{history}}
+ }
+ push @debug, scalar @{$fullstats->{history}} if $sdebug;
+ push @debug, time if $sdebug;
+ push @debug, scalar localtime($fullstats->{history}[0]{start}) if $sdebug;
+ # need no eval because if this fails, it is serious
+ my $sfile = File::Spec->catfile($CPAN::Config->{cpan_home},"FTPstats.yml");
+ CPAN->_yaml_dumpfile("$sfile.$$",$fullstats);
+ if ( $sdebug||$CPAN::DEBUG ) {
+ local $CPAN::DEBUG = 512; # FTP
+ push @debug, time;
+ CPAN->debug(sprintf("DEBUG history: before_read[%d]before[%d]at[%d]".
+ "after[%d]at[%d]oldest[%s]dumped backat[%d]",
+ @debug,
+ ));
+ }
+ # Win32 cannot rename a file to an existing filename
+ unlink($sfile) if ($^O eq 'MSWin32');
+ rename "$sfile.$$", $sfile
+ or $CPAN::Frontend->mydie("Could not rename '$sfile.$$' to '$sfile': $!\n");
}
- my $fh = FileHandle->new;
- my $fullstats = $self->_ftp_statistics($fh);
- push @{$fullstats->{history}}, $stats;
- my $time = time;
- shift @{$fullstats->{history}}
- while $time - $fullstats->{history}[0]{start} > 30*86400; # one month too much?
- CPAN->_yaml_dumpfile($fh,$fullstats);
}
# if file is CHECKSUMS, suggest the place where we got the file to be
# checked from, maybe only for young files?
+#-> sub CPAN::FTP::_recommend_url_for
sub _recommend_url_for {
my($self, $file) = @_;
my $urllist = $self->_get_urllist;
my $history = $fullstats->{history} || [];
while (my $last = pop @$history) {
last if $last->{end} - time > 3600; # only young results are interesting
+ next unless $last->{file}; # dirname of nothing dies!
next unless $file eq File::Basename::dirname($last->{file});
return $last->{thesiteurl};
}
}
}
+#-> sub CPAN::FTP::_get_urllist
sub _get_urllist {
my($self) = @_;
$CPAN::Config->{urllist} ||= [];
if ($ret) {
$stats->{filesize} = -s $ret;
}
+ $self->debug("before _add_to_statistics") if $CPAN::DEBUG;
$self->_add_to_statistics($stats);
+ $self->debug("after _add_to_statistics") if $CPAN::DEBUG;
if ($ret) {
+ unlink "$aslocal.bak$$";
return $ret;
}
unless ($CPAN::Signal) {
# Maybe mirror has compressed it?
if (-f "$l.gz") {
$self->debug("found compressed $l.gz") if $CPAN::DEBUG;
- CPAN::Tarzip->new("$l.gz")->gunzip($aslocal);
+ eval { CPAN::Tarzip->new("$l.gz")->gunzip($aslocal) };
if ( -f $aslocal) {
$ThesiteURL = $ro_url;
return $aslocal;
$gzurl
");
$res = $Ua->mirror($gzurl, "$aslocal.gz");
- if ($res->is_success &&
- CPAN::Tarzip->new("$aslocal.gz")->gunzip($aslocal)
- ) {
- $ThesiteURL = $ro_url;
- return $aslocal;
+ if ($res->is_success) {
+ if (eval {CPAN::Tarzip->new("$aslocal.gz")->gunzip($aslocal)}) {
+ $ThesiteURL = $ro_url;
+ return $aslocal;
+ }
}
} else {
$CPAN::Frontend->myprint(sprintf(
$dir,
"$getfile.gz",
$gz) &&
- CPAN::Tarzip->new($gz)->gunzip($aslocal)
+ eval{CPAN::Tarzip->new($gz)->gunzip($aslocal)}
){
$ThesiteURL = $ro_url;
return $aslocal;
# Looks good
} elsif ($asl_ungz ne $aslocal) {
# test gzip integrity
- if (CPAN::Tarzip->new($asl_ungz)->gtest) {
+ if (eval{CPAN::Tarzip->new($asl_ungz)->gtest}) {
# e.g. foo.tar is gzipped --> foo.tar.gz
rename $asl_ungz, $aslocal;
} else {
- CPAN::Tarzip->new($asl_gz)->gzip($asl_ungz);
+ eval{CPAN::Tarzip->new($asl_gz)->gzip($asl_ungz)};
}
}
$ThesiteURL = $ro_url;
-s $asl_gz
) {
# test gzip integrity
- my $ct = CPAN::Tarzip->new($asl_gz);
- if ($ct->gtest) {
- $ct->gunzip($aslocal);
- } else {
- # somebody uncompressed file for us?
- rename $asl_ungz, $aslocal;
- }
- $ThesiteURL = $ro_url;
- return $aslocal;
+ my $ct = eval{CPAN::Tarzip->new($asl_gz)};
+ if ($ct && $ct->gtest) {
+ $ct->gunzip($aslocal);
+ } else {
+ # somebody uncompressed file for us?
+ rename $asl_ungz, $aslocal;
+ }
+ $ThesiteURL = $ro_url;
+ return $aslocal;
} else {
unlink $asl_gz if -f $asl_gz;
}
$pos ||= 0;
CPAN->debug("word [$word] line[$line] pos[$pos]") if $CPAN::DEBUG;
$line =~ s/^\s*//;
- if ($line =~ s/^(force\s*)//) {
+ if ($line =~ s/^((?:notest|f?force)\s*)//) {
$pos -= length($1);
}
my @return;
#-> sub CPAN::Complete::cplx ;
sub cplx {
my($class, $word) = @_;
- # I believed for many years that this was sorted, today I
- # realized, it wasn't sorted anymore. Now (rev 1.301 / v 1.55) I
- # make it sorted again. Maybe sort was dropped when GNU-readline
- # support came in? The RCS file is difficult to read on that:-(
+ if (CPAN::_sqlite_running) {
+ $CPAN::SQLite->search($class, "^\Q$word\E");
+ }
sort grep /^\Q$word\E/, map { $_->id } $CPAN::META->all_objects($class);
}
if ($CPAN::Config->{build_dir_reuse}) {
$self->reanimate_build_dir;
}
+ if (CPAN::_sqlite_running) {
+ $CPAN::SQLite->reload(time => $time, force => $force)
+ if not $LAST_TIME;
+ }
$LAST_TIME = $time;
$CPAN::META->{PROTOCOL} = PROTOCOL;
}
my $painted = 0;
my $restored = 0;
$CPAN::Frontend->myprint("Going to read $CPAN::Config->{build_dir}/\n");
- my @candidates = grep {/\.yml$/} readdir $dh;
+ my @candidates = map { $_->[0] }
+ sort { $b->[1] <=> $a->[1] }
+ map { [ $_, -M File::Spec->catfile($d,$_) ] }
+ grep {/\.yml$/} readdir $dh;
DISTRO: for $dirent (@candidates) {
- my $c = CPAN->_yaml_loadfile(File::Spec->catfile($d,$dirent))->[0];
+ my $y = eval {CPAN->_yaml_loadfile(File::Spec->catfile($d,$dirent))};
+ die $@ if $@;
+ my $c = $y->[0];
if ($c && CPAN->_perl_fingerprint($c->{perl})) {
my $key = $c->{distribution}{ID};
for my $k (keys %{$c->{distribution}}) {
if ($c->{distribution}{$k}
&& ref $c->{distribution}{$k}
&& UNIVERSAL::isa($c->{distribution}{$k},"CPAN::Distrostatus")) {
- # the correct algorithm would be a
- # two-pass and we would subtract the
- # maximum of all old commands minus 2
- $c->{distribution}{$k}{COMMANDID} -= scalar @candidates - 2 ;
+ $c->{distribution}{$k}{COMMANDID} = $i - @candidates;
}
}
#we tried to restore only if element already
#exists; but then we do not work with metadata
#turned off.
- $CPAN::META->{readwrite}{'CPAN::Distribution'}{$key} = $c->{distribution};
+ my $do
+ = $CPAN::META->{readwrite}{'CPAN::Distribution'}{$key}
+ = $c->{distribution};
+ delete $do->{badtestcnt};
+ # $DB::single = 1;
+ if ($do->{make_test}
+ && $do->{build_dir}
+ && !$do->{make_test}->failed
+ && (
+ !$do->{install}
+ ||
+ $do->{install}->failed
+ )
+ ) {
+ $CPAN::META->is_tested($do->{build_dir},$do->{make_test}{TIME});
+ }
$restored++;
}
$i++;
#-> sub CPAN::Index::rd_authindex ;
sub rd_authindex {
my($cl, $index_target) = @_;
- my @lines;
return unless defined $index_target;
+ return if CPAN::_sqlite_running;
+ my @lines;
$CPAN::Frontend->myprint("Going to read $index_target\n");
local(*FH);
tie *FH, 'CPAN::Tarzip', $index_target;
local($_);
push @lines, split /\012/ while <FH>;
my $i = 0;
- my $modulus = int($#lines/75) || 1;
- CPAN->debug(sprintf "modulus[%d]lines[%s]", $modulus, scalar @lines) if $CPAN::DEBUG;
+ my $painted = 0;
foreach (@lines) {
my($userid,$fullname,$email) =
m/alias\s+(\S+)\s+\"([^\"\<]*)\s+\<(.*)\>\"/;
} else {
CPAN->debug(sprintf "line[%s]", $_) if $CPAN::DEBUG;
}
- $CPAN::Frontend->myprint(".") unless $i++ % $modulus;
+ $i++;
+ while (($painted/76) < ($i/@lines)) {
+ $CPAN::Frontend->myprint(".");
+ $painted++;
+ }
return if $CPAN::Signal;
}
$CPAN::Frontend->myprint("DONE\n");
sub rd_modpacks {
my($self, $index_target) = @_;
return unless defined $index_target;
+ return if CPAN::_sqlite_running;
$CPAN::Frontend->myprint("Going to read $index_target\n");
my $fh = CPAN::Tarzip->TIEHANDLE($index_target);
local $_;
CPAN->debug("secondtime[$secondtime]") if $CPAN::DEBUG;
my(%exists);
my $i = 0;
- my $modulus = int($#lines/75) || 1;
+ my $painted = 0;
foreach (@lines) {
# before 1.56 we split into 3 and discarded the rest. From
# 1.57 we assign remaining text to $comment thus allowing to
$exists{$name} = undef;
}
}
- $CPAN::Frontend->myprint(".") unless $i++ % $modulus;
+ $i++;
+ while (($painted/76) < ($i/@lines)) {
+ $CPAN::Frontend->myprint(".");
+ $painted++;
+ }
return if $CPAN::Signal;
}
$CPAN::Frontend->myprint("DONE\n");
sub rd_modlist {
my($cl,$index_target) = @_;
return unless defined $index_target;
+ return if CPAN::_sqlite_running;
$CPAN::Frontend->myprint("Going to read $index_target\n");
my $fh = CPAN::Tarzip->TIEHANDLE($index_target);
local $_;
Carp::confess($@) if $@;
return if $CPAN::Signal;
my $i = 0;
- my $until = keys(%$ret) - 1;
- my $modulus = int($until/75) || 1;
+ my $until = keys(%$ret);
+ my $painted = 0;
CPAN->debug(sprintf "until[%d]", $until) if $CPAN::DEBUG;
for (keys %$ret) {
my $obj = $CPAN::META->instance("CPAN::Module",$_);
delete $ret->{$_}{modid}; # not needed here, maybe elsewhere
$obj->set(%{$ret->{$_}});
- $CPAN::Frontend->myprint(".") unless $i++ % $modulus;
+ $i++;
+ while (($painted/76) < ($i/$until)) {
+ $CPAN::Frontend->myprint(".");
+ $painted++;
+ }
return if $CPAN::Signal;
}
$CPAN::Frontend->myprint("DONE\n");
sub write_metadata_cache {
my($self) = @_;
return unless $CPAN::Config->{'cache_metadata'};
+ return if CPAN::_sqlite_running;
return unless $CPAN::META->has_usable("Storable");
my $cache;
foreach my $k (qw(CPAN::Bundle CPAN::Author CPAN::Module
sub read_metadata_cache {
my($self) = @_;
return unless $CPAN::Config->{'cache_metadata'};
+ return if CPAN::_sqlite_running;
return unless $CPAN::META->has_usable("Storable");
my $metadata_file = File::Spec->catfile($CPAN::Config->{cpan_home},"Metadata");
return unless -r $metadata_file and -f $metadata_file;
"$lc_want.gz",1);
if ($lc_file) {
$lc_file =~ s{\.gz(?!\n)\Z}{}; #};
- CPAN::Tarzip->new("$lc_file.gz")->gunzip($lc_file);
+ eval{CPAN::Tarzip->new("$lc_file.gz")->gunzip($lc_file)};
} else {
return;
}
substr($id,5);
}
-# mark as dirty/clean
+# mark as dirty/clean for the sake of recursion detection. $color=1
+# means "in use", $color=0 means "not in use anymore". $color=2 means
+# we have determined prereqs now and thus insist on passing this
+# through (at least) once again.
+
#-> sub CPAN::Distribution::color_cmd_tmps ;
sub color_cmd_tmps {
my($self) = shift;
# a distribution needs to recurse into its prereq_pms
return if exists $self->{incommandcolor}
+ && $color==1
&& $self->{incommandcolor}==$color;
- if ($depth>=100){
+ if ($depth>=$CPAN::MAX_RECURSION){
$CPAN::Frontend->mydie(CPAN::Exception::RecursiveDependency->new($ancestors));
}
# warn "color_cmd_tmps $depth $color " . $self->id; # sleep 1;
}
if ($color==0) {
delete $self->{sponsored_mods};
+
+ # as we are at the end of a command, we'll give up this
+ # reminder of a broken test. Other commands may test this guy
+ # again. Maybe 'badtestcnt' should be renamed to
+ # 'make_test_failed_within_command'?
delete $self->{badtestcnt};
}
$self->{incommandcolor} = $color;
my $mod_id = $mod->{ID} or next;
# warn "mod_file[$mod_file] dist_id[$dist_id] mod_id[$mod_id]";
# sleep 1;
+ if ($CPAN::Signal) {
+ delete $self->{CONTAINSMODS};
+ return;
+ }
$self->{CONTAINSMODS}{$mod_id} = undef if $mod_file eq $dist_id;
}
- keys %{$self->{CONTAINSMODS}};
+ keys %{$self->{CONTAINSMODS}||{}};
}
#-> sub CPAN::Distribution::upload_date ;
#-> sub CPAN::Distribution::get ;
sub get {
my($self) = @_;
+ $self->debug("checking goto id[$self->{ID}]") if $CPAN::DEBUG;
+ if (my $goto = $self->prefs->{goto}) {
+ $CPAN::Frontend->mywarn
+ (sprintf(
+ "delegating to '%s' as specified in prefs file '%s' doc %d\n",
+ $goto,
+ $self->{prefs_file},
+ $self->{prefs_file_doc},
+ ));
+ return $self->goto($goto);
+ }
local $ENV{PERL5LIB} = defined($ENV{PERL5LIB})
? $ENV{PERL5LIB}
: ($ENV{PERLLIB} || "");
EXCUSE: {
my @e;
+ $self->debug("checking disabled id[$self->{ID}]") if $CPAN::DEBUG;
if ($self->prefs->{disabled}) {
- push @e, sprintf(
- "disabled via prefs file '%s' doc %d",
- $self->{prefs_file},
- $self->{prefs_file_doc},
- );
- }
- exists $self->{build_dir} and push @e,
- "Is already unwrapped into directory $self->{build_dir}";
+ my $why = sprintf(
+ "Disabled via prefs file '%s' doc %d",
+ $self->{prefs_file},
+ $self->{prefs_file_doc},
+ );
+ push @e, $why;
+ $self->{unwrapped} = CPAN::Distrostatus->new("NO -- $why");
+ # note: not intended to be persistent but at least visible
+ # during this session
+ } else {
+ if (exists $self->{build_dir}) {
+ # this deserves print, not warn:
+ $CPAN::Frontend->myprint(" Has already been unwrapped into directory ".
+ "$self->{build_dir}\n"
+ );
+ return;
+ }
- exists $self->{unwrapped} and (
- $self->{unwrapped}->can("failed") ?
- $self->{unwrapped}->failed :
- $self->{unwrapped} =~ /^NO/
- )
- and push @e, "Unwrapping had some problem, won't try again without force";
+ # although we talk about 'force' we shall not test on
+ # force directly. New model of force tries to refrain from
+ # direct checking of force.
+ exists $self->{unwrapped} and (
+ UNIVERSAL::can($self->{unwrapped},"failed") ?
+ $self->{unwrapped}->failed :
+ $self->{unwrapped} =~ /^NO/
+ )
+ and push @e, "Unwrapping had some problem, won't try again without force";
+ }
- $CPAN::Frontend->mywarn(join "", map {" $_\n"} @e) and return if @e;
+ $CPAN::Frontend->mywarn(join "", map {"$_\n"} @e) and return if @e;
}
my $sub_wd = CPAN::anycwd(); # for cleaning up as good as possible
#
# Unpack the goods
#
- my $ct = CPAN::Tarzip->new($local_file);
+ my $ct = eval{CPAN::Tarzip->new($local_file)};
+ unless ($ct) {
+ $self->{unwrapped} = CPAN::Distrostatus->new("NO");
+ delete $self->{build_dir};
+ return;
+ }
if ($local_file =~ /(\.tar\.(bz2|gz|Z)|\.tgz)(?!\n)\Z/i){
- $self->{was_uncompressed}++ unless $ct->gtest();
+ $self->{was_uncompressed}++ unless eval{$ct->gtest()};
$self->untar_me($ct);
} elsif ( $local_file =~ /\.zip(?!\n)\Z/i ) {
$self->unzip_me($ct);
} else {
$self->{was_uncompressed}++ unless $ct->gtest();
$local_file = $self->handle_singlefile($local_file);
-# } else {
-# $self->{archived} = "NO";
-# $self->safe_chdir($sub_wd);
-# return;
}
# we are still in the tmp directory!
for $f (@dirents) { # is already without "." and ".."
my $from = File::Spec->catdir($from_dir,$f);
my $to = File::Spec->catdir($packagedir,$f);
- File::Copy::move($from,$to) or Carp::confess("Couldn't move $from to $to: $!");
+ unless (File::Copy::move($from,$to)) {
+ my $err = $!;
+ $from = File::Spec->rel2abs($from);
+ Carp::confess("Couldn't move $from to $to: $err");
+ }
}
} else { # older code below, still better than nothing when there is no File::Temp
my($distdir);
)) if $CPAN::DEBUG;
} else {
my $userid = $self->cpan_userid;
- CPAN->debug("userid[$userid]");
+ CPAN->debug("userid[$userid]") if $CPAN::DEBUG;
if (!$userid or $userid eq "N/A") {
$userid = "anon";
}
return;
}
- $self->{'build_dir'} = $packagedir;
+ $self->{build_dir} = $packagedir;
$self->safe_chdir($builddir);
File::Path::rmtree("tmp-$$");
my $prefer_installer = "eumm"; # eumm|mb
if (-f File::Spec->catfile($packagedir,"Build.PL")) {
if ($mpl_exists) { # they *can* choose
- $prefer_installer = CPAN::HandleConfig->prefs_lookup($self,
- q{prefer_installer});
+ if ($CPAN::META->has_inst("Module::Build")) {
+ $prefer_installer = CPAN::HandleConfig->prefs_lookup($self,
+ q{prefer_installer});
+ }
} else {
$prefer_installer = "mb";
}
return unless $self->patch;
if (lc($prefer_installer) eq "mb") {
$self->{modulebuild} = 1;
+ } elsif ($self->{archived} eq "patch") {
+ # not an edge case, nothing to install for sure
+ my $why = "A patch file cannot be installed";
+ $CPAN::Frontend->mywarn("Refusing to handle this file: $why\n");
+ $self->{writemakefile} = CPAN::Distrostatus->new("NO $why");
} elsif (! $mpl_exists) {
$self->_edge_cases($mpl,$packagedir,$local_file);
}
#-> CPAN::Distribution::store_persistent_state
sub store_persistent_state {
my($self) = @_;
- my $file = sprintf "%s.yml", $self->{build_dir};
- CPAN->_yaml_dumpfile(
- $file,
- {
- time => time,
- perl => CPAN::_perl_fingerprint,
- distribution => $self,
- }
- );
+ my $dir = $self->{build_dir};
+ unless (File::Spec->canonpath(File::Basename::dirname($dir))
+ eq File::Spec->canonpath($CPAN::Config->{build_dir})) {
+ $CPAN::Frontend->mywarn("Directory '$dir' not below $CPAN::Config->{build_dir}, ".
+ "will not store persistent state\n");
+ return;
+ }
+ my $file = sprintf "%s.yml", $dir;
+ my $yaml_module = CPAN::_yaml_module;
+ if ($CPAN::META->has_inst($yaml_module)) {
+ CPAN->_yaml_dumpfile(
+ $file,
+ {
+ time => time,
+ perl => CPAN::_perl_fingerprint,
+ distribution => $self,
+ }
+ );
+ } else {
+ $CPAN::Frontend->myprint("Warning (usually harmless): '$yaml_module' not installed, ".
+ "will not store persistent state\n");
+ }
}
#-> CPAN::Distribution::patch
#-> CPAN::Distribution::patch
sub patch {
my($self) = @_;
- if (my $patches = $self->prefs->{patches}) {
+ $self->debug("checking patches id[$self->{ID}]") if $CPAN::DEBUG;
+ my $patches = $self->prefs->{patches};
+ $patches ||= "";
+ $self->debug("patches[$patches]") if $CPAN::DEBUG;
+ if ($patches) {
return unless @$patches;
$self->safe_chdir($self->{build_dir});
- CPAN->debug("patches[$patches]");
+ CPAN->debug("patches[$patches]") if $CPAN::DEBUG;
my $patchbin = $CPAN::Config->{patch};
unless ($patchbin && length $patchbin) {
$CPAN::Frontend->mydie("No external patch command configured\n\n".
}
$CPAN::Frontend->myprint(" $patch\n");
my $readfh = CPAN::Tarzip->TIEHANDLE($patch);
- my $thispatchargs = join " ", $stdpatchargs, $self->_patch_p_parameter($readfh);
- $readfh = CPAN::Tarzip->TIEHANDLE($patch);
+
+ my $pcommand;
+ my $ppp = $self->_patch_p_parameter($readfh);
+ if ($ppp eq "applypatch") {
+ $pcommand = "$CPAN::Config->{applypatch} -verbose";
+ } else {
+ my $thispatchargs = join " ", $stdpatchargs, $ppp;
+ $pcommand = "$patchbin $thispatchargs";
+ }
+
+ $readfh = CPAN::Tarzip->TIEHANDLE($patch); # open again
my $writefh = FileHandle->new;
- unless (open $writefh, "|$patchbin $thispatchargs") {
- my $fail = "Could not fork '$patchbin $thispatchargs'";
+ $CPAN::Frontend->myprint(" $pcommand\n");
+ unless (open $writefh, "|$pcommand") {
+ my $fail = "Could not fork '$pcommand'";
$CPAN::Frontend->mywarn("$fail; cannot continue\n");
$self->{unwrapped} = CPAN::Distrostatus->new("NO -- $fail");
delete $self->{build_dir};
sub _patch_p_parameter {
my($self,$fh) = @_;
- my($cnt_files,$cnt_p0files);
+ my $cnt_files = 0;
+ my $cnt_p0files = 0;
local($_);
while ($_ = $fh->READLINE) {
+ if (
+ $CPAN::Config->{applypatch}
+ &&
+ /\#\#\#\# ApplyPatch data follows \#\#\#\#/
+ ) {
+ return "applypatch"
+ }
next unless /^[\*\+]{3}\s(\S+)/;
my $file = $1;
$cnt_files++;
$cnt_p0files++ if -f $file;
+ CPAN->debug("file[$file]cnt_files[$cnt_files]cnt_p0files[$cnt_p0files]")
+ if $CPAN::DEBUG;
}
+ return "-p1" unless $cnt_files;
return $cnt_files==$cnt_p0files ? "-p0" : "-p1";
}
#-> CPAN::Distribution::_signature_business
sub _signature_business {
my($self) = @_;
- if ($CPAN::Config->{check_sigs}) {
+ my $check_sigs = CPAN::HandleConfig->prefs_lookup($self,
+ q{check_sigs});
+ if ($check_sigs) {
if ($CPAN::META->has_inst("Module::Signature")) {
if (-f "SIGNATURE") {
$self->debug("Module::Signature is installed, verifying") if $CPAN::DEBUG;
if ( $local_file =~ /\.pm(\.(gz|Z))?(?!\n)\Z/ ){
$self->{archived} = "pm";
+ } elsif ( $local_file =~ /\.patch(\.(gz|bz2))?(?!\n)\Z/ ) {
+ $self->{archived} = "patch";
} else {
$self->{archived} = "maybe_pl";
}
my $to = File::Basename::basename($local_file);
if ($to =~ s/\.(gz|Z)(?!\n)\Z//) {
- if (CPAN::Tarzip->new($local_file)->gunzip($to)) {
+ if (eval{CPAN::Tarzip->new($local_file)->gunzip($to)}) {
$self->{unwrapped} = CPAN::Distrostatus->new("YES");
} else {
$self->{unwrapped} = CPAN::Distrostatus->new("NO -- uncompressing failed");
}
} else {
- File::Copy::cp($local_file,".");
- $self->{unwrapped} = CPAN::Distrostatus->new("NO -- copying failed");
+ if (File::Copy::cp($local_file,".")) {
+ $self->{unwrapped} = CPAN::Distrostatus->new("YES");
+ } else {
+ $self->{unwrapped} = CPAN::Distrostatus->new("NO -- copying failed");
+ }
}
return $to;
}
"$lc_want.gz",1);
if ($lc_file) {
$lc_file =~ s/\.gz(?!\n)\Z//;
- CPAN::Tarzip->new("$lc_file.gz")->gunzip($lc_file);
+ eval{CPAN::Tarzip->new("$lc_file.gz")->gunzip($lc_file)};
} else {
return;
}
$sloppy ||= 0;
$self->debug("chk_file[$chk_file]sloppy[$sloppy]") if $CPAN::DEBUG;
- if ($CPAN::Config->{check_sigs}) {
+ my $check_sigs = CPAN::HandleConfig->prefs_lookup($self,
+ q{check_sigs});
+ if ($check_sigs) {
if ($CPAN::META->has_inst("Module::Signature")) {
- $self->debug("Module::Signature is installed, verifying");
+ $self->debug("Module::Signature is installed, verifying") if $CPAN::DEBUG;
$self->SIG_check_file($chk_file);
} else {
- $self->debug("Module::Signature is NOT installed");
+ $self->debug("Module::Signature is NOT installed") if $CPAN::DEBUG;
}
}
# "Force get forgets previous error conditions"
+#-> sub CPAN::Distribution::fforce ;
+sub fforce {
+ my($self, $method) = @_;
+ $self->force($method,1);
+}
+
#-> sub CPAN::Distribution::force ;
sub force {
- my($self, $method) = @_;
- for my $att (qw(
- CHECKSUM_STATUS
- archived
- badtestcnt
- build_dir
- install
- localfile
- make
- make_test
- modulebuild
- prefs
- prefs_file
- prereq_pm
- prereq_pm_detected
- reqtype
- signature_verify
- unwrapped
- writemakefile
- yaml_content
- )) {
- delete $self->{$att};
- CPAN->debug(sprintf "att[%s]", $att) if $CPAN::DEBUG;
+ my($self, $method,$fforce) = @_;
+ my %phase_map = (
+ get => [
+ "unwrapped",
+ "build_dir",
+ "archived",
+ "localfile",
+ "CHECKSUM_STATUS",
+ "signature_verify",
+ "prefs",
+ "prefs_file",
+ "prefs_file_doc",
+ ],
+ make => [
+ "writemakefile",
+ "make",
+ "modulebuild",
+ "prereq_pm",
+ "prereq_pm_detected",
+ ],
+ test => [
+ "badtestcnt",
+ "make_test",
+ ],
+ install => [
+ "install",
+ ],
+ unknown => [
+ "reqtype",
+ "yaml_content",
+ ],
+ );
+ my $methodmatch = 0;
+ my $ldebug = 0;
+ PHASE: for my $phase (qw(unknown get make test install)) { # order matters
+ $methodmatch = 1 if $fforce || $phase eq $method;
+ next unless $methodmatch;
+ ATTRIBUTE: for my $att (@{$phase_map{$phase}}) {
+ if ($phase eq "get") {
+ if (substr($self->id,-1,1) eq "."
+ && $att =~ /(unwrapped|build_dir|archived)/ ) {
+ # cannot be undone for local distros
+ next ATTRIBUTE;
+ }
+ if ($att eq "build_dir"
+ && $self->{build_dir}
+ && $CPAN::META->{is_tested}
+ ) {
+ delete $CPAN::META->{is_tested}{$self->{build_dir}};
+ }
+ } elsif ($phase eq "test") {
+ if ($att eq "make_test"
+ && $self->{make_test}
+ && $self->{make_test}{COMMANDID}
+ && $self->{make_test}{COMMANDID} == $CPAN::CurrentCommandId
+ ) {
+ # endless loop too likely
+ next ATTRIBUTE;
+ }
+ }
+ delete $self->{$att};
+ if ($ldebug || $CPAN::DEBUG) {
+ # local $CPAN::DEBUG = 16; # Distribution
+ CPAN->debug(sprintf "id[%s]phase[%s]att[%s]", $self->id, $phase, $att);
+ }
+ }
}
if ($method && $method =~ /make|test|install/) {
- $self->{"force_update"}++; # name should probably have been force_install
+ $self->{force_update} = 1; # name should probably have been force_install
}
}
#-> sub CPAN::Distribution::unforce ;
sub unforce {
my($self) = @_;
- delete $self->{'force_update'};
+ delete $self->{force_update};
}
#-> sub CPAN::Distribution::isa_perl ;
#-> sub CPAN::Distribution::make ;
sub make {
my($self) = @_;
+ if (my $goto = $self->prefs->{goto}) {
+ return $self->goto($goto);
+ }
my $make = $self->{modulebuild} ? "Build" : "make";
# Emergency brake if they said install Pippi and get newest perl
if ($self->isa_perl) {
local $ENV{PERL5LIB} = defined($ENV{PERL5LIB})
? $ENV{PERL5LIB}
: ($ENV{PERLLIB} || "");
-
$CPAN::META->set_perl5lib;
local $ENV{MAKEFLAGS}; # protect us from outer make calls
delete $self->{force_update};
return;
}
+
+ my $builddir;
EXCUSE: {
my @e;
if (!$self->{archived} || $self->{archived} eq "NO") {
if (!$self->{unwrapped}
|| (
- $self->{unwrapped}->can("failed") ?
+ UNIVERSAL::can($self->{unwrapped},"failed") ?
$self->{unwrapped}->failed :
$self->{unwrapped} =~ /^NO/
)) {
}
unless ($self->{force_update}) {
- exists $self->{signature_verify} and (
- $self->{signature_verify}->can("failed") ?
- $self->{signature_verify}->failed :
- $self->{signature_verify} =~ /^NO/
- )
+ exists $self->{signature_verify} and
+ (
+ UNIVERSAL::can($self->{signature_verify},"failed") ?
+ $self->{signature_verify}->failed :
+ $self->{signature_verify} =~ /^NO/
+ )
and push @e, "Did not pass the signature test.";
}
if (exists $self->{writemakefile} &&
(
- $self->{writemakefile}->can("failed") ?
+ UNIVERSAL::can($self->{writemakefile},"failed") ?
$self->{writemakefile}->failed :
$self->{writemakefile} =~ /^NO/
)) {
# XXX maybe a retry would be in order?
- my $err = $self->{writemakefile}->can("text") ?
+ my $err = UNIVERSAL::can($self->{writemakefile},"text") ?
$self->{writemakefile}->text :
$self->{writemakefile};
$err =~ s/^NO\s*//;
}
defined $self->{make} and push @e,
- "Has already been processed within this session";
+ "Has already been made";
if (exists $self->{later} and length($self->{later})) {
if ($self->unsat_prereq) {
}
$CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
+ $builddir = $self->dir or
+ $CPAN::Frontend->mydie("PANIC: Cannot determine build directory\n");
+ unless (chdir $builddir) {
+ push @e, "Couldn't chdir to '$builddir': $!";
+ }
+ $CPAN::Frontend->mywarn(join "", map {" $_\n"} @e) and return if @e;
}
if ($CPAN::Signal){
delete $self->{force_update};
return;
}
$CPAN::Frontend->myprint("\n CPAN.pm: Going to build ".$self->id."\n\n");
- my $builddir = $self->dir or
- $CPAN::Frontend->mydie("PANIC: Cannot determine build directory\n");
- chdir $builddir or Carp::croak("Couldn't chdir $builddir: $!");
$self->debug("Changed directory to $builddir") if $CPAN::DEBUG;
if ($^O eq 'MacOS') {
return;
}
- my $system;
- if ($self->{'configure'}) {
- $system = $self->{'configure'};
- } elsif ($self->{modulebuild}) {
- my($perl) = $self->perl or die "Couldn\'t find executable perl\n";
+ my %env;
+ while (my($k,$v) = each %ENV) {
+ next unless defined $v;
+ $env{$k} = $v;
+ }
+ local %ENV = %env;
+ my $system;
+ if (my $commandline = $self->prefs->{pl}{commandline}) {
+ $system = $commandline;
+ $ENV{PERL} = $^X;
+ } elsif ($self->{'configure'}) {
+ $system = $self->{'configure'};
+ } elsif ($self->{modulebuild}) {
+ my($perl) = $self->perl or die "Couldn\'t find executable perl\n";
$system = "$perl Build.PL $CPAN::Config->{mbuildpl_arg}";
} else {
my($perl) = $self->perl or die "Couldn\'t find executable perl\n";
$makepl_arg ? " $makepl_arg" : "",
);
}
- my %env;
- while (my($k,$v) = each %ENV) {
- next unless defined $v;
- $env{$k} = $v;
- }
- local %ENV = %env;
if (my $env = $self->prefs->{pl}{env}) {
for my $e (keys %$env) {
$ENV{$e} = $env->{$e};
delete $self->{force_update};
return;
}
- if ($self->{modulebuild}) {
- unless (-f "Build") {
- my $cwd = Cwd::cwd;
- $CPAN::Frontend->mywarn("Alert: no Build file available for 'make $self->{id}'".
- " in cwd[$cwd]. Danger, Will Robinson!");
- $CPAN::Frontend->mysleep(5);
- }
- $system = sprintf "%s %s", $self->_build_command(), $CPAN::Config->{mbuild_arg};
+ if (my $commandline = $self->prefs->{make}{commandline}) {
+ $system = $commandline;
+ $ENV{PERL} = $^X;
} else {
- $system = join " ", $self->_make_command(), $CPAN::Config->{make_arg};
+ if ($self->{modulebuild}) {
+ unless (-f "Build") {
+ my $cwd = CPAN::anycwd();
+ $CPAN::Frontend->mywarn("Alert: no Build file available for 'make $self->{id}'".
+ " in cwd[$cwd]. Danger, Will Robinson!");
+ $CPAN::Frontend->mysleep(5);
+ }
+ $system = join " ", $self->_build_command(), $CPAN::Config->{mbuild_arg};
+ } else {
+ $system = join " ", $self->_make_command(), $CPAN::Config->{make_arg};
+ }
+ $system =~ s/\s+$//;
+ my $make_arg = $self->make_x_arg("make");
+ $system = sprintf("%s%s",
+ $system,
+ $make_arg ? " $make_arg" : "",
+ );
}
- my $make_arg = $self->make_x_arg("make");
- $system = sprintf("%s%s",
- $system,
- $make_arg ? " $make_arg" : "",
- );
if (my $env = $self->prefs->{make}{env}) { # overriding the local
# ENV of PL, not the
# outer ENV, but
$want_expect = 1;
} else {
$CPAN::Frontend->mywarn("Expect not installed, falling back to ".
- "system\n");
+ "system()\n");
}
}
my $system_ok;
if ($CPAN::META->has_inst("Expect")) {
my $expo = Expect->new; # expo Expect object;
$expo->spawn($system);
- my $expecta = $expect_model->{talk};
- if ($expect_model->{mode} eq "expect") {
- return $self->_run_via_expect_deterministic($expo,$expecta);
- } elsif ($expect_model->{mode} eq "expect-in-any-order") {
- return $self->_run_via_expect_anyorder($expo,$expecta);
+ $expect_model->{mode} ||= "deterministic";
+ if ($expect_model->{mode} eq "deterministic") {
+ return $self->_run_via_expect_deterministic($expo,$expect_model);
+ } elsif ($expect_model->{mode} eq "anyorder") {
+ return $self->_run_via_expect_anyorder($expo,$expect_model);
} else {
die "Panic: Illegal expect mode: $expect_model->{mode}";
}
}
sub _run_via_expect_anyorder {
- my($self,$expo,$expecta) = @_;
- my $timeout = 3; # currently unsettable
- my @expectacopy = @$expecta; # we trash it!
+ my($self,$expo,$expect_model) = @_;
+ my $timeout = $expect_model->{timeout} || 5;
+ my @expectacopy = @{$expect_model->{talk}}; # we trash it!
my $but = "";
EXPECT: while () {
my($eof,$ran_into_timeout);
}
sub _run_via_expect_deterministic {
- my($self,$expo,$expecta) = @_;
+ my($self,$expo,$expect_model) = @_;
my $ran_into_timeout;
+ my $timeout = $expect_model->{timeout} || 15; # currently unsettable
+ my $expecta = $expect_model->{talk};
EXPECT: for (my $i = 0; $i <= $#$expecta; $i+=2) {
- my($next,$send) = @$expecta[$i,$i+1];
- my($timeout,$re);
- if (ref $next) {
- $timeout = $next->{timeout};
- $re = $next->{expect};
- } else {
- $timeout = 15;
- $re = $next;
- }
+ my($re,$send) = @$expecta[$i,$i+1];
CPAN->debug("timeout[$timeout]re[$re]") if $CPAN::DEBUG;
my $regex = eval "qr{$re}";
$expo->expect($timeout,
return $expo->exitstatus();
}
-# CPAN::Distribution::_find_prefs
+#-> CPAN::Distribution::_validate_distropref
+sub _validate_distropref {
+ my($self,@args) = @_;
+ if (
+ $CPAN::META->has_inst("CPAN::Kwalify")
+ &&
+ $CPAN::META->has_inst("Kwalify")
+ ) {
+ eval {CPAN::Kwalify::_validate("distroprefs",@args);};
+ if ($@) {
+ $CPAN::Frontend->mywarn($@);
+ }
+ } else {
+ CPAN->debug("not validating '@args'") if $CPAN::DEBUG;
+ }
+}
+
+#-> CPAN::Distribution::_find_prefs
sub _find_prefs {
my($self) = @_;
my $distroid = $self->pretty_id;
- CPAN->debug("distroid[$distroid]") if $CPAN::DEBUG;
+ #CPAN->debug("distroid[$distroid]") if $CPAN::DEBUG;
my $prefs_dir = $CPAN::Config->{prefs_dir};
eval { File::Path::mkpath($prefs_dir); };
if ($@) {
$CPAN::Frontend->mydie("Cannot create directory $prefs_dir");
}
- my $yaml_module = CPAN->_yaml_module;
+ my $yaml_module = CPAN::_yaml_module;
+ my @extensions;
if ($CPAN::META->has_inst($yaml_module)) {
+ push @extensions, "yml";
+ } else {
+ my @fallbacks;
+ if ($CPAN::META->has_inst("Data::Dumper")) {
+ push @extensions, "dd";
+ push @fallbacks, "Data::Dumper";
+ }
+ if ($CPAN::META->has_inst("Storable")) {
+ push @extensions, "st";
+ push @fallbacks, "Storable";
+ }
+ if (@fallbacks) {
+ local $" = " and ";
+ unless ($self->{have_complained_about_missing_yaml}++) {
+ $CPAN::Frontend->mywarn("'$yaml_module' not installed, falling back ".
+ "to @fallbacks to read prefs '$prefs_dir'\n");
+ }
+ } else {
+ unless ($self->{have_complained_about_missing_yaml}++) {
+ $CPAN::Frontend->mywarn("'$yaml_module' not installed, cannot ".
+ "read prefs '$prefs_dir'\n");
+ }
+ }
+ }
+ if (@extensions) {
my $dh = DirHandle->new($prefs_dir)
or die Carp::croak("Couldn't open '$prefs_dir': $!");
DIRENT: for (sort $dh->read) {
next if $_ eq "." || $_ eq "..";
- next unless /\.yml$/;
+ my $exte = join "|", @extensions;
+ next unless /\.($exte)$/;
+ my $thisexte = $1;
my $abs = File::Spec->catfile($prefs_dir, $_);
if (-f $abs) {
- CPAN->debug(sprintf "abs[%s]", $abs) if $CPAN::DEBUG;
- my @yaml = @{CPAN->_yaml_loadfile($abs)};
+ #CPAN->debug(sprintf "abs[%s]", $abs) if $CPAN::DEBUG;
+ my @distropref;
+ if ($thisexte eq "yml") {
+ # need no eval because if we have no YAML we do not try to read *.yml
+ #CPAN->debug(sprintf "before yaml load abs[%s]", $abs) if $CPAN::DEBUG;
+ @distropref = @{CPAN->_yaml_loadfile($abs)};
+ #CPAN->debug(sprintf "after yaml load abs[%s]", $abs) if $CPAN::DEBUG;
+ } elsif ($thisexte eq "dd") {
+ package CPAN::Eval;
+ no strict;
+ open FH, "<$abs" or $CPAN::Frontend->mydie("Could not open '$abs': $!");
+ local $/;
+ my $eval = <FH>;
+ close FH;
+ eval $eval;
+ if ($@) {
+ $CPAN::Frontend->mydie("Error in distroprefs file $_\: $@");
+ }
+ my $i = 1;
+ while (${"VAR".$i}) {
+ push @distropref, ${"VAR".$i};
+ $i++;
+ }
+ } elsif ($thisexte eq "st") {
+ # eval because Storable is never forward compatible
+ eval { @distropref = @{scalar Storable::retrieve($abs)}; };
+ if ($@) {
+ $CPAN::Frontend->mywarn("Error reading distroprefs file ".
+ "$_, skipping\: $@");
+ $CPAN::Frontend->mysleep(4);
+ next DIRENT;
+ }
+ }
# $DB::single=1;
- ELEMENT: for my $y (0..$#yaml) {
- my $yaml = $yaml[$y];
- my $match = $yaml->{match};
+ #CPAN->debug(sprintf "#distropref[%d]", scalar @distropref) if $CPAN::DEBUG;
+ ELEMENT: for my $y (0..$#distropref) {
+ my $distropref = $distropref[$y];
+ $self->_validate_distropref($distropref,$abs,$y);
+ my $match = $distropref->{match};
unless ($match) {
- CPAN->debug("no 'match' in abs[$abs], skipping");
+ #CPAN->debug("no 'match' in abs[$abs], skipping") if $CPAN::DEBUG;
next ELEMENT;
}
my $ok = 1;
- for my $sub_attribute (keys %$match) {
- my $qr = eval "qr{$yaml->{match}{$sub_attribute}}";
+ # do not take the order of C<keys %$match> because
+ # "module" is by far the slowest
+ my $saw_valid_subkeys = 0;
+ for my $sub_attribute (qw(distribution perl perlconfig module)) {
+ next unless exists $match->{$sub_attribute};
+ $saw_valid_subkeys++;
+ my $qr = eval "qr{$distropref->{match}{$sub_attribute}}";
if ($sub_attribute eq "module") {
my $okm = 0;
- CPAN->debug(sprintf "abs[%s]yaml[%d]", $abs, scalar @yaml) if $CPAN::DEBUG;
+ #CPAN->debug(sprintf "distropref[%d]", scalar @distropref) if $CPAN::DEBUG;
my @modules = $self->containsmods;
- CPAN->debug(sprintf "abs[%s]yaml[%d]modules[%s]", $abs, scalar @yaml, join(",",@modules)) if $CPAN::DEBUG;
+ #CPAN->debug(sprintf "modules[%s]", join(",",@modules)) if $CPAN::DEBUG;
MODULE: for my $module (@modules) {
$okm ||= $module =~ /$qr/;
last MODULE if $okm;
} elsif ($sub_attribute eq "perl") {
my $okp = $^X =~ /$qr/;
$ok &&= $okp;
+ } elsif ($sub_attribute eq "perlconfig") {
+ for my $perlconfigkey (keys %{$match->{perlconfig}}) {
+ my $perlconfigval = $match->{perlconfig}->{$perlconfigkey};
+ # XXX should probably warn if Config does not exist
+ my $okpc = $Config::Config{$perlconfigkey} =~ /$perlconfigval/;
+ $ok &&= $okpc;
+ last if $ok == 0;
+ }
} else {
- $CPAN::Frontend->mydie("Nonconforming YAML file '$abs': ".
+ $CPAN::Frontend->mydie("Nonconforming .$thisexte file '$abs': ".
"unknown sub_attribut '$sub_attribute'. ".
"Please ".
"remove, cannot continue.");
}
+ last if $ok == 0; # short circuit
}
- CPAN->debug(sprintf "abs[%s]yaml[%d]ok[%d]", $abs, scalar @yaml, $ok) if $CPAN::DEBUG;
+ unless ($saw_valid_subkeys) {
+ $CPAN::Frontend->mydie("Nonconforming .$thisexte file '$abs': ".
+ "missing match/* subattribute. ".
+ "Please ".
+ "remove, cannot continue.");
+ }
+ #CPAN->debug(sprintf "ok[%d]", $ok) if $CPAN::DEBUG;
if ($ok) {
return {
- prefs => $yaml,
+ prefs => $distropref,
prefs_file => $abs,
prefs_file_doc => $y,
};
}
}
}
- } else {
- unless ($self->{have_complained_about_missing_yaml}++) {
- $CPAN::Frontend->mywarn("'$yaml_module' not installed, cannot read prefs '$prefs_dir'\n");
- }
+ $dh->close;
}
return;
}
# CPAN::Distribution::prefs
sub prefs {
my($self) = @_;
+ if (exists $self->{negative_prefs_cache}
+ &&
+ $self->{negative_prefs_cache} != $CPAN::CurrentCommandId
+ ) {
+ delete $self->{negative_prefs_cache};
+ delete $self->{prefs};
+ }
if (exists $self->{prefs}) {
return $self->{prefs}; # XXX comment out during debugging
}
if ($CPAN::Config->{prefs_dir}) {
CPAN->debug("prefs_dir[$CPAN::Config->{prefs_dir}]") if $CPAN::DEBUG;
my $prefs = $self->_find_prefs();
+ $prefs ||= ""; # avoid warning next line
+ CPAN->debug("prefs[$prefs]") if $CPAN::DEBUG;
if ($prefs) {
for my $x (qw(prefs prefs_file prefs_file_doc)) {
$self->{$x} = $prefs->{$x};
return $self->{prefs};
}
}
- return +{};
+ $self->{negative_prefs_cache} = $CPAN::CurrentCommandId;
+ return $self->{prefs} = +{};
}
# CPAN::Distribution::make_x_arg
c => "commandline",
);
my($filler1,$filler2,$filler3,$filler4);
+ # $DB::single=1;
my $unsat = "Unsatisfied dependencies detected during";
my $w = length($unsat) > length($pretty_id) ? length($unsat) : length($pretty_id);
{
# color them as dirty
for my $p (@prereq) {
# warn "calling color_cmd_tmps(0,1)";
- CPAN::Shell->expandany($p)->color_cmd_tmps(0,1);
+ my $any = CPAN::Shell->expandany($p);
+ if ($any) {
+ $any->color_cmd_tmps(0,2);
+ } else {
+ $CPAN::Frontend->mywarn("Warning (maybe a bug): Cannot expand prereq '$p'\n");
+ $CPAN::Frontend->mysleep(2);
+ }
}
# queue them and re-queue yourself
CPAN::Queue->jumpqueue([$id,$self->{reqtype}],
my $prereq_pm = $self->prereq_pm or return;
my(@need);
my %merged = (%{$prereq_pm->{requires}||{}},%{$prereq_pm->{build_requires}||{}});
+ my @merged = %merged;
+ CPAN->debug("all merged_prereqs[@merged]") if $CPAN::DEBUG;
NEED: while (my($need_module, $need_version) = each %merged) {
- my($have_version,$inst_file);
+ my($available_version,$available_file,$nmo);
if ($need_module eq "perl") {
- $have_version = $];
- $inst_file = $^X;
+ $available_version = $];
+ $available_file = $^X;
} else {
- my $nmo = $CPAN::META->instance("CPAN::Module",$need_module);
+ $nmo = $CPAN::META->instance("CPAN::Module",$need_module);
next if $nmo->uptodate;
- $inst_file = $nmo->inst_file;
+ $available_file = $nmo->available_file;
# if they have not specified a version, we accept any installed one
if (not defined $need_version or
- $need_version eq "0" or
+ $need_version == 0 or
$need_version eq "undef") {
- next if defined $inst_file;
+ next if defined $available_file;
}
- $have_version = $nmo->inst_version;
+ $available_version = $nmo->available_version;
}
# We only want to install prereqs if either they're not installed
# or if the installed version is too old. We cannot omit this
# check, because if 'force' is in effect, nobody else will check.
- if (defined $inst_file) {
+ if (defined $available_file) {
my(@all_requirements) = split /\s*,\s*/, $need_version;
local($^W) = 0;
my $ok = 0;
if ($rq =~ s|>=\s*||) {
} elsif ($rq =~ s|>\s*||) {
# 2005-12: one user
- if (CPAN::Version->vgt($have_version,$rq)){
+ if (CPAN::Version->vgt($available_version,$rq)){
$ok++;
}
next RQ;
} elsif ($rq =~ s|!=\s*||) {
# 2005-12: no user
- if (CPAN::Version->vcmp($have_version,$rq)){
+ if (CPAN::Version->vcmp($available_version,$rq)){
$ok++;
next RQ;
} else {
}
} elsif ($rq =~ m|<=?\s*|) {
# 2005-12: no user
- $CPAN::Frontend->mywarn("Downgrading not supported (rq[$rq])");
+ $CPAN::Frontend->mywarn("Downgrading not supported (rq[$rq])\n");
$ok++;
next RQ;
}
- if (! CPAN::Version->vgt($rq, $have_version)){
+ if (! CPAN::Version->vgt($rq, $available_version)){
$ok++;
}
- CPAN->debug(sprintf("need_module[%s]inst_file[%s]".
- "inst_version[%s]rq[%s]ok[%d]",
+ CPAN->debug(sprintf("need_module[%s]available_file[%s]".
+ "available_version[%s]rq[%s]ok[%d]",
$need_module,
- $inst_file,
- $have_version,
+ $available_file,
+ $available_version,
CPAN::Version->readable($rq),
$ok,
)) if $CPAN::DEBUG;
}
if ($self->{sponsored_mods}{$need_module}++){
# We have already sponsored it and for some reason it's still
- # not available. So we do nothing. Or what should we do?
+ # not available. So we do ... what??
+
# if we push it again, we have a potential infinite loop
- next;
+
+ # The following "next" was a very problematic construct.
+ # It helped a lot but broke some day and must be replaced.
+
+ # We must be able to deal with modules that come again and
+ # again as a prereq and have themselves prereqs and the
+ # queue becomes long but finally we would find the correct
+ # order. The RecursiveDependency check should trigger a
+ # die when it's becoming too weird. Unfortunately removing
+ # this next breaks many other things.
+
+ # The bug that brought this up is described in Todo under
+ # "5.8.9 cannot install Compress::Zlib"
+
+ # next; # this is the next that must go away
+
+ # The following "next NEED" are fine and the error message
+ # explains well what is going on. For example when the DBI
+ # fails and consequently DBD::SQLite fails and now we are
+ # processing CPAN::SQLite. Then we must have a "next" for
+ # DBD::SQLite. How can we get it and how can we identify
+ # all other cases we must identify?
+
+ my $do = $nmo->distribution;
+ next NEED unless $do; # not on CPAN
+ NOSAYER: for my $nosayer (
+ "unwrapped",
+ "writemakefile",
+ "signature_verify",
+ "make",
+ "make_test",
+ "install",
+ "make_clean",
+ ) {
+ if (
+ $do->{$nosayer}
+ &&(UNIVERSAL::can($do->{$nosayer},"failed") ?
+ $do->{$nosayer}->failed :
+ $do->{$nosayer} =~ /^NO/)
+ ) {
+ if ($nosayer eq "make_test"
+ &&
+ $do->{make_test}{COMMANDID} != $CPAN::CurrentCommandId
+ ) {
+ next NOSAYER;
+ }
+ $CPAN::Frontend->mywarn("Warning: Prerequisite ".
+ "'$need_module => $need_version' ".
+ "for '$self->{ID}' failed when ".
+ "processing '$do->{ID}' with ".
+ "'$nosayer => $do->{$nosayer}'. Continuing, ".
+ "but chances to succeed are limited.\n"
+ );
+ next NEED;
+ }
+ }
}
my $needed_as = exists $prereq_pm->{requires}{$need_module} ? "r" : "b";
push @need, [$need_module,$needed_as];
}
+ my @unfolded = map { "[".join(",",@$_)."]" } @need;
+ CPAN->debug("returning from unsat_prereq[@unfolded]") if $CPAN::DEBUG;
@need;
}
return unless -f $yaml;
eval { $self->{yaml_content} = CPAN->_yaml_loadfile($yaml)->[0]; };
if ($@) {
- return; # if we die, then we cannot read YAML's own META.yml
- }
+ $CPAN::Frontend->mywarn("Could not read ".
+ "'$yaml'. Falling back to other ".
+ "methods to determine prerequisites\n");
+ return $self->{yaml_content} = undef; # if we die, then we
+ # cannot read YAML's own
+ # META.yml
+ }
+ # not "authoritative"
if (not exists $self->{yaml_content}{dynamic_config}
or $self->{yaml_content}{dynamic_config}
) {
#-> sub CPAN::Distribution::prereq_pm ;
sub prereq_pm {
my($self) = @_;
- return $self->{prereq_pm} if
- exists $self->{prereq_pm_detected} && $self->{prereq_pm_detected};
+ $self->{prereq_pm_detected} ||= 0;
+ CPAN->debug("ID[$self->{ID}]prereq_pm_detected[$self->{prereq_pm_detected}]") if $CPAN::DEBUG;
+ return $self->{prereq_pm} if $self->{prereq_pm_detected};
return unless $self->{writemakefile} # no need to have succeeded
# but we must have run it
|| $self->{modulebuild};
+ CPAN->debug(sprintf "writemakefile[%s]modulebuild[%s]",
+ $self->{writemakefile}||"",
+ $self->{modulebuild}||"",
+ ) if $CPAN::DEBUG;
my($req,$breq);
if (my $yaml = $self->read_yaml) { # often dynamic_config prevents a result here
$req = $yaml->{requires} || {};
$breq = $yaml->{build_requires} || {};
undef $req unless ref $req eq "HASH" && %$req;
if ($req) {
- if ($yaml->{generated_by} =~ /ExtUtils::MakeMaker version ([\d\._]+)/) {
+ if ($yaml->{generated_by} &&
+ $yaml->{generated_by} =~ /ExtUtils::MakeMaker version ([\d\._]+)/) {
my $eummv = do { local $^W = 0; $1+0; };
if ($eummv < 6.2501) {
# thanks to Slaven for digging that out: MM before
if (-f $makefile
and
$fh = FileHandle->new("<$makefile\0")) {
+ CPAN->debug("Getting prereq from Makefile") if $CPAN::DEBUG;
local($/) = "\n";
while (<$fh>) {
last if /MakeMaker post_initialize section/;
# Regexp modified by A.Speer to remember actual version of file
# PREREQ_PM hash key wants, then add to
- while ( $p =~ m/(?:\s)([\w\:]+)=>q\[(.*?)\],?/g ){
+ while ( $p =~ m/(?:\s)([\w\:]+)=>(q\[.*?\]|undef),?/g ){
# In case a prereq is mentioned twice, complain.
if ( defined $req->{$1} ) {
warn "Warning: PREREQ_PM mentions $1 more than once, ".
"last mention wins";
}
- $req->{$1} = $2;
+ my($m,$n) = ($1,$2);
+ if ($n =~ /^q\[(.*?)\]$/) {
+ $n = $1;
+ }
+ $req->{$m} = $n;
}
last;
}
- } elsif (-f "Build") {
- if ($CPAN::META->has_inst("Module::Build")) {
- eval {
- $req = Module::Build->current->requires();
- $breq = Module::Build->current->build_requires();
- };
- # this failed for example for HTML::Mason and for
- # Error.pm because they are subclassing Module::Build
- # in their Build.PL in such a way that Module::Build
- # cannot read the _build directory. We DO need a dump
- # command for that.
+ }
+ }
+ unless ($req || $breq) {
+ my $build_dir = $self->{build_dir} or die "Panic: no build_dir?";
+ my $buildfile = File::Spec->catfile($build_dir,"Build");
+ if (-f $buildfile) {
+ CPAN->debug("Found '$buildfile'") if $CPAN::DEBUG;
+ my $build_prereqs = File::Spec->catfile($build_dir,"_build","prereqs");
+ if (-f $build_prereqs) {
+ CPAN->debug("Getting prerequisites from '$build_prereqs'") if $CPAN::DEBUG;
+ my $content = do { local *FH;
+ open FH, $build_prereqs
+ or $CPAN::Frontend->mydie("Could not open ".
+ "'$build_prereqs': $!");
+ local $/;
+ <FH>;
+ };
+ my $bphash = eval $content;
if ($@) {
- $CPAN::Frontend
- ->mywarn(
- sprintf("Warning: while trying to determine ".
- "prerequisites for %s with the help of ".
- "Module::Build the following error ".
- "occurred: '%s'\n\nFalling back to META.yml ".
- "for prerequisites\n",
- $self->id,
- $@
- ));
- my $build_dir = $self->{build_dir};
- my $yaml = File::Spec->catfile($build_dir,"META.yml");
- if ($yaml = CPAN->_yaml_loadfile($yaml)->[0]) {
- $req = $yaml->{requires} || {};
- $breq = $yaml->{build_requires} || {};
- }
+ } else {
+ $req = $bphash->{requires} || +{};
+ $breq = $bphash->{build_requires} || +{};
}
}
}
$req->{"Module::Build"} = 0;
delete $self->{writemakefile};
}
- $self->{prereq_pm_detected}++;
- return $self->{prereq_pm} = { requires => $req, build_requires => $breq };
+ if ($req || $breq) {
+ $self->{prereq_pm_detected}++;
+ return $self->{prereq_pm} = { requires => $req, build_requires => $breq };
+ }
}
#-> sub CPAN::Distribution::test ;
sub test {
my($self) = @_;
+ if (my $goto = $self->prefs->{goto}) {
+ return $self->goto($goto);
+ }
$self->make;
if ($CPAN::Signal){
delete $self->{force_update};
local $ENV{MAKEFLAGS}; # protect us from outer make calls
$CPAN::Frontend->myprint("Running $make test\n");
- if (my @prereq = $self->unsat_prereq){
- unless ($prereq[0][0] eq "perl") {
- return 1 if $self->follow_prereqs(@prereq); # signal success to the queuerunner
- }
- }
+
+# if (my @prereq = $self->unsat_prereq){
+# if ( $CPAN::DEBUG ) {
+# require Data::Dumper;
+# CPAN->debug(sprintf "unsat_prereq[%s]", Data::Dumper::Dumper(\@prereq));
+# }
+# unless ($prereq[0][0] eq "perl") {
+# return 1 if $self->follow_prereqs(@prereq); # signal success to the queuerunner
+# }
+# }
+
EXCUSE: {
my @e;
unless (exists $self->{make} or exists $self->{later}) {
exists $self->{make} and
(
- $self->{make}->can("failed") ?
+ UNIVERSAL::can($self->{make},"failed") ?
$self->{make}->failed :
$self->{make} =~ /^NO/
) and push @e, "Can't test without successful make";
$self->{badtestcnt} ||= 0;
- $self->{badtestcnt} > 0 and
+ if ($self->{badtestcnt} > 0) {
+ require Data::Dumper;
+ CPAN->debug(sprintf "NOREPEAT[%s]", Data::Dumper::Dumper($self)) if $CPAN::DEBUG;
push @e, "Won't repeat unsuccessful test during this command";
+ }
exists $self->{later} and length($self->{later}) and
push @e, $self->{later};
exists $self->{make_test}
&&
!(
- $self->{make_test}->can("failed") ?
+ UNIVERSAL::can($self->{make_test},"failed") ?
$self->{make_test}->failed :
$self->{make_test} =~ /^NO/
)
) {
- push @e, "Already tested successfully";
+ push @e, "Has already been tested successfully";
}
} elsif (!@e) {
push @e, "Has no own directory";
}
-
$CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
+ unless (chdir $self->{build_dir}) {
+ push @e, "Couldn't chdir to '$self->{build_dir}': $!";
+ }
+ $CPAN::Frontend->mywarn(join "", map {" $_\n"} @e) and return if @e;
}
- chdir $self->{'build_dir'} or
- Carp::croak("Couldn't chdir to $self->{'build_dir'}");
- $self->debug("Changed directory to $self->{'build_dir'}")
+ $self->debug("Changed directory to $self->{build_dir}")
if $CPAN::DEBUG;
if ($^O eq 'MacOS') {
}
my $system;
- if ($self->{modulebuild}) {
+ if (my $commandline = $self->prefs->{test}{commandline}) {
+ $system = $commandline;
+ $ENV{PERL} = $^X;
+ } elsif ($self->{modulebuild}) {
$system = sprintf "%s test", $self->_build_command();
} else {
$system = join " ", $self->_make_command(), "test";
}
+ my $make_test_arg = $self->make_x_arg("test");
+ $system = sprintf("%s%s",
+ $system,
+ $make_test_arg ? " $make_test_arg" : "",
+ );
my($tests_ok);
my %env;
while (my($k,$v) = each %ENV) {
if ($can_report) {
$want_report = 1;
} else {
- $CPAN::Frontend->mywarn->("CPAN::Reporter not installed, falling back to ".
- "testing without\n");
+ $CPAN::Frontend->mywarn("CPAN::Reporter not installed, falling back to ".
+ "testing without\n");
}
}
my $ready_to_report = $want_report;
if ( $tests_ok ) {
{
my @prereq;
+
+ # local $CPAN::DEBUG = 16; # Distribution
for my $m (keys %{$self->{sponsored_mods}}) {
- my $m_obj = CPAN::Shell->expand("Module",$m);
- my $d_obj = $m_obj->distribution;
- if ($d_obj) {
- if (!$d_obj->{make_test}
- ||
- $d_obj->{make_test}->failed){
- #$m_obj->dump;
- push @prereq, $m;
- }
+ my $m_obj = CPAN::Shell->expand("Module",$m) or next;
+ # XXX we need available_version which reflects
+ # $ENV{PERL5LIB} so that already tested but not yet
+ # installed modules are counted.
+ my $available_version = $m_obj->available_version;
+ my $available_file = $m_obj->available_file;
+ if ($available_version &&
+ !CPAN::Version->vlt($available_version,$self->{prereq_pm}{$m})
+ ) {
+ CPAN->debug("m[$m] good enough available_version[$available_version]")
+ if $CPAN::DEBUG;
+ } elsif ($available_file
+ && (
+ !$self->{prereq_pm}{$m}
+ ||
+ $self->{prereq_pm}{$m} == 0
+ )
+ ) {
+ # lex Class::Accessor::Chained::Fast which has no $VERSION
+ CPAN->debug("m[$m] have available_file[$available_file]")
+ if $CPAN::DEBUG;
+ } else {
+ push @prereq, $m;
}
}
if (@prereq){
my $cnt = @prereq;
my $which = join ",", @prereq;
- my $verb = $cnt == 1 ? "one dependency not OK ($which)" :
+ my $but = $cnt == 1 ? "one dependency not OK ($which)" :
"$cnt dependencies missing ($which)";
- $CPAN::Frontend->mywarn("Tests succeeded but $verb\n");
- $self->{make_test} = CPAN::Distrostatus->new("NO $verb");
+ $CPAN::Frontend->mywarn("Tests succeeded but $but\n");
+ $self->{make_test} = CPAN::Distrostatus->new("NO $but");
$self->store_persistent_state;
return;
}
}
$CPAN::Frontend->myprint(" $system -- OK\n");
- $CPAN::META->is_tested($self->{'build_dir'});
$self->{make_test} = CPAN::Distrostatus->new("YES");
+ $CPAN::META->is_tested($self->{build_dir},$self->{make_test}{TIME});
+ # probably impossible to need the next line because badtestcnt
+ # has a lifespan of one command
+ delete $self->{badtestcnt};
} else {
$self->{make_test} = CPAN::Distrostatus->new("NO");
$self->{badtestcnt}++;
return unless my $where_prefs = $prefs->{$where};
if ($where_prefs->{expect}) {
return {
- mode => "expect",
+ mode => "deterministic",
+ timeout => 15,
talk => $where_prefs->{expect},
};
- } elsif ($where_prefs->{"expect-in-any-order"}) {
- return {
- mode => "expect-in-any-order",
- talk => $where_prefs->{"expect-in-any-order"},
- };
+ } elsif ($where_prefs->{"eexpect"}) {
+ return $where_prefs->{"eexpect"};
}
return;
}
push @e, "make clean already called once";
$CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
}
- chdir $self->{'build_dir'} or
- Carp::croak("Couldn't chdir to $self->{'build_dir'}");
- $self->debug("Changed directory to $self->{'build_dir'}") if $CPAN::DEBUG;
+ chdir $self->{build_dir} or
+ Carp::confess("Couldn't chdir to $self->{build_dir}: $!");
+ $self->debug("Changed directory to $self->{build_dir}") if $CPAN::DEBUG;
if ($^O eq 'MacOS') {
Mac::BuildTools::make_clean($self);
my $system;
if ($self->{modulebuild}) {
unless (-f "Build") {
- my $cwd = Cwd::cwd;
+ my $cwd = CPAN::anycwd();
$CPAN::Frontend->mywarn("Alert: no Build file available for 'clean $self->{id}".
" in cwd[$cwd]. Danger, Will Robinson!");
$CPAN::Frontend->mysleep(5);
$self->store_persistent_state;
}
+#-> sub CPAN::Distribution::goto ;
+sub goto {
+ my($self,$goto) = @_;
+ $goto = $self->normalize($goto);
+
+ # inject into the queue
+
+ CPAN::Queue->delete($self->id);
+ CPAN::Queue->jumpqueue([$goto,$self->{reqtype}]);
+
+ # and run where we left off
+
+ my($method) = (caller(1))[3];
+ CPAN->instance("CPAN::Distribution",$goto)->$method;
+ CPAN::Queue->delete_first($goto);
+}
+
#-> sub CPAN::Distribution::install ;
sub install {
my($self) = @_;
- $self->test;
+ if (my $goto = $self->prefs->{goto}) {
+ return $self->goto($goto);
+ }
+ $DB::single=1;
+ unless ($self->{badtestcnt}) {
+ $self->test;
+ }
if ($CPAN::Signal){
delete $self->{force_update};
return;
exists $self->{make} and
(
- $self->{make}->can("failed") ?
+ UNIVERSAL::can($self->{make},"failed") ?
$self->{make}->failed :
$self->{make} =~ /^NO/
) and
if (exists $self->{make_test} and
(
- $self->{make_test}->can("failed") ?
+ UNIVERSAL::can($self->{make_test},"failed") ?
$self->{make_test}->failed :
$self->{make_test} =~ /^NO/
)){
"won't install without force"
}
}
- if (exists $self->{'install'}) {
- if ($self->{'install'}->can("text") ?
- $self->{'install'}->text eq "YES" :
- $self->{'install'} =~ /^YES/
+ if (exists $self->{install}) {
+ if (UNIVERSAL::can($self->{install},"text") ?
+ $self->{install}->text eq "YES" :
+ $self->{install} =~ /^YES/
) {
push @e, "Already done";
} else {
push @e, $self->{later};
$CPAN::Frontend->myprint(join "", map {" $_\n"} @e) and return if @e;
+ unless (chdir $self->{build_dir}) {
+ push @e, "Couldn't chdir to '$self->{build_dir}': $!";
+ }
+ $CPAN::Frontend->mywarn(join "", map {" $_\n"} @e) and return if @e;
}
- chdir $self->{'build_dir'} or
- Carp::croak("Couldn't chdir to $self->{'build_dir'}");
- $self->debug("Changed directory to $self->{'build_dir'}")
+ $self->debug("Changed directory to $self->{build_dir}")
if $CPAN::DEBUG;
if ($^O eq 'MacOS') {
}
my $system;
- if ($self->{modulebuild}) {
+ if (my $commandline = $self->prefs->{install}{commandline}) {
+ $system = $commandline;
+ $ENV{PERL} = $^X;
+ } elsif ($self->{modulebuild}) {
my($mbuild_install_build_command) =
exists $CPAN::HandleConfig::keys{mbuild_install_build_command} &&
$CPAN::Config->{mbuild_install_build_command} ?
if ( $close_ok ) {
$CPAN::Frontend->myprint(" $system -- OK\n");
$CPAN::META->is_installed($self->{build_dir});
- return $self->{install} = CPAN::Distrostatus->new("YES");
+ $self->{install} = CPAN::Distrostatus->new("YES");
} else {
$self->{install} = CPAN::Distrostatus->new("NO");
$CPAN::Frontend->mywarn(" $system -- NOT OK\n");
}
}
delete $self->{force_update};
+ # $DB::single = 1;
$self->store_persistent_state;
}
#-> sub CPAN::Distribution::dir ;
sub dir {
- shift->{'build_dir'};
+ shift->{build_dir};
}
#-> sub CPAN::Distribution::perldoc ;
# to recurse into its prereq_pms, a bundle needs to recurse into its modules
return if exists $self->{incommandcolor}
+ && $color==1
&& $self->{incommandcolor}==$color;
- if ($depth>=100){
+ if ($depth>=$CPAN::MAX_RECURSION){
$CPAN::Frontend->mydie(CPAN::Exception::RecursiveDependency->new($ancestors));
}
# warn "color_cmd_tmps $depth $color " . $self->id; # sleep 1;
CPAN->debug("c[$c]obj[$obj]") if $CPAN::DEBUG;
$obj->color_cmd_tmps($depth+1,$color,[@$ancestors, $self->id]);
}
- if ($color==0) {
- delete $self->{badtestcnt};
- }
+ # never reached code?
+ #if ($color==0) {
+ #delete $self->{badtestcnt};
+ #}
$self->{incommandcolor} = $color;
}
}
my $dist = $CPAN::META->instance('CPAN::Distribution',
$self->cpan_file);
+ $self->debug("before get id[$dist->{ID}]") if $CPAN::DEBUG;
$dist->get;
- $self->debug("id[$dist->{ID}]") if $CPAN::DEBUG;
+ $self->debug("after get id[$dist->{ID}]") if $CPAN::DEBUG;
my($todir) = $CPAN::Config->{'cpan_home'};
my(@me,$from,$to,$me);
@me = split /::/, $self->id;
$me[-1] .= ".pm";
$me = File::Spec->catfile(@me);
- $from = $self->find_bundle_file($dist->{'build_dir'},join('/',@me));
+ $from = $self->find_bundle_file($dist->{build_dir},join('/',@me));
$to = File::Spec->catfile($todir,$me);
File::Path::mkpath(File::Basename::dirname($to));
File::Copy::copy($from, $to)
my $obj = $CPAN::META->instance($type,$s);
$obj->{reqtype} = $self->{reqtype};
$obj->$meth();
- if ($obj->isa('CPAN::Bundle')
- &&
- exists $obj->{install_failed}
- &&
- ref($obj->{install_failed}) eq "HASH"
- ) {
- for (keys %{$obj->{install_failed}}) {
- $self->{install_failed}{$_} = undef; # propagate faiure up
- # to me in a
- # recursive call
- $fail{$s} = 1; # the bundle itself may have succeeded but
- # not all children
- }
- } else {
- my $success;
- $success = $obj->can("uptodate") ? $obj->uptodate : 0;
- $success ||= $obj->{'install'} && $obj->{'install'} eq "YES";
- if ($success) {
- delete $self->{install_failed}{$s};
- } else {
- $fail{$s} = 1;
- }
- }
- }
-
- # recap with less noise
- if ( $meth eq "install" ) {
- if (%fail) {
- require Text::Wrap;
- my $raw = sprintf(qq{Bundle summary:
-The following items in bundle %s had installation problems:},
- $self->id
- );
- $CPAN::Frontend->myprint(Text::Wrap::fill("","",$raw));
- $CPAN::Frontend->myprint("\n");
- my $paragraph = "";
- my %reported;
- for $s ($self->contains) {
- if ($fail{$s}){
- $paragraph .= "$s ";
- $self->{install_failed}{$s} = undef;
- $reported{$s} = undef;
- }
- }
- my $report_propagated;
- for $s (sort keys %{$self->{install_failed}}) {
- next if exists $reported{$s};
- $paragraph .= "and the following items had problems
-during recursive bundle calls: " unless $report_propagated++;
- $paragraph .= "$s ";
- }
- $CPAN::Frontend->myprint(Text::Wrap::fill(" "," ",$paragraph));
- $CPAN::Frontend->myprint("\n");
- } else {
- $self->{'install'} = 'YES';
- }
}
}
}
#-> sub CPAN::Bundle::force ;
+sub fforce { shift->rematein('fforce',@_); }
+#-> sub CPAN::Bundle::force ;
sub force { shift->rematein('force',@_); }
#-> sub CPAN::Bundle::notest ;
sub notest { shift->rematein('notest',@_); }
#-> sub CPAN::Bundle::test ;
sub test {
my $self = shift;
- $self->{badtestcnt} ||= 0;
+ # $self->{badtestcnt} ||= 0;
$self->rematein('test',@_);
}
#-> sub CPAN::Bundle::install ;
# a module needs to recurse to its cpan_file
return if exists $self->{incommandcolor}
+ && $color==1
&& $self->{incommandcolor}==$color;
- return if $depth>=1 && $self->uptodate;
- if ($depth>=100){
+ return if $color==0 && !$self->{incommandcolor};
+ if ($color>=1) {
+ if ( $self->uptodate ) {
+ $self->{incommandcolor} = $color;
+ return;
+ } elsif (my $have_version = $self->available_version) {
+ # maybe what we have is good enough
+ if (@$ancestors) {
+ my $who_asked_for_me = $ancestors->[-1];
+ my $obj = CPAN::Shell->expandany($who_asked_for_me);
+ if (0) {
+ } elsif ($obj->isa("CPAN::Bundle")) {
+ # bundles cannot specify a minimum version
+ return;
+ } elsif ($obj->isa("CPAN::Distribution")) {
+ if (my $prereq_pm = $obj->prereq_pm) {
+ for my $k (keys %$prereq_pm) {
+ if (my $want_version = $prereq_pm->{$k}{$self->id}) {
+ if (CPAN::Version->vcmp($have_version,$want_version) >= 0) {
+ $self->{incommandcolor} = $color;
+ return;
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ } else {
+ $self->{incommandcolor} = $color; # set me before recursion,
+ # so we can break it
+ }
+ if ($depth>=$CPAN::MAX_RECURSION){
$CPAN::Frontend->mydie(CPAN::Exception::RecursiveDependency->new($ancestors));
}
# warn "color_cmd_tmps $depth $color " . $self->id; # sleep 1;
if ( my $dist = CPAN::Shell->expand("Distribution", $self->cpan_file) ) {
$dist->color_cmd_tmps($depth+1,$color,[@$ancestors, $self->id]);
}
- if ($color==0) {
- delete $self->{badtestcnt};
- }
+ # unreached code?
+ # if ($color==0) {
+ # delete $self->{badtestcnt};
+ # }
$self->{incommandcolor} = $color;
}
sub dslip_status {
my($self) = @_;
my($stat);
+ # development status
@{$stat->{D}}{qw,i c a b R M S,} = qw,idea
pre-alpha alpha beta released
mature standard,;
+ # support level
@{$stat->{S}}{qw,m d u n a,} = qw,mailing-list
developer comp.lang.perl.*
none abandoned,;
+ # language
@{$stat->{L}}{qw,p c + o h,} = qw,perl C C++ other hybrid,;
+ # interface
@{$stat->{I}}{qw,f r O p h n,} = qw,functions
references+ties
object-oriented pragma
hybrid none,;
+ # public licence
@{$stat->{P}}{qw,p g l b a o d r n,} = qw,Standard-Perl
GPL LGPL
BSD Artistic
#-> sub CPAN::Module::force ;
sub force {
my($self) = @_;
- $self->{'force_update'}++;
+ $self->{force_update} = 1;
+}
+
+#-> sub CPAN::Module::fforce ;
+sub fforce {
+ my($self) = @_;
+ $self->{force_update} = 2;
}
sub notest {
}
my $pack = $CPAN::META->instance('CPAN::Distribution',$cpan_file);
$pack->called_for($self->id);
- $pack->force($meth) if exists $self->{'force_update'};
+ if (exists $self->{force_update}){
+ if ($self->{force_update} == 2) {
+ $pack->fforce($meth);
+ } else {
+ $pack->force($meth);
+ }
+ }
$pack->notest($meth) if exists $self->{'notest'};
$pack->{reqtype} ||= "";
exists $pack->{install}
&&
(
- $pack->{install}->can("failed") ?
+ UNIVERSAL::can($pack->{install},"failed") ?
$pack->{install}->failed :
$pack->{install} =~ /^NO/
)
$pack->$meth();
};
my $err = $@;
- $pack->unforce if $pack->can("unforce") && exists $self->{'force_update'};
+ $pack->unforce if $pack->can("unforce") && exists $self->{force_update};
$pack->unnotest if $pack->can("unnotest") && exists $self->{'notest'};
- delete $self->{'force_update'};
+ delete $self->{force_update};
delete $self->{'notest'};
if ($err) {
die $err;
#-> sub CPAN::Module::test ;
sub test {
my $self = shift;
- $self->{badtestcnt} ||= 0;
+ # $self->{badtestcnt} ||= 0;
$self->rematein('test',@_);
}
#-> sub CPAN::Module::uptodate ;
my($doit) = 0;
if ($self->uptodate
&&
- not exists $self->{'force_update'}
+ not exists $self->{force_update}
) {
$CPAN::Frontend->myprint(sprintf("%s is up to date (%s).\n",
$self->id,
#-> sub CPAN::Module::inst_file ;
sub inst_file {
my($self) = @_;
+ $self->_file_in_path([@INC]);
+}
+
+#-> sub CPAN::Module::available_file ;
+sub available_file {
+ my($self) = @_;
+ my $sep = $Config::Config{path_sep};
+ my $perllib = $ENV{PERL5LIB};
+ $perllib = $ENV{PERLLIB} unless defined $perllib;
+ my @perllib = split(/$sep/,$perllib) if defined $perllib;
+ $self->_file_in_path([@perllib,@INC]);
+}
+
+#-> sub CPAN::Module::file_in_path ;
+sub _file_in_path {
+ my($self,$path) = @_;
my($dir,@packpath);
@packpath = split /::/, $self->{ID};
$packpath[-1] .= ".pm";
if (@packpath == 1 && $packpath[0] eq "readline.pm") {
unshift @packpath, "Term", "ReadLine"; # historical reasons
}
- foreach $dir (@INC) {
+ foreach $dir (@$path) {
my $pmfile = File::Spec->catfile($dir,@packpath);
if (-f $pmfile){
return $pmfile;
sub inst_version {
my($self) = @_;
my $parsefile = $self->inst_file or return;
- local($^W) = 0 if $] < 5.00303 && $ExtUtils::MakeMaker::VERSION < 5.38;
- my $have;
+ my $have = $self->parse_version($parsefile);
+ $have;
+}
+
+#-> sub CPAN::Module::inst_version ;
+sub available_version {
+ my($self) = @_;
+ my $parsefile = $self->available_file or return;
+ my $have = $self->parse_version($parsefile);
+ $have;
+}
- $have = MM->parse_version($parsefile) || "undef";
+#-> sub CPAN::Module::parse_version ;
+sub parse_version {
+ my($self,$parsefile) = @_;
+ my $have = MM->parse_version($parsefile);
+ $have = "undef" unless defined $have && length $have;
$have =~ s/^ //; # since the %vd hack these two lines here are needed
$have =~ s/ $//; # trailing whitespace happens all the time
- # My thoughts about why %vd processing should happen here
-
- # Alt1 maintain it as string with leading v:
- # read index files do nothing
- # compare it use utility for compare
- # print it do nothing
-
- # Alt2 maintain it as what it is
- # read index files convert
- # compare it use utility because there's still a ">" vs "gt" issue
- # print it use CPAN::Version for print
-
- # Seems cleaner to hold it in memory as a string starting with a "v"
-
- # If the author of this module made a mistake and wrote a quoted
- # "v1.13" instead of v1.13, we simply leave it at that with the
- # effect that *we* will treat it like a v-tring while the rest of
- # perl won't. Seems sensible when we consider that any action we
- # could take now would just add complexity.
-
$have = CPAN::Version->readable($have);
$have =~ s/\s*//g; # stringify to float around floating point issues
Interactive mode:
- perl -MCPAN -e shell;
+ perl -MCPAN -e shell
+
+--or--
-Batch mode:
+ cpan
- use CPAN;
+Basic commands:
# Modules:
$do = CPAN::Shell->expand("Distribution",
$distro); # same thing
-=head1 STATUS
-
-This module and its competitor, the CPANPLUS module, are both much
-cooler than the other.
-
-=head1 COMPATIBILITY
-
-CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted
-newer versions. It is getting more and more difficult to get the
-minimal prerequisites working on older perls. It is close to
-impossible to get the whole Bundle::CPAN working there. If you're in
-the position to have only these old versions, be advised that CPAN is
-designed to work fine without the Bundle::CPAN installed.
-
-To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
-compatible with ancient perls and that File::Temp is listed as a
-prerequisite but CPAN has reasonable workarounds if it is missing.
-
=head1 DESCRIPTION
-The CPAN module is designed to automate the make and install of perl
-modules and extensions. It includes some primitive searching
-capabilities and knows how to use Net::FTP or LWP (or some external
-download clients) to fetch the raw data from the net.
+The CPAN module automates or at least simplifies the make and install
+of perl modules and extensions. It includes some primitive searching
+capabilities and knows how to use Net::FTP or LWP or some external
+download clients to fetch the distributions from the net.
-Modules are fetched from one or more of the mirrored CPAN
-(Comprehensive Perl Archive Network) sites and unpacked in a dedicated
-directory.
+These are fetched from one or more of the mirrored CPAN (Comprehensive
+Perl Archive Network) sites and unpacked in a dedicated directory.
The CPAN module also supports the concept of named and versioned
I<bundles> of modules. Bundles simplify the handling of sets of
related modules. See Bundles below.
-The package contains a session manager and a cache manager. There is
-no status retained between sessions. The session manager keeps track
-of what has been fetched, built and installed in the current
-session. The cache manager keeps track of the disk space occupied by
-the make processes and deletes excess space according to a simple FIFO
-mechanism.
+The package contains a session manager and a cache manager. The
+session manager keeps track of what has been fetched, built and
+installed in the current session. The cache manager keeps track of the
+disk space occupied by the make processes and deletes excess space
+according to a simple FIFO mechanism.
All methods provided are accessible in a programmer style and in an
interactive shell style.
perl -MCPAN -e shell
-which puts you into a readline interface. You will have the most fun if
-you install Term::ReadKey and Term::ReadLine to enjoy both history and
-command completion.
+or
+
+ cpan
-Once you are on the command line, type 'h' and the rest should be
-self-explanatory.
+which puts you into a readline interface. If C<Term::ReadKey> and
+either C<Term::ReadLine::Perl> or C<Term::ReadLine::Gnu> are installed
+it supports both history and command completion.
+
+Once you are on the command line, type C<h> to get a one page help
+screen and the rest should be self-explanatory.
The function call C<shell> takes two optional arguments, one is the
prompt, the second is the default initial command line (the latter
more than one, we display each object with the terse method
C<as_glimpse>.
-=item make, test, install, clean modules or distributions
+=item C<get>, C<make>, C<test>, C<install>, C<clean> modules or distributions
These commands take any number of arguments and investigate what is
necessary to perform the action. If the argument is a distribution
the module's META.yml or Makefile.PL (this behavior is controlled by
the configuration parameter C<prerequisites_policy>.)
+C<get> downloads a distribution file and untars or unzips it, C<make>
+builds it, C<test> runs the test suite, and C<install> installs it.
+
Any C<make> or C<test> are run unconditionally. An
install <distribution_file>
CPAN also keeps track of what it has done within the current session
and doesn't try to build a package a second time regardless if it
-succeeded or not. The C<force> pragma may precede another command
-(currently: C<make>, C<test>, or C<install>) and executes the
-command from scratch and tries to continue in case of some errors.
+succeeded or not. It does not repeat a test run if the test
+has been run successfully before. Same for install runs.
-Example:
-
- cpan> install OpenGL
- OpenGL is up to date.
- cpan> force install OpenGL
- Running make
- OpenGL-0.4/
- OpenGL-0.4/COPYRIGHT
- [...]
+The C<force> pragma may precede another command (currently: C<get>,
+C<make>, C<test>, or C<install>) and executes the command from scratch
+and tries to continue in case of some errors. See the section below on
+the C<force> and the C<fforce> pragma.
-The C<notest> pragma may be set to skip the test part in the build
+The C<notest> pragma may be used to skip the test part in the build
process.
Example:
being executed within the distribution file's working directory.
-=item get, readme, perldoc, look module or distribution
+=item C<readme>, C<perldoc>, C<look> module or distribution
-C<get> downloads a distribution file without further action. C<readme>
-displays the README file of the associated distribution. C<Look> gets
-and untars (if not yet done) the distribution file, changes to the
-appropriate directory and opens a subshell process in that directory.
-C<perldoc> displays the pod documentation of the module in html or
-plain text format.
+C<readme> displays the README file of the associated distribution.
+C<Look> gets and untars (if not yet done) the distribution file,
+changes to the appropriate directory and opens a subshell process in
+that directory. C<perldoc> displays the pod documentation of the
+module in html or plain text format.
-=item ls author
+=item C<ls> author
-=item ls globbing_expression
+=item C<ls> globbing_expression
The first form lists all distribution files in and below an author's
CPAN directory as they are stored in the CHECKUMS files distributed on
example FOO/* will not list FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be
regarded as a bug and may be changed in future versions.
-=item failed
+=item C<failed>
The C<failed> command reports all distributions that failed on one of
C<make>, C<test> or C<install> for some reason in the currently
running shell session.
+=item Persistence between sessions
+
+If the C<YAML> or the c<YAML::Syck> module is installed a record of
+the internal state of all modules is written to disk after each step.
+The files contain a signature of the currently running perl version
+for later perusal.
+
+If the configurations variable C<build_dir_reuse> is set to a true
+value, then CPAN.pm reads the collected YAML files. If the stored
+signature matches the currently running perl the stored state is
+loaded into memory such that effectively persistence between sessions
+is established.
+
+=item The C<force> and the C<fforce> pragma
+
+To speed things up in complex installation scenarios, CPAN.pm keeps
+track of what it has already done and refuses to do some things a
+second time. A C<get>, a C<make>, and an C<install> are not repeated.
+A C<test> is only repeated if the previous test was unsuccessful. The
+diagnostic message when CPAN.pm refuses to do something a second time
+is one of I<Has already been >C<unwrapped|made|tested successfully> or
+something similar. Another situation where CPAN refuses to act is an
+C<install> if the according C<test> was not successful.
+
+In all these cases, the user can override the goatish behaviour by
+prepending the command with the word force, for example:
+
+ cpan> force get Foo
+ cpan> force make AUTHOR/Bar-3.14.tar.gz
+ cpan> force test Baz
+ cpan> force install Acme::Meta
+
+Each I<forced> command is executed with the according part of its
+memory erased.
+
+The C<fforce> pragma is a variant that emulates a C<force get> which
+erases the entire memory followed by the action specified, effectively
+restarting the whole get/make/test/install procedure from scratch.
+
=item Lockfile
-Interactive sessions maintain a lockfile, per default C<~/.cpan/.lock>
-(but the directory can be configured via the C<cpan_home> config
-variable). The shell is a bit picky if you try to start another CPAN
-session. It dies immediately if there is a lockfile and the lock seems
-to belong to a running process. In case you want to run a second shell
-session, it is probably safest to maintain another directory, say
-C<~/.cpan-for-X/> and a C<~/.cpan-for-X/CPAN/MyConfig.pm> that
-contains the configuration options. Then you can start the second
-shell with
+Interactive sessions maintain a lockfile, per default C<~/.cpan/.lock>.
+Batch jobs can run without a lockfile and do not disturb each other.
- perl -I ~/.cpan-for-X -MCPAN::MyConfig -MCPAN -e shell
+The shell offers to run in I<degraded mode> when another process is
+holding the lockfile. This is an experimental feature that is not yet
+tested very well. This second shell then does not write the history
+file, does not use the metadata file and has a different prompt.
=item Signals
=head2 hosts
+Note: this feature is still in alpha state and may change in future
+versions of CPAN.pm
+
This commands provides a statistical overview over recent download
activities. The data for this is collected in the YAML file
C<FTPstats.yml> in your C<cpan_home> directory. If no YAML module is
=head2 Integrating local directories
+Note: this feature is still in alpha state and may change in future
+versions of CPAN.pm
+
Distribution objects are normally distributions from the CPAN, but
-there is a slightly degenerate case for Distribution objects, too,
-normally only needed by developers. If a distribution object ends with
-a dot or is a dot by itself, then it represents a local directory and
-all actions such as C<make>, C<test>, and C<install> are applied
+there is a slightly degenerate case for Distribution objects, too, of
+projects held on the local disk. These distribution objects have the
+same name as the local directory and end with a dot. A dot by itself
+is also allowed for the current directory at the time CPAN.pm was
+used. All actions such as C<make>, C<test>, and C<install> are applied
directly to that directory. This gives the command C<cpan .> an
interesting touch: while the normal mantra of installing a CPAN module
without CPAN.pm is one of
installation of the module in the current directory, be it a CPAN
module or not.
-=head1 PROGRAMMER'S INTERFACE
+The typical usage case is for private modules or working copies of
+projects from remote repositories on the local disk.
-If you do not enter the shell, the available shell commands are both
-available as methods (C<CPAN::Shell-E<gt>install(...)>) and as
-functions in the calling package (C<install(...)>). Before calling low-level
-commands it makes sense to initialize components of CPAN you need, e.g.:
+=head1 CONFIGURATION
- CPAN::HandleConfig->load;
- CPAN::Shell::setup_output;
- CPAN::Index->reload;
+When the CPAN module is used for the first time, a configuration
+dialog tries to determine a couple of site specific options. The
+result of the dialog is stored in a hash reference C< $CPAN::Config >
+in a file CPAN/Config.pm.
-High-level commands do such initializations automatically.
+The default values defined in the CPAN/Config.pm file can be
+overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
+best placed in $HOME/.cpan/CPAN/MyConfig.pm, because $HOME/.cpan is
+added to the search path of the CPAN module before the use() or
+require() statements. The mkmyconfig command writes this file for you.
-There's currently only one class that has a stable interface -
-CPAN::Shell. All commands that are available in the CPAN shell are
-methods of the class CPAN::Shell. Each of the commands that produce
-listings of modules (C<r>, C<autobundle>, C<u>) also return a list of
-the IDs of all modules within the list.
+The C<o conf> command has various bells and whistles:
-=over 2
+=over
-=item expand($type,@things)
+=item completion support
-The IDs of all objects available within a program are strings that can
-be expanded to the corresponding real objects with the
-C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a
-list of CPAN::Module objects according to the C<@things> arguments
-given. In scalar context it only returns the first element of the
-list.
+If you have a ReadLine module installed, you can hit TAB at any point
+of the commandline and C<o conf> will offer you completion for the
+built-in subcommands and/or config variable names.
-=item expandany(@things)
+=item displaying some help: o conf help
-Like expand, but returns objects of the appropriate type, i.e.
-CPAN::Bundle objects for bundles, CPAN::Module objects for modules and
-CPAN::Distribution objects for distributions. Note: it does not expand
-to CPAN::Author objects.
+Displays a short help
-=item Programming Examples
+=item displaying current values: o conf [KEY]
-This enables the programmer to do operations that combine
-functionalities that are available in the shell.
+Displays the current value(s) for this config variable. Without KEY
+displays all subcommands and config variables.
- # install everything that is outdated on my disk:
- perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
+Example:
- # install my favorite programs if necessary:
- for $mod (qw(Net::FTP Digest::SHA Data::Dumper)){
- CPAN::Shell->install($mod);
- }
+ o conf shell
- # list all modules on my disk that have no VERSION number
- for $mod (CPAN::Shell->expand("Module","/./")){
- next unless $mod->inst_file;
- # MakeMaker convention for undefined $VERSION:
- next unless $mod->inst_version eq "undef";
- print "No VERSION in ", $mod->id, "\n";
- }
+=item changing of scalar values: o conf KEY VALUE
- # find out which distribution on CPAN contains a module:
- print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
+Sets the config variable KEY to VALUE. The empty string can be
+specified as usual in shells, with C<''> or C<"">
-Or if you want to write a cronjob to watch The CPAN, you could list
-all modules that need updating. First a quick and dirty way:
+Example:
- perl -e 'use CPAN; CPAN::Shell->r;'
+ o conf wget /usr/bin/wget
-If you don't want to get any output in the case that all modules are
-up to date, you can parse the output of above command for the regular
-expression //modules are up to date// and decide to mail the output
-only if it doesn't match. Ick?
+=item changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
-If you prefer to do it more in a programmer style in one single
-process, maybe something like this suits you better:
+If a config variable name ends with C<list>, it is a list. C<o conf
+KEY shift> removes the first element of the list, C<o conf KEY pop>
+removes the last element of the list. C<o conf KEYS unshift LIST>
+prepends a list of values to the list, C<o conf KEYS push LIST>
+appends a list of valued to the list.
- # list all modules on my disk that have newer versions on CPAN
- for $mod (CPAN::Shell->expand("Module","/./")){
- next unless $mod->inst_file;
- next if $mod->uptodate;
- printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
- $mod->id, $mod->inst_version, $mod->cpan_version;
- }
+Likewise, C<o conf KEY splice LIST> passes the LIST to the according
+splice command.
-If that gives you too much output every day, you maybe only want to
-watch for three modules. You can write
+Finally, any other list of arguments is taken as a new list value for
+the KEY variable discarding the previous value.
- for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")){
+Examples:
-as the first line instead. Or you can combine some of the above
-tricks:
+ o conf urllist unshift http://cpan.dev.local/CPAN
+ o conf urllist splice 3 1
+ o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
- # watch only for a new mod_perl module
- $mod = CPAN::Shell->expand("Module","mod_perl");
- exit if $mod->uptodate;
- # new mod_perl arrived, let me know all update recommendations
- CPAN::Shell->r;
+=item reverting to saved: o conf defaults
-=back
+Reverts all config variables to the state in the saved config file.
-=head2 Methods in the other Classes
+=item saving the config: o conf commit
-The programming interface for the classes CPAN::Module,
-CPAN::Distribution, CPAN::Bundle, and CPAN::Author is still considered
-beta and partially even alpha. In the following paragraphs only those
-methods are documented that have proven useful over a longer time and
-thus are unlikely to change.
+Saves all config variables to the current config file (CPAN/Config.pm
+or CPAN/MyConfig.pm that was loaded at start).
-=over 4
+=back
-=item CPAN::Author::as_glimpse()
+The configuration dialog can be started any time later again by
+issuing the command C< o conf init > in the CPAN shell. A subset of
+the configuration dialog can be run by issuing C<o conf init WORD>
+where WORD is any valid config variable or a regular expression.
-Returns a one-line description of the author
+=head2 Config Variables
-=item CPAN::Author::as_string()
+Currently the following keys in the hash reference $CPAN::Config are
+defined:
-Returns a multi-line description of the author
+ applypatch path to external prg
+ auto_commit commit all changes to config variables to disk
+ build_cache size of cache for directories to build modules
+ build_dir locally accessible directory to build modules
+ build_dir_reuse boolean if distros in build_dir are persistent
+ build_requires_install_policy
+ to install or not to install when a module is
+ only needed for building. yes|no|ask/yes|ask/no
+ bzip2 path to external prg
+ cache_metadata use serializer to cache metadata
+ commands_quote prefered character to use for quoting external
+ commands when running them. Defaults to double
+ quote on Windows, single tick everywhere else;
+ can be set to space to disable quoting
+ check_sigs if signatures should be verified
+ colorize_debug Term::ANSIColor attributes for debugging output
+ colorize_output boolean if Term::ANSIColor should colorize output
+ colorize_print Term::ANSIColor attributes for normal output
+ colorize_warn Term::ANSIColor attributes for warnings
+ commandnumber_in_prompt
+ boolean if you want to see current command number
+ cpan_home local directory reserved for this package
+ curl path to external prg
+ dontload_hash DEPRECATED
+ dontload_list arrayref: modules in the list will not be
+ loaded by the CPAN::has_inst() routine
+ ftp path to external prg
+ ftp_passive if set, the envariable FTP_PASSIVE is set for downloads
+ ftp_proxy proxy host for ftp requests
+ getcwd see below
+ gpg path to external prg
+ gzip location of external program gzip
+ histfile file to maintain history between sessions
+ histsize maximum number of lines to keep in histfile
+ http_proxy proxy host for http requests
+ inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
+ after this many seconds inactivity. Set to 0 to
+ never break.
+ index_expire after this many days refetch index files
+ inhibit_startup_message
+ if true, does not print the startup message
+ keep_source_where directory in which to keep the source (if we do)
+ lynx path to external prg
+ make location of external make program
+ make_arg arguments that should always be passed to 'make'
+ make_install_make_command
+ the make command for running 'make install', for
+ example 'sudo make'
+ make_install_arg same as make_arg for 'make install'
+ makepl_arg arguments passed to 'perl Makefile.PL'
+ mbuild_arg arguments passed to './Build'
+ mbuild_install_arg arguments passed to './Build install'
+ mbuild_install_build_command
+ command to use instead of './Build' when we are
+ in the install stage, for example 'sudo ./Build'
+ mbuildpl_arg arguments passed to 'perl Build.PL'
+ ncftp path to external prg
+ ncftpget path to external prg
+ no_proxy don't proxy to these hosts/domains (comma separated list)
+ pager location of external program more (or any pager)
+ password your password if you CPAN server wants one
+ patch path to external prg
+ prefer_installer legal values are MB and EUMM: if a module comes
+ with both a Makefile.PL and a Build.PL, use the
+ former (EUMM) or the latter (MB); if the module
+ comes with only one of the two, that one will be
+ used in any case
+ prerequisites_policy
+ what to do if you are missing module prerequisites
+ ('follow' automatically, 'ask' me, or 'ignore')
+ prefs_dir local directory to store per-distro build options
+ proxy_user username for accessing an authenticating proxy
+ proxy_pass password for accessing an authenticating proxy
+ randomize_urllist add some randomness to the sequence of the urllist
+ scan_cache controls scanning of cache ('atstart' or 'never')
+ shell your favorite shell
+ show_upload_date boolean if commands should try to determine upload date
+ tar location of external program tar
+ term_is_latin if true internal UTF-8 is translated to ISO-8859-1
+ (and nonsense for characters outside latin range)
+ term_ornaments boolean to turn ReadLine ornamenting on/off
+ test_report email test reports (if CPAN::Reporter is installed)
+ unzip location of external program unzip
+ urllist arrayref to nearby CPAN sites (or equivalent locations)
+ use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
+ username your username if you CPAN server wants one
+ wait_list arrayref to a wait server to try (See CPAN::WAIT)
+ wget path to external prg
+ yaml_module which module to use to read/write YAML files
-=item CPAN::Author::email()
+You can set and query each of these options interactively in the cpan
+shell with the C<o conf> or the C<o conf init> command as specified below.
-Returns the author's email address
+=over 2
-=item CPAN::Author::fullname()
+=item C<o conf E<lt>scalar optionE<gt>>
-Returns the author's name
+prints the current value of the I<scalar option>
-=item CPAN::Author::name()
+=item C<o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>>
-An alias for fullname
+Sets the value of the I<scalar option> to I<value>
-=item CPAN::Bundle::as_glimpse()
+=item C<o conf E<lt>list optionE<gt>>
-Returns a one-line description of the bundle
+prints the current value of the I<list option> in MakeMaker's
+neatvalue format.
-=item CPAN::Bundle::as_string()
+=item C<o conf E<lt>list optionE<gt> [shift|pop]>
-Returns a multi-line description of the bundle
+shifts or pops the array in the I<list option> variable
-=item CPAN::Bundle::clean()
+=item C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>>
-Recursively runs the C<clean> method on all items contained in the bundle.
+works like the corresponding perl commands.
-=item CPAN::Bundle::contains()
+=item interactive editing: o conf init [MATCH|LIST]
-Returns a list of objects' IDs contained in a bundle. The associated
-objects may be bundles, modules or distributions.
+Runs an interactive configuration dialog for matching variables.
+Without argument runs the dialog over all supported config variables.
+To specify a MATCH the argument must be enclosed by slashes.
-=item CPAN::Bundle::force($method,@args)
+Examples:
-Forces CPAN to perform a task that normally would have failed. Force
-takes as arguments a method name to be called and any number of
-additional arguments that should be passed to the called method. The
-internals of the object get the needed changes so that CPAN.pm does
-not refuse to take the action. The C<force> is passed recursively to
-all contained objects.
+ o conf init ftp_passive ftp_proxy
+ o conf init /color/
-=item CPAN::Bundle::get()
+Note: this method of setting config variables often provides more
+explanation about the functioning of a variable than the manpage.
-Recursively runs the C<get> method on all items contained in the bundle
+=back
-=item CPAN::Bundle::inst_file()
+=head2 CPAN::anycwd($path): Note on config variable getcwd
-Returns the highest installed version of the bundle in either @INC or
-C<$CPAN::Config->{cpan_home}>. Note that this is different from
-CPAN::Module::inst_file.
+CPAN.pm changes the current working directory often and needs to
+determine its own current working directory. Per default it uses
+Cwd::cwd but if this doesn't work on your system for some reason,
+alternatives can be configured according to the following table:
-=item CPAN::Bundle::inst_version()
+=over 4
-Like CPAN::Bundle::inst_file, but returns the $VERSION
+=item cwd
-=item CPAN::Bundle::uptodate()
+Calls Cwd::cwd
-Returns 1 if the bundle itself and all its members are uptodate.
+=item getcwd
-=item CPAN::Bundle::install()
+Calls Cwd::getcwd
-Recursively runs the C<install> method on all items contained in the bundle
+=item fastcwd
-=item CPAN::Bundle::make()
+Calls Cwd::fastcwd
-Recursively runs the C<make> method on all items contained in the bundle
+=item backtickcwd
-=item CPAN::Bundle::readme()
+Calls the external command cwd.
-Recursively runs the C<readme> method on all items contained in the bundle
+=back
-=item CPAN::Bundle::test()
+=head2 Note on the format of the urllist parameter
-Recursively runs the C<test> method on all items contained in the bundle
+urllist parameters are URLs according to RFC 1738. We do a little
+guessing if your URL is not compliant, but if you have problems with
+C<file> URLs, please try the correct format. Either:
-=item CPAN::Distribution::as_glimpse()
+ file://localhost/whatever/ftp/pub/CPAN/
-Returns a one-line description of the distribution
+or
-=item CPAN::Distribution::as_string()
+ file:///home/ftp/pub/CPAN/
-Returns a multi-line description of the distribution
+=head2 The urllist parameter has CD-ROM support
-=item CPAN::Distribution::author
+The C<urllist> parameter of the configuration table contains a list of
+URLs that are to be used for downloading. If the list contains any
+C<file> URLs, CPAN always tries to get files from there first. This
+feature is disabled for index files. So the recommendation for the
+owner of a CD-ROM with CPAN contents is: include your local, possibly
+outdated CD-ROM as a C<file> URL at the end of urllist, e.g.
-Returns the CPAN::Author object of the maintainer who uploaded this
-distribution
+ o conf urllist push file://localhost/CDROM/CPAN
-=item CPAN::Distribution::clean()
+CPAN.pm will then fetch the index files from one of the CPAN sites
+that come at the beginning of urllist. It will later check for each
+module if there is a local copy of the most recent version.
-Changes to the directory where the distribution has been unpacked and
-runs C<make clean> there.
+Another peculiarity of urllist is that the site that we could
+successfully fetch the last file from automatically gets a preference
+token and is tried as the first site for the next request. So if you
+add a new site at runtime it may happen that the previously preferred
+site will be tried another time. This means that if you want to disallow
+a site for the next transfer, it must be explicitly removed from
+urllist.
-=item CPAN::Distribution::containsmods()
+=head2 Maintaining the urllist parameter
-Returns a list of IDs of modules contained in a distribution file.
-Only works for distributions listed in the 02packages.details.txt.gz
-file. This typically means that only the most recent version of a
-distribution is covered.
+If you have YAML.pm (or some other YAML module configured in
+C<yaml_module>) installed, CPAN.pm collects a few statistical data
+about recent downloads. You can view the statistics with the C<hosts>
+command or inspect them directly by looking into the C<FTPstats.yml>
+file in your C<cpan_home> directory.
-=item CPAN::Distribution::cvs_import()
+To get some interesting statistics it is recommended to set the
+C<randomize_urllist> parameter that introduces some amount of
+randomness into the URL selection.
-Changes to the directory where the distribution has been unpacked and
-runs something like
+=head2 The C<requires> and C<build_requires> dependency declarations
- cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
+Since CPAN.pm version 1.88_51 modules declared as C<build_requires> by
+a distribution are treated differently depending on the config
+variable C<build_requires_install_policy>. By setting
+C<build_requires_install_policy> to C<no> such a module is not being
+installed. It is only built and tested and then kept in the list of
+tested but uninstalled modules. As such it is available during the
+build of the dependent module by integrating the path to the
+C<blib/arch> and C<blib/lib> directories in the environment variable
+PERL5LIB. If C<build_requires_install_policy> is set ti C<yes>, then
+both modules declared as C<requires> and those declared as
+C<build_requires> are treated alike. By setting to C<ask/yes> or
+C<ask/no>, CPAN.pm asks the user and sets the default accordingly.
-there.
+=head2 Configuration for individual distributions (I<Distroprefs>)
-=item CPAN::Distribution::dir()
+(B<Note:> This feature has been introduced in CPAN.pm 1.8854 and is
+still considered beta quality)
-Returns the directory into which this distribution has been unpacked.
+Distributions on the CPAN usually behave according to what we call the
+CPAN mantra. Or since the event of Module::Build we should talk about
+two mantras:
-=item CPAN::Distribution::force($method,@args)
+ perl Makefile.PL perl Build.PL
+ make ./Build
+ make test ./Build test
+ make install ./Build install
-Forces CPAN to perform a task that normally would have failed. Force
-takes as arguments a method name to be called and any number of
-additional arguments that should be passed to the called method. The
-internals of the object get the needed changes so that CPAN.pm does
-not refuse to take the action.
+But some modules cannot be built with this mantra. They try to get
+some extra data from the user via the environment, extra arguments or
+interactively thus disturbing the installation of large bundles like
+Phalanx100 or modules with many dependencies like Plagger.
-=item CPAN::Distribution::get()
+The distroprefs system of C<CPAN.pm> addresses this problem by
+allowing the user to specify extra informations and recipes in YAML
+files to either
-Downloads the distribution from CPAN and unpacks it. Does nothing if
-the distribution has already been downloaded and unpacked within the
-current session.
+=over
-=item CPAN::Distribution::install()
+=item
-Changes to the directory where the distribution has been unpacked and
-runs the external command C<make install> there. If C<make> has not
-yet been run, it will be run first. A C<make test> will be issued in
-any case and if this fails, the install will be canceled. The
-cancellation can be avoided by letting C<force> run the C<install> for
-you.
+pass additional arguments to one of the four commands,
-This install method has only the power to install the distribution if
-there are no dependencies in the way. To install an object and all of
-its dependencies, use CPAN::Shell->install.
+=item
-Note that install() gives no meaningful return value. See uptodate().
+set environment variables
-=item CPAN::Distribution::isa_perl()
+=item
-Returns 1 if this distribution file seems to be a perl distribution.
-Normally this is derived from the file name only, but the index from
-CPAN can contain a hint to achieve a return value of true for other
-filenames too.
+instantiate an Expect object that reads from the console, waits for
+some regular expressions and enters some answers
-=item CPAN::Distribution::look()
+=item
-Changes to the directory where the distribution has been unpacked and
-opens a subshell there. Exiting the subshell returns.
+temporarily override assorted C<CPAN.pm> configuration variables
-=item CPAN::Distribution::make()
+=item
-First runs the C<get> method to make sure the distribution is
-downloaded and unpacked. Changes to the directory where the
-distribution has been unpacked and runs the external commands C<perl
-Makefile.PL> or C<perl Build.PL> and C<make> there.
+disable the installation of an object altogether
-=item CPAN::Distribution::perldoc()
+=back
-Downloads the pod documentation of the file associated with a
-distribution (in html format) and runs it through the external
-command lynx specified in C<$CPAN::Config->{lynx}>. If lynx
-isn't available, it converts it to plain text with external
-command html2text and runs it through the pager specified
-in C<$CPAN::Config->{pager}>
+See the YAML and Data::Dumper files that come with the C<CPAN.pm>
+distribution in the C<distroprefs/> directory for examples.
-=item CPAN::Distribution::prefs()
+=head2 Filenames
-Returns the hash reference from the first matching YAML file that the
-user has deposited in the C<prefs_dir/> directory. The first
-succeeding match wins. The files in the C<prefs_dir/> are processed
-alphabetically and the canonical distroname (e.g.
-AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions
-stored in the $root->{match}{distribution} attribute value.
-Additionally all module names contained in a distribution are matched
-agains the regular expressions in the $root->{match}{module} attribute
-value. The two match values are ANDed together. Each of the two
-attributes are optional.
+The YAML files themselves must have the C<.yml> extension, all other
+files are ignored (for two exceptions see I<Fallback Data::Dumper and
+Storable> below). The containing directory can be specified in
+C<CPAN.pm> in the C<prefs_dir> config variable. Try C<o conf init
+prefs_dir> in the CPAN shell to set and activate the distroprefs
+system.
-=item CPAN::Distribution::prereq_pm()
+Every YAML file may contain arbitrary documents according to the YAML
+specification and every single document is treated as an entity that
+can specify the treatment of a single distribution.
-Returns the hash reference that has been announced by a distribution
-as the merge of the C<requires> element and the C<build_requires>
-element of the META.yml or the C<PREREQ_PM> hash in the
-C<Makefile.PL>. Note: works only after an attempt has been made to
-C<make> the distribution. Returns undef otherwise.
+The names of the files can be picked freely, C<CPAN.pm> always reads
+all files (in alphabetical order) and takes the key C<match> (see
+below in I<Language Specs>) as a hashref containing match criteria
+that determine if the current distribution matches the YAML document
+or not.
-=item CPAN::Distribution::readme()
+=head2 Fallback Data::Dumper and Storable
-Downloads the README file associated with a distribution and runs it
-through the pager specified in C<$CPAN::Config->{pager}>.
+If neither your configured C<yaml_module> nor YAML.pm is installed
+CPAN.pm falls back to using Data::Dumper and Storable and looks for
+files with the extensions C<.dd> or C<.st> in the C<prefs_dir>
+directory. These files are expected to contain one or more hashrefs.
+For Data::Dumper generated files, this is expected to be done with by
+defining C<$VAR1>, C<$VAR2>, etc. The YAML shell would produce these
+with the command
-=item CPAN::Distribution::read_yaml()
+ ysh < somefile.yml > somefile.dd
-Returns the content of the META.yml of this distro as a hashref. Note:
-works only after an attempt has been made to C<make> the distribution.
-Returns undef otherwise. Also returns undef if the content of META.yml
-is dynamic.
+For Storable files the rule is that they must be constructed such that
+C<Storable::retrieve(file)> returns an array reference and the array
+elements represent one distropref object each. The conversion from
+YAML would look like so:
-=item CPAN::Distribution::test()
+ perl -MYAML=LoadFile -MStorable=nstore -e '
+ @y=LoadFile(shift);
+ nstore(\@y, shift)' somefile.yml somefile.st
-Changes to the directory where the distribution has been unpacked and
-runs C<make test> there.
+In bootstrapping situations it is usually sufficient to translate only
+a few YAML files to Data::Dumper for the crucial modules like
+C<YAML::Syck>, C<YAML.pm> and C<Expect.pm>. If you prefer Storable
+over Data::Dumper, remember to pull out a Storable version that writes
+an older format than all the other Storable versions that will need to
+read them.
-=item CPAN::Distribution::uptodate()
+=head2 Blueprint
-Returns 1 if all the modules contained in the distribution are
-uptodate. Relies on containsmods.
+The following example contains all supported keywords and structures
+with the exception of C<eexpect> which can be used instead of
+C<expect>.
-=item CPAN::Index::force_reload()
+ ---
+ comment: "Demo"
+ match:
+ module: "Dancing::Queen"
+ distribution: "^CHACHACHA/Dancing-"
+ perl: "/usr/local/cariba-perl/bin/perl"
+ perlconfig:
+ archname: "freebsd"
+ disabled: 1
+ cpanconfig:
+ make: gmake
+ pl:
+ args:
+ - "--somearg=specialcase"
-Forces a reload of all indices.
+ env: {}
-=item CPAN::Index::reload()
+ expect:
+ - "Which is your favorite fruit"
+ - "apple\n"
-Reloads all indices if they have not been read for more than
-C<$CPAN::Config->{index_expire}> days.
+ make:
+ args:
+ - all
+ - extra-all
-=item CPAN::InfoObj::dump()
+ env: {}
-CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
-inherit this method. It prints the data structure associated with an
-object. Useful for debugging. Note: the data structure is considered
-internal and thus subject to change without notice.
+ expect: []
-=item CPAN::Module::as_glimpse()
+ commendline: "echo SKIPPING make"
-Returns a one-line description of the module in four columns: The
-first column contains the word C<Module>, the second column consists
-of one character: an equals sign if this module is already installed
-and uptodate, a less-than sign if this module is installed but can be
-upgraded, and a space if the module is not installed. The third column
-is the name of the module and the fourth column gives maintainer or
-distribution information.
+ test:
+ args: []
-=item CPAN::Module::as_string()
+ env: {}
-Returns a multi-line description of the module
+ expect: []
-=item CPAN::Module::clean()
+ install:
+ args: []
-Runs a clean on the distribution associated with this module.
+ env:
+ WANT_TO_INSTALL: YES
-=item CPAN::Module::cpan_file()
+ expect:
+ - "Do you really want to install"
+ - "y\n"
-Returns the filename on CPAN that is associated with the module.
+ patches:
+ - "ABCDE/Fedcba-3.14-ABCDE-01.patch"
-=item CPAN::Module::cpan_version()
-Returns the latest version of this module available on CPAN.
+=head2 Language Specs
-=item CPAN::Module::cvs_import()
+Every YAML document represents a single hash reference. The valid keys
+in this hash are as follows:
-Runs a cvs_import on the distribution associated with this module.
+=over
-=item CPAN::Module::description()
+=item comment [scalar]
-Returns a 44 character description of this module. Only available for
-modules listed in The Module List (CPAN/modules/00modlist.long.html
-or 00modlist.long.txt.gz)
+A comment
-=item CPAN::Module::distribution()
+=item cpanconfig [hash]
-Returns the CPAN::Distribution object that contains the current
-version of this module.
+Temporarily override assorted C<CPAN.pm> configuration variables.
-=item CPAN::Module::dslip_status()
+Supported are: C<build_requires_install_policy>, C<check_sigs>,
+C<make>, C<make_install_make_command>, C<prefer_installer>,
+C<test_report>. Please report as a bug when you need another one
+supported.
-Returns a hash reference. The keys of the hash are the letters C<D>,
-C<S>, C<L>, C<I>, and <P>, for development status, support level,
-language, interface and public licence respectively. The data for the
-DSLIP status are collected by pause.perl.org when authors register
-their namespaces. The values of the 5 hash elements are one-character
-words whose meaning is described in the table below. There are also 5
-hash elements C<DV>, C<SV>, C<LV>, C<IV>, and <PV> that carry a more
-verbose value of the 5 status variables.
+=item disabled [boolean]
-Where the 'DSLIP' characters have the following meanings:
+Specifies that this distribution shall not be processed at all.
- D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
- i - Idea, listed to gain consensus or as a placeholder
- c - under construction but pre-alpha (not yet released)
- a/b - Alpha/Beta testing
- R - Released
- M - Mature (no rigorous definition)
- S - Standard, supplied with Perl 5
+=item goto [string]
- S - Support Level:
- m - Mailing-list
- d - Developer
- u - Usenet newsgroup comp.lang.perl.modules
- n - None known, try comp.lang.perl.modules
- a - abandoned; volunteers welcome to take over maintainance
+The canonical name of a delegate distribution that shall be installed
+instead. Useful when a new version, although it tests OK itself,
+breaks something else or a developer release or a fork is already
+uploaded that is better than the last released version.
- L - Language Used:
- p - Perl-only, no compiler needed, should be platform independent
- c - C and perl, a C compiler will be needed
- h - Hybrid, written in perl with optional C code, no compiler needed
- + - C++ and perl, a C++ compiler will be needed
- o - perl and another language other than C or C++
+=item install [hash]
- I - Interface Style
- f - plain Functions, no references used
- h - hybrid, object and function interfaces available
- n - no interface at all (huh?)
- r - some use of unblessed References or ties
- O - Object oriented using blessed references and/or inheritance
+Processing instructions for the C<make install> or C<./Build install>
+phase of the CPAN mantra. See below under I<Processiong Instructions>.
- P - Public License
- p - Standard-Perl: user may choose between GPL and Artistic
- g - GPL: GNU General Public License
- l - LGPL: "GNU Lesser General Public License" (previously known as
- "GNU Library General Public License")
- b - BSD: The BSD License
- a - Artistic license alone
- o - open source: appoved by www.opensource.org
- d - allows distribution without restrictions
- r - restricted distribtion
- n - no license at all
+=item make [hash]
-=item CPAN::Module::force($method,@args)
+Processing instructions for the C<make> or C<./Build> phase of the
+CPAN mantra. See below under I<Processiong Instructions>.
-Forces CPAN to perform a task that normally would have failed. Force
-takes as arguments a method name to be called and any number of
-additional arguments that should be passed to the called method. The
-internals of the object get the needed changes so that CPAN.pm does
-not refuse to take the action.
+=item match [hash]
-=item CPAN::Module::get()
+A hashref with one or more of the keys C<distribution>, C<modules>,
+C<perl>, and C<perlconfig> that specify if a document is targeted at a
+specific CPAN distribution or installation.
-Runs a get on the distribution associated with this module.
+The corresponding values are interpreted as regular expressions. The
+C<distribution> related one will be matched against the canonical
+distribution name, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".
-=item CPAN::Module::inst_file()
+The C<module> related one will be matched against I<all> modules
+contained in the distribution until one module matches.
-Returns the filename of the module found in @INC. The first file found
-is reported just like perl itself stops searching @INC when it finds a
-module.
+The C<perl> related one will be matched against C<$^X>.
-=item CPAN::Module::inst_version()
+The value associated with C<perlconfig> is itself a hashref that is
+matched against corresponding values in the C<%Config::Config> hash
+living in the C< Config.pm > module.
-Returns the version number of the module in readable format.
+If more than one restriction of C<module>, C<distribution>, and
+C<perl> is specified, the results of the separately computed match
+values must all match. If this is the case then the hashref
+represented by the YAML document is returned as the preference
+structure for the current distribution.
-=item CPAN::Module::install()
+=item patches [array]
-Runs an C<install> on the distribution associated with this module.
+An array of patches on CPAN or on the local disk to be applied in
+order via the external patch program. If the value for the C<-p>
+parameter is C<0> or C<1> is determined by reading the patch
+beforehand.
-=item CPAN::Module::look()
+Note: if the C<applypatch> program is installed and C<CPAN::Config>
+knows about it B<and> a patch is written by the C<makepatch> program,
+then C<CPAN.pm> lets C<applypatch> apply the patch. Both C<makepatch>
+and C<applypatch> are available from CPAN in the C<JV/makepatch-*>
+distribution.
-Changes to the directory where the distribution associated with this
-module has been unpacked and opens a subshell there. Exiting the
-subshell returns.
+=item pl [hash]
-=item CPAN::Module::make()
+Processing instructions for the C<perl Makefile.PL> or C<perl
+Build.PL> phase of the CPAN mantra. See below under I<Processiong
+Instructions>.
-Runs a C<make> on the distribution associated with this module.
+=item test [hash]
-=item CPAN::Module::manpage_headline()
+Processing instructions for the C<make test> or C<./Build test> phase
+of the CPAN mantra. See below under I<Processiong Instructions>.
-If module is installed, peeks into the module's manpage, reads the
-headline and returns it. Moreover, if the module has been downloaded
-within this session, does the equivalent on the downloaded module even
-if it is not installed.
+=back
-=item CPAN::Module::perldoc()
+=head2 Processing Instructions
-Runs a C<perldoc> on this module.
+=over
-=item CPAN::Module::readme()
+=item args [array]
-Runs a C<readme> on the distribution associated with this module.
+Arguments to be added to the command line
-=item CPAN::Module::test()
+=item commandline
-Runs a C<test> on the distribution associated with this module.
+A full commandline that will be executed as it stands by a system
+call. During the execution the environment variable PERL will is set
+to $^X. If C<commandline> is specified, the content of C<args> is not
+used.
-=item CPAN::Module::uptodate()
+=item eexpect [hash]
-Returns 1 if the module is installed and up-to-date.
+Extended C<expect>. This is a hash reference with three allowed keys,
+C<mode>, C<timeout>, and C<talk>.
-=item CPAN::Module::userid()
+C<mode> may have the values C<deterministic> for the case where all
+questions come in the order written down and C<anyorder> for the case
+where the questions may come in any order. The default mode is
+C<deterministic>.
-Returns the author's ID of the module.
+C<timeout> denotes a timeout in seconds. Floating point timeouts are
+OK. In the case of a C<mode=deterministic> the timeout denotes the
+timeout per question, in the case of C<mode=anyorder> it denotes the
+timeout per byte received from the stream or questions.
-=back
+C<talk> is a reference to an array that contains alternating questions
+and answers. Questions are regular expressions and answers are literal
+strings. The Expect module will then watch the stream coming from the
+execution of the external program (C<perl Makefile.PL>, C<perl
+Build.PL>, C<make>, etc.).
-=head2 Cache Manager
+In the case of C<mode=deterministic> the CPAN.pm will inject the
+according answer as soon as the stream matches the regular expression.
+In the case of C<mode=anyorder> the CPAN.pm will answer a question as
+soon as the timeout is reached for the next byte in the input stream.
+In the latter case it removes the according question/answer pair from
+the array, so if you want to answer the question C<Do you really want
+to do that> several times, then it must be included in the array at
+least as often as you want this answer to be given.
-Currently the cache manager only keeps track of the build directory
-($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
-deletes complete directories below C<build_dir> as soon as the size of
-all directories there gets bigger than $CPAN::Config->{build_cache}
-(in MB). The contents of this cache may be used for later
-re-installations that you intend to do manually, but will never be
-trusted by CPAN itself. This is due to the fact that the user might
-use these directories for building modules on different architectures.
+=item env [hash]
-There is another directory ($CPAN::Config->{keep_source_where}) where
-the original distribution files are kept. This directory is not
-covered by the cache manager and must be controlled by the user. If
-you choose to have the same directory as build_dir and as
-keep_source_where directory, then your sources will be deleted with
-the same fifo mechanism.
+Environment variables to be set during the command
-=head2 Bundles
+=item expect [array]
-A bundle is just a perl module in the namespace Bundle:: that does not
-define any functions or methods. It usually only contains documentation.
+C<< expect: <array> >> is a short notation for
-It starts like a perl module with a package declaration and a $VERSION
-variable. After that the pod section looks like any other pod with the
-only difference being that I<one special pod section> exists starting with
-(verbatim):
+ eexpect:
+ mode: deterministic
+ timeout: 15
+ talk: <array>
- =head1 CONTENTS
+=back
-In this pod section each line obeys the format
+=head2 Schema verification with C<Kwalify>
- Module_Name [Version_String] [- optional text]
+If you have the C<Kwalify> module installed (which is part of the
+Bundle::CPANxxl), then all your distroprefs files are checked for
+syntactical correctness.
-The only required part is the first field, the name of a module
-(e.g. Foo::Bar, ie. I<not> the name of the distribution file). The rest
-of the line is optional. The comment part is delimited by a dash just
-as in the man page header.
+=head2 Example Distroprefs Files
-The distribution of a bundle should follow the same convention as
-other distributions.
+C<CPAN.pm> comes with a collection of example YAML files. Note that these
+are really just examples and should not be used without care because
+they cannot fit everybody's purpose. After all the authors of the
+packages that ask questions had a need to ask, so you should watch
+their questions and adjust the examples to your environment and your
+needs. You have beend warned:-)
-Bundles are treated specially in the CPAN package. If you say 'install
-Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
-the modules in the CONTENTS section of the pod. You can install your
-own Bundles locally by placing a conformant Bundle file somewhere into
-your @INC path. The autobundle() command which is available in the
-shell interface does that for you by including all currently installed
-modules in a snapshot bundle file.
-
-=head1 PREREQUISITES
-
-If you have a local mirror of CPAN and can access all files with
-"file:" URLs, then you only need a perl better than perl5.003 to run
-this module. Otherwise Net::FTP is strongly recommended. LWP may be
-required for non-UNIX systems or if your nearest CPAN site is
-associated with a URL that is not C<ftp:>.
+=head1 PROGRAMMER'S INTERFACE
-If you have neither Net::FTP nor LWP, there is a fallback mechanism
-implemented for an external ftp command or for an external lynx
-command.
+If you do not enter the shell, the available shell commands are both
+available as methods (C<CPAN::Shell-E<gt>install(...)>) and as
+functions in the calling package (C<install(...)>). Before calling low-level
+commands it makes sense to initialize components of CPAN you need, e.g.:
-=head1 UTILITIES
+ CPAN::HandleConfig->load;
+ CPAN::Shell::setup_output;
+ CPAN::Index->reload;
-=head2 Finding packages and VERSION
+High-level commands do such initializations automatically.
-This module presumes that all packages on CPAN
+There's currently only one class that has a stable interface -
+CPAN::Shell. All commands that are available in the CPAN shell are
+methods of the class CPAN::Shell. Each of the commands that produce
+listings of modules (C<r>, C<autobundle>, C<u>) also return a list of
+the IDs of all modules within the list.
=over 2
-=item *
+=item expand($type,@things)
-declare their $VERSION variable in an easy to parse manner. This
-prerequisite can hardly be relaxed because it consumes far too much
-memory to load all packages into the running program just to determine
-the $VERSION variable. Currently all programs that are dealing with
-version use something like this
+The IDs of all objects available within a program are strings that can
+be expanded to the corresponding real objects with the
+C<CPAN::Shell-E<gt>expand("Module",@things)> method. Expand returns a
+list of CPAN::Module objects according to the C<@things> arguments
+given. In scalar context it only returns the first element of the
+list.
- perl -MExtUtils::MakeMaker -le \
- 'print MM->parse_version(shift)' filename
+=item expandany(@things)
-If you are author of a package and wonder if your $VERSION can be
-parsed, please try the above method.
+Like expand, but returns objects of the appropriate type, i.e.
+CPAN::Bundle objects for bundles, CPAN::Module objects for modules and
+CPAN::Distribution objects for distributions. Note: it does not expand
+to CPAN::Author objects.
-=item *
+=item Programming Examples
-come as compressed or gzipped tarfiles or as zip files and contain a
-C<Makefile.PL> or C<Build.PL> (well, we try to handle a bit more, but
-without much enthusiasm).
+This enables the programmer to do operations that combine
+functionalities that are available in the shell.
-=back
+ # install everything that is outdated on my disk:
+ perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
-=head2 Debugging
+ # install my favorite programs if necessary:
+ for $mod (qw(Net::FTP Digest::SHA Data::Dumper)){
+ CPAN::Shell->install($mod);
+ }
-The debugging of this module is a bit complex, because we have
-interferences of the software producing the indices on CPAN, of the
-mirroring process on CPAN, of packaging, of configuration, of
-synchronicity, and of bugs within CPAN.pm.
+ # list all modules on my disk that have no VERSION number
+ for $mod (CPAN::Shell->expand("Module","/./")){
+ next unless $mod->inst_file;
+ # MakeMaker convention for undefined $VERSION:
+ next unless $mod->inst_version eq "undef";
+ print "No VERSION in ", $mod->id, "\n";
+ }
-For debugging the code of CPAN.pm itself in interactive mode some more
-or less useful debugging aid can be turned on for most packages within
-CPAN.pm with one of
+ # find out which distribution on CPAN contains a module:
+ print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file
-=over 2
+Or if you want to write a cronjob to watch The CPAN, you could list
+all modules that need updating. First a quick and dirty way:
-=item o debug package...
+ perl -e 'use CPAN; CPAN::Shell->r;'
-sets debug mode for packages.
+If you don't want to get any output in the case that all modules are
+up to date, you can parse the output of above command for the regular
+expression //modules are up to date// and decide to mail the output
+only if it doesn't match. Ick?
-=item o debug -package...
+If you prefer to do it more in a programmer style in one single
+process, maybe something like this suits you better:
-unsets debug mode for packages.
+ # list all modules on my disk that have newer versions on CPAN
+ for $mod (CPAN::Shell->expand("Module","/./")){
+ next unless $mod->inst_file;
+ next if $mod->uptodate;
+ printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
+ $mod->id, $mod->inst_version, $mod->cpan_version;
+ }
-=item o debug all
+If that gives you too much output every day, you maybe only want to
+watch for three modules. You can write
-turns debugging on for all packages.
+ for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")){
-=item o debug number
+as the first line instead. Or you can combine some of the above
+tricks:
+
+ # watch only for a new mod_perl module
+ $mod = CPAN::Shell->expand("Module","mod_perl");
+ exit if $mod->uptodate;
+ # new mod_perl arrived, let me know all update recommendations
+ CPAN::Shell->r;
=back
-which sets the debugging packages directly. Note that C<o debug 0>
-turns debugging off.
+=head2 Methods in the other Classes
-What seems quite a successful strategy is the combination of C<reload
-cpan> and the debugging switches. Add a new debug statement while
-running in the shell and then issue a C<reload cpan> and see the new
-debugging messages immediately without losing the current context.
+=over 4
-C<o debug> without an argument lists the valid package names and the
-current set of packages in debugging mode. C<o debug> has built-in
-completion support.
+=item CPAN::Author::as_glimpse()
-For debugging of CPAN data there is the C<dump> command which takes
-the same arguments as make/test/install and outputs each object's
-Data::Dumper dump. If an argument looks like a perl variable and
-contains one of C<$>, C<@> or C<%>, it is eval()ed and fed to
-Data::Dumper directly.
+Returns a one-line description of the author
-=head2 Floppy, Zip, Offline Mode
+=item CPAN::Author::as_string()
-CPAN.pm works nicely without network too. If you maintain machines
-that are not networked at all, you should consider working with file:
-URLs. Of course, you have to collect your modules somewhere first. So
-you might use CPAN.pm to put together all you need on a networked
-machine. Then copy the $CPAN::Config->{keep_source_where} (but not
-$CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
-of a personal CPAN. CPAN.pm on the non-networked machines works nicely
-with this floppy. See also below the paragraph about CD-ROM support.
+Returns a multi-line description of the author
-=head2 Basic Utilities for Programmers
+=item CPAN::Author::email()
-=over 2
+Returns the author's email address
-=item has_inst($module)
+=item CPAN::Author::fullname()
-Returns true if the module is installed. See the source for details.
+Returns the author's name
-=item has_usable($module)
+=item CPAN::Author::name()
-Returns true if the module is installed and several and is in a usable
-state. Only useful for a handful of modules that are used internally.
-See the source for details.
+An alias for fullname
-=item instance($module)
+=item CPAN::Bundle::as_glimpse()
-The constructor for all the singletons used to represent modules,
-distributions, authors and bundles. If the object already exists, this
-method returns the object, otherwise it calls the constructor.
+Returns a one-line description of the bundle
-=back
+=item CPAN::Bundle::as_string()
-=head1 CONFIGURATION
+Returns a multi-line description of the bundle
-When the CPAN module is used for the first time, a configuration
-dialog tries to determine a couple of site specific options. The
-result of the dialog is stored in a hash reference C< $CPAN::Config >
-in a file CPAN/Config.pm.
+=item CPAN::Bundle::clean()
-The default values defined in the CPAN/Config.pm file can be
-overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
-best placed in $HOME/.cpan/CPAN/MyConfig.pm, because $HOME/.cpan is
-added to the search path of the CPAN module before the use() or
-require() statements. The mkmyconfig command writes this file for you.
+Recursively runs the C<clean> method on all items contained in the bundle.
-The C<o conf> command has various bells and whistles:
+=item CPAN::Bundle::contains()
-=over
+Returns a list of objects' IDs contained in a bundle. The associated
+objects may be bundles, modules or distributions.
-=item completion support
+=item CPAN::Bundle::force($method,@args)
-If you have a ReadLine module installed, you can hit TAB at any point
-of the commandline and C<o conf> will offer you completion for the
-built-in subcommands and/or config variable names.
+Forces CPAN to perform a task that it normally would have refused to
+do. Force takes as arguments a method name to be called and any number
+of additional arguments that should be passed to the called method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. The C<force> is passed recursively
+to all contained objects. See also the section above on the C<force>
+and the C<fforce> pragma.
-=item displaying some help: o conf help
+=item CPAN::Bundle::get()
-Displays a short help
+Recursively runs the C<get> method on all items contained in the bundle
-=item displaying current values: o conf [KEY]
+=item CPAN::Bundle::inst_file()
-Displays the current value(s) for this config variable. Without KEY
-displays all subcommands and config variables.
+Returns the highest installed version of the bundle in either @INC or
+C<$CPAN::Config->{cpan_home}>. Note that this is different from
+CPAN::Module::inst_file.
-Example:
+=item CPAN::Bundle::inst_version()
- o conf shell
+Like CPAN::Bundle::inst_file, but returns the $VERSION
-=item changing of scalar values: o conf KEY VALUE
+=item CPAN::Bundle::uptodate()
-Sets the config variable KEY to VALUE. The empty string can be
-specified as usual in shells, with C<''> or C<"">
+Returns 1 if the bundle itself and all its members are uptodate.
-Example:
+=item CPAN::Bundle::install()
- o conf wget /usr/bin/wget
+Recursively runs the C<install> method on all items contained in the bundle
-=item changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST
+=item CPAN::Bundle::make()
-If a config variable name ends with C<list>, it is a list. C<o conf
-KEY shift> removes the first element of the list, C<o conf KEY pop>
-removes the last element of the list. C<o conf KEYS unshift LIST>
-prepends a list of values to the list, C<o conf KEYS push LIST>
-appends a list of valued to the list.
+Recursively runs the C<make> method on all items contained in the bundle
-Likewise, C<o conf KEY splice LIST> passes the LIST to the according
-splice command.
+=item CPAN::Bundle::readme()
-Finally, any other list of arguments is taken as a new list value for
-the KEY variable discarding the previous value.
+Recursively runs the C<readme> method on all items contained in the bundle
-Examples:
+=item CPAN::Bundle::test()
- o conf urllist unshift http://cpan.dev.local/CPAN
- o conf urllist splice 3 1
- o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
+Recursively runs the C<test> method on all items contained in the bundle
-=item interactive editing: o conf init [MATCH|LIST]
+=item CPAN::Distribution::as_glimpse()
-Runs an interactive configuration dialog for matching variables.
-Without argument runs the dialog over all supported config variables.
-To specify a MATCH the argument must be enclosed by slashes.
+Returns a one-line description of the distribution
-Examples:
+=item CPAN::Distribution::as_string()
- o conf init ftp_passive ftp_proxy
- o conf init /color/
+Returns a multi-line description of the distribution
-=item reverting to saved: o conf defaults
+=item CPAN::Distribution::author
-Reverts all config variables to the state in the saved config file.
+Returns the CPAN::Author object of the maintainer who uploaded this
+distribution
-=item saving the config: o conf commit
+=item CPAN::Distribution::clean()
-Saves all config variables to the current config file (CPAN/Config.pm
-or CPAN/MyConfig.pm that was loaded at start).
+Changes to the directory where the distribution has been unpacked and
+runs C<make clean> there.
-=back
+=item CPAN::Distribution::containsmods()
-The configuration dialog can be started any time later again by
-issuing the command C< o conf init > in the CPAN shell. A subset of
-the configuration dialog can be run by issuing C<o conf init WORD>
-where WORD is any valid config variable or a regular expression.
+Returns a list of IDs of modules contained in a distribution file.
+Only works for distributions listed in the 02packages.details.txt.gz
+file. This typically means that only the most recent version of a
+distribution is covered.
-=head2 Config Variables
+=item CPAN::Distribution::cvs_import()
-Currently the following keys in the hash reference $CPAN::Config are
-defined:
+Changes to the directory where the distribution has been unpacked and
+runs something like
- build_cache size of cache for directories to build modules
- build_dir locally accessible directory to build modules
- build_dir_reuse boolean if distros in build_dir are persistent
- build_requires_install_policy
- to install or not to install: when a module is
- only needed for building. yes|no|ask/yes|ask/no
- bzip2 path to external prg
- cache_metadata use serializer to cache metadata
- commands_quote prefered character to use for quoting external
- commands when running them. Defaults to double
- quote on Windows, single tick everywhere else;
- can be set to space to disable quoting
- check_sigs if signatures should be verified
- colorize_output boolean if Term::ANSIColor should colorize output
- colorize_print Term::ANSIColor attributes for normal output
- colorize_warn Term::ANSIColor attributes for warnings
- commandnumber_in_prompt
- boolean if you want to see current command number
- cpan_home local directory reserved for this package
- curl path to external prg
- dontload_hash DEPRECATED
- dontload_list arrayref: modules in the list will not be
- loaded by the CPAN::has_inst() routine
- ftp path to external prg
- ftp_passive if set, the envariable FTP_PASSIVE is set for downloads
- ftp_proxy proxy host for ftp requests
- getcwd see below
- gpg path to external prg
- gzip location of external program gzip
- histfile file to maintain history between sessions
- histsize maximum number of lines to keep in histfile
- http_proxy proxy host for http requests
- inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
- after this many seconds inactivity. Set to 0 to
- never break.
- index_expire after this many days refetch index files
- inhibit_startup_message
- if true, does not print the startup message
- keep_source_where directory in which to keep the source (if we do)
- lynx path to external prg
- make location of external make program
- make_arg arguments that should always be passed to 'make'
- make_install_make_command
- the make command for running 'make install', for
- example 'sudo make'
- make_install_arg same as make_arg for 'make install'
- makepl_arg arguments passed to 'perl Makefile.PL'
- mbuild_arg arguments passed to './Build'
- mbuild_install_arg arguments passed to './Build install'
- mbuild_install_build_command
- command to use instead of './Build' when we are
- in the install stage, for example 'sudo ./Build'
- mbuildpl_arg arguments passed to 'perl Build.PL'
- ncftp path to external prg
- ncftpget path to external prg
- no_proxy don't proxy to these hosts/domains (comma separated list)
- pager location of external program more (or any pager)
- password your password if you CPAN server wants one
- patch path to external prg
- prefer_installer legal values are MB and EUMM: if a module comes
- with both a Makefile.PL and a Build.PL, use the
- former (EUMM) or the latter (MB); if the module
- comes with only one of the two, that one will be
- used in any case
- prerequisites_policy
- what to do if you are missing module prerequisites
- ('follow' automatically, 'ask' me, or 'ignore')
- prefs_dir local directory to store per-distro build options
- proxy_user username for accessing an authenticating proxy
- proxy_pass password for accessing an authenticating proxy
- randomize_urllist add some randomness to the sequence of the urllist
- scan_cache controls scanning of cache ('atstart' or 'never')
- shell your favorite shell
- show_upload_date boolean if commands should try to determine upload date
- tar location of external program tar
- term_is_latin if true internal UTF-8 is translated to ISO-8859-1
- (and nonsense for characters outside latin range)
- term_ornaments boolean to turn ReadLine ornamenting on/off
- test_report email test reports (if CPAN::Reporter is installed)
- unzip location of external program unzip
- urllist arrayref to nearby CPAN sites (or equivalent locations)
- username your username if you CPAN server wants one
- wait_list arrayref to a wait server to try (See CPAN::WAIT)
- wget path to external prg
- yaml_module which module to use to read/write YAML files
+ cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version
-You can set and query each of these options interactively in the cpan
-shell with the command set defined within the C<o conf> command:
+there.
+
+=item CPAN::Distribution::dir()
+
+Returns the directory into which this distribution has been unpacked.
+
+=item CPAN::Distribution::force($method,@args)
+
+Forces CPAN to perform a task that it normally would have refused to
+do. Force takes as arguments a method name to be called and any number
+of additional arguments that should be passed to the called method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. See also the section above on the
+C<force> and the C<fforce> pragma.
+
+=item CPAN::Distribution::get()
+
+Downloads the distribution from CPAN and unpacks it. Does nothing if
+the distribution has already been downloaded and unpacked within the
+current session.
+
+=item CPAN::Distribution::install()
+
+Changes to the directory where the distribution has been unpacked and
+runs the external command C<make install> there. If C<make> has not
+yet been run, it will be run first. A C<make test> will be issued in
+any case and if this fails, the install will be canceled. The
+cancellation can be avoided by letting C<force> run the C<install> for
+you.
+
+This install method has only the power to install the distribution if
+there are no dependencies in the way. To install an object and all of
+its dependencies, use CPAN::Shell->install.
+
+Note that install() gives no meaningful return value. See uptodate().
+
+=item CPAN::Distribution::install_tested()
+
+Install all the distributions that have been tested sucessfully but
+not yet installed. See also C<is_tested>.
+
+=item CPAN::Distribution::isa_perl()
+
+Returns 1 if this distribution file seems to be a perl distribution.
+Normally this is derived from the file name only, but the index from
+CPAN can contain a hint to achieve a return value of true for other
+filenames too.
+
+=item CPAN::Distribution::is_tested()
+
+List all the distributions that have been tested sucessfully but not
+yet installed. See also C<install_tested>.
+
+=item CPAN::Distribution::look()
+
+Changes to the directory where the distribution has been unpacked and
+opens a subshell there. Exiting the subshell returns.
+
+=item CPAN::Distribution::make()
+
+First runs the C<get> method to make sure the distribution is
+downloaded and unpacked. Changes to the directory where the
+distribution has been unpacked and runs the external commands C<perl
+Makefile.PL> or C<perl Build.PL> and C<make> there.
+
+=item CPAN::Distribution::perldoc()
+
+Downloads the pod documentation of the file associated with a
+distribution (in html format) and runs it through the external
+command lynx specified in C<$CPAN::Config->{lynx}>. If lynx
+isn't available, it converts it to plain text with external
+command html2text and runs it through the pager specified
+in C<$CPAN::Config->{pager}>
+
+=item CPAN::Distribution::prefs()
+
+Returns the hash reference from the first matching YAML file that the
+user has deposited in the C<prefs_dir/> directory. The first
+succeeding match wins. The files in the C<prefs_dir/> are processed
+alphabetically and the canonical distroname (e.g.
+AUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions
+stored in the $root->{match}{distribution} attribute value.
+Additionally all module names contained in a distribution are matched
+agains the regular expressions in the $root->{match}{module} attribute
+value. The two match values are ANDed together. Each of the two
+attributes are optional.
+
+=item CPAN::Distribution::prereq_pm()
+
+Returns the hash reference that has been announced by a distribution
+as the the C<requires> and C<build_requires> elements. These can be
+declared either by the C<META.yml> (if authoritative) or can be
+deposited after the run of C<Build.PL> in the file C<./_build/prereqs>
+or after the run of C<Makfile.PL> written as the C<PREREQ_PM> hash in
+a comment in the produced C<Makefile>. I<Note>: this method only works
+after an attempt has been made to C<make> the distribution. Returns
+undef otherwise.
+
+=item CPAN::Distribution::readme()
+
+Downloads the README file associated with a distribution and runs it
+through the pager specified in C<$CPAN::Config->{pager}>.
+
+=item CPAN::Distribution::read_yaml()
+
+Returns the content of the META.yml of this distro as a hashref. Note:
+works only after an attempt has been made to C<make> the distribution.
+Returns undef otherwise. Also returns undef if the content of META.yml
+is not authoritative. (The rules about what exactly makes the content
+authoritative are still in flux.)
+
+=item CPAN::Distribution::test()
+
+Changes to the directory where the distribution has been unpacked and
+runs C<make test> there.
+
+=item CPAN::Distribution::uptodate()
+
+Returns 1 if all the modules contained in the distribution are
+uptodate. Relies on containsmods.
+
+=item CPAN::Index::force_reload()
+
+Forces a reload of all indices.
+
+=item CPAN::Index::reload()
+
+Reloads all indices if they have not been read for more than
+C<$CPAN::Config->{index_expire}> days.
+
+=item CPAN::InfoObj::dump()
+
+CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
+inherit this method. It prints the data structure associated with an
+object. Useful for debugging. Note: the data structure is considered
+internal and thus subject to change without notice.
+
+=item CPAN::Module::as_glimpse()
+
+Returns a one-line description of the module in four columns: The
+first column contains the word C<Module>, the second column consists
+of one character: an equals sign if this module is already installed
+and uptodate, a less-than sign if this module is installed but can be
+upgraded, and a space if the module is not installed. The third column
+is the name of the module and the fourth column gives maintainer or
+distribution information.
+
+=item CPAN::Module::as_string()
+
+Returns a multi-line description of the module
+
+=item CPAN::Module::clean()
+
+Runs a clean on the distribution associated with this module.
+
+=item CPAN::Module::cpan_file()
+
+Returns the filename on CPAN that is associated with the module.
+
+=item CPAN::Module::cpan_version()
+
+Returns the latest version of this module available on CPAN.
+
+=item CPAN::Module::cvs_import()
+
+Runs a cvs_import on the distribution associated with this module.
+
+=item CPAN::Module::description()
+
+Returns a 44 character description of this module. Only available for
+modules listed in The Module List (CPAN/modules/00modlist.long.html
+or 00modlist.long.txt.gz)
+
+=item CPAN::Module::distribution()
+
+Returns the CPAN::Distribution object that contains the current
+version of this module.
+
+=item CPAN::Module::dslip_status()
+
+Returns a hash reference. The keys of the hash are the letters C<D>,
+C<S>, C<L>, C<I>, and <P>, for development status, support level,
+language, interface and public licence respectively. The data for the
+DSLIP status are collected by pause.perl.org when authors register
+their namespaces. The values of the 5 hash elements are one-character
+words whose meaning is described in the table below. There are also 5
+hash elements C<DV>, C<SV>, C<LV>, C<IV>, and <PV> that carry a more
+verbose value of the 5 status variables.
+
+Where the 'DSLIP' characters have the following meanings:
+
+ D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
+ i - Idea, listed to gain consensus or as a placeholder
+ c - under construction but pre-alpha (not yet released)
+ a/b - Alpha/Beta testing
+ R - Released
+ M - Mature (no rigorous definition)
+ S - Standard, supplied with Perl 5
+
+ S - Support Level:
+ m - Mailing-list
+ d - Developer
+ u - Usenet newsgroup comp.lang.perl.modules
+ n - None known, try comp.lang.perl.modules
+ a - abandoned; volunteers welcome to take over maintainance
+
+ L - Language Used:
+ p - Perl-only, no compiler needed, should be platform independent
+ c - C and perl, a C compiler will be needed
+ h - Hybrid, written in perl with optional C code, no compiler needed
+ + - C++ and perl, a C++ compiler will be needed
+ o - perl and another language other than C or C++
+
+ I - Interface Style
+ f - plain Functions, no references used
+ h - hybrid, object and function interfaces available
+ n - no interface at all (huh?)
+ r - some use of unblessed References or ties
+ O - Object oriented using blessed references and/or inheritance
+
+ P - Public License
+ p - Standard-Perl: user may choose between GPL and Artistic
+ g - GPL: GNU General Public License
+ l - LGPL: "GNU Lesser General Public License" (previously known as
+ "GNU Library General Public License")
+ b - BSD: The BSD License
+ a - Artistic license alone
+ o - open source: appoved by www.opensource.org
+ d - allows distribution without restrictions
+ r - restricted distribtion
+ n - no license at all
+
+=item CPAN::Module::force($method,@args)
+
+Forces CPAN to perform a task that it normally would have refused to
+do. Force takes as arguments a method name to be called and any number
+of additional arguments that should be passed to the called method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. See also the section above on the
+C<force> and the C<fforce> pragma.
+
+=item CPAN::Module::get()
+
+Runs a get on the distribution associated with this module.
+
+=item CPAN::Module::inst_file()
+
+Returns the filename of the module found in @INC. The first file found
+is reported just like perl itself stops searching @INC when it finds a
+module.
+
+=item CPAN::Module::available_file()
+
+Returns the filename of the module found in PERL5LIB or @INC. The
+first file found is reported. The advantage of this method over
+C<inst_file> is that modules that have been tested but not yet
+installed are included because PERL5LIB keeps track of tested modules.
+
+=item CPAN::Module::inst_version()
+
+Returns the version number of the installed module in readable format.
+
+=item CPAN::Module::available_version()
+
+Returns the version number of the available module in readable format.
+
+=item CPAN::Module::install()
+
+Runs an C<install> on the distribution associated with this module.
+
+=item CPAN::Module::look()
+
+Changes to the directory where the distribution associated with this
+module has been unpacked and opens a subshell there. Exiting the
+subshell returns.
+
+=item CPAN::Module::make()
+
+Runs a C<make> on the distribution associated with this module.
+
+=item CPAN::Module::manpage_headline()
-=over 2
+If module is installed, peeks into the module's manpage, reads the
+headline and returns it. Moreover, if the module has been downloaded
+within this session, does the equivalent on the downloaded module even
+if it is not installed.
-=item C<o conf E<lt>scalar optionE<gt>>
+=item CPAN::Module::perldoc()
-prints the current value of the I<scalar option>
+Runs a C<perldoc> on this module.
-=item C<o conf E<lt>scalar optionE<gt> E<lt>valueE<gt>>
+=item CPAN::Module::readme()
-Sets the value of the I<scalar option> to I<value>
+Runs a C<readme> on the distribution associated with this module.
-=item C<o conf E<lt>list optionE<gt>>
+=item CPAN::Module::test()
-prints the current value of the I<list option> in MakeMaker's
-neatvalue format.
+Runs a C<test> on the distribution associated with this module.
-=item C<o conf E<lt>list optionE<gt> [shift|pop]>
+=item CPAN::Module::uptodate()
-shifts or pops the array in the I<list option> variable
+Returns 1 if the module is installed and up-to-date.
-=item C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>>
+=item CPAN::Module::userid()
-works like the corresponding perl commands.
+Returns the author's ID of the module.
=back
-=head2 CPAN::anycwd($path): Note on config variable getcwd
+=head2 Cache Manager
-CPAN.pm changes the current working directory often and needs to
-determine its own current working directory. Per default it uses
-Cwd::cwd but if this doesn't work on your system for some reason,
-alternatives can be configured according to the following table:
+Currently the cache manager only keeps track of the build directory
+($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that
+deletes complete directories below C<build_dir> as soon as the size of
+all directories there gets bigger than $CPAN::Config->{build_cache}
+(in MB). The contents of this cache may be used for later
+re-installations that you intend to do manually, but will never be
+trusted by CPAN itself. This is due to the fact that the user might
+use these directories for building modules on different architectures.
+
+There is another directory ($CPAN::Config->{keep_source_where}) where
+the original distribution files are kept. This directory is not
+covered by the cache manager and must be controlled by the user. If
+you choose to have the same directory as build_dir and as
+keep_source_where directory, then your sources will be deleted with
+the same fifo mechanism.
+
+=head2 Bundles
+
+A bundle is just a perl module in the namespace Bundle:: that does not
+define any functions or methods. It usually only contains documentation.
+
+It starts like a perl module with a package declaration and a $VERSION
+variable. After that the pod section looks like any other pod with the
+only difference being that I<one special pod section> exists starting with
+(verbatim):
+
+ =head1 CONTENTS
+
+In this pod section each line obeys the format
+
+ Module_Name [Version_String] [- optional text]
+
+The only required part is the first field, the name of a module
+(e.g. Foo::Bar, ie. I<not> the name of the distribution file). The rest
+of the line is optional. The comment part is delimited by a dash just
+as in the man page header.
+
+The distribution of a bundle should follow the same convention as
+other distributions.
+
+Bundles are treated specially in the CPAN package. If you say 'install
+Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
+the modules in the CONTENTS section of the pod. You can install your
+own Bundles locally by placing a conformant Bundle file somewhere into
+your @INC path. The autobundle() command which is available in the
+shell interface does that for you by including all currently installed
+modules in a snapshot bundle file.
+
+=head1 PREREQUISITES
+
+If you have a local mirror of CPAN and can access all files with
+"file:" URLs, then you only need a perl better than perl5.003 to run
+this module. Otherwise Net::FTP is strongly recommended. LWP may be
+required for non-UNIX systems or if your nearest CPAN site is
+associated with a URL that is not C<ftp:>.
+
+If you have neither Net::FTP nor LWP, there is a fallback mechanism
+implemented for an external ftp command or for an external lynx
+command.
+
+=head1 UTILITIES
+
+=head2 Finding packages and VERSION
+
+This module presumes that all packages on CPAN
=over 2
-=item cwd
+=item *
-Calls Cwd::cwd
+declare their $VERSION variable in an easy to parse manner. This
+prerequisite can hardly be relaxed because it consumes far too much
+memory to load all packages into the running program just to determine
+the $VERSION variable. Currently all programs that are dealing with
+version use something like this
-=item getcwd
+ perl -MExtUtils::MakeMaker -le \
+ 'print MM->parse_version(shift)' filename
-Calls Cwd::getcwd
+If you are author of a package and wonder if your $VERSION can be
+parsed, please try the above method.
-=item fastcwd
+=item *
-Calls Cwd::fastcwd
+come as compressed or gzipped tarfiles or as zip files and contain a
+C<Makefile.PL> or C<Build.PL> (well, we try to handle a bit more, but
+without much enthusiasm).
-=item backtickcwd
+=back
-Calls the external command cwd.
+=head2 Debugging
+
+The debugging of this module is a bit complex, because we have
+interferences of the software producing the indices on CPAN, of the
+mirroring process on CPAN, of packaging, of configuration, of
+synchronicity, and of bugs within CPAN.pm.
+
+For debugging the code of CPAN.pm itself in interactive mode some more
+or less useful debugging aid can be turned on for most packages within
+CPAN.pm with one of
+
+=over 2
+
+=item o debug package...
+
+sets debug mode for packages.
+
+=item o debug -package...
+
+unsets debug mode for packages.
+
+=item o debug all
+
+turns debugging on for all packages.
+
+=item o debug number
=back
-=head2 Note on the format of the urllist parameter
+which sets the debugging packages directly. Note that C<o debug 0>
+turns debugging off.
-urllist parameters are URLs according to RFC 1738. We do a little
-guessing if your URL is not compliant, but if you have problems with
-C<file> URLs, please try the correct format. Either:
+What seems quite a successful strategy is the combination of C<reload
+cpan> and the debugging switches. Add a new debug statement while
+running in the shell and then issue a C<reload cpan> and see the new
+debugging messages immediately without losing the current context.
- file://localhost/whatever/ftp/pub/CPAN/
+C<o debug> without an argument lists the valid package names and the
+current set of packages in debugging mode. C<o debug> has built-in
+completion support.
-or
+For debugging of CPAN data there is the C<dump> command which takes
+the same arguments as make/test/install and outputs each object's
+Data::Dumper dump. If an argument looks like a perl variable and
+contains one of C<$>, C<@> or C<%>, it is eval()ed and fed to
+Data::Dumper directly.
- file:///home/ftp/pub/CPAN/
+=head2 Floppy, Zip, Offline Mode
-=head2 urllist parameter has CD-ROM support
+CPAN.pm works nicely without network too. If you maintain machines
+that are not networked at all, you should consider working with file:
+URLs. Of course, you have to collect your modules somewhere first. So
+you might use CPAN.pm to put together all you need on a networked
+machine. Then copy the $CPAN::Config->{keep_source_where} (but not
+$CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind
+of a personal CPAN. CPAN.pm on the non-networked machines works nicely
+with this floppy. See also below the paragraph about CD-ROM support.
-The C<urllist> parameter of the configuration table contains a list of
-URLs that are to be used for downloading. If the list contains any
-C<file> URLs, CPAN always tries to get files from there first. This
-feature is disabled for index files. So the recommendation for the
-owner of a CD-ROM with CPAN contents is: include your local, possibly
-outdated CD-ROM as a C<file> URL at the end of urllist, e.g.
+=head2 Basic Utilities for Programmers
- o conf urllist push file://localhost/CDROM/CPAN
+=over 2
-CPAN.pm will then fetch the index files from one of the CPAN sites
-that come at the beginning of urllist. It will later check for each
-module if there is a local copy of the most recent version.
+=item has_inst($module)
-Another peculiarity of urllist is that the site that we could
-successfully fetch the last file from automatically gets a preference
-token and is tried as the first site for the next request. So if you
-add a new site at runtime it may happen that the previously preferred
-site will be tried another time. This means that if you want to disallow
-a site for the next transfer, it must be explicitly removed from
-urllist.
+Returns true if the module is installed. Used to load all modules into
+the running CPAN.pm which are considered optional. The config variable
+C<dontload_list> can be used to intercept the C<has_inst()> call such
+that an optional module is not loaded despite being available. For
+example the following command will prevent that C<YAML.pm> is being
+loaded:
-=head2 Maintaining the urllist parameter
+ cpan> o conf dontload_list push YAML
-If you have YAML.pm (or some other YAML module configured in
-C<yaml_module>) installed, CPAN.pm collects a few statistical data
-about recent downloads. You can view the statistics with the C<hosts>
-command or inspect them directly by looking into the C<FTPstats.yml>
-file in your C<cpan_home> directory.
+See the source for details.
-To get some interesting statistics it is recommended to set the
-C<randomize_urllist> parameter that introduces some amount of
-randomness into the URL selection.
+=item has_usable($module)
-=head2 prefs_dir for avoiding interactive questions (ALPHA)
+Returns true if the module is installed and is in a usable state. Only
+useful for a handful of modules that are used internally. See the
+source for details.
-(B<Note:> This feature has been introduced in CPAN.pm 1.8854 and is
-still considered experimental and may still be changed)
-
-The files in the directory specified in C<prefs_dir> are YAML files
-that specify how CPAN.pm shall treat distributions that deviate from
-the normal non-interactive model of building and installing CPAN
-modules.
-
-Some modules try to get some data from the user interactively thus
-disturbing the installation of large bundles like Phalanx100 or
-modules like Plagger.
-
-CPAN.pm can use YAML files to either pass additional arguments to one
-of the four commands, set environment variables or instantiate an
-Expect object that reads from the console and enters answers on your
-behalf (latter option requires Expect.pm installed). A further option
-is to apply patches from the local disk or from CPAN.
-
-CPAN.pm comes with a couple of such YAML files. The structure is
-currently not documented because in flux. Please see the distroprefs
-directory of the CPAN distribution for examples and follow the README
-in there.
-
-Please note that setting the environment variable PERL_MM_USE_DEFAULT
-to a true value can also get you a long way if you want to always pick
-the default answers. But this only works if the author of a package
-used the prompt function provided by ExtUtils::MakeMaker and if the
-defaults are OK for you.
+=item instance($module)
+
+The constructor for all the singletons used to represent modules,
+distributions, authors and bundles. If the object already exists, this
+method returns the object, otherwise it calls the constructor.
+
+=back
=head1 SECURITY
the environment CPAN_SHELL_LEVEL to 1 or increments it if it is
already set.
+When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING.
+
When the config variable ftp_passive is set, all downloads will be run
with the environment variable FTP_PASSIVE set to this value. This is
in general a good idea as it influences both Net::FTP and LWP based
o conf makepl_arg "LIB=~/myperl/lib \
INSTALLMAN1DIR=~/myperl/man/man1 \
- INSTALLMAN3DIR=~/myperl/man/man3"
+ INSTALLMAN3DIR=~/myperl/man/man3 \
+ INSTALLSCRIPT=~/myperl/bin \
+ INSTALLBIN=~/myperl/bin"
+
+and then (oh joy) the equivalent command for Module::Build.
You can make this setting permanent like all C<o conf> settings with
-C<o conf commit>.
+C<o conf commit> or by setting C<auto_commit> beforehand.
You will have to add ~/myperl/man to the MANPATH environment variable
and also tell your perl programs to look into ~/myperl/lib, e.g. by
force install Foo::Bar
-This does a bit more than really needed because it untars the
-distribution again and runs make and test and only then install.
-
-Or, if you find this is too fast and you would prefer to do smaller
-steps, say
-
- force get Foo::Bar
-
-first and then continue as always. C<Force get> I<forgets> previous
-error conditions.
-
Or you can use
look Foo::Bar
and then 'make install' directly in the subshell.
-Or you leave the CPAN shell and start it again.
-
-For the really curious, by accessing internals directly, you I<could>
-
- !delete CPAN::Shell->expandany("Foo::Bar")->distribution->{install}
-
-but this is neither guaranteed to work in the future nor is it a
-decent command.
-
=item 12)
How do I install a "DEVELOPER RELEASE" of a module?
=back
-=head1 BUGS
+=head1 COMPATIBILITY
-Please report bugs via http://rt.cpan.org/
+=head2 OLD PERL VERSIONS
-Before submitting a bug, please make sure that the traditional method
-of building a Perl module package from a shell by following the
-installation instructions of that package still works in your
-environment.
+CPAN.pm is regularly tested to run under 5.004, 5.005, and assorted
+newer versions. It is getting more and more difficult to get the
+minimal prerequisites working on older perls. It is close to
+impossible to get the whole Bundle::CPAN working there. If you're in
+the position to have only these old versions, be advised that CPAN is
+designed to work fine without the Bundle::CPAN installed.
+
+To get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is
+compatible with ancient perls and that File::Temp is listed as a
+prerequisite but CPAN has reasonable workarounds if it is missing.
+
+=head2 CPANPLUS
+
+This module and its competitor, the CPANPLUS module, are both much
+cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
+more modular but it was never tried to make it compatible with CPAN.pm.
=head1 SECURITY ADVICE
contain bugs and may alter the way your computer works or even make it
unusable. Please consider backing up your data before every upgrade.
+=head1 BUGS
+
+Please report bugs via http://rt.cpan.org/
+
+Before submitting a bug, please make sure that the traditional method
+of building a Perl module package from a shell by following the
+installation instructions of that package still works in your
+environment.
+
=head1 AUTHOR
Andreas Koenig C<< <andk@cpan.org> >>
=head1 TRANSLATIONS
Kawai,Takanori provides a Japanese translation of this manpage at
-http://member.nifty.ne.jp/hippo2000/perltips/CPAN.htm
+http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm
=head1 SEE ALSO
cpan(1), CPAN::Nox(3pm), CPAN::Version(3pm)
=cut
+
+
projects / p5sagit/p5-mst-13.2.git / blobdiff