ABRelease
=========

This component is designed to be inserted into builds (any type of build) so
that they can more fully interact with the Autobuild system.


HOW IT WORKS

The ABRelease component will run a build-specifiy script (obey file) for each
phase of the build process to allow any special behaviour to take place. To
do this, it will invoke the script by running it from a specific path, which
includes (in this order) the following Resources subdirectories:

  1. Resources.<Name of Autobuild build>  - e.g. "TungstenDev"
  2. Resources.<Name of build>            - e.g. "Tungsten"
  3. Resources.Generic

The script that is executed has a leafname which matches that of the phase it
will be run during, for example:

  Resources.TungstenDev.clean - run in the "clean" phase

If no script file is found for a given phase of a specific build, then no
action is taken by this component in that build phase.


THE DEFAULT SCRIPT

By default, only one phase has a corresponding obey file, and this will be
executed by any build, unless overridden by placing a script with the same
leafname into an earlier directory on the path. This default script is:

  Resources.Generic.release_autobuild

There are a few things to note about this script:

  1. It is only executed during the "release_autobuild" phase of the build
     process, so this won't happen when the build is initiated by !Builder,
     because that doesn't perform the "release_autobuild" phase. Normally,
     only the Autobuild process itself will run "release_autobuild" as the
     final build phase.

  2. This default script assumes a ROM build. It will create a zip archive
     which includes a copy of the Castle licence, a ReadMe text file and the
     ROM image (if found) and upload the archive onto the Autobuild server.

  3. All of the scripts are called with a single parameter, which is the
     INSTDIR build variable. This will be particularly useful for disc builds
     to locate the installed components.

For disc builds, there will need to be a "release_autobuild" script placed
earlier on the path which will do whatever packaging up and uploading is
required.

The default script will perform the following actions:

  * If there is no ROM image (e.g. the build failed), exit here
  * Create an empty directory to hold the files that will be zipped up
  * Copy the Castle licence file into the zip directory
  * Copy the ReadMe for this build into the zip directory
  * Copy the ROM image into the zip directory
  * Set the zip directory as the current directory
  * Create a zip archive with the required files in it
  * Return the CSD to its original state
  * Delete any pre-existing zip archive on the autobuild server
  * Copy the template zip archive onto the autobuild server
  * Remove any old crud from our build-specific resources directory

There is also a default script for the "clean" phase which deletes any copy
of the template zip archive from the Resources.<Name of Autobuild build>
directory (if there is one). This is really little more than an example.


ENVIRONMENT VARIABLES

In order to make writing these scripts easier, the ABRelease script sets up
some environment variables before looking for and runnnig the script for a
given build phase (if it exists):

  ab_res$dir    - the Autobuild resource directory (e.g. Resources.TungstenDev)
  ab_red$path   - the Resources path, as described above
  ab_build$dir  - the directory on the Autobuild server to upload into
  ab_build$path - path to ab_build$dir - for convenience
  ab_zip$file   - the name of the zipfile to create on the Autobuild server (if any)

Note: some types of build might upload something other than a single zipfile
into their upload directory. In that case, the ab_zip$file variable can be
ignored.


FINAL NOTES

The Resources.Generic directory includes some resources which are generically
useful for builds, these are:

  * A copy of the Castle licence (PDF)
  * A template ReadMe text file containing only some generic information