Compass Version 1.3

Specifying Build Step Options

Once a build step is added there are a variety of options and settings that may need to be changed for each build step. This section describes all of the options available for every build step. In the build editor, each build step consists of a row in the build plan and looks like this:

Each build step has three configurable parts: an arguments section, a details button and a defaults button. This section is broken down into four parts, one for each of the configuration parts, starting with the 'arguments' section below, and one final section on build step execution order.

Build Step Arguments

The build step arguments are the arguments that are passed in to the script that is selected. Some scripts do not handle script arguments, while others have required parameters. This results in a potential drawback for build plan creators since in many circumstances the user who added the script is not the same user who is creating the build plan. In order for script authors to communicate the requirements for their scripts to build plan creators they add usage notes for their script when adding it to Compass. The usage notes for scripts can be viewed in three ways in the build editor:

In the Script drop down box, users can mouse over each script and the tooltip text displays the usage notes for that script.
Clicking the help button on the script column heading will bring up a dialog with all of the scripts' usage help information.
After selecting a script to execute, users can click on the ellipses next to the Arguments textbox. This brings up the 'Edit Text' dialog that allows users to enter in arguments and also shows the usage notes at the bottom of the dialog as shown here for the Compass built-in PyUnit Test Runner script:

As you can see in the 'Edit Text' argument dialog. The Usage Notes are displayed and describe how to use the arguments for this script.

Build Step Details Dialog

The details dialog controls how the script is executed and what to do when a script is not successful. To access the details dialog, users click the magnifying glass icon on the build plan editor for the build step they want to update:

After clicking on the details icon the Build Step Details Dialog opens, which looks like this:

The Script Details dialog controls where the script will execute in the directory structure of the project, what to do when the script fails, when to run the script and how to execute a unit test parser (if any) on the resulting output. Below is a table explaining the usage of each of these options:

Build Plan Details Dialog Option	Description
On Fail	The 'On Fail' option allows creators of build plans to specify what to do if this build step fails. There are three options. 1) Halt, which reports the build as failed and does not proceed to the next build step. 2) Continue, which reports success and continues on to the next build step as if nothing went wrong. 3) Warn then Continue, which reports the build step as a warning and the entire build plan will be considered a warning, however the build plan will continue on to the next build step.
Run In Directory	The 'Run In Directory' option allows creators of the build plan to execute the script for this build step in a sub directory of the project. This allows reuse of many scripts without script authors requiring arguments to their script telling them what directory to run the script in. As an example a visual studio build may need to be run from the <root>/project/visual_studio directory of a repository checkout. In this case, build plan creators could use the visual studio build script and specify 'project/visual_studio' for the 'Run In Directory' Option here.
Unit Test Parser	The 'Unit Test Parser' option tells Compass that the output of this build step can be parsed by a unit test parser script and that the number of tests run, and the number of successful tests should be reported with the results of this build step.
Unit Test Arguments	It may be necessary for some unit test parsers to be passed arguments so they know how to parse the output from a build step. In that case, the 'Unit Test Arguments' option allows build plan creators the ability to specify those arguments.
Run On	The 'Run On' option is directly tied to if the build is incremental or not. Incremental builds keep source code between executions of the build plan. This way, Compass can execute repository updates rather than full checkouts on every execution of the build plan, significantly reducing the load on source-code repository servers as well as overall build time. If a build plan is not set to incremental, all build steps will execute every time, regardless of this option, but when a build plan is set to incremental then this option becomes critical to executing the build plan successfully. There are 3 options available: 1) Always, which will make the build step execute every time the build plan is executed. 2) First Time Only, which will only execute this step the first time this build plan is run. 3) Only Incremental, which will execute this step every time except the first time the build plan is run.

The 'Run On' option can be confusing for first time users, for more information on creating incremental builds, and how the 'Run on' parameter is used for repository checkout and update scripts please see the section on Incremental Build plans. For more information on Unit Test Parsers please see the section titled Adding Unit Test Parsers.

Build Step Defaults Dialog

The defaults dialog provides a way for build plan creators to specify default options to a script that the script exposes to Compass but not on the command line. It is also a way for script authors to explicitly require parameters. Because of this, default parameters are used in a variety of ways which we discuss here. To access the Build Step Defaults Dialog, users click the defaults icon on the build plan editor for the build step they want to update:

After clicking on the details icon the Build Step Details Dialog opens, which looks like this:

There are two columns on this dialog, the Variable column and the Value column. when the user clicks on the variable column a popup with a drop down of available options is displayed that looks like this:

The drop down box contains all of the available arguments that can be passed to the script for this build step. Some script authors prefer that users specify options to their script through this mechanism so they do not have to worry about parsing command line options correctly as regular inputs to the script. When a script author requires the use of a default argument it should be noted in the usage notes so that build plan creators know how to correctly parametrize the build step.

Another reason for using default values (and the reason they are called default values) is for the case where the build plan is scheduled to be triggered to run by a repository change (ie: any of the 'revision' checkout scripts) but we also want the ability to manually start the build for testing. For triggered scripts, the arguments that the script requires are passed to it by the trigger mechanism, but when we start the build manually the arguments are not supplied to the script. But, if we specify default argument values for the script then even when the build plan is executed manually or at a regularly scheduled interval it will still have valid values for all the arguments passed to the script.

Build Step Execution Order

When creating build plans it is easy to adjust the order that build steps execute. This is sometimes necessary as build systems evolve, new Compass build steps may need to be added or removed. Or, sometimes it is useful to place unit tests that are most likely to fail at the beginning of a build plan so that errors are detected and reported quicker. To move a script up or down in the build steps order simply click on the up and down arrows for that build step:

When adding a new script it is always placed at the bottom of the build step list; often it is necessary to move newly added build steps up/down through the build step order. When a build step is no longer needed, users can remove it permanently from the build plan by clicking the 'remove' button:

Removing a build step permanently removes the build step, all information about the build step details and build step defaults is lost once the build plan is saved.