Getting Started with setting up Jazz Builds
Introduction
This document is intended to help the build script writer understand the purpose of the Jazz Build technology and to help in setting up builds for a team using Jazz. For a user-level guide to using Jazz Build, please read the client tour.
The Team Build component integrates the team’s build system into Jazz and provides build awareness to the team. This is accomplished with build progress monitoring, build alerts, build result viewing, and linkage of builds with other artifacts in Jazz, such as change sets and work items.
Jazz build is primarily intended to support build scripts written with Apache Ant. Other scripting technologies can be used, however, callouts to Ant are required to enable fine-grained build awareness for the developer. Jazz provides several Ant tasks, including tasks for tracking build progress, and publishing build artifacts into the Jazz repository. Some existing build scripts can be used with Jazz unmodified, while others will require small modifications by simply sprinkling the Jazz Ant tasks at the appropriate places.
Overview of the build environment
A typical build environment will use a stack of tools consisting of at least one build engine and one or more build scripts. A build engine, such as the Jazz Build Engine, launches the process that will run the build script and collects output. You must provide the build scripts that perform the detailed tasks to compile, test, and further process the code and build artifacts. You may choose to use the Jazz Build Engine, or continue with the build engine you’re already using. Any existing build scripts can be used. Using the Jazz Build Engine is optional, however, some features are only available when it is used.
Creating a new Jazz Build
Creating a new Jazz build requires you to create a build engine and build definition in the Jazz repository. The build engine identifies the build system that will perform builds. The build definition identifies a particular build and its properties. The Build Definition wizard is provided to help you create these items. The wizard supports two primary scenarios: 1) You are creating a build from scratch, or, 2) you are duplicating an existing build and modifying the copy.
Creating a special-purpose build user
The Jazz build toolkit and the Jazz build engine will both require a user and password for logging into the Jazz repository. It is recommended that you create a special-purpose build user so operations performed by the build (such as creating a baseline) don’t appear to be performed by a real user. You must assign the “Build System” client access license to your build user. When getting started, you can put the build user’s password directly in the Ant task or build engine invocation. However, for production use, you should create an encrypted password file using the Jazz Build Engine-createPasswordFile argument. This encrypted file can then be referenced by the Ant task passwordFile attribute and the Jazz Build Engine -passwordFile argument.When creating Jazz SCM workspaces for builds, it is important to set the owner of the workspace to the build user that will be specified during build engine launch or in the Ant task “userId” attribute. This is required so that the build can modify the build workspace when accepting the latest changes to be built.
Running the Build Definition wizard
To launch the wizard, choose File->New->Other from the eclipse main menu. Within the list of wizards, you will see a Team category containing a Build Definition wizard.
The choices available in the wizard are described below.Choosing a repository and team area
All builds must be created in the context of a given repository and team area. The wizard allows you to select an appropriate repository and team area.
Choosing a template for the build
If you are using the Jazz Build Engine, select either the Ant, Maven, or Command Line template. The command line template enables you to invoke any kind of build, for example, Perl or Make. If you are not using the Jazz Build Engine, select the Generic template.
Choosing pre-build and additional options
The wizard will guide you through selecting pre-build options, such as Jazz SCM. Check this option if you want to build files from a Jazz SCM workspace. Additional options include choices such as build scheduling.
Finish the wizard
After finishing the wizard, your new build definition opens in the definition editor. When you save the definition, you will be alerted to any required fields you must fill out.
Filling out the required fields for the build
Depending on the template you selected, you will need to provide more information to configure the build. Typically, you will need to provide the path to a build file or command line. Paths in the definition can be absolute or relative to the current directory of the build engine process. Remember that the build typically runs on a remote build machine, so if you use absolute paths they must resolve on the machine that runs the build.
Selecting a build engine
If you have build engines already defined, they will be shown in the definition editor on the General tab, “Supporting Build Engines” section. In order to run builds, you must select an existing engine, or create a new one. You’ll need to remember the build engine ID you choose for later. If you did not already have an existing build engine, you may have noticed that the New Build Definition wizard created a “default” build engine for you.
Testing the new build definition
To test the build, you will want to have these build-related views showing in eclipse:
- Team Artifacts – shows team areas and their related build definitions and engines
- Builds – shows the build results
To test your new build, request a build by clicking the “Request Build” button in the header of the definition editor. After you submit your request, the Builds view will open and your pending request will be shown.
The pending request will sit there forever, unless a build engine processes the request. You need to start the Jazz build engine, so it can process the pending request. Typically, you will run the engine on a remote build machine, but for testing purposes, we’ll run it on the local machine.
The Jazz Build Engine is a headless eclipse command line application. The engine is included in the Build System Toolkit install, or the RTC-BuildSystemToolkit-*.zip. To start the engine, open a command prompt or shell to <installpath>/buildsystem/buildengine/eclipse. Type “jbe” and enter. Assuming you have a Java 7 VM on your path, you will see the usage message for the engine. Here is an example invocation:
jbe -repository https://localhost:9443/jazz -engineId default -userId myUser -pass myPass
Notice the connection between the “engineId” and the build engine you created earlier. Once started, the Jazz Build Engine will run indefinitely, polling the Jazz repository for requests, and processing them. To stop the engine, press control-c in the command prompt or shell.
Note: it is recommended to use a JDK (not a JRE) for running the build engine because some tools invoked from a build will require a JDK. If you see the message “Unable to locate tools.jar” in the console or build log, try executing the build engine with a JDK.
Once the engine is started, go back to Team Concert. Refresh the Builds view. You should soon see the pending request turned into an in-progress build.
If the build does not start, and instead remains pending, check the build engine editor: Be sure the engineId you pass to the engine matches the engine ID in the editor, that your build is listed as a supported build definition, and that the engine is marked active.
If the build failed, open the build result and go to the Logs tab to examine the build log.
Built-in properties available to Ant scripts
There are several properties available to Ant scripts when using the Jazz build engine. You will need these properties to make use of the Jazz Ant tasks to publish information to the repository. For example, the StartBuildActivityTask task updates the build with current activities. These activities are visible in the Team Concert UI. This is a simple mechanism that provides valuable awareness of the build’s activity to the team.
| Property Name | Description |
| buildLabel | This is the build label that was generated by the Jazz Build Engine. For example, 20080215-1234. |
| buildResultUUID | This is the unique identifier for the build result. Any task that publishes progress or information to a build result must provide this attribute. The value for the attribute is passed to your build script in the ${buildResultUUID} ant property. For example, you will typically see it used like this in the ant script: buildResultUUID="${buildResultUUID}". |
| requestUUID | This is the unique identifier for the build request. |
| buildDefinitionId | This is the friendly identifier for the build definition (not the UUID). |
| repositoryAddress | This is the address of the jazz repository where the build request originated. For example, http://myteam.mycompany.com/jazz. |
| * | All properties defined in the build engine editor are available to the Ant script. |
| * | All properties defined in the Properties tab of the build definition editor are available to the Ant script. These properties override the build engine properties in case of property name conflict. |
User-defined properties
If your build script requires certain properties, such as ECLIPSE_HOME, you can define these in the build definition or build engine properties tab. Properties defined in the build definition or build engine will be available to your Ant script.
You can use variables in property values by specifying the ${propertyName} format. For example, you could create a property on the build engine named “toolsdir” with a value of /home/build/tools. Then, in property values or other fields of the build definition editor, you can reference it with ${toolsdir}. The Jazz Build Engine substitutes the property variables just before the build is started, and their substituted form is given to the build script.
Examples
Further build examples can be found here.
Documentation
Detailed documentation of the Jazz Ant tasks can be found in the Team Concert Help Contents under “Managing change and releases / Building with Jazz / Jazz build Ant task reference”.
References
Starting and stopping Jazz Build Engines
Getting started with Ant builds on the Jazz Build Engine
Getting Started with Ant scripts and RTC Build Ant Tasks
Jazz build Ant task reference