Implement continuous integration using Rational Build Forge and Rational ClearCase

Through an example, Lily Wang and Jin Feng demonstrate how to create a continuous integration project in IBM® Rational® Build Forge® and integrate it with IBM® Rational® ClearCase® as the code library system. The demonstration is based on Rational Build Forge 7.1.2 and Rational ClearCase 7.1.2.

Lily Wang (liwang@au1.ibm.com), Technical Support Professional, IBM

Lily Wang is working in Rational Client Support as a technical support professional. She has ten years experience on software configuration and change management design and support with Rational ClearCase, Rational Team Concert and continuous integration products.



Jin Feng (jinfeng@au1.ibm.com), Technical Support Engineer, IBM

Jin Feng is a technical support engineer for Rational Customer Service. She has nearly 10 years of ex-perience supporting Rational ClearCase, and Rational Build Forge, Rational Automation Framework for Web-Sphere.



14 May 2013

Introduction and prerequisites

This article demonstrates how IBM® Rational® Build Forge® implements continuous integration when integrated with IBM® Rational® ClearCase® configuration management software. It includes a step-by-step guide to integrating Build Forge and Rational ClearCase. Through an example, it also shows how to create a continuous integration project in Build Forge with Rational ClearCase as the code library system. The demonstration is based on Build Forge 7.1.2 and Rational ClearCase 7.1.2.

Note:
This article does not include a Rational ClearCase or Build Forge installation guide.

To follow the steps in this article, you need to have these components installed:

  • Rational ClearCase server (including the registry server, VOB server, and view server)
  • Rational Build Forage console (with web server)Build Forge agent
  • IBM® DB2® Express Edition or Enterprise Server Edition

Create a continuous integration project

In this section, we use a sample project to demonstrate how to create a Rational Build Forge project with Rational ClearCase integration. The project will run every hour automatically. If any version changes are made on the integration stream of the ClearCase UCM project, a build will be triggered.

Workflow

You can follow the workflow shown in Figure 1 to implement a Build Forge project.

Figure 1. Workflow chart of the integration project
Flow diagram of workflow details

Set up the ClearCase environment

First, you need to set up a Unified Change Management (UCM) project and the views required by Build Forge:

  1. Create a project versioned object base (VOB), \CC_BF_PVOB, and a component VOB, \CC_BF_CVOB.
  2. Create a UCM project called CC_BF_Test and an integration stream called CC_BF_Test_Integration in the project.
  3. Create a view on the integration stream, and import the HelloWorld testing project. The project contains a HelloWorld.java file and a build.xml file. When using Apache Ant to execute the build, a HelloWorld.jar file will be created as a result.
  4. To perform the build, you also need to create a ClearCase snapshot view so that the source code in ClearCase VOBs can be loaded and the build can be performed in the snapshot view.

Integrate Build Forge with ClearCase

Build Forge can work with ClearCase for code source management. There are many ways to implement this integration, using the adaptor is the easiest one.

There are two ways to implement Build Forge adaptors:

  • Adaptor link method
  • Dot command method

The adaptor link option connects an adaptor to a project and associates an environment with an adaptor. This has the following benefits:

  • Test for source code changes before running other project steps if you are adding the adaptor code as the first step of the Build Forge project
    • If the adaptor runs and passes, the remaining steps in the job will run.
    • If the adaptor fails, none of the other jobs will run. The build will be purged, and the build tag will be rolled back.
  • Automatically populates an environment with application environment variables
  • Enables you to control whether the adaptor code is run by selecting the state of Active, Inactive, or Debug
  • Allows you to run the adaptor as a manual job

Consider this as the first option during adaptor implementation. However, we give the examples of both adaptor link and dot command methods in this article.

There are five different ClearCase adaptor templates. In the example for this article, we use the ClearCaseByDate template, which has the following functions:

  • Queries a ClearCase view for changes between two dates (default dates are the current timestamp and the timestamp of the previous adaptor execution)
  • For each changed file, writes the following information to the BOM report: file name, version, date, user, and comments
  • For each changed file, writes change details (from diff command output) to the Bill of Materials (BOM) report

To use the template, you need to configure the following variables:

  • CurDate
  • LAST_RUN
  • LABEL
  • VIEW
  • VOB_PATH
  • PROJECT_VOB
  • CCSERVER
  • UNIXCLIENT
  • _CHAR_NATIVE

To set up ClearCase adaptor and the preceding variables, as well as other variables that can be used when creating a Build Forge project, follow these steps:

  1. Create a new Rational ClearCase adaptor:
    1. Select Projects > Adaptors in the left panel.
    2. In the right panel, click the Add Adaptor button on the top.
    3. In the New Adaptor window in the lower-right panel (Figure 2), provide values for these fields:
      • Name: ClearCaseAdaptor
      • Type: Source
      • Template: ClearCaseByDate
    4. Click the Save Adaptor button at the top to save your changes.
Figure 2. Creating a Rational ClearCase adaptor
Parameters' details in the ClearCaseAdapter tab
  1. Create build-related environment variables:
    1. In the left panel, select Environment.
    2. In the right panel, click the Add Environment button on the top.
    3. In the New Environment window in the lower-right panel, enter a new environment name, ClearCaseEnv, and set the Access as Build Engineer (Figure 3).
    4. Save the environment.
Figure 3. Creating a new environment group
Details in the ClearCaseEnv tab
  1. Click the Add Environment Variable button at the upper-right (Figure 4).
  2. In the lower-right panel, enter the new environment variable name, ANT_HOME, and set the Value as the directory where you install the ANT. We use value C:\ant\apache-ant-1.8.4 for this example.
  3. Click Save Variable to create the new environment variable.
  4. Repeat steps e through g to create these new environment variables:
    • Enter Name as CurDate, enter Value as .date %d-%b-%y.%H;%M:%S.
    • Enter Name as LAST_RUN, leave Value blank.
    • Enter Name as VIEW, enter Value as administrator_CC_BF_Test_int, which is the ClearCase snapshot view name in this example.
    • Enter Name as VOB_PATH, enter Value as \CC_BF_CVOB, which is the ClearCase component VOB name in this example.
    • Enter Name as PVOB, enter Value as \CC_BF_PVOB, which is the ClearCase component VOB name in this example.
    • Enter Name as CCSERVER, enter Value as build_server.
    • Enter Name as UNIXCLIENT, enter Value as 0 because this example uses Windows environment.
    • Enter Name as _CHAR_NATIVE, enter Value as 1.
    • Enter Name as COMPONENT, enter Value as CC_BF_CVOB for this example.
    • Enter Name as FULL_STREAM_NAME, enter Value as CC_BF_Test_Integration@$PVOBfor this example.
    • Enter Name as BUILD_VIEW, enter Value as CC_BF_build_view.for this example.
    • Enter Name as VIEW_PATH, enter Value as C:\Documents and Settings\Administrator\ for this example.
    • Enter Name as APP, enter Value as HelloWorld for this example.
    • Enter Name as LOAD_DIRS, enter Value as $VIEW_PATH$BUILD_VIEW$VOB_PATH for this example.
    • Enter Name as BUILD_USER, enter Value as Administrator.

Note:
Set the values of VIEW, VOB_PATH, and other ClearCase-related environment variables according to your ClearCase project environment.

Figure 4. Add environment variables to the group
Screen capture shows environment variables list added into group
  1. If you are using the adaptor link method to implement the integration, you can create a new adaptor link:
    1. Select Projects > Adaptors Links in the left panel.
    2. In the right panel, select the Add Adaptor Link button at the top.
    3. In the new adaptor link definition (Figure 5):
      • For Adaptor, select ClearCaseAdaptor, which was created in the Step 1.
      • For Environment, select the ClearCaseEnv created in Step 2.
    4. For Project, you might not see any Build Forge project yet. After you create a new Build Forge project in the next section, you will see the project name listed, and you can select the newly created Build Forge project.
    5. Click Save to save the new adaptor link.
Figure 5. Creating an adaptor link
Adapter link definition, details

Implement the Build Forge project

Follow the steps in this section to set up a Build Forge project to implement the workflow shown previously in Figure 1.

Create a new Build Forge project

  1. Launch the Build Forge console from a web browser and log in as a Build Forge administrator.
  2. Create a new Build Forge project:
    1. In the left panel, select Projects (Figure 6).
    2. In the Project: Add Project panel:
      • For Name, enter CC_Integrate_Build.
      • For Class, select ClearCase.
      • For Environment, select ClearCaseEnv.
    3. Set up the notification. In this example, when a build is started, the build engineer will be notified. When a build passes or fails, the developer will get the notification. Therefore, select these options:
      • Start Notify: Build Engineer
      • Pass Notify and Fail Notify: Developer
    4. Click the Save button at the top.
Figure 6. Creating a Build Forge project
Project Details tab shows selections

Set the scheduler for an automatic continuous integration build

  1. Select Schedules in the left panel (Figure 7).
  2. In the right panel, select the Add Scheduled Run button at the top to create a new scheduler.
  3. In the lower-right panel:
    • For Description, enter CC_Integrate_Build_Scheduler.
    • In the Project field, select the CC_Integrate_Build project created in earlier.
    • For Environment, select ClearCaseEnv, which you created previously.
    • For Minutes, enter 0 [zero] so the scheduler will run every hour.
  4. Click the Save Schedule button at the top.
Figure 7. Creating a Build Forge schedule
Schedule detail selections

Create the build steps in the build project

In this step, the ClearCase adaptor is called. If there are any file changes in the integration stream of the ClearCase UCM project, a build will be triggered.

Note:
This step is required only when implementing the ClearCase and Build Forge integration using Dot command method. If you create the adaptor link which is required by adaptor link method, this step is not required and must be disabled.

Create the Run Source Adaptor step

  1. In the left panel of Build Forge console, select Projects (Figure 8).
  2. In the right panel, click the CC_Integrate_Build project to open the project
  3. Click the Add Step button at the top to add a new step.
  4. Enter the required information in these fields in the new step Details area:
    • Name: Run Source Adaptor
    • Command:
      .bset env "CCSERVER=$build_server"
      .source "ClearCaseAdaptor"
  5. Click the Save Step button at the top.
Figure 8. Creating the Run Source Adaptor step
details for creating the Run Source Adaptor step

Create the Lock Stream step

During the build, the integration stream is locked so that no changes can be made to the stream. The purpose is to keep a stable code base.

  1. In the CC_Integrate_Build project, click the Add Step button (Figure 9).
  2. In the new step definition of the lower-right panel
    • For Name, enter Lock Stream.
    • For Command, enter:
      cleartool lock -nusers $BUILD_USER stream:$FULL_STREAM_NAME
  3. Click the Save Step button at the top.

You can use the -nusers $BUILD_USER argument here so that the build user has permission to create a baseline if the build succeeds.

Figure 9. Creating the Lock Stream step
details for creating Lock Stream step

(Optional) Create the Clean Up Build Area step

This step is optional. If you need to run a clean build, you can enable this step to delete all files used by the last build. However, if you want to do an incremental build, you can disable this step.

  1. In the CC_Integrate_Build project, click the Add Step button (Figure 10).
  2. Enter these values in the new step definition Details section:
    • For Name enter Clean Up Build Area
    • For Command, enter:
      cd "$VIEW_PATH$BUILD_VIEW"
      rmdir /s /q $COMPONENT
  3. Click Save Step.
Figure 10. Creating the Cleanup Build Area step
Cleanup Build Area selected as step name

Create the Load Files to View step

In this step, the Build Forge project calls cleartool update command to load all files to the snapshot view of the integration stream.

  1. In the CC_Integrate_Build project, click Add Step (Figure 11).
  2. In the new step definition area, enter these details:
    • Name: Load Files to View
    • Command:
      cd "$VIEW_PATH$BUILD_VIEW"
      cleartool update .
  3. Click Save Step button on the top.
Figure 11. Creating the Load Files to View step
details for creating Load Files to View step

Create the Compile step

The Compile step executes the product build script and creates the build artifacts as a result. In this example, Apache Ant is used to compile the HelloWorld project.

  1. In the CC_Integrate_Build project, and click Add Step button (Figure 12).
  2. In the new step definition area, enter these details:
    • Name: Compile
    • Command:
      cd "$LOAD_DIRS"
      cd ccbf.src
      cd HelloWorld
      ant -buildfile build.xml jar
  3. Click Save Step at the top.
Figure 12. Creating the Compile step
Compile selected as step name

(Optional) Create a Sanity Test step

If a quick sanity test is required after the build artifacts are created, you can create a Sanity Test step. In this example, Ant is used to compile and test the HelloWorld project.

  1. In the CC_Integrate_Build project, click Add Step button (Figure 13).
  2. In the new step definition, enter these details:
    • Name: Sanity Test
    • Command:
      cd "$LOAD_DIRS"
      cd ccbf.src
      cd HelloWorld
      ant -buildfile build.xml test
  3. Click Save Step at the top.
Figure 13. Creating the Sanity Test step
Create the Create and recommend baselines step

The seventh step is "Create and recommend baselines," which is used to label the successful build of the ClearCase source code in the integration stream.

  1. In the CC_Integrate_Build project, click Add Step button (Figure 14).
  2. Enter these details:
    • Name: Create and Recommend Baselines
    • Command:
      cd "$LOAD_DIRS"
      cleartool mkbl -identical $BF_TAG
      cleartool chstream -recommended $BF_TAG stream:$FULL_STREAM_NAME
  3. Click Save Step.
Figure 14. Creating the "Create and recommend baselines" step
Commands' details for creating Create and recommend baselines step

Create the Unlock Stream step

After the build completes and the baseline has been created, the integration stream can be unlocked.

  1. In the CC_Integrate_Build project, click Add Step (Figure 15).
  2. Enter these details:
    • Name: Unlock Stream
    • Command:
      cleartool unlock stream:$FULL_STREAM_NAME
  3. Click Save Step.
Figure 15. Creating the Unlock Stream step
Commands' details for creating Unlock Stream step

Create the last step, Export BOM report

This last step exports the Bill of Materials (BOM) for a job to an XML file.

  1. In the CC_Integrate_Build project, and click Add Step button (Figure 16).
  2. In the new step definition area, enter these details:
    • Name: Export BOM Report
    • Command:
      cd "C:\Program Files\IBM\Build Forge"
      bfbomexport -f $BF_SERVER_ROOT\bom_$BF_TAG.xml -P "CC_Integrate_Build" -t $BF_TAG -L
  3. Click Save Step.
Commands' details for creating Export BOM report step

Run the Build Forge project

Dot command method

  1. To test the Build Forge project using the dot command method, you can modify the ClearCase HelloWorld.java file by check-out and check-in from an integration view (Figure 17).
Figure 17. Creating a new version from the integration view
Screen capture shows modifying a file in the integration view

A build will be triggered every hour, based on the schedule that you created in the Set the scheduler for an automatic continuous integration build step.

You can see the build status by selecting Jobs in the left panel of the Build Forge console (Figure 18).

Figure 18. Check the build status when a build is triggered
Screen capture shows the ongoing build status
  1. After the build completes, you can view the Bill of Materials report:
    1. Select Jobs in the left panel of the Build Forge console (Figure 19).
    2. Click the build ID of the completed build in the right Jobs panel.
    3. Select Bill of Materials from the extended menu in the left panel.

The HelloWorld.java file and the corresponding version are listed in the Source Changes section.

Figure 19. Check the Bill of Materials after the build completes
Screen capture shows Bill of Materials details

Adaptor link method

To test the Build Forge project using the adaptor link option, configure the method:

  1. In the left panel, select Projects > Adaptor Links (Figure 20).
  2. In the right panel, click the ClearCaseAdpator adaptor link.
  3. For the Project, check the Build Forge project, CC_Integrate_Build.
Figure 20. Check the adaptor link that is created for the Build Forge project
project selection in the adaptor link definition
  1. In the left panel, turn on the Adaptor link quick start switch by selecting Administration > System (Figure 21).
  2. In the right panel, click the Link Manual Jobs, change the job from the default value of No to Yes, and then save the change.
Figure 21. Change system settings to enable the adaptor link function
Enabled Adaptor Link function in Administrator-System
  1. Select Projects in the left panel, and open the CC_Integrate_Build Build Forge project (Figure 22).
  2. Disable the first step, Run Source Adaptor, in the Build Forge project, because the adaptor link will automatically insert the adaptor step into the project when the build job is executed.
Figure 22. Disable the Run Source Adaptor dot command step
Disabled Run Source Adaptor dot command

After that, when you modify the file HelloWorld.java file in ClearCase, a build will be triggered as scheduled.

As the Job Steps section in Figure 23 shows, the first step in the project is replaced by Adaptor ClearCaseAdaptor, which is created by the Adaptor Link method automatically.

Figure 23. Adaptor ClearCaseAdaptor listed first under Job Steps
Job steps by name, all results show passed

Summary

Using the ClearCase Adapter in Build Forge, a continuous integration system can be set up easily. With the system, the build efficiency and release quality can improve in both agile and traditional development environments.

Resources

Learn

Get products and technologies

  • Download a free trial version of Rational software.
  • Evaluate other IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=929435
ArticleTitle=Implement continuous integration using Rational Build Forge and Rational ClearCase
publish-date=05142013