#!/usr/bin/perl

## [TO THE DEVELOPER OR HISTORIAN:  SEARCH FOR COMMENT(S) MARKED "##"]

# (If "which perl" indicates a different path to perl, we recommend 
#  that you (or your system administrator) create a symbolic link to it 
#  at  /usr/bin/perl, so that you don't have to change the above path 
#  in this script and the other scripts in this distribution; 
#  this is the syntax:
#	ln  -s  <wherever perl is>  /usr/bin/perl
#  where "<wherever perl is>" is replaced by the path shown by "which perl".)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Variables within this block must be set correctly for the specific 
#  distribution

# Set the names of the new release and the previous release
$newrelname = "V2.2";
$oldrelname = "V2.00";
$oldrelnamebrev = "v200";

# For $oldrelname before "V2.00", $old_build_script_name = "build" and 
#  $old_build_env_script_name = "build-env";
# for $oldrelname of "V2.00" or later, $old_build_script_name = "build.pl" 
#  and $old_build_env_script_name = "build-env.pl"
$build_script_name_base = "build";
$build_env_script_name_base = "build-env";
$old_build_script_name = "${build_script_name_base}.pl";
$old_build_env_script_name = "${build_env_script_name_base}.pl";
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

$timestamp = `date +"%Y%m%d%H%M%S"`;
chomp ($timestamp);

# Take the name of the current working directory as the server name
#  (On fleetlink, data server root directories are under /data1/.)
#  (On globec, the data server root directory is under /data5/.)
$cwdpath = `pwd`;
chomp $cwdpath;
@cwdfields = split (/\//, $cwdpath);
$servername = $cwdfields[$#cwdfields];

# Get the name of this script from the last element of its path 
#  (i.e., following last '/')
@thisscriptpathfields = split (/\//, $0);
$thisscriptname = $thisscriptpathfields[$#thisscriptpathfields];

# Get the new release tag from the beginning of the script's name 
#  (before first '_')
@thisscriptnamefields = split (/_/, $thisscriptname);
$newreleasetag = $thisscriptnamefields[0];
$newreleasetaglc = length $newreleasetag;

# Set the terminating substring identifying the gzipped tar files 
#  containing the actual new distribution and the previous distribution
$dontuntarfilestring = "dontuntar_file";
$dontuntarfilestringlc = length $dontuntarfilestring;

# Set the terminating substring identifying the gzipped tar file 
#  containing the extra files needed if this is an upgrade
$specialwrap1string = "specialwrap1";
$specialwrap1stringlc = length $specialwrap1string;

# Set up names of the two files that this script requires 
#  to be unpacked from the "specialwrap1" file if preparing for an upgrade
$oldreleasetag = "jgofs-${oldrelname}";
$oldreldontuntarfilename = "${oldreleasetag}_${dontuntarfilestring}";
$getoldrelsitediffsname = "get_${oldrelnamebrev}_site_diffs.pl";

# Set up names for "upgrade prep" and "fresh install" log files 
#  (only one of which will be used)
$upgrade_prep_logfile = "log_${newreleasetag}_1upgrade_prep_${timestamp}";
$fresh_install_logfile = "log_${newreleasetag}_1install_${timestamp}";

# Set up name of the $oldrelname installation backup gzipped tar file.
$oldrelbackupfilename = "${servername}_${oldreleasetag}_backup_${timestamp}.tz";

# Set up name for temp directory for uncustomized $oldrelname distribution, 
#  for use in upgrade preparation
$jgofs_oldrel_dist_root = "/tmp/${oldreleasetag}_${timestamp}";

# Set up name for site customization diffs file, for use in upgrade 
#  preparation
$diffsfilename = "${servername}_${oldrelname}diffs.output";

# Set up name for root directory under which to save convenience copies 
#  of customized files from installed $oldrelname data server
$customcopyrootname = "./${servername}_${oldrelname}customcopyroot";


print "Begin  ${thisscriptname}  ...\n";
print "\n";
print "Begin checking this directory and the ${newrelname} distribution ...\n";

# Make a list of files in this directory
@filesindir = `/bin/ls -A`;
chomp (@filesindir);

# Find any .tar files
foreach (@filesindir) {
    @filenamefields = split (/\./);
    if ($filenamefields[$#filenamefields] eq "tar") {
	push (@dottarfilesindir, $_);
    }
}

# Check each .tar file for this script; there must be exactly one
$ndottarfileswiththisscript = 0;
foreach $dottarfile (@dottarfilesindir) {
    @dottarfilesls = `tar tf $dottarfile | cut -f 2 -d'/'`;
    chomp (@dottarfilesls);
    if ($dottarfilesls[0] eq "") {
	shift @dottarfilesls;
    }
    foreach $fileindottarfile (@dottarfilesls) {
	if ($fileindottarfile eq $thisscriptname) {
	    ++$ndottarfileswiththisscript;
	    $outertarfilename = $dottarfile;
	    last;
	}
    }
}
if ($ndottarfileswiththisscript != 1) {
    &print_usage_err_msg;
    exit -1;
}

# Check that the name of the .tar file containing this script starts with 
#  the same string ($newreleasetag) as this script's name
if (substr ($outertarfilename, 0, $newreleasetaglc) ne $newreleasetag) {
    print STDERR "\nERROR:  The tar file containing  ${thisscriptname}\n";
    print STDERR " is named  ${outertarfilename}; its name should begin \"${newreleasetag}\";\n";
    print STDERR " either the tar file has the wrong content or it has been renamed;\n";
    print STDERR " you should resolve this problem and start over.\n";
    exit -1;
}

# Create list of all files that should have been unpacked from the .tar file 
#  containing this script, and add the name of that .tar file to the list
@outertarfilels = `tar tf $outertarfilename | cut -f 2 -d'/'`;
chomp (@outertarfilels);
if ($outertarfilels[0] eq "") {
    shift @outertarfilels;
}
@newdistfilenames = (@outertarfilels, $outertarfilename);

# Now check that we have: 
#  the tar file (whose name must start with $newreleasetag) 
#        that contains this script, 
#  and the files unpacked from it, 
#    exactly one of whose names ends with $dontuntarfilestring 
#        and starts with $newreleasetag, 
#    and exactly one of whose names ends with $specialwrap1string 
#        and starts with $newreleasetag (this check done only if upgrading);
#  and either:
#    - no other files [fresh install], or 
#    - additional files, including both $old_build_script_name and 
#        $old_build_env_script_name [upgrade]

$nnewdistfiles = 0;
$nnewdistdontuntarfiles = 0;
$nnewdistspecialwrap1s = 0;
$nnotnewdistfiles = 0;
foreach $fileindir (@filesindir) {
    $isanewdistfilename = 0;
    foreach $newdistfilename (@newdistfilenames) {
	if ($fileindir eq $newdistfilename) {
	    $isanewdistfilename = 1;
	    ++$nnewdistfiles;
	    if (substr ($newdistfilename, -$dontuntarfilestringlc, 
			$dontuntarfilestringlc) eq $dontuntarfilestring) {
	        $newreldontuntarfilename = $newdistfilename;
		++$nnewdistdontuntarfiles;
	    } elsif (substr ($newdistfilename, -$specialwrap1stringlc, 
			     $specialwrap1stringlc) eq $specialwrap1string) {
	        $newrelspecialwrap1name = $newdistfilename;
		++$nnewdistspecialwrap1s;
	    }
	    last;
	}
    }
    unless ($isanewdistfilename) {
	++$nnotnewdistfiles;
	@notnewdistfilenames = (@notnewdistfilenames, $_);
    }
}
if ($nnewdistfiles != $#newdistfilenames + 1) {
    # Not everything from the new install/upgrade distribution is present 
    #  in this directory
    &print_usage_err_msg;
    exit -1;
}

if ($nnewdistdontuntarfiles != 1) {
    # Either the new distribution's "dontuntar_file" is missing 
    #  or there's more than one
    &print_distrib_err_msg;
    &offer_clean_up_and_quit;
}

# Check that  $newreldontuntarfilename  starts with 
#  the same string ($newreleasetag) as this script's name
if (substr ($newreldontuntarfilename, 0, $newreleasetaglc) ne 
							$newreleasetag) {
    &print_distrib_err_msg;
    &offer_clean_up_and_quit;
}


# Determine whether upgrade or fresh install
if ($nnotnewdistfiles > 0) {

    #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # This directory contains files in addition to the $newrelname 
    #  install/upgrade .tar file and the files unpacked from it, so this 
    #  should be the root directory of an existing $oldrelname installation.
    # Check that files $old_build_script_name and $old_build_env_script_name 
    #  are here and, if they are, prepare for the upgrade.
    # (For the case of no files in the directory except the $newrelname 
    #  install/upgrade files, see below, following a comment marked off like 
    #  this one.)
    #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    # Continue checking the consistency and integrity of the contents 
    #  of $outertarfilename, checking files needed in preparing to upgrade

    if ($nnewdistspecialwrap1s != 1) {
	# Either the new distribution's "specialwrap1" file is missing 
	#  or there's more than one
	&print_distrib_err_msg;
	&offer_clean_up_and_quit;
    }

    # Check that  $newrelspecialwrap1name  starts with 
    #  the same string ($newreleasetag) as this script's name
    if (substr ($newrelspecialwrap1name, 0, $newreleasetaglc) ne 
							$newreleasetag) {
	&print_distrib_err_msg;
	&offer_clean_up_and_quit;
    }


    # Check that this looks like the root directory of a $oldrelname data server
    unless (-e $old_build_script_name && -e $old_build_env_script_name) {
        # Not a fresh directory, but $old_build_script_name and/or 
	#  $old_build_env_script_name not found
	&print_usage_err_msg;
	&offer_clean_up_and_quit;
    }


    # Check that the  $newrelspecialwrap1name  file is a gzipped tar file
    if (system ("tar tfz ${newrelspecialwrap1name} >/dev/null 2>&1")) {
	&print_distrib_err_msg;
	&offer_clean_up_and_quit;
    }

    # Make a list of the files in the  $newrelspecialwrap1name  file
    @newrelspecialwrap1ls = `tar tfz $newrelspecialwrap1name | cut -f 2 -d'/'`;
    chomp (@newrelspecialwrap1ls);
    if ($newrelspecialwrap1ls[0] eq "") {
	shift @newrelspecialwrap1ls;
    }

    # Check that the  $newrelspecialwrap1name  file contains files 
    #  $oldreldontuntarfilename  and  $getoldrelsitediffsname .
    # (It should also contain  jgofs-${newrelname}_2upgrade_script.pl  and  
    #  jgofs-${newrelname}_specialwrap2, but we'll leave concern with them 
    #  for the second stage of the upgrade procedure.)

    $foundrequiredfiles = 0;
    $foundoldreldontuntarfilename = 0;
    $foundgetoldrelsitediffsname = 0;
    foreach $fileinnewspecialwrap1 (@newrelspecialwrap1ls) {
	unless ($foundoldreldontuntarfilename) {
	    if ($fileinnewspecialwrap1 eq $oldreldontuntarfilename) {
		$foundoldreldontuntarfilename = 1;
		next;
	    }
	}
	unless ($foundgetoldrelsitediffsname) {
	    if ($fileinnewspecialwrap1 eq $getoldrelsitediffsname) {
		$foundgetoldrelsitediffsname = 1;
		next;
	    }
	}
    } continue {
	if ($foundoldreldontuntarfilename && $foundgetoldrelsitediffsname) {
	    $foundrequiredfiles = 1;
	    last;
	}
    }
    unless ($foundrequiredfiles) {
	&print_distrib_err_msg;
	&offer_clean_up_and_quit;
    }

    print "... This directory looks like the root of a JGOFS ${oldrelname} data server,\n";
    print "       and the ${newrelname} distribution looks OK.\n";


    # Start logging, in $upgrade_prep_logfile
    system ("echo \"Begin  ${thisscriptname}:\" >${upgrade_prep_logfile}");
    system ("echo \"       Preparing to upgrade from ${oldreleasetag} ...\" >>${upgrade_prep_logfile}");


    # Unpack  $newrelspecialwrap1name  into the current working directory
    print "\n";
    print "Begin unpacking  ${newrelspecialwrap1name}  ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin unpacking  ${newrelspecialwrap1name}  ...\" >>${upgrade_prep_logfile}");
    system ("echo \"tar xfvzp ${newrelspecialwrap1name} >>${upgrade_prep_logfile} 2>&1\" >>${upgrade_prep_logfile}");
    if (system ("tar xfvzp ${newrelspecialwrap1name} >>${upgrade_prep_logfile} 2>&1")) {
	system ("echo \"ERROR:  Unpacking  ${newrelspecialwrap1name}  failed.\" >>${upgrade_prep_logfile}");
	system ("echo \" It is a gzipped tar file; there was a problem untarring it.\" >>${upgrade_prep_logfile}");
	print STDERR 
	    "ERROR:  Unpacking  ${newrelspecialwrap1name}  failed.\n";
	print STDERR
	    " It is a gzipped tar file; there was a problem untarring it.\n";
	exit -1;
    }
    system ("echo \"... Finished unpacking  ${newrelspecialwrap1name}.\" >>${upgrade_prep_logfile}");
    print "... Finished unpacking  ${newrelspecialwrap1name}.\n";


    # Back up (tar) existing installation
    ##  [For future development:  This section isn't generalized: 
    ##   it assumes V2.00 root directory contents]
    print "\n";
    print "Begin backing up existing ${oldrelname} installation ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin backing up existing ${oldrelname} installation\" >>${upgrade_prep_logfile}");
    system ("echo \"       to  ./${oldrelbackupfilename}  ...\" >>${upgrade_prep_logfile}");
    system ("echo \"tar cfvz  ./${oldrelbackupfilename}  ./${old_build_script_name}  ./${build_script_name_base}.doc  ./${old_build_env_script_name}  ./${build_env_script_name_base}.doc  ./RELEASE_NOTES  ./README_${oldreleasetag}_INSTALL_NEW  ./README_${oldreleasetag}_INSTALL_UPGRADE  ./bin  ./htmlbin  ./images  ./methods  ./objects  ./src  >>${upgrade_prep_logfile} 2>&1\" >>${upgrade_prep_logfile}");
    if (system ("tar cfvz  ./${oldrelbackupfilename}  ./${old_build_script_name}  ./${build_script_name_base}.doc  ./${old_build_env_script_name}  ./${build_env_script_name_base}.doc  ./RELEASE_NOTES  ./README_${oldreleasetag}_INSTALL_NEW  ./README_${oldreleasetag}_INSTALL_UPGRADE  ./bin  ./htmlbin  ./images  ./methods  ./objects  ./src  >>${upgrade_prep_logfile} 2>&1")) {
	system ("echo \"ERROR:  Creating  ./${oldrelbackupfilename}  failed.\" >>${upgrade_prep_logfile}");
	print STDERR "ERROR:  Creating  ./${oldrelbackupfilename}  failed.\n";
	exit -1;
    }
    system ("echo \"... Finished backing up existing ${oldrelname} installation\" >>${upgrade_prep_logfile}");
    system ("echo \"       to  ./${oldrelbackupfilename}.\" >>${upgrade_prep_logfile}");
    print "... Finished backing up existing ${oldrelname} installation\n";
    print "       to  ./${oldrelbackupfilename}.\n";

 
    # Create temp directory to unpack original $oldrelname distribution 
    #  for comparison with the existing installation
    print "\n";
    print "Creating temp directory  ${jgofs_oldrel_dist_root}\n";
    print "       to unpack original ${oldrelname} distribution.\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Create temp directory to unpack original ${oldrelname} distribution:\" >>${upgrade_prep_logfile}");
    system ("echo \"mkdir  ${jgofs_oldrel_dist_root}\" >>${upgrade_prep_logfile}");
    unless (mkdir ($jgofs_oldrel_dist_root, 0755)) {
	system ("echo \"ERROR:  Can't create temp directory to unpack original ${oldrelname} distribution.\" >>${upgrade_prep_logfile}");
	print STDERR "ERROR:  Can't create temp directory to unpack original ${oldrelname} distribution.\n";
	exit -1;
    }


    # Unpack the gzipped $oldrelname distribution .tar file 
    #  into the temp directory created for it
    print "Begin unpacking original ${oldrelname} distribution into temp directory ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin unpacking original ${oldrelname} distribution into temp directory ...\" >>${upgrade_prep_logfile}");
    system ("echo \"tar xfvzp ${oldreldontuntarfilename} -C ${jgofs_oldrel_dist_root} >>${upgrade_prep_logfile} 2>&1\" >>${upgrade_prep_logfile}");
    if (system ("tar xfvzp ${oldreldontuntarfilename} -C ${jgofs_oldrel_dist_root} >>${upgrade_prep_logfile} 2>&1")) {
	system ("echo \"ERROR:  Unpacking  ${oldreldontuntarfilename}  failed.\" >>${upgrade_prep_logfile}");
	system ("echo \" It should be a gzipped tar file; there was a problem untarring it.\" >>${upgrade_prep_logfile}");
	print STDERR 
	    "ERROR:  Unpacking  ${oldreldontuntarfilename}  failed.\n";
	print STDERR
	    " It should be a gzipped tar file; there was a problem untarring it.\n";
	exit -1;
    }
    system ("echo \"... Finished unpacking original ${oldrelname} distribution into temp directory.\" >>${upgrade_prep_logfile}");
    print "... Finished unpacking original ${oldrelname} distribution into temp directory.\n";

    # Use the  $getoldrelsitediffsname  script to generate the diffs file 
    #  showing local customizations of the existing $oldrelname installation
    print "\n";
    print "Launching script to identify ${oldrelname} site customizations:\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Launching script to identify ${oldrelname} site customizations\" >>${upgrade_prep_logfile}");
    system ("echo \"(A line reporting that  ${getoldrelsitediffsname}  finished should follow:)\" >>${upgrade_prep_logfile}");
    @ARGV = ();
    require $getoldrelsitediffsname;
    system ("echo \"... Finished  ${getoldrelsitediffsname};\" >>${upgrade_prep_logfile}");
    system ("echo \"       see file  ${diffsfilename}  for the results.\" >>${upgrade_prep_logfile}");

    # Clear out the temp  $jgofs_oldrel_dist_root tree
    print "\n";
    print "Begin removing the unpacked unmodified ${oldrelname} distribution ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin removing the unpacked unmodified ${oldrelname} distribution ...\" >>${upgrade_prep_logfile}");
    system ("echo \"rm -rf ${jgofs_oldrel_dist_root}\" >>${upgrade_prep_logfile}");
    system ("rm -rf ${jgofs_oldrel_dist_root}");
    system ("echo \"... Finished removing the unpacked unmodified ${oldrelname} distribution.\" >>${upgrade_prep_logfile}");
    print "... Finished removing the unpacked unmodified ${oldrelname} distribution.\n";

    ### Make the already-used  $getoldrelsitediffsname  script non-executable
    ##system ("echo \"chmod 644 ${getoldrelsitediffsname}\" >>${upgrade_prep_logfile}");
    ##chmod (0644, $getoldrelsitediffsname);


    # Remove no-longer-needed files unpacked from  
    #  $outertarfilename  and  $newrelspecialwrap1name
    print "\n";
    print "Begin removing no-longer-needed files used for upgrade preparation ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin removing no-longer-needed files used for upgrade preparation ...\" >>${upgrade_prep_logfile}");
    system ("echo \"rm ${getoldrelsitediffsname}\" >>${upgrade_prep_logfile}");
    unlink ($getoldrelsitediffsname);
    system ("echo \"rm ${oldreldontuntarfilename}\" >>${upgrade_prep_logfile}");
    unlink ($oldreldontuntarfilename);
    system ("echo \"rm ${newrelspecialwrap1name}\" >>${upgrade_prep_logfile}");
    unlink ($newrelspecialwrap1name);
    system ("echo \"... Finished removing no-longer-needed files used for upgrade preparation.\" >>${upgrade_prep_logfile}");
    print "... Finished removing no-longer-needed files used for upgrade preparation.\n";


    # Scan the diffs file and save convenience copies of any files that were 
    #  customized

    print "\n";
    print "Begin making convenience copies of site-customized ${oldrelname} files ...\n";
    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"Begin making convenience copies of site-customized ${oldrelname} files ...\" >>${upgrade_prep_logfile}");
    unless (open (DIFFSFILE, $diffsfilename)) {
	print "Can't open file  ${diffsfilename}  for input.\n";
	exit -1;
    }
    $maybe_a_customfile = 0;
    while (<DIFFSFILE>) {
	if (substr ($_, 0, 9) eq "******** ") {
	    chomp;
	    @inputlinefields = split (/ /);
	    $candidatefilepath = $inputlinefields[1];
	    $maybe_a_customfile = 1;
	} elsif ($_ eq "\n") {
	    $maybe_a_customfile = 0;
	} else {
	    if ($maybe_a_customfile) {
		chomp;
		# Save a copy of the file, which shows diffs
		@customfilepathfields = split (/\//, $candidatefilepath);
		$customfilename = pop (@customfilepathfields);
		$customfiledir = join ("/", @customfilepathfields);
		unless (-e "${customcopyrootname}/${customfiledir}") {
		    system ("mkdir -p ${customcopyrootname}/${customfiledir}");
		}
		print "cp -p ./${candidatefilepath} ${customcopyrootname}/${candidatefilepath}\n";
		system ("echo \"cp -p ./${candidatefilepath} ${customcopyrootname}/${candidatefilepath}\" >>${upgrade_prep_logfile}");
		system ("cp -p ./${candidatefilepath} ${customcopyrootname}/${candidatefilepath}");
		$maybe_a_customfile = 0;
	    }
	}
    }
    system ("echo \"... Finished making convenience copies of site-customized ${oldrelname} files.\" >>${upgrade_prep_logfile}");
    print "... Finished making convenience copies of site-customized ${oldrelname} files.\n";


    system ("echo \"\" >>${upgrade_prep_logfile}");
    system ("echo \"...  ${thisscriptname}  is done.\" >>${upgrade_prep_logfile}");

    # That's all for the initial installation script; 
    # now the installer has to plan site customizations
    print "\n";
    print "...  ${thisscriptname}  is done.\n\n";
    print "Now check  ${upgrade_prep_logfile}  for\n";
    print "  any problems, and note the site customizations detailed in\n";
    print "  file  ${diffsfilename}  (referring to the explanations\n";
    print "  in step (1) in file  README_${newreleasetag}_INSTALL_UPGRADE).\n";
    print "Then continue the upgrade with step (2)\n";
    print "  in file  README_${newreleasetag}_INSTALL_UPGRADE.\n\n";


} else {

    #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # This directory contains no files except the $newrelname install/upgrade 
    #  .tar file and the files unpacked from it, so we will do a fresh 
    #  $newrelname install here.
    # (For the case of additional files found in the directory, see above, 
    #  following a comment marked off like this one.)
    #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    print "... This directory looks OK for a new JGOFS ${newrelname} data server,\n";
    print "       and the ${newrelname} distribution looks OK.\n";

    system ("echo \"Begin  ${thisscriptname}:\" >${fresh_install_logfile}");
    system ("echo \"       Creating a new ${newreleasetag} data server ...\" >>${fresh_install_logfile}");

    # The $newreldontuntarfilename file should be a gzipped tar file; 
    #  unpack it into this directory

    print "\n";
    print "Begin unpacking the JGOFS ${newrelname} distribution ...\n";
    system ("echo \"\" >>${fresh_install_logfile}");
    system ("echo \"Begin unpacking the JGOFS ${newrelname} distribution ...\" >>${fresh_install_logfile}");
    system ("echo \"tar xfvzp ${newreldontuntarfilename} >>${fresh_install_logfile} 2>&1\" >>${fresh_install_logfile}");
    # [THE FOLLOWING COMMENT AND COMMENTED-OUT "tar" COMMAND ARE FROM 
    #  oo2008_initial_script.pl; BUT NOW I DON'T FIND WHAT IT SAYS TO BE 
    #  TRUE, SO I AM REDIRECTING stderr HERE.]
    ### I don't redirect stderr in the following system call, because it doesn't 
    ###  work, and it causes the value returned by the system call to be 0 
    ###  instead of 512 when $newreldontuntarfilename isn't a gzipped tar file
    ##if (system ("tar xfvzp ${newreldontuntarfilename} >>${fresh_install_logfile}")) {
    if (system ("tar xfvzp ${newreldontuntarfilename} >>${fresh_install_logfile} 2>&1")) {
	system ("echo \"ERROR:  Unpacking  ${newreldontuntarfilename}  failed.\" >>${fresh_install_logfile}");
	system ("echo \" It should be a gzipped tar file; there was a problem untarring it.\" >>${fresh_install_logfile}");
	print STDERR 
	    "ERROR:  Unpacking  ${newreldontuntarfilename}  failed.\n";
	print STDERR
	    " It should be a gzipped tar file; there was a problem untarring it.\n";
	exit -1;
    }
    system ("echo \"... Finished unpacking the JGOFS ${newrelname} distribution.\" >>${fresh_install_logfile}");
    print "... Finished unpacking the JGOFS ${newrelname} distribution.\n";

    # Since this is a fresh directory and the installer will need to merge 
    #  library customizations (if any) after this script finishes, we'll copy 
    #  src/lib/_makefile_.jgofs to src/lib/makefile.jgofs now, 
    #  freeing the user from the need to do anything with it if there are 
    #  no library customizations
    print "\n";
    print "Installing  src/lib/makefile.jgofs  ...\n";
    system ("echo \"\" >>${fresh_install_logfile}");
    system ("echo \"Installing  src/lib/makefile.jgofs  ...\" >>${fresh_install_logfile}");
    unless (-e "src/lib/_makefile_.jgofs") {
	system ("echo \"ERROR IN DISTRIBUTION:  src/lib/_makefile_.jgofs  not found.\" >>${fresh_install_logfile}");
	print STDERR 
	    "ERROR IN DISTRIBUTION:  src/lib/_makefile_.jgofs  not found.\n";
	exit -1;
    }
    system ("echo \"cp -p  src/lib/_makefile_.jgofs  src/lib/makefile.jgofs\" >>${fresh_install_logfile}");
    if (system ("cp -p  src/lib/_makefile_.jgofs  src/lib/makefile.jgofs")) {
	system ("echo \"ERROR:  Copying  src/lib/_makefile_.jgofs  to  src/lib/makefile.jgofs  failed.\" >>${fresh_install_logfile}");
	print STDERR "ERROR:  Copying  src/lib/_makefile_.jgofs\n";
	print STDERR "             to  src/lib/makefile.jgofs  failed.\n";
	exit -1;
    }
    system ("echo \"Copied  src/lib/_makefile_.jgofs  to  src/lib/makefile.jgofs.\" >>${fresh_install_logfile}");
    print "... Finished installing  src/lib/makefile.jgofs.\n";

    ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ## THIS SECTION WAS WRITTEN BEFORE WE ADDED AN UNCONFIGURED  build-env.pl  
    ##  TO THE RELEASE (WITH DEFAULTS SET DIFFERENTLY THAN IN  _build-env_.pl); 
    ##  THIS SECTION IS NO LONGER NEEDED, AND SO IS COMMENTED OUT 
    ##  UNCONDITIONALLY.
    ## COMMENT OUT THIS SECTION IF $newrelname IS LESS THAN "V2.1":
    ## Since this is a fresh directory and the installer will need to merge 
    ##  site customizations into  build-env.pl  after this script finishes, 
    ##  we'll copy  _build-env_.pl  to  build-env.pl  now, freeing the user 
    ##  from the need to rename it after doing the needed customizations
    ##print "\n";
    ##print "Installing  build-env.pl  ...\n";
    ##system ("echo \"\" >>${fresh_install_logfile}");
    ##system ("echo \"Installing  build-env.pl  ...\" >>${fresh_install_logfile}");
    ##unless (-e "_build-env_.pl") {
	##system ("echo \"ERROR IN DISTRIBUTION:  _build-env_.pl  not found.\" >>${fresh_install_logfile}");
	##print STDERR 
	##    "ERROR IN DISTRIBUTION:  _build-env_.pl  not found.\n";
	##exit -1;
    ##}
    ##system ("echo \"cp -p  _build-env_.pl  build-env.pl\" >>${fresh_install_logfile}");
    ##if (system ("cp -p  _build-env_.pl  build-env.pl")) {
	##system ("echo \"ERROR:  Copying  _build-env_.pl  to  build-env.pl  failed.\" >>${fresh_install_logfile}");
	##print STDERR "ERROR:  Copying  _build-env_.pl\n";
	##print STDERR "             to  build-env.pl  failed.\n";
	##exit -1;
    ##}
    ##system ("echo \"Copied  _build-env_.pl  to  build-env.pl.\" >>${fresh_install_logfile}");
    ##print "... Finished installing  build-env.pl.\n";
    ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


    # Remove unneeded/no-longer-needed files unpacked from $outertarfilename
    print "\n";
    print "Begin removing unneeded/no-longer-needed files\n";
    print "       unpacked from  ${outertarfilename}  ...\n";
    system ("echo \"\" >>${fresh_install_logfile}");
    system ("echo \"Begin removing unneeded/no-longer-needed files\" >>${fresh_install_logfile}");
    system ("echo \"       unpacked from  ${outertarfilename}  ...\" >>${fresh_install_logfile}");
    system ("echo \"rm ${newrelspecialwrap1name}\" >>${fresh_install_logfile}");
    unlink ($newrelspecialwrap1name);
    system ("echo \"rm ${newreldontuntarfilename}\" >>${fresh_install_logfile}");
    unlink ($newreldontuntarfilename);
    system ("echo \"... Finished removing unneeded/no-longer-needed files\" >>${fresh_install_logfile}");
    system ("echo \"       unpacked from  ${outertarfilename}.\" >>${fresh_install_logfile}");
    print "... Finished removing unneeded/no-longer-needed files\n";
    print "       unpacked from  ${outertarfilename}.\n";


    system ("echo \"\" >>${fresh_install_logfile}");
    system ("echo \"...  ${thisscriptname}  is done.\" >>${fresh_install_logfile}");

    # That's all for the initial installation script; 
    # now the installer has to do site customizations
    print "\n";
    print "...  ${thisscriptname}  is done.\n\n";
    print "Now check file  ${fresh_install_logfile}  for\n";
    print "  any problems.  Then, if all is well, continue the installation\n";
    print "  with step (2) in file README_${newreleasetag}_INSTALL_NEW.\n\n";
}


exit 0;



sub print_usage_err_msg
{
    print STDERR "\n";
    print STDERR "ERROR:  The ${newreleasetag} initial script must run in a\n";
    print STDERR " directory that contains a single copy of the main\n";
    print STDERR " ${newreleasetag} tar file; the files unpacked from it; and\n";
    print STDERR " EITHER\n";
    print STDERR "   no other files (for a new installation)\n";
    print STDERR " OR\n";
    print STDERR "   the files of the root of an existing ${oldrelname} installation\n";
    print STDERR "   (to upgrade to ${newrelname}).\n";
    print STDERR "\n";
    print STDERR "You should put the main ${newreleasetag} tar file into\n";
    print STDERR " either a newly-created directory\n";
    print STDERR " or the root directory of an existing ${oldrelname} installation;\n";
    print STDERR " then unpack the ${newreleasetag} tar file there, and\n";
    print STDERR " follow the directions in the  README_${newreleasetag}_INSTALL  file.\n";
}


sub print_distrib_err_msg
{
    print STDERR "\n";
    print STDERR "ERROR IN DISTRIBUTION:\n";
    print STDERR " The main ${newreleasetag} tar file contents must include:\n";
    print STDERR "   - File  ${thisscriptname}  (this script);\n";
    print STDERR "   - File  ${newreleasetag}_${dontuntarfilestring},\n";
    print STDERR "       and no other file whose name ends in \"${dontuntarfilestring}\";\n";
    print STDERR "   - File  ${newreleasetag}_${specialwrap1string},\n";
    print STDERR "       and no other file whose name ends in \"${specialwrap1string}\";\n";
    print STDERR "      it must be a gzipped tar file whose contents include files\n";
    print STDERR "       ${oldreldontuntarfilename}  and  ${getoldrelsitediffsname}.\n";
    print STDERR " The main ${newreleasetag} tar file here doesn't meet these conditions.\n";
}


sub offer_clean_up_and_quit
{
    print "\n";
    print "Ready to clean out files unpacked from ${outertarfilename};";
    do {
	print " proceed? (y/n) ";
	$reply = substr (<STDIN>, 0, 1);
    } until ($reply eq "y" || $reply eq "Y" || $reply eq "n" || $reply eq "N");
    if ($reply eq "y" || $reply eq "Y") {
	foreach (@outertarfilels) {
	    print "    Removing $_ ...\n";
	    unlink;
	}
	print "Done.\n";
    }
    exit 1;
}