This ReadMe describes the deprecated AutoBuild system.  AutoBuild has been
replaced by nightly_cvs_build.pl in build/tools/.  For full documentation
on nightly_cvs_build.pl run "perldoc nightly_cvs_build.pl".

Automated Build Tools ReadMe
============================

Revision History:
	24 June 03, Jim Trainor. Initial revision.


These scripts implement a simple automated build system.

The primary script is AutoBuild.  It performs the following actions:

- Check out the tip of CVS tree.
- Determine the build number by reading ref-impl/include/AAFSDKBuild.h
- Optionally increment the build number, edit AAFSDKBuild.h, and tag the tree.
- Execute "make everything" and log the results.
- Filter the log to identify errors and other unexpected output.
- Run the regression tests, and log the results.
- Copy the make, filtered make, and regression logs to a aaf.sourceforge.net.

  Incrementing the build number, is implemented by the BuildNumber
script.  This may be executed on its own, but would normally be
executed by AutoBuild.

  Filtering the make log is implemented by a platform dependent
script.  The name of the script is be: FilterLog_PLATFORM.  Where
PLATFORM is the output of the AAF/build/aafplatform.sh script.

  CVS access may be done using pserver or ssh.  If pserver is used,
operations that require write access to repository will fail.  Bumping
(i.e. incrementing) the build number requires write access, hence, ssh
must be used.

  The AutoBuild and BuildNumber scripts make a number of cvs, ssh, and
scp calls.  Users are advised to take advantage of ssh's RSA
authentication feature to avoid the need to repeatedly enter a
password.

AAFSDKBuild.h and the BuildNumber script
========================================

  The AutoBuild and BuildNumber scripts consult AAFSDKBuild.h to
determine the build number.  Each time this file is edited to change
the build number, a new Build-XXXX tag must be applied.  Hence, each
time the build number is incremented ("bumped") a new version of
AAFSDKBuild.h is created.  The BuildNumber script does this work.

  The BuildNumber script verifies that the build number found in
AAFSDKBuild.h is identical to the most recent build tag found in the
cvs header for that file.  "Most recent" means numerically greatest.
The script sorts the Build-XXXX tags to determine this.  If the build
number in AAFSDKBuild.h, and the most recent Build-XXXX tag on that
file are ever found to be out of sync the BuildNumber script will
report the error and exit.  An developer must resolve the problem.

  Errantly editing AAFSDKBuild.h manually, manually tagging the tree,
or a failed partial execution of the BuildNumber script would leave
AAFSDKBuild.h in such a state.

  The build manager can execute BuildNumber on its own, or the
AutoBuild script will execute it if the "-bump" option is used.

CVS pserver Caveats
===================

  SourceForge more often than not (at the time of this writing)
rejects pserver connections.  The following type of error is
generated: "cvs [checkout aborted]: recv() from server
cvs.aaf.sourceforge.net: EOF"
 
  Repeated attempts to access server eventually succeed.

  The Source Forge compile farm machines do not appear to get
preferred access to the CSV server(s).

  To work around these problems, cvs calls are made using the
RepeatUntil script.  This script simply repeats the call until it
works (exit status of zero) or until some maximum number of execution
attempts complete.

[Today, I tested using pserver to retreive the tip of tree.  The
files, at least AAFSDKBuild.h, were out of date!  The build tag should
have been at Build-0511 and it was only at Build-0510!?!?  Build-0510
was the latest build tag in the cvs header!  In addition to having
unreliable connection availability and being slow, the files it sends
back are out of date. - Jim Trainor, 24 June 2003]

aaf.sourceforge.net File Location
=================================

Build logs are copied to the following directory:
aaf.sourceforge.net:/home/groups/a/aa/aaf/htdocs/build/AutoMake.logs.

  A directory is created for each build tag, and under that, for each
platform.  For example if AutoBuild compiles Build-0511 on i686Linux,
then the following directory is created to store the logs:
.../AutoMake.logs/Build-0511/i686Linux
  
  The log filenames are created by concatenating a time stamp, the
build tag, the platform name, and the build type (debug or
release). Multiple logs can be placed in a single directory.  The time
stamp ensures the filenames are unique.  The AutoBuild script creates
a link to the most recent log.  The link does not have the time stamp,
build tag, or platform name.

  The logs may be accessed using a web server at the following URL:
http://aaf.sourceforge.net:/build/AutoMake.logs

Source Forge Compile Farm
=========================

  Currently, the source forge compile farm is of somewhat meager
value.  The AAF SDK support Mac, Windows, Linux, and Irix.  The
compile farm only supports Linux.

  Further, the most recent SDK supports GCC 3, and RedHat 8 or later.
(Althought earlier versions of RedHat work without problem as long as
GCC 3 is used.)  Unfortunately, the Source Forge compiler farm only
supports RedHat 7.3 and GCC 2.96.

  The compiler farm does not support ssh access to the CVS repository.
pserver access is supported.  The AutoBuild script must have write
access to the repository in order to update the AAFSDKBuild.h file and
tag the tree.  Other than this limitation, AutoBuild should run
without problem on Source Forge compile farm machines (assuming
pserver access is reliable).

  Please refer to Source Forge site documentation regarding access to
the compile farm.

Expected Nightly Build Management
=================================

  Several machines must work together to implement an all platform
nightly build.  One platform must be assigned the task of bumping the
build number.  The others simply checkout the tip of the three and
compile it.

  The machine responsible for bumping the build number must be
configured to access the CVS repository using ssh.  It should execute
the following command:

	AutoBuild -basedir directory_to_write_AAF_tree -copylogs -bump 
	AutoBuild -basedir directory_to_write_AAF_tree -copylogs -nocvsco -release 

  That will check out the tip of the tree, bump the build number,
build the tree, run the regression tests and copy the logs to
aaf.sourceforge.net.  The second AutoBuild execution will use the
existing source tree (i.e. not checkout the tree again), and build and
test the release version of the SDK.

  Other machines can use ssh or pserver to access the cvs repository
(pserver caveats not withstanding).  However, in all cases ssh is used
copy log files to aaf.sourceforge.net.  These machines must execute
the following command:

	AutoBuild -basedir directory_to_write_AAF_tree -copylogs 
	AutoBuild -basedir directory_to_write_AAF_tree -copylogs -nocvsco -release 

  The AutoBuild script always checks out the tip of the tree.  It will
consult AAFSDKBuild.h to determine the current build tag.  The script
will execute a "cvs -nq update -r Build-XXXX" command to determine if
any files have been modified in the repository since the build tag was
applied.

Temporary Files
===============

  The AutoMake and BuildNumber scripts create a number of temporary
log files.  These are written to ~/tmp, *not* /tmp.  These logs are
useful for debug purposes.  They are written to a tmp directory in the
users home directory in the belief that a users might want to consult
these on a shared server where others are executing AutoMake and
writing them to /tmp would create a conflict, or after a server
rebooted (erasing ~/tmp).

  AutoBuild and BuildNumber both create the ~/tmp directory if it does
not already exist.

END
