Add Perl debugging tutorial, regen toc.

[perl5.git] / installperl

#!./perl

BEGIN {
    require 5.004;
    chdir '..' if !-d 'lib' and -d '..\lib';
    @INC = 'lib';
    $ENV{PERL5LIB} = 'lib';
}

use strict;
use vars qw($Is_VMS $Is_W32 $Is_OS2 $Is_Cygwin $nonono $dostrip $versiononly $depth);

BEGIN {
    $Is_VMS = $^O eq 'VMS';
    $Is_W32 = $^O eq 'MSWin32';
    $Is_OS2 = $^O eq 'os2';
    $Is_Cygwin = $^O eq 'cygwin';
    if ($Is_VMS) { eval 'use VMS::Filespec;' }
}

my $scr_ext = ($Is_VMS ? '.Com' : $Is_W32 ? '.bat' : '');

use File::Find;
use File::Compare;
use File::Copy ();
use File::Path ();
use ExtUtils::Packlist;
use Config;
use subs qw(unlink link chmod);
use vars qw($packlist);

# override the ones in the rest of the script
sub mkpath {
    File::Path::mkpath(@_) unless $nonono;
}

my $mainperldir = "/usr/bin";
my $exe_ext = $Config{exe_ext};

# Allow ``make install PERLNAME=something_besides_perl'':
my $perl = defined($ENV{PERLNAME}) ? $ENV{PERLNAME} : 'perl';

# This is the base used for versioned names, like "perl5.6.0".
# It's separate because a common use of $PERLNAME is to install
# perl as "perl5", if that's used as base for versioned files you
# get "perl55.6.0".
my $perl_verbase = defined($ENV{PERLNAME_VERBASE})
		    ? $ENV{PERLNAME_VERBASE}
		    : $perl;

while (@ARGV) {
    $nonono = 1 if $ARGV[0] eq '-n';
    $dostrip = 1 if $ARGV[0] eq '-s';
    $versiononly = 1 if $ARGV[0] eq '-v';
    shift;
}

my @scripts = qw(utils/c2ph utils/h2ph utils/h2xs utils/perlbug utils/perldoc
		utils/pl2pm utils/splain utils/perlcc utils/dprofpp
		x2p/s2p x2p/find2perl 
		pod/pod2man pod/pod2html pod/pod2latex pod/pod2text
		pod/pod2usage pod/podchecker pod/podselect);

if ($scr_ext) { @scripts = map { "$_$scr_ext" } @scripts; }

my @pods = (<pod/*.pod>);

# Specify here any .pm files that are actually architecture-dependent.
# (Those included with XS extensions under ext/ are automatically
# added later.)
# Now that the default privlib has the full perl version number included,
# we no longer have to play the trick of sticking version-specific .pm 
# files under the archlib directory.
my %archpms = (
    Config => 1, 
);

if ($^O eq 'dos') {
    push(@scripts,'djgpp/fixpmain');
    $archpms{config} = $archpms{filehand} = 1;
}

if ((-e "testcompile") && (defined($ENV{'COMPILE'})))
{
	push(@scripts, map("$_.exe", @scripts));
}

find(sub {
	if ("$File::Find::dir/$_" =~ m{^ext\b(.*)/([^/]+)\.pm$}) {
	    my($path, $modname) = ($1,$2);

	    # strip trailing component first
	    $path =~ s{/[^/]*$}{};

	    # strip optional "/lib";
	    $path =~ s{/lib\b}{};

	    # strip any leading /
	    $path =~ s{^/}{};

	    # reconstitute canonical module name
	    $modname = "$path/$modname" if length $path;

	    # remember it
	    $archpms{$modname} = 1;
	}
    }, 'ext');

# print "[$_]\n" for sort keys %archpms;

my $ver = $Config{version};
my $release = substr($],0,3);   # Not used presently.
my $patchlevel = substr($],3,2);
die "Patchlevel of perl ($patchlevel)",
    "and patchlevel of config.sh ($Config{'PERL_VERSION'}) don't match\n"
	if $patchlevel != $Config{'PERL_VERSION'};

# Fetch some frequently-used items from %Config
my $installbin = $Config{installbin};
my $installscript = $Config{installscript};
my $installprivlib = $Config{installprivlib};
my $installarchlib = $Config{installarchlib};
my $installsitelib = $Config{installsitelib};
my $installsitearch = $Config{installsitearch};
my $installman1dir = $Config{installman1dir};
my $man1ext = $Config{man1ext};
my $libperl = $Config{libperl};
# Shared library and dynamic loading suffixes.
my $so = $Config{so};
my $dlext = $Config{dlext};
my $dlsrc = $Config{dlsrc};

my $d_dosuid = $Config{d_dosuid};
my $binexp = $Config{binexp};

if ($Is_VMS) {  # Hang in there until File::Spec hits the big time
    foreach ( \$installbin,     \$installscript,  \$installprivlib,
              \$installarchlib, \$installsitelib, \$installsitearch,
              \$installman1dir ) {
      $$_ = unixify($$_);  $$_ =~ s:/$::;
    }
}

# Do some quick sanity checks.

if ($d_dosuid && $>) { die "You must run as root to install suidperl\n"; }

   $installbin		|| die "No installbin directory in config.sh\n";
-d $installbin		|| mkpath($installbin, 1, 0777);
-d $installbin		|| $nonono || die "$installbin is not a directory\n";
-w $installbin		|| $nonono || die "$installbin is not writable by you\n"
	unless $installbin =~ m#^/afs/# || $nonono;

-x 'perl' . $exe_ext	|| die "perl isn't executable!\n";
-x 'suidperl' . $exe_ext|| die "suidperl isn't executable!\n" if $d_dosuid;

-x 't/TEST'		|| $Is_W32
			|| warn "WARNING: You've never run 'make test'!!!",
				"  (Installing anyway.)\n";

if ($Is_W32 or $Is_Cygwin) {
  my $perldll;

if ($Is_Cygwin) {
  $perldll = $libperl;
  $perldll =~ s/(\..*)?$/.$dlext/;
  if ($Config{useshrplib} eq 'true') {
    # install ld2 and perlld as well
    foreach ('ld2', 'perlld') {
      safe_unlink("$installbin/$_");
      copy("$_", "$installbin/$_");
      chmod(0755, "$installbin/$_");
    };
  };
} else {
  $perldll = 'perl56.' . $dlext;
}

   if ($dlsrc ne "dl_none.xs") {
      -f $perldll || die "No perl DLL built\n";
   }
# Install the DLL

   safe_unlink("$installbin/$perldll");
   copy("$perldll", "$installbin/$perldll");
   chmod(0755, "$installbin/$perldll");
   
} # if ($Is_W32 or $Is_Cygwin)

# This will be used to store the packlist
my $packlist = ExtUtils::Packlist->new("$installarchlib/.packlist");

# First we install the version-numbered executables.

if ($Is_VMS) {
    safe_unlink("$installbin/$perl$exe_ext");
    copy("perl$exe_ext", "$installbin/$perl$exe_ext");
    chmod(0755, "$installbin/$perl$exe_ext");
    safe_unlink("$installbin/${perl}shr$exe_ext");
    copy("perlshr$exe_ext", "$installbin/${perl}shr$exe_ext");
    chmod(0755, "$installbin/${perl}shr$exe_ext");
}
elsif ($^O eq 'mpeix') {
    # MPE lacks hard links and requires that executables with special
    # capabilities reside in the MPE namespace.
    safe_unlink("$installbin/perl$ver$exe_ext", $Config{perlpath});
    # Install the primary executable into the MPE namespace as perlpath.
    copy("perl$exe_ext", $Config{perlpath});
    chmod(0755, $Config{perlpath});
    # Create a backup copy with the version number.
    link($Config{perlpath}, "$installbin/perl$ver$exe_ext");
}
elsif ($^O ne 'dos') {
    safe_unlink("$installbin/$perl_verbase$ver$exe_ext");
    copy("perl$exe_ext", "$installbin/$perl_verbase$ver$exe_ext");
    strip("$installbin/$perl_verbase$ver$exe_ext");
    chmod(0755, "$installbin/$perl_verbase$ver$exe_ext");
}
else {
    safe_unlink("$installbin/$perl.exe");
    copy("perl.exe", "$installbin/$perl.exe");
}

safe_unlink("$installbin/s$perl_verbase$ver$exe_ext");
if ($d_dosuid) {
    copy("suidperl$exe_ext", "$installbin/s$perl_verbase$ver$exe_ext");
    chmod(04711, "$installbin/s$perl_verbase$ver$exe_ext");
}

# Install library files.

my ($do_installarchlib, $do_installprivlib) = (0, 0);
    
mkpath($installprivlib, 1, 0777);
mkpath($installarchlib, 1, 0777);
mkpath($installsitelib, 1, 0777) if ($installsitelib);
mkpath($installsitearch, 1, 0777) if ($installsitearch);

if (chdir "lib") {
    $do_installarchlib = ! samepath($installarchlib, '.');
    $do_installprivlib = ! samepath($installprivlib, '.');
    $do_installprivlib = 0 if $versiononly && !($installprivlib =~ m/\Q$ver/);

    if ($do_installarchlib || $do_installprivlib) {
	find(\&installlib, '.');
    }
    chdir ".." || die "Can't cd back to source directory: $!\n";
}
else {
    warn "Can't cd to lib to install lib files: $!\n";
}

# Install header files and libraries.
mkpath("$installarchlib/CORE", 1, 0777);
my @corefiles;
if ($Is_VMS) {  # We did core file selection during build
    my $coredir = "lib/$Config{archname}/$ver/CORE";
    $coredir =~ tr/./_/;
    map { s|^$coredir/||i; } @corefiles = <$coredir/*.*>;
}
else {
    # [als] hard-coded 'libperl' name... not good!
    @corefiles = <*.h libperl*.*>;

    # AIX needs perl.exp installed as well.
    push(@corefiles,'perl.exp') if $^O eq 'aix';
    if ($^O eq 'mpeix') {
        # MPE needs mpeixish.h installed as well.
        mkpath("$installarchlib/CORE/mpeix", 1, 0777);
        push(@corefiles,'mpeix/mpeixish.h');
    }
    # If they have built sperl.o...
    push(@corefiles,'sperl.o') if -f 'sperl.o';
}
foreach my $file (@corefiles) {
    # HP-UX (at least) needs to maintain execute permissions
    # on dynamically-loadable libraries. So we do it for all.
    if (copy_if_diff($file,"$installarchlib/CORE/$file")) {
	if ($file =~ /\.(\Q$so\E|\Q$dlext\E)$/) {
	    chmod(0555, "$installarchlib/CORE/$file");
	    strip("-S", "$installarchlib/CORE/$file") if $^O =~ /^(rhapsody|darwin)$/;
	} else {
	    chmod(0444, "$installarchlib/CORE/$file");
	}
    }
}

# Install main perl executables
# Make links to ordinary names if installbin directory isn't current directory.

if (! $versiononly && ! samepath($installbin, '.') && ($^O ne 'dos') && ! $Is_VMS) {
    safe_unlink("$installbin/$perl$exe_ext", "$installbin/suid$perl$exe_ext");
    if ($^O eq 'mpeix') {
	# MPE doesn't support hard links, so use a symlink.
	# We don't want another cloned copy.
        symlink($Config{perlpath}, "$installbin/perl$exe_ext");
    } else {
	link("$installbin/$perl_verbase$ver$exe_ext",
		"$installbin/$perl$exe_ext");
    }
    link("$installbin/s$perl_verbase$ver$exe_ext",
	    "$installbin/suid$perl$exe_ext") 
      if $d_dosuid;
}

# Offer to install perl in a "standard" location

my $mainperl_is_instperl = 0;

if ($Config{installusrbinperl} && $Config{installusrbinperl} eq 'define' &&
    !$versiononly && !$nonono && !$Is_W32 && !$Is_VMS && -t STDIN && -t STDERR
	&& -w $mainperldir && ! samepath($mainperldir, $installbin)) {
    my($usrbinperl)	= "$mainperldir/$perl$exe_ext";
    my($instperl)	= "$installbin/$perl$exe_ext";
    my($expinstperl)	= "$binexp/$perl$exe_ext";

    # First make sure $usrbinperl is not already the same as the perl we
    # just installed.
    if (-x $usrbinperl) {
	# Try to be clever about mainperl being a symbolic link
	# to binexp/perl if binexp and installbin are different.
	$mainperl_is_instperl =
	    samepath($usrbinperl, $instperl) ||
	    samepath($usrbinperl, $expinstperl) ||
	     (($binexp ne $installbin) &&
	      (-l $usrbinperl) &&
	      ((readlink $usrbinperl) eq $expinstperl));
    }
    if ((! $mainperl_is_instperl) &&
	(yn("Many scripts expect perl to be installed as $usrbinperl.\n" . 
	     "Do you wish to have $usrbinperl be the same as\n" .
	     "$expinstperl? [y] ")))
    {
	unlink($usrbinperl);
	( $Config{'d_link'} eq 'define' &&
	  eval { CORE::link $instperl, $usrbinperl } )	||
	eval { symlink $expinstperl, $usrbinperl }	||
	copy($instperl, $usrbinperl);

	$mainperl_is_instperl = 1;
    }
}

# Make links to ordinary names if installbin directory isn't current directory.

if (!$versiononly && ! samepath($installbin, 'x2p')) {
    safe_unlink("$installbin/a2p$exe_ext");
    copy("x2p/a2p$exe_ext", "$installbin/a2p$exe_ext");
    chmod(0755, "$installbin/a2p$exe_ext");
}

# cppstdin is just a script, but it is architecture-dependent, so
# it can't safely be shared.  Place it in $installbin.
# Note that Configure doesn't build cppstin if it isn't needed, so
# we skip this if cppstdin doesn't exist.
if (! $versiononly && (-f 'cppstdin') && (! samepath($installbin, '.'))) {
    safe_unlink("$installbin/cppstdin");
    copy("cppstdin", "$installbin/cppstdin");
    chmod(0755, "$installbin/cppstdin");
}

# Install scripts.

mkpath($installscript, 1, 0777);

if (! $versiononly) {
    for (@scripts) {
	(my $base = $_) =~ s#.*/##;
	copy($_, "$installscript/$base");
	chmod(0755, "$installscript/$base");
    }
}

# pstruct should be a link to c2ph

if (! $versiononly) {
    safe_unlink("$installscript/pstruct$scr_ext");
    if ($^O eq 'dos' or $Is_VMS or $^O eq 'transit') {
        copy("$installscript/c2ph$scr_ext", "$installscript/pstruct$scr_ext"); 
    } else {
        link("$installscript/c2ph$scr_ext", "$installscript/pstruct$scr_ext");
    }
}

# Install pod pages.  Where? I guess in $installprivlib/pod
# ($installprivlib/pods for cygwin).

my $pod = $Is_Cygwin ? 'pods' : 'pod';
unless ( $versiononly && !($installprivlib =~ m/\Q$ver/)) {
    mkpath("${installprivlib}/$pod", 1, 0777);

    # If Perl 5.003's perldiag.pod is there, rename it.
    if (open POD, "${installprivlib}/$pod/perldiag.pod") {
	read POD, $_, 4000;
	close POD;
	# Some of Perl 5.003's diagnostic messages ended with periods.
	if (/^=.*\.$/m) {
	    my ($from, $to) = ("${installprivlib}/$pod/perldiag.pod",
			       "${installprivlib}/$pod/perldiag-5.003.pod");
	    print "  rename $from $to";
	    rename($from, $to)
		or warn "Couldn't rename $from to $to: $!\n"
		unless $nonono;
	}
    }

    for (@pods) {
	# $_ is a name like  pod/perl.pod
        (my $base = $_) =~ s#.*/##;
	copy_if_diff($_, "${installprivlib}/$pod/${base}");
    }

}

# Check to make sure there aren't other perls around in installer's
# path.  This is probably UNIX-specific.  Check all absolute directories
# in the path except for where public executables are supposed to live.
# Also skip $mainperl if the user opted to have it be a link to the
# installed perl.

if (!$versiononly) {
    my ($path, @path);
    my $dirsep = ($Is_OS2 || $Is_W32) ? ';' : ':' ;
    ($path = $ENV{"PATH"}) =~ s:\\:/:g ;
    @path = split(/$dirsep/, $path);
    if ($Is_VMS) {
        my $i = 0;
        while (exists $ENV{'DCL$PATH' . $i}) {
            my $dir = unixpath($ENV{'DCL$PATH' . $i});  $dir =~ s-/$--;
            push(@path,$dir);
        }
    }
    my @otherperls;
    my %otherperls;
    for (@path) {
	next unless m,^/,;
	# Use &samepath here because some systems have other dirs linked
	# to $mainperldir (like SunOS)
	next if samepath($_, $binexp);
	next if ($mainperl_is_instperl && samepath($_, $mainperldir));
        my $otherperl = "$_/$perl$exe_ext";
	next if $otherperls{$otherperl}++;
	push(@otherperls, $otherperl)
	    if (-x $otherperl && ! -d $otherperl);
    }
    if (@otherperls) {
	print STDERR "\nWarning: $perl appears in your path in the following " .
	    "locations beyond where\nwe just installed it:\n";
	for (@otherperls) {
	    print STDERR "    ", $_, "\n";
	}
	print STDERR "\n";
    }

}

$packlist->write() unless $nonono;
print "  Installation complete\n";

exit 0;

###############################################################################

sub yn {
    my($prompt) = @_;
    my($answer);
    my($default) = $prompt =~ m/\[([yn])\]\s*$/i;
    print STDERR $prompt;
    chop($answer = <STDIN>);
    $answer = $default if $answer =~ m/^\s*$/;
    ($answer =~ m/^[yY]/);
}

sub unlink {
    my(@names) = @_;
    my($cnt) = 0;

    return scalar(@names) if $Is_VMS;

    foreach my $name (@names) {
	next unless -e $name;
	chmod 0777, $name if ($Is_OS2 || $Is_W32 || $Is_Cygwin);
	print "  unlink $name\n";
	( CORE::unlink($name) and ++$cnt 
	  or warn "Couldn't unlink $name: $!\n" ) unless $nonono;
    }
    return $cnt;
}

sub safe_unlink {
    return if $nonono or $Is_VMS;
    my @names = @_;
    foreach my $name (@names) {
	next unless -e $name;
	chmod 0777, $name if ($Is_OS2 || $Is_W32);
	print "  unlink $name\n";
	next if CORE::unlink($name);
	warn "Couldn't unlink $name: $!\n";
	if ($! =~ /busy/i) {
	    print "  mv $name $name.old\n";
	    safe_rename($name, "$name.old")
		or warn "Couldn't rename $name: $!\n";
	}
    }
}

sub safe_rename {
    my($from,$to) = @_;
    if (-f $to and not unlink($to)) {
	my($i);
	for ($i = 1; $i < 50; $i++) {
	    last if rename($to, "$to.$i");
	}
	warn("Cannot rename to `$to.$i': $!"), return 0 
	   if $i >= 50;	# Give up!
    }
    link($from,$to) || return 0;
    unlink($from);
}

sub link {
    my($from,$to) = @_;
    my($success) = 0;

    print "  ln $from $to\n";
    eval {
	CORE::link($from, $to)
	    ? $success++
	    : ($from =~ m#^/afs/# || $to =~ m#^/afs/#)
	      ? die "AFS"  # okay inside eval {}
	      : die "Couldn't link $from to $to: $!\n"
	  unless $nonono;
        $packlist->{$to} = { from => $from, type => 'link' };
    };
    if ($@) {
	warn $@;
	print "  cp $from $to\n";
	print "  creating new version of $to\n" if $Is_VMS and -e $to;
	File::Copy::copy($from, $to)
	    ? $success++
	    : warn "Couldn't copy $from to $to: $!\n"
	  unless $nonono;
        $packlist->{$to} = { type => 'file' };
    }
    $success;
}

sub chmod {
    my($mode,$name) = @_;

    return if ($^O eq 'dos');
    printf "  chmod %o %s\n", $mode, $name;
    CORE::chmod($mode,$name)
	|| warn sprintf("Couldn't chmod %o %s: $!\n", $mode, $name)
      unless $nonono;
}

sub copy {
    my($from,$to) = @_;

    print "  cp $from $to\n";
    print "  creating new version of $to\n" if $Is_VMS and -e $to;
    File::Copy::copy($from, $to)
	|| warn "Couldn't copy $from to $to: $!\n"
      unless $nonono;
    $packlist->{$to} = { type => 'file' };
}

sub samepath {
    my($p1, $p2) = @_;

    return (lc($p1) eq lc($p2)) if $Is_W32;

    if ($p1 ne $p2) {
	my($dev1, $ino1, $dev2, $ino2);
	($dev1, $ino1) = stat($p1);
	($dev2, $ino2) = stat($p2);
	($dev1 == $dev2 && $ino1 == $ino2);
    }
    else {
	1;
    }
}

sub installlib {
    my $dir = $File::Find::dir;
    $dir =~ s#^\.(?![^/])/?##;
    local($depth) = $dir ? "lib/$dir" : "lib";

    my $name = $_;

    # Ignore RCS and CVS directories.
    if (($name eq 'CVS' or $name eq 'RCS') and -d $name) {
	$File::Find::prune = 1;
	return;
    }
    
    # ignore patch backups, RCS files, emacs backup & temp files and the
    # .exists files.
    return if $name =~ m{\.orig$|~$|^#.+#$|,v$|^\.exists};

    $name = "$dir/$name" if $dir ne '';

    my $installlib = $installprivlib;
    if ($dir =~ /^auto/ ||
	  ($name =~ /^(.*)\.(?:pm|pod)$/ && $archpms{$1}) ||
	  ($name =~ /^(.*)\.(?:h|lib)$/i && $Is_W32)
       ) {
        $installlib = $installarchlib;
	return unless $do_installarchlib;
    } else {
	return unless $do_installprivlib;
    }

    if (-f $_) {
	if (/\.(?:al|ix)$/ && !($dir =~ m[^auto/(.*)$] && $archpms{$1})) {
	    $installlib = $installprivlib;
	    #We're installing *.al and *.ix files into $installprivlib,
	    #but we have to delete old *.al and *.ix files from the 5.000
	    #distribution:
	    #This might not work because $archname might have changed.
	    unlink("$installarchlib/$name");
	}
        $packlist->{"$installlib/$name"} = { type => 'file' };
	if (compare($_, "$installlib/$name") || $nonono) {
	    unlink("$installlib/$name");
	    mkpath("$installlib/$dir", 1, 0777);
	    # HP-UX (at least) needs to maintain execute permissions
	    # on dynamically-loaded libraries.
	    copy_if_diff($_, "$installlib/$name")
		and chmod($name =~ /\.(so|$dlext)$/o ? 0555 : 0444,
			   "$installlib/$name");
	}
    }
}

# Copy $from to $to, only if $from is different than $to.
# Also preserve modification times for .a libraries.
# On some systems, if you do
#   ranlib libperl.a
#   cp libperl.a /usr/local/lib/perl5/archlib/CORE/libperl.a
# and then try to link against the installed libperl.a, you might
# get an error message to the effect that the symbol table is older
# than the library.
# Return true if copying occurred.

sub copy_if_diff {
    my($from,$to)=@_;
    return 1 if (($^O eq 'VMS') && (-d $from));
    -f $from || warn "$0: $from not found";
    $packlist->{$to} = { type => 'file' };
    if (compare($from, $to) || $nonono) {
	safe_unlink($to);   # In case we don't have write permissions.
        if ($nonono) {
            $from = $depth . "/" . $from if $depth;
        }
	copy($from, $to);
	# Restore timestamps if it's a .a library or for OS/2.
	if (!$nonono && ($Is_OS2 || $to =~ /\.a$/)) {
	    my ($atime, $mtime) = (stat $from)[8,9];
	    utime $atime, $mtime, $to;
	}
	1;
    }
}

sub strip
{
    my(@args) = @_;

    return unless $dostrip;

    my @opts;
    while (@args && $args[0] =~ /^(-\w+)$/) {
        push @opts, shift @args;
    }

    foreach my $file (@args) {
        if (-f $file) {
            print "  strip $file\n";
            system("strip", @opts, $file);
        } else {
            print "# file '$file' skipped\n";
        }
    }
}