%-----------------------------------------------------------------------
%;  Copyright (C) 1995-1996, 2001
%;  Associated Universities, Inc. Washington DC, USA.
%;
%;  This program is free software; you can redistribute it and/or
%;  modify it under the terms of the GNU General Public License as
%;  published by the Free Software Foundation; either version 2 of
%;  the License, or (at your option) any later version.
%;
%;  This program is distributed in the hope that it will be useful,
%;  but WITHOUT ANY WARRANTY; without even the implied warranty of
%;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%;  GNU General Public License for more details.
%;
%;  You should have received a copy of the GNU General Public
%;  License along with this program; if not, write to the Free
%;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
%;  MA 02139, USA.
%;
%;  Correspondence concerning AIPS should be addressed as follows:
%;          Internet email: aipsmail@nrao.edu.
%;          Postal address: AIPS Project Office
%;                          National Radio Astronomy Observatory
%;                          520 Edgemont Road
%;                          Charlottesville, VA 22903-2475 USA
%-----------------------------------------------------------------------
\input NRAO_MACROS.TEX
\input FORTRAN.TEX

\title{AIPS ``Quarterly'' Update Procedures} \ \vskip 2cm
\centerline{\nraofont The AIPS ``Quarterly'' Update Procedures} \medskip
\centerline{Most recently changed on 1998/09/17 04:04:43 (UT)} \bigskip
\centerline{Patrick P.~Murphy} \bigskip
\bigskip

This document attempts to cover what is necessary for the ``bi-annual''
(formerly quarterly) update, when a new version of AIPS is created and
the old one gets shipped.  It also covers some, and hopefully most, of
the procedures necessary at the AOC and other ``midnight job'' sites.
Material that is specific to Charlottesville is indented and preceded
with the heading ``CV:''.

\newsection Preliminaries

\newsubsection Let Everyone Know It's Imminent

\item{CV:} send out mail to all the real people in the list {\tt
/aips1/master/access} as well as the \AIPS\ managers at other sites that
run the MNJ (currently: Caltech, Bonn, CfA; additional possibility:
Jodrell).  There is a mailing list on orangutan called ``mnj'' that you
can use by emailing to {\tt mnj@orangutan.cv.nrao.edu} that will reach
the keepers of the jobs.  Let the ``access'' and ``mnj'' users know that
you're about to start the quarterly update and thereby freeze the AIPS
checkout system.  Co-ordinate the timing with them.

\noindent For all sites, the file {\tt\$AIPS\_ROOT/AIPS.MSG} should be
edited to include an appropriate notice.  This file is printed out
whenever someone tries to start up AIPS.  You should edit this file and
indicate that the quarterly update is about to start.  Also make sure
that all aips root areas get covered (in CV, just {\tt /AIPS}; at the
AOC: {\tt /AIPS} on {\tt kiowa}, {\tt aguila}, and {\tt sol}; at the
VLA: {\tt /AIPS} on {\tt miranda}.

Consider also having the notice added to {\tt /etc/motd} on the more
commonly used systems (polaris, rhesus, ringtail, siamang, zia, {\it
etc\/}. regardless of whether they run AIPS or not; the point is to get
the message out to users who might be impacted) and maybe even post a
notice in the various \AIPS\ cages.  {\it Keep the users informed\/} as
you make progress by updating the message in these files.

If you use symbolic links (as is done in CV, e.g. {\tt
/AIPS/15APR97/ALPHA/LOAD} is a symbolic link to a directory that is
physically on our workhorse Alpha system, siamang), you may want to
check for these with a command like:\medskip

\example{find 15APR97 -type l -ls}\medskip

\newsubsection Stopping the Midnight Jobs

The following machines are currently served off baboon.  The midnight
jobs run as a crontab entry which calls something like {\tt
do\_daily.<host>} in the login area of {\tt aipsmgr}, currently {\tt
/AIPS}.  For all of the midnight jobs, you should just edit this file
and uncomment the ``{\tt exit}'' before the {\tt cd /AIPS} line.  All
the machines in Charlottesville, even the backward-byte ones, share the
same {\tt /AIPS} partition on polaris.
\medskip

\item{$\bullet$} {\tt rhesus}, the IBM RS6000/580 system.  It supplies
		 binaries for ringtail as well.
\item{$\bullet$} {\tt gibbon}, a SparcStation 20/151 running SunOS 5.4.
		 It also supplies binaries for the SOL architecture to
		 all CV-based SunOS 5 systems.
\item{$\bullet$} {\tt siamang}, a Dec AlphaStation 5/266 running OSF/1
		 T3.2.  Eventually it will serve the other Alpha systems
		 (pongo -- needs an OS update, and future systems).
\item{$\bullet$} {\tt marmoset}, a Gateway 2000 486DX2/66 PC clone
		 running Linux 1.2.8 (a.out) for now; due for an update
		 to Linux 2.x (ELF) in November 1996.
\item{$\bullet$} {\tt aguila.aoc.nrao.edu} at the AOC has a midnight
		 job and it is the master in turn for other systems.
		 Edit file {\tt /AIPS/do\_daily.aguila} as above.
		 Have the AOC aips manager edit the corresponding
		 files on {\tt kiowa}, {\tt sol}, and {\tt miranda}.
\item{$\bullet$} {\tt sif.ncsa.uiuc.edu} at NCSA, one of the SGI Power
		 Challenge systems, runs a midnight job.  This is
		 currently administered from Charlottesville.
\item{$\bullet$} Three non-NRAO sites are currently running a MNJ from
		 baboon. These are Caltech, Bonn, and CfA.  There may be
		 more by the time you read this (Jodrell for one).
\medskip

\newsubsection Backups

The primary concern is to back up the OLD version, as that is probably
going to be deleted if disk space is tight (isn't it always?).  For
example, using the exabyte on gibbon from the {\tt aipsmgr} account in
CV, you would do:

\fortran
gibbon_aipsmgr<127> cd /AIPS
gibbon_aipsmgr<128> mt -f /dev/rmt/2ln rewind
gibbon_aipsmgr<129> tar cvfh /dev/rmt/2ln 15JAN96
\endfortran
\medskip

The first command {\tt cd} just puts you in the login area for the {\tt
aipsmgr} account, and the {\tt mt} command is probably not necessary as
exabyte tapes are almost always rewound when you first put them in the
drive.  The {\tt -h} option forces {\tt tar} to follow symbolic links
such as for the {\tt LOAD} areas of different architectures.

\item{CV:} {The master {\it RCS\/} files also need to be backed up.
These are in the {\tt /aips1/master} areas.  From account {\tt aipssrc},
you should do:\medskip

\fortran
baboon_aipssrc<130> cd /aips1/master
baboon_aipssrc<131> tar cvf /dev/nrst0 .
\endfortran
}
\medskip

\noindent At the AOC, you also need to back up each version that has its
own {\tt AIPS\_ROOT}.  Counting the VLA site, there may be four or more
of these as the IBM {\tt /AIPS} is different from that for the Suns.
Check with Frazer Owen for the large AP version; it also runs a MNJ.

\newsubsection Disable the Checkout System

\item{CV:}  You should have already sent out e-mail to all the people in
            the aips checkout list (see above).  When you are ready to
	    disable things, just create two files in the {\tt aipssrc}
	    login area called {\tt AIPS\_IS\_FROZEN.NEW} and {\tt
	    AIPS\_IS\_FROZEN.TST}.  This completely disables the {\tt
	    chkout} command and its siblings.  You should put messages
	    in these files, as they will get printed out anytime someone
	    tries to use the checkout system.  The {\tt .NEW} file will
	    probably already exist but should be edited to at least
	    reflect the newer version.\medskip

\item{CV:} You need to update the help list files ({\tt
	   \$HLPFIL/ZZ*.HLP}).  This is done via running the {\tt SHOPH}
	   shell script in {\tt\$SYSUNIX}.  You need to be in an area
	   other than the {\tt\$HLPFIL} area to do this.  Somewhere like
	   {\tt /tmp} or {\tt /AIPS/tmp/BABOON} will do.  The changed
	   files need to be formally {\tt putbck} in {\tt TST} and {\tt
	   NEW} after things are unfrozen. %%% note: reminder below???

\medskip

\newsection Performing the Update

\newsubsection Disk Space

Disk space may be a problem (You can get up after your roll on the floor
laughing now).  The {\tt /AIPS} partition which is on polaris in CV {\it
should\/} have enough space to work with, but you may have to delete the
OLD version to make room; if you do, be sure to edit the {\tt
AIPSPATH.SH} and {\tt AIPSPATH.CSH} to make OLD and NEW the same and
then document this in {\tt /AIPS/AIPS.MSG} and use {\tt rwall -n
aips\_hosts} to broadcast a message to all users.

\item{CV:} Check space on the architecture-specific directories on each
	   system (baboon, gibbon, siamang, tarsier/marmoset, rhesus).
	   It may be necessary to temporarily move OLD load, {\it
	   etc\/}.~to some other holding area.

However, if using shareable libraries (SunOS or elsewhere), do NOT build
that version in a temporary place!  The binaries will be looking for the
shareable libraries wherever they were first built so do it in the right
place first time!  I recommend against using shared libraries; they have
been far more trouble than they're worth over the last few years (IMHO).

Use the {\tt df} command to check for space on these partitions ({\tt df
-k} on SunOS 5).  You should make sure that there will be at least 300
megabytes free for the extra version that you are about to make, unless
you are using shared libraries (NOT recommended) in which case the
figure is closer to 200.  Add more if you are generating two sets of
libraries ({\tt\$SYSLOCAL/DOTWOLIB}), and {\it watch for the\/ {\tt
.EXE.OLD} files if you have\/ {\tt SAVE=TRUE} in\/ {\tt\$LDOPTS.SH}}; if
for any reason while rebuilding, you need to re-do {\tt INSTEP4} or part
thereof, these old binaries can quickly swell to increase the total size
of the version to over 500 megabytes.

\newsubsection Creating the Brand-New Version

\item{CV:}  From the {\tt aipsmgr} account, use the {\tt allout}
shell script in the {\tt \~{}aipssrc/bin} area.  You want to check out
all of TST into something like {\tt /AIPS/15APR97}.  Syntax: {\tt allout
TST /AIPS/15APR97 >allout.out 2>allout.err\&}

\noindent For other sites: Wait until the CV aips manager gives the OK
for copying the new version (\ie, {\tt allout} and {\tt adiff} completed
and differences resolved; see below), and then just copy the brand-new
version direct from {\tt aipsmgr@baboon.cv.nrao.edu:/AIPS}.  The CV aips
manager will give you the name of the compressed tar file ({\it e.g.\/}
{\tt 15APR97.tar.Z}) and you should try to remotely copy it with {\tt
rcp}.

\item{CV:} The file {\tt /AIPS/exclude.update} in CV lists areas that
	   should {\it not\/} be copied.  Make sure this file has the
	   right version date in it.  The command {\tt tar cvfXh
	   15APR97.tar exclude.update ./15APR97} will generate this
	   file, but be careful; under SunOS 5, the exclusion option did
	   not work for the binaries!  It worked fine on the Alpha.

\medskip\noindent At the AOC, this new area can be copied (using the
{\tt -p} option!) to {\tt kiowa}, {\tt miranda} (also maybe {\tt sol}?).

Be careful with the {\tt \$SYSSUN} and {\tt\$UPDUNIX} areas; the former
is the effective {\tt\$SYSLOCAL} for CV (and the AOC) and you may need
to reconcile changes there with necessary site-specific files from the
older version of AIPS at your site.  Likewise {\tt\$SYSIBM},
{\tt\$SYSLINUX}, and so on.  Hopefully we now have enough site-specific
case statements in the various files to make this not a problem.  If
not, inform the CV aips manager of what needs changed for your site.
One bonus non-CV sites get is prebuilt versions of {\tt PP.EXE}, {\tt
NEWEST}, and so on in the tar file mentioned above for the five
architectures (and counting) present in CV.

The {\tt\$UPDUNIX} area has the master midnight job scripts, but in CV
the Midnight jobs are run out of {\tt\$AIPS\_VERSION/\$ARCH/UPDATE/} of
necessity, given the sharing by multiple architectures of the same
{\tt\$AIPS\_ROOT}.

For non-NRAO sites, contact us to ensure that your system has permission
to perform rsh commands to {\tt baboon}.  Because of enhanced security
(necessitated by recent breakins), we have to restrict traffic more than
we'd like.  At the time of writing, the current MNJ sites all have
permission to get through the router and to access {\tt aipsmgr@baboon}.

Also, for non-CV sites, you may prefer to copy the architecture-specific
version of the GNU readline library
{\tt\$AIPS\_VERSION/\$ARCH/LIBR/GNU/libreadline.a} from CV rather than
going through the pain of remaking it.

\item{CV:} {You need to shuffle the versions of the {\it rcs\/} files
	    found in the area {\tt /aips1/master} as follows, from the
	    {\tt aipssrc} account ({\it after you have backed this area
	    up!  See above\/}).  It is also a good idea to forcibly
	    ``forget'' any current checkouts in {\tt WHATISOUT.UPD}
	    before doing this little shuffle, and make it a zero length
	    file.  Use the raw rcs command {\tt rcs -u
	    /aips1/master/TST/...} for this.  Then, the shuffle goes:
	    \medskip

\fortran
baboon_aipssrc<101> cd /aips1/master
baboon_aipssrc<102> rm -fr OLD
baboon_aipssrc<103> mv NEW OLD; mv TST NEW; cp -r NEW TST
\endfortran
	    \medskip
}

\item{} The purpose of this little dance is to ensure that the rcs files
        track the actual ``checked-out'' source code hierarchies that
        you have already shuffled around.  It's important as people may
        be checking stuff out of {\tt NEW} as well as {\tt TST}.

\item{} In addition, you will need to change the string {\tt TST} to
        {\tt NEW} in the {\tt
        /aips1/master/NEW/UP\-DATE/WHAT\-IS\-OUT.UPD} {\it if\/} you
        didn't already zero it, and fix the {\tt WHATISOUT.UPD.SUM}
        checksum file (it contains the first number you see on doing
        {\tt sum WHATISOUT.UPD}).  Also zero out the other {\tt *.UPD}
        files in the directory {\tt /aips1/mas\-ter/TST/UP\-DATE/} ({\it
        i.e.\/}, make them empty) and create the {\tt .SUM} files for
        them.

\item{} DON`T do this shuffle while the {\tt allout} script is running!
        If you try (experience talking here) that will yank the files
        out from under the script and cause it to crash.

%%% (There is a note in the version Dave wrote in '92 that says to run
%%% {\tt\$SYSUNIX/AREAS}
%%% now; not sure this is necessary --- {\it PPM\/})

\noindent Make a copy of the {\tt AIPSPATH.SH} and {\tt AIPSPATH.CSH}
files in the {\tt /AIPS} area (in CV, this may already exist as a
symlink to {\tt /AIPS/aipsmgr/aipspath.sh}; as csh is not used in CV by
aips or aipsmgr accounts, you may elect not to do the second file).
It's probably best to use a lowercase version of the names.  Edit these
to put in the new version names ({\tt 15APR97} or whatever).  You should
source (or dot) the relevant one for the shell you are in (depends on
site and machine; most systems now have {\tt aipsmgr} using the Bash or
Korn shells).  Then do, \eg:\medskip

\example{aguila\$ . ./aipspath.sh}
\example{aguila\$ . ./AIPSASSN.SH}
\example{aguila\$ . \$SYSUNIX/AREAS.SH}\medskip

\noindent DO NOT type {\tt \$CDTST} as this will get you the old
definitions (it calls {\tt CDVER.SH} which in turn calls
{\tt\$AIPS\_ROOT/AIPSPATH.SH}, not the one you just modified).

%%% this really belongs in the NEW rebuild section; there won't be any
%%% in TST.
Blow away any {\tt SEARCH*.DAT} files in {\tt \$SYSLOCAL} as they have
explicit filenames in them; the recompilation will rebuild these anyway.
There shouldn't be any.

\item{CV:} Edit the file {\tt \$APLSUB/GETRLS.FOR} to change the release
           date, \eg, to {\tt 15OCT96}.  Use the raw RCS commands ({\tt
           ~{}aipssrc/bin/aipssrc\_exec /local/bin/co}$dots$) to put it
           back.

\noindent Other sites: Double-check {GETRLS.FOR} and edit if necessary
(reminding the CV AIPS Manager that he forgot!)

\noindent Also check the {\tt \$INC/PAPC.INC} file to make sure the
second AP size is the same as before (or change it if the AIPS group
wants it differently).  The default anymore is 1.25 Megawords (5
Megabytes), though in CV on the IBMs and the Alphas it is 80 or 20
Megabytes (there is a non-checked-in {\tt\$INCIBM/PAPC.INC}; copy it
from the older area).  The generic {\tt \$INC/PAPC.INC} has examples of
different AP sizes; it has several {\tt PARAMETER} statements that set
{\tt APSIZE} and {\tt PKPWD2}.  Also double-check that there isn't a
{\tt PAPC.INC} or {\tt DAPC.INC} file in {\tt\$INCSUN} or the
architecture-specific include area for your system that might over-ride
this definition (or for other sites, that there {\it is\/} one if that's
what you want).

Finally, create the {\tt LOAD} and {\tt LIBR} areas (use {\tt mkdir -p
\$LOAD}, \etc).  These will be under, e.g. {\tt /AIPS/15OCT96/SUN4/}.
If you are using dual (debug/nodebug) libraries, don't forget LIBRDBG.
You may have to delete {\tt\$SYSLOCAL/DOTWOLIB} if you don't want the
dual libraries, or create it if you do.  In CV, most directories under
{\tt \$AIPS\_VERSION/\$ARCH} except for the {\tt SYSTEM} directory are
symlinks to a set of directories on a different host (gibbon for SOL,
rhesus for IBM, siamang for ALPHA, tarsier or marmoset for LINUX, and
baboon for SUN4).  There isn't enough room on the /AIPS partition for
three sets of binaries for 5 architectures so you may have to be
creative.  When making symlinks, because of the way the {\tt PWD}
program in {\tt \$SYSLOCAL} works, it is essential that you make the
destination directory have the architecture in the name.  Example: the
{\tt LOAD} area for Solaris in CV is a symlink to {\tt
/net/gibbon/gibbon\_0/aips/15OCT96/SOL/LOAD/}.  The {\tt PWD} program
gets very confused if the {\tt SOL} directory is omitted ({\it e.g.\/},
if you used $\dots${\tt /aips/15OCT96/LOAD/}).

Once you have a brand-new version, before proceeding any further, do
either of the following two things:\medskip

\item{1.} At CV, run {\tt\~{}aipssrc/bin/adiff} on the newly created
	  area, comparing it to what was {\tt TST}, or:
\item{2.} Elsewhere, run, \eg, {\tt diff -r 15OCT96 15JAN96 >
	  diffs.log}.  Or copy the file {\tt adiff} from the {\tt
	  \~{}aipssrc/bin} area on {\tt baboon} and customize it to your
	  liking.

\medskip\noindent You should resolve any unexpected differences.  This
will usually amount to checking in things that are not properly
checked in and moving them to the newly created area, removing junk
from the old area and things like that.  This can be time consuming
but it is {\it essential\/}.

The {\tt adiff} script compares what is now {\tt TST} with {\tt NEW}.
This script produces five files:
\medskip

\item{1.} {\tt same.log} not very interesting, files that are the same
	in both areas.
\item{2.} {\tt adiff.log}, files that differ (summary info).
\item{3.} {\tt diffs.log}, The output of {\tt diff} on files in {\tt
	adiff.log}.
\item{4.} {\tt ignore.log} list of files that {\tt adiff} thinks can
	be safely ignored.
\item{5.} {\tt nofiles.log} files that only exist in one of the areas.
\medskip

\noindent You need to resolve any differences that show up in the {\tt
adiff.log/diffs.log} and {\tt nofiles.log} files.  Hopefully there won't
be any beyond those you've already changed.  If there are a bunch of
ignored files that can be removed (e.g. {\tt *.o} in {\tt NEW}, or {\tt
*\~{}}, \etc), go ahead and blow them away.  You may need the disk
space.

\newsubsection Rebuilding the TST version

Before anything else, check your umask.  It should be {\tt 002} or {\tt
0002}, and you should be {\tt aipsmgr} with primary group {\tt
aipspgmr}.  See the note at the end of this section too, when you're
done.

Change to the brand new {\tt TST} area.  Do {\bf NOT} use {\tt\$CDTST};
use the following recipe instead (bourne/korn/bash shell):\medskip

\example{. /AIPS/aipspath.sh}
\example{. /AIPS/AIPSASSN.SH}
\example{. \$SYSUNIX/AREAS.SH}\medskip

\noindent For C shell, substitute {\tt source} for ``{\tt .}'' (dot),
and {\tt .CSH} or {\tt .csh} for {\tt .sh} and {.SH}.

Now for each architecture (at CV, these will be {\tt SUN4}, {\tt SOL},
{\tt AIX}, {\tt LINUX}, and {\tt ALPHA}), do the following:\medskip

\item{1.} Move to the {\tt\$SYSLOCAL} area and check the options files
          {\tt LDOPTS.SH} and {CCOPTS.SH} (no changes should be needed),
          then check the settings in {\tt FDEFAULT.SH} and {\tt
          OPTIMIZE.LIS} (in {\tt\$SYSUNIX}).  Other sites may want to
          use shared libraries (caveat emptor!).  At CV, it may be
          desirable to set {\tt PURGE=FALSE} so that the preprocessed
          source code is left around for debugging, depending on disk
          space.  (If it is necessary to make permanent changes to files
          in {\tt\$SYSUNIX} or {\tt\$SYSLOCAL} (which on NRAO systems is
          also {\tt\$SYSSUN} or {\tt \$SYSALPHA} or whatever), these
          changes should be put back in the checkout system later.  It
          is possible to bracket them if need be with a check on the
          {\tt\$SITE} environment variable.

\item{2.} Do the following magic dance from a bourne-like shell (bash,
	  ksh):
\medskip
\example{cd \$SYSLOCAL}
\example{for i in F2PS F2TEXT NEWEST PRINTENV PWD REVENV ; do}
\example{\ \  ln -s \$SYSUNIX/\$i.C \$i.c}
\example{\ \  [ -f \$i ] \&\& rm -f \$i}
\example{\ \  cc -O -o \$i \$i.c}
\example{done}
\medskip

\item{3.} Remake the preprocessor as follows:

\example{cd \$SYSLOCAL \hfill\rm (you should be there already)}
\example{ln -s \$SYSUNIX/PP.FOR pp.f}
\example{ln -s \$APLUNIX/ZTRLOG.C ztrlog.c}\medskip
\example{cc -c -I\$INC ztrlog.c}\medskip
\example{f77 -O -o PP.EXE pp.f ztrlog.o}\medskip

\item{} On IBM's the fortran command is:\medskip

\example{xlf -O -qextname -o PP.EXE pp.f ztrlog.o}\medskip

\item{} (you may also have to unset the {\tt PSALLOC} variable) and on
Linux, you need to do this little dance because {\tt f2c} does not know
about the non-standard {\tt CALL EXIT}:\medskip

\example{f2c pp.f}
\example{cat pp.c | sed -e 's/exit\_(/exit(/g' -e '/int exit/d' >pp.new}
\example{mv pp.new pp.c}
\example{f77 -O -o PP.EXE pp.c ztrlog.o}\medskip

\noindent Go back up to {\tt\$AIPS\_ROOT}, and compare the shell scripts
there that have counterparts in {\tt\$SYS\-UNIX}.  Something like this
will work for bourne/korn/bash shells:\medskip

\example{\$\ cd \$SYSUNIX}
\example{\$\ for file in * ; do}
\example{>   if [ -f \$AIPS\_ROOT/\$file ] ; then}
\example{> \ \ echo comparing \$file...}
\example{> \ \ diff -c \$AIPS\_ROOT/\$file ./\$file | more}
\example{> \ \ echo -n return to continue...; read dum}
\example{>   fi}
\example{> done}\medskip

There may be differences other than the site-specific ones that need to
be resolved (usually something will have changed in the {\tt\$SYSUNIX}
version that needs incorporated in the aips root version; if you decide
to copy the former to the latter, make sure you change the definitions
of {\tt\$AIPS\_ROOT} and if necessary {\tt\$DATA\_ROOT}).  Then go down
to {\tt \$ARCH} and make the {\tt ERRORS}, {\tt INSTALL}, {\tt LIBR},
{\tt LIBRDBG}, {\tt LOAD}, {\tt MEMORY}, {\tt PREP} and {\tt TEMPLATE}
areas.  Remember that these may need to be symlinks to another set of
directories (see above).  You really only need a max of two template
areas, one for little-endian and one for big-endian systems; use of
symlinks can reduce the workload here.

\noindent Now get down to business.  Here's a checklist:\medskip

\item{1)} Move to {\tt\$LIBR/GNU} and make the {\tt libreadline.a}
	  library (or cheat and copy it from elsewhere).  You will
	  probably have to do this:\medskip
\example{\$\ ln -s \$YSERV/UNSHR.FOR unshr.f}
\example{\$\ ln -s \$SYSUNIX/READLINE.SHR}
\example{\$\ f77 -O -o UNSHR unshr.f}
\example{\$\ ./UNSHR}
\example{./READLINE.SHR}
\example{\$\ chmod +x configure}
\example{\$\ ./configure}
\example{\$\ make}
\item{2)} Move to {\tt \$TST/\$ARCH/INSTALL} and create symlinks to
	  {\tt INSTEP2} and {\tt INSTEP4} in {\tt\$INSUNIX}.  Then start
	  {\tt INSTEP2} whichever way you like (\eg, {\tt (INSTEP2
	  >/dev/null 2>IN\-STEP2.ERRS\&)} for bour\-ne like shells).
	  When it's done, start {\tt INSTEP4}.  These take a long time;
	  in CV on a Sparc 20 with dual libraries, INSTEP2 took 12
	  hours and INSTEP4 quite a bit less (interrupted multiple times
	  due to disk space problems.  Expect something like 75 minutes
	  and 2.5 hours on a Dec Alpha.
\item{3)} Make XAS by unpacking {\tt\$YSERV/XAS.SHR} in a temporary
	  directory, \eg. {\tt\$YSERV/XAS/}.  You can use the version of
	  {\tt UNSHR} made for the readline library to unpack the
	  archive, then just type {\tt make}.  You may want to check the
	  Makefile first.  On SunOS, Solaris, AIX, Linux, and Digital
	  Unix, you should not need to edit it.
\item{4)} When {\tt INSTEP4} is done, set the {\tt\$DA00} environment
	  variable to the brand-new template area
	  ({\tt\$AIPS\_VERSION/\-\$ARCH/\-TEM\-PLATE}), set {\tt\$DA01}
	  to {\tt /tmp}, then {\tt \$LOAD/FILAIP.EXE}.  You want to
	  generate a good set of clean system files here.  The number of
	  TV devices should be 1, and 36 for Tek devices.
\item{5)} Run {\tt \$LOAD/POPSGN.EXE} to initialize the memory files.
          The inputs you will need are {\tt 0 POPSDAT TST}, and press
          return when the {\tt >} prompt appears.  The memory files are
          in two places, {\tt\$DA00} and {\tt\$TSTMEM}.  It is {\bf
          VITAL} that you make sure the memory file in the latter area
          is created (and has the right --- {\tt aipsuser} ---
          protection).  Only worry about moving memory files in DA00
          back to the ``real'' DA00 areas if there's been a change in
          their format or size.  There usually won't be.
\item{6)} Check the results with a DDT.  You will need to create a
	  temporary aips startup file to get a {\tt TST} session
	  started.  {\tt cp START\_AIPS start\_aips}, edit {\tt
	  start\_aips} and change {\tt AIPSPATH.SH} to {\tt
	  aipspath.sh}, make sure it's executable ({\tt chmod +x
	  start\_aips}, then type {\tt ./start\_aips notv tpok pr=...}
	  to start the aips session.
\medskip

\item{CV:} After you have completed this for the {\tt SUN4}
	   architecture, from the {\tt aipssrc} account's login area,
	   remove the {\tt AIPS\_IS\_FROZEN.TST} and {\tt .NEW} files,
	   and notify everyone that the checkout system is ready again.
	   Create {\tt AIPS\_SHOULD\_BE\_FROZEN.NEW}, and put in it a
	   caveat that NEW is ``slushy'' and it better be important (and
	   that important fixes must be moved from TST to NEW).

\item{CV:} Now is a good time to create the {\tt 15mmmYY.tar.Z} file for
	   the other midnight job sites.  Edit and update the {\tt
	   exclude.update} file as needed.  Watch out; SunOS 5's tar
	   does not seem to honour the X qualifier if the file is a
	   followed symlink.

\item{CV:} I have a cryptic note to myself to ``rebuilt {\tt
	   HLPIT.LIS}'' but can't remember how$\dots$ This is probably
	   also a good time to run {\tt SHOPH} and update the ZZ help
	   files used by apropos and about. \medskip

\noindent Finally, modify the {\tt\$AIPS\_ROOT} versions of {\tt
AIPSPATH.CSH} and {\tt AIPSPATH.SH} to refer to the correct versions and
announce to your users that the brand-new version is ready.

\item{CV:} Using the checkout system, modify the versions accordingly
           in their {\tt\$SYSUNIX} counterparts.  Go through your notes
           and see what else needs fixed.  You {\it did\/} take notes,
           didn't you?\medskip

\noindent Make sure there are symlinks {\tt aips} and {\tt AIPS} in
{\tt\$SYSLOCAL} that point to {\tt\$AIPS\_ROOT/START\_AIPS} (they should
NOT go in the checkout system; {\tt INSTEP1} and {\tt allout} set these
up for other installers).  There used to be files by these names in {\tt
/usr/local/bin} (or {\tt /local/bin}) but these should almost certainly
be removed.

One last thing: check the protections on the directories you have
created.  The umask should have been {\tt 002} or {\tt 0002} as
mentioned above, the ownership should be {\tt aipsmgr} and group
ownership {\tt aipspgmr}, except for the {\tt DA00} and {\tt TSTMEM}
areas for which you want group {\tt aipsuser}, and the protection should
be such that the setgid and group-write bits are on ({\tt chmod g+ws}).
World-write should NEVER be used.

\newsubsection Rebuilding the NEW version

Ideally, this should be done {\it in parallel with rebuilding TST\/} but
it may be difficult to find a second guinea-pig machine, and/or keep
track of up to 5 different architectures.  Here's a checklist:

\item{1)} Make sure that {\tt NEW} points to what you want, such as {\tt
	  15OCT96}.  Then do {\tt\$CDNEW} and cd to {\tt \$SYSLOCAL}.
\item{2)} Check {\tt CCOPTS.SH} and {\tt LDOPTS.SH}, and for Fortran,
	  {\tt\$SYSUNIX/FDEFAULT.SH} and {\tt\$SYSUNIX/OP\-TIM\-IZE.LIS}
	  (or {\tt\$SYSLOCAL/OPTI\-MIZE.LIS}; latter takes precedence if
	  it exists which it should not!).  You're checking to make sure
	  that {\tt PURGE} is {\tt YES}, and that there are no {\tt -g}
	  or {\tt \$DEBUG} options in the {\tt COMP=} or {\tt LINK=}
	  lines in the {\tt *OPTS.SH} files, or if relevant in the {\tt
	  FDEFAULTS.SH} and/or {\tt OPTIMIZE.LIS} file.  For CV,
	  remember to put back any changes via the checkout system.
\item{3)} Turn on optimization up to at least level 2 both for C and
	  Fortran (add {\tt \$OPT2}, which in turn should be {\tt -O2}
	  or similar, to the {\tt COMP=} line in
	  {\tt\$SYSLOCAL/*OPTS.SH}, or make sure the {\tt DEFAULT} is 2
	  in {\tt OPTIMIZE.LIS}).  For Sparc/SC4.0 compilers, -O3 is a
	  safe default for most of the system.
\item{4)} You might be thinking of using shared libraries (I do {\bf
	  NOT} recommend it); if so, make sure files {\tt
	  \$SYSLOCAL/USESHARED} and {\tt\$SYSLOCAL/NOSHARE.LIS} exist.
	  The latter should no longer be needed, in theory.
\item{5)} Delete all {\tt .LIS} and {\tt .LOG} files in
	  {\tt\$AIPS\_VERSION/\$ARCH/INSTALL}.
\item{6)} Delete all {\tt\$LIBR/*/SUBLIB} files (but {\it NOT\/} any
	  shared libraries {\tt \$LIBR/SUBLIB.so}!  That'll break
	  everything!)
\item{7)} Move to {\tt \$AIPS\_VERSION/\$ARCH/INSTALL}, then start {\tt
	  INSTEP2}.  Monitor it for a little while just to make sure the
	  compilations are doing what you want (no debug, {\it etc\/}.)
\item{8)} Start {\tt INSTEP4} when {\tt INSTEP2} is done.
\item{9)} Optional: run a small DDT just as a sanity check.  See \AIPS~
	  memo 85 and possibly 73.

\item{CV:} Edit the {\tt\$HIST/CHANGE.DOC} files in TST and NEW so that
	   the former is empty except for the next change number (and
	   the usual header comments), and the latter has the divider
	   indicating the following changes were made with that version
	   as NEW.  Later, copy the NEW version to
	   {\tt\$AIPS\-PUBL/CHAN\-GED.YYr} where {\tt YY} is the year
	   (\eg, 93) and {\tt r} is keyed to the release date: A for
	   JAN, B for APR, C for JUL and D for OCT.  {\bf DO THIS ONLY
	   AFTER NEW IS TOTALLY FROZEN FOR GOOD}.  If release dates have
	   been skipped, make a dummy {\tt CHANGED.YYr} file with a
	   short notice to this effect anyway.\medskip

\newsubsection Documentation!

\item{CV:} If it hasn't already been done, edit the
           {\tt\$DOCTXT/INSTALL.TEX} installation summary to bring it up
           to date for this to-be-released version.  Generally it's a
           good idea to give it a once-over before NEW is permamently
           frozen, and make changes as needed to {\tt INSTEP1} too.
           This can be time-consuming and you'll have to iterate
           probably once or twice (hah!  more like a dozen times) later
           when doing the install testing.  If you're exceedingly brave
           or have too much spare time, consider tackling the
           ``book-o-hell'', {\tt\$DOCTXT/UGUIDE.TEX}, but it is badly
           out of date and has a lot of overlap with the installation
           summary.

\newsubsection Cut the ``Tape''

\item{CV:} Use {\tt allout} to generate a copy of the
           now-(almost)-frozen NEW version.  There are some good
	   instructions in the {\tt README} file in {\tt
	   /aips1/tape\_cut/} which is where most of the work is usually
	   done.  Here's a quick summary:\medskip

\item{1.} {\tt allout} is run separately on the NEW and TEXT areas
	  (trimming WHO and GRIP from the latter).  Then the master tar
	  file is created with {\tt tar cf 15mmmYY.tar 15mmmYY BIN DA00
	  TEXT INSTEP1 REGISTER} (last two are symlinks to the real
	  files in the {\tt\$INSUNIX} area of the directory tree).
\item{2.} This tar file is unpacked in the various install-test areas
	  (disk space seems to disappear like water in a desert about
	  now), and the installation tested.  Problems occur, are
	  resolved, put back (there's a hook in putbck for a desperate
	  install tester even when things are frozen solid in NEW) and
	  tested again.  This can take a LONG time.  Use the {\tt
	  aipstest} account.
\item{3.} Update the README file in {\tt /aips1/tape\_cut} if the
	  locations of the install testing change.  You'll need this
          next time.
\item{4.} When all install testing is done, copy the binaries from the
          different {\tt\$SYSLOCAL} areas to the relevant {\tt
          BIN/\$ARCH} areas; these include {\tt PP.EXE}, {\tt NEWEST},
          {\tt F2PS}, {\tt F2TEXT}, {\tt PWD}, {\tt PRINTENV}, and {\tt
          REVENV}.  Copy a clean message file for user 1 to this area
          too.  You only need two ``real'' {\tt\$ARCH} directories, one
          for big-endian and one for little.  Use symlinks for the
          others.
\item{5.} Strip the test-install binaries (in LOAD and those above) and
          copy the LOAD area binaries ({\tt *.EXE XAS}) to the
          appropriate area in the AIPS directory tree here.  Likewise
          for {\tt \$LIBR/*/SUBLIB} and {\tt \$ARCH/MEMORY/*}.
\item{6.} Move the binaries to the ftp area (via loopback or lofs mounts
          if necessary) but protect them until you're ready to release
          everything.
\item{7.} If necessary, copy the libF77.so library for Suns to the ftp
          area.
\item{8.} Prepare a GNU zipped version of the tar file, and split it
          into about 50 parts as well.  Move these into place in the
          ftp area.
\item{9.} Finish the {\tt INSTALL.TEX} document, and when it's done,
          update the AIPS web pages (in CV, this is in {\tt
          ~{}docs/aips/}), unprotect things and send a bananagram
          announcing the new release.  Then copy the tar file to tape
          for Ernie and make sure the {\tt cut\_aips\_tape} procedure
          works.

\newsection Finishing Up

If you haven't already, turn the midnight jobs back on.  Use the {\tt
MAKE.MNJ} script in the {\tt\$UPDUNIX} area to set things up (it had a
typo in {\tt 15JAN96}: {\tt chomd} instead of {\tt chmod}; fix this or
do the right thing by hand).
\medskip

\item{1)} {cd to {\tt \$AIPS\_VERSION/\$ARCH} and {\tt mkdir UPDATE; cd
	UPDATE}.  Then:\medskip

\example{aguila\$ \$UPDUNIX/MAKE.MNJ}

\item{2)} go to {\tt /AIPS}, take out the ``exit'' from the
        {\tt do\_daily} file, make sure {\tt NEW} and {\tt TST} are in
	the {\tt AIPSUPD} line, and run the midnight job.
\medskip

Update this document from your notes (it's {\tt\$DOCTXT/QUPDATE.TEX}).

Let everyone know you're done and take a well-deserved rest.  Then ask
the boss for a raise$...$ (don't hold yer breath!)

\end
