********************************************************************************
* _____          _   _       _     ______    _ _ _                             *
* |  __ \        | \ | |     | |   |  ____|  | (_) |           		       *
* | |  | | ___   |  \| | ___ | |_  | |__   __| |_| |_ 			       *
* | |  | |/ _ \  | . ` |/ _ \| __| |  __| / _` | | __|			       *
* | |__| | (_) | | |\  | (_) | |_  | |___| (_| | | |_ 			       *
* |_____/ \___/  |_| \_|\___/ \__| |______\__,_|_|\__|			       *
* 									       *
* This document has been generated by running the script with the help option, *
* as per:								       *
* 									       *
* erlang_automated_build -h						       *
* 									       *
* Documentation changes should be made there not here			       *
* 									       *
********************************************************************************
Introduction
------------
This script performs the daily build for an Erlang system. It has
ONLY been tested on SuSE 9.2.

Purpose
-------
This script can perform the following build tasks:
* take a CVS extract of code
* compile that source code and check the results
* run a test suite
* run the dialyzer
* run tsunami
* graphs all or some of the previous results over time
* copy the graphs to some other location

How To Use This Script
----------------------
The following steps should be followed to implement this script.

1  Run the configuration test

   ./erlang_automated_build -c

   This will attempt to autodetect the components it needs and report back
   success or failure. It will also dump out the values of all the hardwired
   values in this script. You have the option of either editing them here or
   overriding them with command line options.

2  Decide on how you wish to implement this script

   This script can be run in a variety of ways:
   * a monolithic installation  - all steps happen on the same machine
   * a distributed installation - different steps happen on different machines

   The graphing options can be configured such that distributed applications
   produce integrated output.

3  Ensure that you can CVS your code down

   You need to set up CVS to work without having to put in a password

   Run the following at the command line to just run the CVS part to test
   if it is working

   erlang_automated_build -B -C -F -G -I -v

   This script is set up to use an ssh batch wrapper script which
   is in /src and is called erl_auto_bld_ssh_wrapper

   The location of this file is held in the user editable variable:
   * CVS_RSH_SUBSTITUTE

4  Set up a pre-compilation script file to prepare the build

   This script will run an external batch file prior to executing
   the compile - this file needs to exist (even if it does nothing).
   This facility exists in case your CVS needs unpacking or any other
   changes prior to running the compile phase

   The path & filename of this script is in the user editable variable section:
   * PREPARE_BLD_SCRIPT
   It can be overridden with the option:
   * -P PATH/FILE

5  Configure the Erlang helper function

   There is a helper function which you need to set up:
   * compile_code.erl (see src directory)

   This module has the fuctions you wish to compile hard coded in it and
   must be appropriately edited - or replace it with one of your own.

   The return from this file is used in the graphing:
   * every line that contains 'OK: ' will count as 1 successful compile
   * everyline that contains 'Compile failure: ' will count as 1 failed compile

   The path to this file is in the user editable variable section:
   * HELPER_FUN_LOC
   It can be overridden with the option:
   * -H PATH/FILE

6  Configure the test server helper function

   You need to install and compile the test server helper function:
   * ts_stub.erl (see the src directory)

   It needs to go in the test_server directory with all the other
   ts_*.erl/ts_*.beam files

   This function is needed coz the erl batch command dont take lists as a
   parameter.It doesnt need to be edited. It is passed the test suite spec
   on the command line

7  Set up a pre-tsunami script

   This script will run an external batch file prior to executing
   the load test - this file needs to exist (even if it does nothing).
   This facility exists to start your test system or insert test data or
   any other changes prior to running the load tester

   The pre-tsunami script is started as a background shell with no contact
   with this script. The pre-tsunami script signals to this script via a
   canary - a file whose existance (or not signals) that
   erlang_automated_build can continue and kick off tsunami. An example
   of this shown in the following files available in /doc/examples/src:
   * pre-tsunami.script
   * start_app.erl
 
   The path and filename of this script is in user editable variable section:
   * PRE_TSUNAMI_SCRIPT
   It can be overridden with the option:
   * -Q PATH/FILE

   The path and filename of the canary is in the user editable variable section:
   * WHERES_THE_CANARY
   It can be overridden with the option
   * -C PATH/FILE

8  Create your load testing script

   The path and filename of this script is help in the user editable variable:
   * TSUNAMI_XML_FILE
   It can be overridden with the option:
   * -R PATH/FILE

9  Set up a post-tsunami script

   This script can clean up after your tsunami load testing (ie kill the 
   system under test)

   An example of a post-tsunami script can be found in /doc/examples/src:
   * post-tsunami.script

   The path and filename of this script is help in the user editable variable:
   * POST_TSUNAMI_SCRIPT
   It can be overridden with the option:
   * -S PATH/FILE

10 Set up a location to copy your results to

   This programme will run a series of secure copies with the format:
   * scp [options] results_files username@host:/path/to/directory

   IDX-Tsnumi expects its graphs to be in subdirectory called /images
   be sure to create that as well

   The user editable variable SCP_LOC contains:
   * 'username@host:/path/to/directory'
   It can be overridden with:
   * -Z username@host:/path/to/directory

   scp will use a private key to copy the data.

   The user editable variable SCP_PRIV_KEY contains:
   * /path/to/private.key
   It can be overridden with
   * -z /path/to/private.key

11 Set up the general configuration of the script

   There is a large section of this script marked as user editable
   which contains a series of variable definitions that define where various
   things are to be found. The values of these should be set edited. Explicit
   file locations are specified so that the script can easily run as a cron job
  
   In future version of this script the user editable section will be
   'copy'n'pastable'

When It Will Fail
-----------------

This script contains a Y3K bug - find it and win a coconut!

Prerequesites
-------------

This script requires the following to be installed and working:
* the Erlang base system
  (http://www.erlang.org)
* a CVS client
  (http://savannah.nongnu.org/projects/cvs/)
* the Erlang Test server (and a suite of tests)
  (http://www.erlang.org/project/test_server/)
* the Dialyzer
  (http://www.it.uu.se/research/group/hipe/dialyzer/)
* Tsunami
  (http://www.idealx.org/prj/idx-tsunami/ (french))
  (http://www.idealx.org/prj/idx-tsunami/index.en.html (english))
* Gnuplot
  (http://www.gnuplot.info/)
* Secure Shell
  (http://www.openssh.com/)

Not all the components are needed to run all the parts of the script
but if components are missing then it will not be possible to run the
appropriate section.

Core Activities
---------------
This script performs the following core activities:
* downloads source code from CVS
* compiles the source code
  - runs a prepare build script
  - checks the results
  - graphs the result over time (ie multiple invocations of the script)
  - copies the results to a location
* runs a test suite
  - graphs the results over time (ie multiple invocations of the script)
  - copies the results to a location
* runs the dialyzer
  -  graphs the results over time (ie multiple invocations of the script)
  - copies the results to a location
* runs tsunami
  - runs a pre-tsunami script to set up the system for load testing
  - graphs the results over time (ie multiple invocations of the script)
  - copies the results to a location
* e-mails a defined user list on failure (or success)

Options
-------

erlang_automated_build takes the following options:

    General Options
    ---------------
    -c   checks for prerequisites and dumps the configuration
    -h	 displays this information
    -v   runs in verbose mode
    -d   runs in debug mode (ie super verbose)
    -V   gives the version

    Overriding User Edited Variables
    --------------------------------
    -E [DIR]                 location of Erlang installation
    -L [DIR]                 local CVSROOT
                             (ie where CVS will download the source code to)
    -P [PATH/FILE]           location of prepare build script
    -H [DIR]                 location of compile_code.erl function
                             (the helper function)
    -Q [PATH/FILE]           location of pre-tsunami load script
    -W [PATH/FILE]           location of the canary
    -R [PATH/FILE]           location of tsunami xml file
    -S [PATH/FILE]           location of post-tsunami load script
    -X [e-mail addresses]    who to notify on success
                             a list of e-mail adresses seperated by a semi-colon 
    -Y [e-mail addresses]    who to notify on failure
                             a list of e-mail adresses seperated by a semi-colon
    -Z [user@host:/path/]    an alternate place to copy the results to
    -z [PATH/FILE]           an alternative private key to use for the scp copy

    Output Options
    --------------
    -r [DIR]   change the location where reports are to output to

    Flow Of Control Options
    -----------------------
    -A   dont cvs new code down
    -B   dont compile the code
    -C   dont run the test suite
    -F   dont run the dialyser
    -G   dont run tsunami
    -I   dont run gnuplot
    -J   dont copy the output anywhere
    -K   dont backup the code before CVSing down a new version
         delete it instead

