These are of historical interest only --- these were once used as the main
nightly build/test scripts for Xyce.  They have been superceded by XTF for
several years now.

This directory contains copies of the scripts I (Tom Russo) run every
night in a cron job.  These are not meant to be run by the average
developer or user, but I'm putting them in the suite to keep
everything available to everyone.

Here's the way the nightly build works.

One machine is the "build master" that has "do_nightly_master" in a
cron job.  do_nightly_master does a CVS update on its copy of the
source, runs the build and test on the master machine, and also uses
ssh and rsh to run do_nightly_slave on several other machines.

do_nightly_slave takes one argument, the platform name, e.g.
"do_nightly_slave dec" Running it that way does builds and tests in a
directory called PLAT_dec.  It does the build and test for that one
platform, and in most cases uses the same NFS-mounted copy of the Xyce
source directory that all the other platforms use.  It is possible
that a modified do_nightly_slave needs to be installed on a machine
that doesn't have /Net/Proj/Xyce mounted, and that modified slave
would do a cvs update with a remote repository in a private source
directory.  It would also have to ssh back to the build master and
deposit its status and "WORKING" files.  I don't have an example of
this right now, as all the machines I build on now mount
/Net/Proj/Xyce.  When I go to test the CPLANT build nightly I'll have
to do something tricky like this.

My nightly build directory is in
/Net/Proj/Xyce/people/tvrusso/nightly_builds.  That directory has a
subdirectory for each platform:

  PLAT_freebsd
  PLAT_sgi
  PLAT_linux
  PLAT_dec

It also has a copy of the source code in the Xyce subdirectory, a copy
of do_nightly_master and do_nightly_slave, and the
"make_a_shadow_test_dir" and "rebuild_test_links" scripts.

Each build machine creates a file called "WORKING" in its platform
directory, and the build master waits until all the platforms have
removed their WORKING files at the end of the run before outputting
the status of all machines to email.

Each platform directory has some number of build directories.  Each
build directory contains a shell script called "reconfigure" that
contains the configure line needed to generate the right build.  For
example, the PLAT_freebsd has the following build directories:

Xyce_freebsd
Xyce_freebsd_ALLDEBUG
Xyce_freebsd_MPI
Xyce_freebsd_MPILAM
Xyce_freebsd_MPILAM_chaco
Xyce_freebsd_MPI_chaco
Xyce_freebsd_gcc3
Xyce_freebsd_mingw

Each has its own "reconfigure" with just the right options to make the
build described by the directory name --- e.g. the
Xyce_freebsd_MPILAM_chaco directory has a reconfigure that turns on
MPI, uses the LAM compiler wrappers and libraries, and links in chaco.
The "Xyce_freebsd" has a simple configure line, and
"Xyce_freebsd_ALLDEBUG" has all the "-enable-debug_foo" flags.

A sample "reconfigure" is stored in this scripts directory for
illustration.

The do_nightly scripts look at every directory in the platform
directory, then cd to each one in turn, execute "./reconfigure" and
"make."  If the configure fails, the output of configure is saved in
the platform directory with the name
<builddirectory>_configure_<date>.  If a build fails, the output of the
make is saved in the main platform directory with the name
<builddirectory>_make_<date>.

After building in a particular build directory, the script checks if
there is an executable script called "runthetests" in the build
directory.  If so, this script is run, OTHERWISE NO TESTS ARE
PERFORMED.  A sample "runthetests" is in this scripts directory.  

The sample "runthetests" uses a "shadow copy" of the Xyce_Test
directory to run the test suite.  The shadow copy of the Xyce_Test
directory is mostly symlinks --- we link back to some other copy of
the Xyce_Test directory so we don't have lots of copies around.  But
it can't just be a straight symlink back to a single Xyce_Test, it's
more complex than that --- Xyce wants to output its .prn file in the
same directory as the netlist, and that would screw up multi-platform
testing out of a single directory.  So what's really happening is that
there is a real directory for every test netlist, and that directory
contains a symlink back to the original test netlist.  The
"OutputData" directory is a straight symlink, and the TestScripts
directory has symlinks to every file in the original place.  This is a
complicated mess that could easily be screwed up, so I wrote a shell
script to do it for me.  The shadow copy is created in a build
directory by running the shell script 'make_a_shadow_test_dir.'  

In my case, since make_a_shadow_test_dir lives in the "nightly_builds"
directory, and the build directories are in
"PLAT_<platform>/<builddir>" I would set up a new build directory by
saying:

   mkdir /Net/Proj/Xyce/people/tvrusso/nightly_builds/PLAT_<platform>/Xyce_<platform>_frobnitz
   cd /Net/Proj/Xyce/people/tvrusso/nightly_builds/PLAT_<platform>/Xyce_<platform>_frobnitz
   <then I'd make a reconfigure script, usually by copying an old one
        and hacking it>
   <then I'd make a runthetests script, same deal, copy and hack>
   <then I'd build the Xyce_Test shadow directory with:>
   ../../make_a_shadow_test_dir

The "runthetests" need to use my modified "test_serial" and
"run_test_suite" scripts to get the output they need.  The original
scripts won't return the exit codes these scripts expect.  The tests
performed by the modified scripts are the same as those performed by
the original scripts.

Each build directory for which there is a "runthetests" script must
have a shadow Xyce_Test subdirectory.  

Since the shadow directories get screwed up if there's a commit to the
Xyce_Test package and the main directory is updated, there's a shell
script called "rebuild_test_links" --- this will be run from the top
level nightly_build directory and will make sure that all the symlinks
are right.

Each do_nightly_slave process creates a file called
"build_stats_<platform>_<date>.  do_nightly_master concatenates all
the stats files together and emails them to XYCE-DEVELOPERS@sandia.gov.

The whole thing is very kludgy, but it does work.  It is not going to
be easy for someone else to take this and make it work for them.  I
didn't write these scripts for convenience or portability, I just
threw them together to do the job I needed done when I needed it.

