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 IfThere
  * If SparkFS isn't running, we're going to have problems so generate error
  * Remove any old template zip archive from our resources directory Remove
  * Copy the central template zip archive into our resources directory
  * Open the archive so we can copy into it
  * Copy a ReadMe file into the zip archive
  * Copy the ROM image into the zip archive
  * Close the archive (filer window)
  * Delete any pre-existing zip archive on the autobuild server
  * Copy the template zip archive onto the autobuild server
  * Remove the template zip archive from our 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 template zip archive containing a copy of the Castle licence (PDF)
  * A template ReadMe text file containing only some generic information
  * A utility (NullEvent) to cause a Task Window to sleep for a Wimp poll

The NullEvent utility is useful for putting between operations in a script in
order to ensure that some processing gets handed back to other Winp tasks.
This is useful for two reasons:

  1. It allows the contents of the Task Window to update on screen and give a
     better indication of progress

  2. Things like Filer_Run and Filer_Boot have a chance to execute