Lesson 7: Building with IBM Engineering Workflow Management Engineering Workflow ManagementBuild

This section examines the Engineering Workflow Management (EWM) Build user interface from the perspective of a developer who is a consumer of what EWM build provides. However, you must perform some setup that might normally be done by your build administrator or release engineer. To make the EWM Build produce what your project requires can involve quite a bit of customization and adoption of build scripts to meet your project requirements. Fortunately, EWM Build makes it easy to get it running so you can see how it operates as if it were working for your team.

About this task

The EWM Build is a fundamental component of EWM. On its own, it does not build anything, but it does provide the infrastructure to retrieve your team's work from the EWM repository, make it available to your build scripts, and deliver the results back to EWM. You, as a EWM user and consumer of builds, can monitor running builds and access the results. Since the early days of EWM, the EWM Build has been used to build EWM itself.
How does the EWMBuild work? Here is the big picture:
  1. Define a schedule: A particular build operates on a schedule you define. Recall from the section on EWM 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, EWM 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 EWM 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 EWM Build includes the Jazz® Build Engine and the Jazz build toolkit. Getting these installed and operational is 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 EWM 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 EWM 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.

About this task

To set up and configure a new Eclipse workspace for the build team member:

Procedure

  1. Switch to a new Eclipse workspace.
  2. Create a repository connection.
  3. Connect to the Prelude project area.

Results

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 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.

About this task

To create a dedicated build repository workspace:

Procedure

  1. In the Team Artifacts view, right-click My Source Control > All 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, and select Prelude Stream (Prelude).
  3. Click Next.
  4. On the New Repository Workspace page, type the build workspace name Prelude Build Workspace and click Next.
  5. On the Select repository page, ensure that Use current repository is selected and click Next.
  6. On the Read Access Permission page, ensure that Public is selected and click Next.
  7. On the Components to Add page, confirm that the stream's component is selected and ensure that the Load repository workspace after creation check box is selected.
  8. Click Finish.
  9. On the Load Repository Workspace page, ensure that Find and load Eclipse projects is selected and click Next.
  10. On the Load Eclipse Projects page, ensure that the Hello World project that you created in an earlier lesson is selected and click Finish.
    The new repository workspace displays below the My Source Control folder.
    New repository workspace
    The workspace component has also loaded. Switch to the Package Explorer view, to view the Hello World project that you created earlier.
    Loaded workspace component

Creating a build script

To create a build script:

Before you begin

Ensure that you have a repository connection defined and you are logged in.

Procedure

  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.

Results

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 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 before the start of the build.

About this task

To create a build definition:

Procedure

  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, select all options, except Rational Build Forge. 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.
    2. In the New Build Engine dialog box, in the Engine ID field, type PreludeBuildEngine.
    3. Click Finish.
  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 Prelude 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.

Results

Set up is complete. The Team Artifacts view displays the build definition and build engine.
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 will not have the necessary instructions to run the build. Deliver the change.

Procedure

  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.

Results

The build script is now in the stream. When the build runs the script is available.

Starting the build engine

Start the build engine to get ready to run a build.

Before you begin

About this task

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:

Procedure

  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/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://hostname.example.com:9443/ccm/.
    • password is the build user's password.
    In this tutorial, the user ID is build and the build engine identifier is PreludeBuildEngine.

Results

The engine starts and waits for build requests.
Build request console

Touring the Engineering Workflow Management Build User Interface

Learn about the build tasks you can do with EWM Build.

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

  • Request that a build run
  • Monitor the status of builds
  • Query available builds
  • Inspect completed builds, identify, and retrieve the artifacts produced

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 affect the build definition status and that runs on a workspace that you specify.

About this task

To request a build:

Procedure

  1. In the Team Artifacts view, expand the project folder.
  2. Expand the Builds folder and locate the build definition name in the list.
  3. Right-click Prelude build; then click Request Build.
    Request build menu item
    1. Optional: To request a personal build that does not affect 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.

Results

The build engine processes the build request. You can observe this process in the command window where you started the build engine. You can also view the status of the build in the Builds view.
Builds view

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.

Procedure

  • If you were quick you could have clicked on the build in the alert window above.
  • Another way is to go the Team Artifacts view, expand your Prelude project area and the Builds section. You will see your build definition. Open the build result using menu action Open Latest Build Details.
    The build result editor opens.

Results

The build result editor has the Overview, Activities, and Logs 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 (Prelude 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:

  • The status of the build: completed or not; successful or not.
  • Start time, completion time, and duration.
  • Any work items or source control changes associated with the build. In the example, below you can see that one work item was included. If you were to open it, you would see that it is the work item associated with the delivery of the HelloWorld build script. Notice in the Links section that there is a reference to the change sets that were included in the work item and the build containing these changes. In Jazz there is bidirectional traceability between work items, change sets, and builds.
    The Build Result editor
  • You can create a work item or associate an existing work item with this build. This is particularly useful if the build failed.
  • Build history. Selecting this displays the history detail in the Builds view (you need to request another build to see a history).
  • The editor is extensible to include additional pages that your team might need.

Examining the build log

Examine the build log to see if our new build script worked.

Procedure

  1. Go to the Logs page.
    Inspect what the build did.
    Logs page
  2. Select the log file and click Open.
    In the log file, you can view the most relevant activities that occurred, such as Fetching changes, Accepting files, and Compiling.

    By now, you are beginning to see how Jazz makes build information 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 Dashboard view Build section and build alerts that briefly display on your screen.

As builds complete, in the Team Dashboard 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:

  • In the Team Dashboard view, from the Build section, click Menu; then click Update Refresh Interval. In the Build Section Refresh Interval Dialog box, type the refresh interval in seconds and click OK.

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 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 several interesting 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 widget in your web-based Jazz dashboard:

Web-based Jazz dashboard build results

The Jazz development team has been customizing its build process for awhile. Jazz's build results editor has additional tabs labeled Compilation, JUnit, and Downloads, and External Links. Here is a screen capture 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 Engineering Workflow Management Build functionality.