< Previous | Next >

Lesson 8: Jazz Team Builds

This section examines the Jazz™ Team Build user interface from the perspective of a developer who is a consumer of what Rational Team Concert™ build provides. However, you will need to do some setup that might normally be done by your build administrator or release engineer. To make the Jazz Team Build produce what your project requires may involve quite a bit of customization and adoption of build scripts to meet your project requirements. Fortunately, Jazz Team Build makes it easy to get it running so you can see how it operates just as if it were working for your team.
The Jazz Team Build is a fundamental component of Rational Team Concert. By itself it does not build anything, but it does provide the infrastructure to retrieve your team's work from the Rational Team Concert repository, make it available to your build scripts, and deliver the results back to Rational Team Concert. You, as a Rational Team Concert user and consumer of builds, can monitor running builds and access the results. Since the early days of Rational Team Concert, the Jazz Team Build has been used to build Rational Team Concert itself.
How does the Jazz Team Build work? Here is the big picture:
  1. Define a schedule: A particular build operates on a schedule you define. Recall from the section on Rational Team Concert source control that a team shares their development work in one or more team streams.
  2. Check for changes: When it is time to run a build for a team, Jazz Team Build checks to see if there are any changes in the content of the team's streams and accepts the changes, known as change sets, into its own build workspace so it has a current copy of the stream(s).
  3. Fetch repository content and run build: The build then fetches the build workspace content to the file system where your build scripts perform the build.
  4. Publish artifacts to repository: Build artifacts are published into the Rational Team Concert repository for access by users.
  5. Send notification that a build is complete: The status of all builds is reported in real time and you are automatically notified when builds complete.
The Jazz Team Build includes the Jazz Build Engine and the Jazz build toolkit. Getting these installed and operational is quite easy. From your Jazz client, complete the following tasks:
  • Define a build script (we'll let your Eclipse Jazz client do most of the work here)
  • Define a build definition that identifies your build script
  • Define a build engine to run the defined build
  • Start the build engine that will respond to build requests, run builds, and publish results
This will allow you to request a build, examine the results and explore the build user interface as though you were a developer and a consumer of what Jazz Team Build produces.
Note: The setup steps are somewhat lengthy. If you want, you can pause now and return to this later. If you decide to not pursue the build set up, you should read the next section titled Touring the Jazz Team Build User Interface. Here you will learn how you can request builds and examine build results.

Setting up an Eclipse workspace for the build team member

In this tutorial, the build team member that you created in an earlier lesson is the dedicated build user. Set up and configure a new Eclipse workspace for the build team member.
To set up and configure a new Eclipse workspace for the build team member:
  1. Switch to a new Eclipse workspace.
  2. Create a repository connection.
  3. Connect to the Prelude project area.
For more information, see Lesson 2: Getting connected. After you complete the setup, your Team Artifacts view should display as follows:

build team member Eclipse workspace

Creating a build script

To create a build script:
Make sure you have a repository connection defined and you are logged in.
  1. In the Package Explorer view, right-click a project; then click Export.
  2. In the Export wizard, on the Select page, under General, select Ant Buildfiles and click Next.
  3. On the Export page, ensure that your project and all check boxes are selected and click Finish.
A build.xml file is added to your project. This file uses the Ant scripting language. This script will compile your project and produce Java™ class files. Note it is identified as an outgoing change.

build.xml added to Package Explorer view

Attention: Do not deliver the Ant script yet.

Creating a dedicated repository workspace

You can create a dedicated repository workspace for use by the Jazz build definition for your project. During a build, the Jazz Build Engine, which is connected to the Jazz repository using a preassigned user identifier, uses this build workspace to identify the content to be built. First, it accepts any incoming changes from the team's stream and then loads the build workspace contents into the local file system for processing.
To create a dedicated build repository workspace:
  1. In the Team Artifacts view, right-click My Repository Workspaces; then click New > Repository Workspace.
  2. In the New Repository Workspace wizard, on the Select a Stream page, click the Flow with a stream radio button and in the pane below, select Team 1 Stream (Team 1).
  3. Click Next.
  4. On the New Repository Workspace page, type the build workspace name Team 1 Build Workspace and click Next.
  5. On the Read Access Permission page, ensure that Public is selected and click Next.
  6. On the Components to Add page, confirm that the stream's component is selected and clear the Load repository workspace after creation check box.
  7. Click Finish. The build repository workspace displays in your view.

    Build repository workspace added to My Repository Workspaces view

Creating a build definition and build engine

You can create a Jazz build definition for your project. The build definition is configured to use the new build workspace, so when the build runs it can accept any changes from the team stream prior to the start of the build.
To create a build definition:
  1. In the Team Artifacts view, expand the project folder.
  2. Right-click Builds; then click New Build Definition.
  3. In the New Build Definition wizard, on the New Build Definition page, accept the defaults and click Next.
  4. On the General Information page, in the Available build templates pane, select Ant – Jazz Build Engine and click Next.
  5. On the Pre-Build page, select Jazz Source Control and click Next.
  6. On the Post-Build page, accept the defaults and click Next.
  7. On the Additional Configuration page ensure that all options are selected and click Finish. The Build Definition editor opens.
  8. Create a build engine for the build definition:
    1. In the Supporting Build Engines pane, click Create Engine.
    2. In the Create Build Engine dialog box, in the Engine ID field, type PreludeBuildEngine.
    3. Click OK.
  9. Click the Jazz Source Control tab of the Build Definition editor.
  10. In the Load Options pane, in the Load directory field, type fetched.
  11. To specify a build workspace, complete the following steps:
    1. In the Build Workspace pane, click Select.
    2. In the Select a Stream or Workspace dialog box, in the Matching items pane, select Team 1 Build Workspace and click OK.
  12. Click the Ant tab.
  13. In the Build file field, type the following path: fetched/projectname/build.xml, where projectname is the name of your Java project. For this tutorial, we use the HelloWorld project.
  14. In the Java home field, type the file path to your Java compiler. For example, C:\Program Files\IBM\TeamConcert\jdk.
  15. Click Save.
Set up is complete! If you examine the Team Artifacts view you will see the build definition and build engine listed.

Build definition and build engine in the Team Artifacts view

Delivering the build script

Before we start the build engine to run our builds, recall that the build script (build.xml) in your Hello Prelude project has not been delivered to the stream. Without it, the Jazz Build Engine won't have the necessary instructions to execute the build. Let's deliver that change now.
  1. In the Pending Changes view, under Default Component, right-click Unresolved; then click Check-in and Deliver.

    Pending Changes view

  2. In the Check-in and Deliver Wizard, in the Change-set comment pane, type a comment and click Next.
  3. On the Associate Work Item page, select an existing work item and click Finish.
The build script is now in the stream. When the build runs the script will be available.

Starting the build engine

Start the build engine to get ready to run a build.
Note: When you start the build engine, to ensure that the correct JDK is used, you can specify the JDK that is included in the Jazz client by using the -vm command line argument.

To start the build engine:
  1. From a command line, navigate to installdir/buildsystem/buildengine/eclipse, where installdir is the Build System Toolkit installation directory
  2. Type jbe -vm clientinstalldir/jazz/client/eclipse/jdk/bin/java -repository repositoryURL -userId build –pass password -engineId PreludeBuildEngine , where
    • clientinstalldir is the Jazz client installation directory.
    • repositoryURL is your repository URL. For example, http://localhost:9080/jazz/.
    • password is the build user's password.
    In this tutorial, the user ID is build and the build engine identifier is PreludeBuildEngine.
The engine starts and looks something like this on the console (you may see some other messages as well):
2009-06-11 16:08:47 Running build loop...
2009-06-11 16:08:47 Waiting for request...

The -sleepTime value of 1 (second) will ensure that the build requests are processed right away.

The build engine is waiting for work. It is time to run a build.

Touring the Jazz Team Build User Interface

Learn about the build tasks you can do with Jazz Team Build.

The Jazz client allows you to do the following build tasks:

Let's examine each of these tasks.

Requesting a build

You can request a build from the Team Artifacts view. You can also change build properties or request a personal build that does not impact the build definition status and that runs on a workspace that you specify.
To request a build:
  1. In the Team Artifacts view, expand the project folder.
  2. Expand the Builds folder and locate the build name in the list.
  3. Right-click Team 1 build; then click Request Build.
    1. Optional: To request a personal build that does not impact the build definition status and that runs on a repository workspace that you specify, in the Build Options pane, select Personal Build. If required, update the Repository workspace and Component load rules fields.
  4. In the Request Build dialog box, click Submit.
The build engine processes the build request. You can observe this process in the command window where you started the build engine.

If the build did not run correctly, examine the log file published in the build result.

Viewing build results

Let's open the build result and see what happened.
The build result editor has the Overview, Logs, and Properties tabs. You can view additional tabs depending on what the build script contributes to the build result. For example, if the build script contributes compilation results and downloads, then the build result editor includes Compilation and Downloads tabs.

You have completed the following tasks:

  1. You submitted a build request. It could have been initiated automatically on a predefined schedule.
  2. The request was received by the Jazz Build Engine along with the build definition.
  3. Using a build workspace configured in the build definition (Team 1 Build Workspace), the Jazz Build Engine performed an accept operation to update the build workspace from the stream. In the first build, this brought the newly created build script (build.xml) to the build workspace, which is essential to run a build.
  4. The updated contents of the build workspace were loaded into the file system, using the directory named fetched in the build definition.
  5. The build script specified in the build definition is called. Our script compiled the HelloWorld project and created Java class files. A more sophisticated script might have created a jar file and published it back to Jazz.
  6. When the script completes, the build log and any other published results are stored in the Jazz repository.
  7. The team is notified that the build has finished.

Build result editor

There a few things to point out about what the build result editor can offer:

Examining the build log

Let's examine the build log to see if our new build script worked.
  1. Go to the Logs page. Let's inspect what the build did.

    Logs page

  2. Select the log file and click Open. Here you can see the most relevant activities that took place.

    A sample build log

    By now, you are beginning to see how Jazz makes build information very visible to you and your team.

Monitoring the status of builds

Build status can be obtained passively or actively. Passive build information is provided in two ways: in the Team Central view Build section and build alerts that briefly appear on your screen.

As builds complete, in the Team Central view, the Build section is updated with the status of completed builds for the team(s) you participate in.

For a selected build in this view you can see the results of the build or request a new build.

To customize how often the status is updated:

Finding Available Builds

You can see what builds are available, the status of running builds, and builds queued to run in the Builds view, which is accessible using the context menu Show Build Results from the Builds folder in the Team Artifacts view.

Show Build Results menu item

The contents of the view can be sorted by selecting a column. There are a number of interesting context menu actions. You can compare a build to the stream from which it was built or create a new stream from a build (helpful for creating a new code base from a proven code base).

Build Results view

You can also view build results by defining a build viewlet in your web-based Jazz dashboard:

Web-based Jazz dashboard build results

The Jazz development team has been customizing its build process for quite awhile. Jazz's build results editor has additional tabs labeled Compilation, JUnit, and Downloads, and External Links. Here is a screen shot from a Jazz build so you can see what the potential is.

Sample customized build results

Lesson checkpoint

In this lesson you learned the basics of the Jazz Team Build functionality.
< Previous | Next >

Feedback