Compass Version1.2

TOC

Adding Scripts

Adding a new script to Compass is a simple procedure. On the Script List page, click the 'Create New Script' button and the following dialog appears:

Each field in this dialog is described in the table below:

New Script Dialog Field	Description
Name	The Name parameter can be any name you want that describes your script. It is used only to identify the script in the web interface and has no baring on the script's execution.
Command	The Command parameter is the executable command that you want to use to execute your script. This is an optional parameter, but one of Command or Script file must be specified. For portability, Anx Labs recommends using Commands where possible. Examples of commands that can be used would include: 'python', 'svn checkout --non-interactive %(ARG)', and 'devenv %(ARG) /rebuild %(CONFIG_NAME). If a command is not specified then it is assumed that the next field, 'Script File' is an executeable file like a windows .exe or Linux bash script file with a hash bang on first line.
Script File	This is the file you want to upload for the script to be executed. The script can do virtually anything; most of the time however, the script will perform a repository command, build source code, or run a unit test. More details on creating scripts are below in the next section.
Usage Notes	When a user enters the build editor and is creating their build plan, they will be selecting Scripts to execute. The Usage Notes is a detailed message about what parameters can be passed to the script or how to use it. Any explanation can be added here, this is merely a documentation mechanism to pass on additional information to other users of the script.

After the dialog is filled out, clicking create will add the script to the script list.

Writing Scripts

Script files can do virtually anything you want them to do. Usually scripts fall into one of four categories:

Source-Control server accessing
Pre-processing or post-processing of code and build output
Building source code
Testing build output

Although scripts usually do these things, they can do anything; in fact, script is even a slightly misleading term because scripts can actually be executable programs too.

When creating a script there are four important ingredients that Compass uses: std output, std error, exceptions, return code of the script/program. These four things are explained below:

std output & std error:

Standard output and standard error are two output streams that programs and scripts will output text to. Both of these are considered 'script output' by compass. Everything that a script outputs on either of these two streams will be recorded by Compass as output. The output can be viewed from the script results screen.

The output and error streams are combined into a single output stream internally by Compass. This is important because there is no thread synchronization between the two streams, meaning that when an error occurs that causes a script to stop executing, the output recorded by Compass may not list the error at the end of the output. It may be followed by lines of standard output, even though it occurred later.

Exceptions:

When an uncaught exception occurs in a script, Compass receives an exit code and assumes the script failed. Exception information is not always printed in the script output, due to limitations of catching the exception while Compass is still receiving output and error stream information.

Return Codes:

When a script or executable completes execution and exists, the exit code of the process is what Compass looks at to determine if the script succeeded or failed. If A zero value, the normal non-error value, is returned then Compass reports the script as having completed successfully. If any other value is returned Compass interprets that as an error and reports that the script failed.

Specifying Arguments in Scripts

In the table above describing the Script dialog's fields. In two of the examples of possible commands we used the syntax %(ARG). In Compass, when a user is creating a build plan to execute a series of scripts they are allowed to pass in arguments to the command. When writing a command for a new script, users can use the %(ARG) to place where the build step arguments will be placed in the command line that is executed. Additionally, users can add any new variable with the syntax %(xxx) to their command line. This is necessary when a command line requires more than 1 argument like: 'cvs %(ARG) co %(MODULE_NAME)' Since the 'co' comes between two parts of the passed in arguments it is necessary to add the %(MODULE_NAME) variable to the command line.

There are 6 built-in variables for Compass which are described in the table below; any other variable that an author provides in a script will be editable on the defaults dialog on the build plan editor.

Built-in Compass script variable	Description
%(ARG)	%(ARG) can be used in the command to specify where the build plan arguments that are entered should be inserted.
%(SCRIPT_FILE)	%(SCRIPT_FILE) can be used in the command to specify where the script file name should be inserted into the command line execution of the build step.
%(SERVER_URL)	%(SERVER_URL) is the URL of the source-control server that should be used in a checkout or update script. This value is automatically filled in when a source-control server binding triggers a build plan to execute. If a 'revision' script is used on a regularly scheduled build, then this value should be set in the defaults section of the build step.
%(SERVER_PATH)	%(SERVER_PATH) is the path in the repository on the source-control server that a checkout or update script is using. This value is automatically filled in when a source-control server binding triggers a build plan to execute. If a 'revision' script is used on a regularly scheduled build, then this value should be set in the defaults section of the build step.
%(REV_TIME)	%(REV_TIME) is the timestamp used in a checkout/update script. This value is automatically filled in when a source-control server binding triggers a build plan to execute.
%(REVISION)	%(REVISION) is the revision number used in a checkout/update script. This value is automatically filled in when a source-control server binding triggers a build plan to execute. If a 'revision' script is used on a regularly scheduled build, then this value should be set in the defaults section of the build step.

Testing New Scripts

New scripts are difficult to test inside of Compass. Because a script can be anything from windows executables to bash scripts, Compass has no way to allow access to the script while it is running. Savvy developers may be able to attach debuggers to script processes once they have started, but that is beyond the scope of this documentation. Because of this limitation, Anx Labs recommends developing scripts as standalone applications functioning on example or test data before adding the script to Compass.

Once a script is running in Compass, turning on the log file and viewing output from the script can be helpful. In many cases, exception info will be logged to the log file when it is not available in the script output. Beyond this additional output in the log file, adding additional script output is the most reliable method of testing scripts inside of Compass.