Overview
Build specifications are used to describe the high level details of a project build. Build specifications are made up of one or more build stages. Each build stage in turn specifies a recipe to build, along with an agent to execute the recipe on. In simple cases, a build specification will have just a single stage. When the specification is executed, the stage will be built by executing the stage on the specified agent.
More advanced builds may make use of multiple stages, usually to test in multiple environments (e.g. multiple operating systems). The stages in a specification execute independently of one another, in parallel where possible. For example, if you need to test on Windows, Linux and Solaris, you can set up three agents, one on each operating system. Then you can add three stages, one for each operating system. When the specification is triggered, each of the stages will be executed in parallel across the three agents. The build will only succeed if the tests pass across all environments. It is even possible to configure a build stage to be executed on any capable agent through the use of required resources. This allows efficient use of a pool of available agents.
Build specifications are also what you tie to triggers to determine when a project is built. Each project may have one or more build specifications to describe different types of builds for the project. For example, one specification may be used for continuous integration builds that are run every 15 minutes, whereas another specification may be used for overnight builds that perform more thorough testing.
The build specifications for a project may be viewed on the "configuration" tab in the "build specifications" table.
Initial Build Specification
When you add a new project to your pulse™ server, an initial build specification (named "default") is created for you automatically. This specification is configured with a single build stage that will execute a build of the project's default recipe on any capable agent. For simple projects, this is usually an appropriate configuration. It also serves as a starting point for creating more sophisticated specifications.
Default Build Specifications
One build specification for a project is always marked as the default specification for that project. The default specification will be used in various circumstances when a specification is required but none is specified. For example, when triggering a project from the "projects" view, the default build specification will be triggered.
To change the default specification, navigate to the "configuration" tab for the project, and click the "make default" link next to the build specification that you wish to delete.
Note that the default build specification cannot be deleted.
Creating Build Specifications
A new build specification can be created by clicking the "add new build specification" link at the bottom of the "build specifications" table on the "configuration" tab for the appropriate project. When adding a specification you will also be prompted for details of the first build stage for that specification.
name
A descriptive name for the build specification. This name will be used throughout the web interface to refer to the specification.
This field is required.
Examples
isolate changelists
When this box is checked, each build of the specification will include at most one new change. This allows a change that breaks the build to be idenitified easily. For projects that can afford this level of isolation (i.e. where the change frequency and build times are low enough), this setting is recommended.
retain working copy
When this box is checked, working copies for each build stage in the specification will be captured and stored when the build completes, so that they may be browsed later. This option is unchecked by default because the cost of transferring the working copies from the agent to the master can slow a build significantly.
enable build timeout/timeout after
If you wish to apply a time limit to the build, check "enable build timeout" and enter a time limit in minutes in the "timeout after" field. If any stage of the specification takes longer than the specified amount of time to complete, the stage will be forcefully terminated and will finish in the error state. The build itself will also finish in the error state.
If the "enable build timeout" box is check, then the "timeout after" field is required.
stage name
A descriptive name for the build stage to add to the specification, used in the user interface to refer to the stage.
This field is required.
recipe
Name of the recipe to execute for the build stage. For built-in projects, leave the recipe blank.
If no recipe name is given, the default recipe will be used.
agent
The agent to execute the recipe on. You may also select the special entry "[any]", which allows the recipe to be executed on any capable agent. A capable agent is one that has all of the required resources for the build stage.
Managing Build Specifications
Existing build specifications may be edited and/or deleted using the "edit" and "delete" links in the appropriate row of the "build specification" table. When clicking the "edit" link, you will be taken to the build specification view. Here you can see the basic details for the specification, along with the build stages. To view the details of a particular stage, click the name of the stage in the left column of the "stages" section.
Build Specification Basics
To edit the basic details of the specification, click the "edit" link in the top right corner of the "basics" table. Several fields presented have the same meaning as when creating a new specification, and are described above. Additionally, this form allows you to change the checkout scheme for the specification, which defines whether the base directory is cleaned between builds and how the source is checked out from the SCM. You can also check the "prompt" checkbox to enable prompting for build revision and properties when the specification is manually triggered; refer to the Build Revision and Build Properties sections below for details.
Build Revision
The default behaviour of pulse™ is to build the latest revision of your project. In some cases, you may wish to build at a specific revision. To achieve this, first you must check the "prompt" option for the build specification you intend to use. Now, when you manually trigger a build of that specification, you will be able to enter the revision to build. If you leave the revision blank, pulse™ will revert to the default behaviour of building the latest revision. Valid values for the revision differ from SCM to SCM, as described below.
CVS
CVS revision should be specified as dates in the same format that pulse™ uses when reporting build revisions, that is:
For example, to build the project as it stood at 10am on the 3rd of May 2006, use:
For convenience, you may also just specify the date, in which case pulse™ will set the time to midnight automatically.
Perforce
Perforce revisions are any valid changelist number. For example, to build your project as it stood just after change 3265 was committed, specify revision:
Subversion
Subversion revisions are any valid repository revision number. For example, to build your project as it stood just after revision 3265 was committed, specify revision:
Build Properties
Build properties may be used to specify properties at the specification level. These properties can be referenced in the project configuration for built-in projects, or in the pulse file for pulse file projects. Build properties are most useful for two purposes:
- To parameterise the configuration for built-in projects. For example, you may be using an Ant project, and wish to create two different build specifications, each of which should execute a different ant target. This can be achieved by setting the target to a property reference, say ${target} in the project configuration. Then in each specification, you can add a property named "target" with the appropriate value.
- To allow properties to be manually specified for a certain build specification. For example, you may wish to use pulse™ to perform release builds of your project. In order to make a release, you may need to specify a version number at release time. This can be achieved by adding a build property to the specification named "version", and checking the "prompt" checkbox for the build specification. Now, when the specification is triggered manually via the pulse™ web interface, you will be prompted for the value of the "version" property.
Build properties are a generic mechanism that you may also use for other purposes.
Adding Build Properties
To add a new property to a specification, click the "add new property" link. You will be prompted for the property name and value, and be able to select various options for the property:
| Option |
Description |
| add to environment |
If checked, the property will be added as an environment variable. |
| add to search path |
If checked, the property value will be added to the start of the search path used by pulse™ to locate executables. |
| resolve variables |
If checked, the property value will have variables resolved, using the ${<property name>} syntax. These variables can be properties introduced from any source, including properties in every build (e.g. ${build.number}), environment variables (${env.PATH}) and so on. |
Managing Build Properties
Existing build properties may be edited at any time using the "edit" link in the corresponding row of the "build properties" table. You can delete an existing property using the corresponding "delete" link.
Build Stages
Build stages are parts of a build specification that are all executed when the build specification as built. Each stage can be configured to build its own recipe, on its own agent. Stages are executed independently and in parallel where possible (i.e. when there are agents available). A typical use for multiple build stages is executing the same recipe (or perhaps similar recipes) in multiple environments. This may include different compilers, operating systems, runtime dependencies and so on.
To add a new build stage, click the "add new build stage" link. You will be prompted for the stage details, all of which have the same meanings as when adding the first stage (when creating the build specification). The fields are described above in the Creating Build Specifications section. You may edit these details for an existing stage by clicking the "edit" link in the "basics" table for the stage. Finally, a stage may be deleted using the "delete stage" link.
Post Stage Actions
Post stage actions can be used to execute actions on the pulse™ master server after a build stage completes. These are similar to post build actions, but are tied to a specific stage rather than the entire build. For more information refer to the Project Post Stage Actions page.
Required Resources
Resources are used in pulse™ to configure external dependencies required for a build. When creating build specifications, you can specify the resources (even specific versions) that are required for the specification. These required resources are used for two purposes:
- To import the resource details (properties, environment variables and PATH directories) for use in the build
- For requirements-based dispatching of recipes to agents, when specifying "[any]" as the agent for a build stage
Required resources can be specified for the build specification (applying to all stages) and on individual build stages. For more information, refer to the Project Required Resources page.
