
BUILD SERVER INSTALLATION
=========================

NOTE: At the time of this writing the build server scripts assume you are using
a Windows system. Obviously this limitation should be removed at some point.

1. First install the necessary tools.
   - The latest version of Open Watcom to use as the compiler for building.
     Be sure to select all possible targets during the installation.
   - Whatever external help compilers are necessary.
   - The latest version of the Perforce command line client.
   - A reasonably recent version of Perl. The build scripts are written in Perl

1. Create a folder OUTSIDE the Open Watcom source tree and copy the contents of
this folder to that folder. Do not attempt to use the system from a folder
inside the Open Watcom source tree. In this document the working copy of the
build system is assumed to be in a folder named C:\OWBUILD. However, any folder
can be used (avoid folders with spaces in their names) provided is is on the
same drive as the OW source tree.

2. Review the file config.txt and make any changes as necessary. See the
comments in the file for more information.

3. Checkout the OW source in the usual way (using Perforce). Do a full build the
first time "manually" (meaning without the help of this build system). The
build.log file created will serve as your baseline. Run the program summary.pl
over this initial build.log and save the results to a file such as bldbase.txt
(use the same name as you specified in config.txt).

        summary c:\OW\bld\build.log bldbase.txt
        
You should verify that all messages in bldbase.txt are normal. This build system
will compare the result of each build with this baseline and report on any
deviations. If bldbase.txt contains serious errors, this build system will not
notice those errors in the future.

4. The scripts provided are as follows

   - summary.pl : Computes a summary of build.log that contains all the strange
     entries in the log file. Use this script to compute a baseline.
     
   - compare.pl : Computes the difference between a baseline summary and a new
     summary. Reports on messages that have been removed or that have been
     added in the new summary.
     
   - dobuild.pl : This is the main script. It prepares a batch file that does
     the build based on the current setvars.bat. It cleans the source tree,
     builds the system, and then invokes summary.pl and compare.pl to check
     the results. Finally it emails a report to the address designated in the
     configuration file. NOTE: This script assumes that the system has been
     built manually first.

Schedule dobuild.pl to run periodically using your operating system's facilities
for that purpose.

NOTE: dobuild.pl never, never, never updates the baseline summary on its own.
You must do that manually when and if you feel it is appropriate to do so. This
policy ensures that the baseline is always appropriate and that human
intelligence is used to make a judgement about when the baseline needs to be
updated.

