Configuring CruiseControl for ClearCase Snapshot Views and baselining
by Kevin A. Lee - mail: kevin.lee@buildmeister.com
Introduction
In this post we will discuss how to configure CruiseControl to work with IBM Rational ClearCase - the most popular commercial Software Configuration Management tool. We will be using ClearCase snapshot views, rather than dynamic views, for better build performance and because they suit the build environment of CruiseControl slightly better.
We will assume that we are building a project called "Example" and that a snapshot build view has already been created for this project, called "C:\Views\Example_build"; finally we will also assume that there is an integration branch or stream called "Example_Int" in this project which we are going to monitor for changes. I will be using UCM for creating baselines but the principles can easily be mapped to Base ClearCase labels instead.
Configure project build file
My preference is to develop a single project "build.xml" file that can be used by anyone: developers, release engineers or automatically invoked by CruiseControl. I believe this is better than maintaining a separate CruiseControl "project-build.xml" file which calls the original "build.xml" file. An example of the additional entries I would put into a project "build.xml" file for CruiseControl are as follows:
1: <?xml version="1.0"?>
2: <?xml-stylesheet type="text/xsl" href="ant2html.xsl"?>
3: <project name="RationalBankWeb"
4: default="help" basedir="."
5: xmlns:ca="antlib:com.buildmeister.clearantlib">
6:
7:
8: <target name="update-view"
9: description="update ClearCase snapshot view">
10: <ca:cleartool failonerror="false">
11: <commandline>
12: <argument line="update -force -log NUL .\..\.."/>
13: </commandline>
14: </ca:cleartool>
15: </target>
16:
17: ... other normal project build tasks ...
18:
19:
20: <target name="cc-build" description="execute a CruiseControl Integration build">
21: <antcall target="update-view" />
22: <antcall target="dist" />
23: <antcall target="deploy"/>
24: <antcall target="javadoc" />
25: <ca:cleartool>
26:
27: <commandline>
28: <argument value="mkbl"/>
29: <argument value="-full"/>
30: <argument value="${label}"/>
31: </commandline>
32:
33: <commandline>
34: <argument value="chbl"/>
35: <argument line="-level BUILT"/>
36: <argument value="${label}@\\ProjectVOB"/>
37: </commandline>
38:
39: <commandline>
40: <argument value="chstream"/>
41: <argument value="-recommend"/>
42: <argument value="${label}@\\ProjectVOB"/>
43: <argument value="Example_Int"/>
44: </commandline>
45: </ca:cleartool>
46: </target>
47: </project>
This build file contains two new tasks: "update-view" and "cc-build". The "update-view" task obviously brings the snapshot view up to date. The "cc-build task" is the one that we will be getting CruiseControl to execute; it basically carries out an integration build and test and then puts a baseline down on the project files. Note that rather than using the ClearCase integration tasks that come with Ant, I am using my own ClearAntLib library as it is more flexible. Further details on this library can be found here.
Configure CruiseControl config file
Next we need to configure CruiseControl's "config.xml" file to call this build file; an example to do this would be as follows:
1: <project name="Example" buildafterfailed="false">
2: <dateformat format="dd/MM/yyyy HH:mm:ss"/>
3: <labelincrementer defaultLabel="EXAMBLD.1" separator="-"/>
4: <listeners>
5: <currentbuildstatuslistener
6: file="logs\Example\buildstatus.txt"/>
7: </listeners>
8: <bootstrappers>
9: <clearcasebootstrapper
10: file="build.xml"
11: viewPath="C:\Views\Example_build\Example"/>
12: </bootstrappers>
13: <modificationset requiremodification="true" quietperiod="60">
14: <clearcase
15: branch="Example_Int"
16: viewpath="C:\Views\Example_build\Example"
17: recursive="true" />
18: </modificationset>
19: <schedule interval="600">
20: <ant
21: antscript="C:\Views\java_tools\JavaTools\bin\ant.bat"
22: antWorkingDir="C:\Views\Example_build\Example"
23: buildfile="C:\Views\Example_build\Example\build.xml"
24: uselogger="true"
25: usedebug="false"
26: target="cc-build"/>
27: </schedule>
28: <log>
29: <merge
30: file="C:\Views\Example_build\Example\build\TESTS-.xml"/>
31: </log>
32: <publishers>
33: <htmlemail
34: mailhost="smtp.mailhost.com"
35: returnaddress="bldadmin"
36: spamwhilebroken="true"
37: subjectprefix="[CruiseControl]: "
38: buildresultsurl="true"/>
39: </htmlemail>
40: </publishers>
41: </project>
There is quite a lot of ClearCase configuration in this file, of note are the following:
- line 3: This is where we define the format of the label that CruiseControl will automatically create, it will be passed to our project "build.xml" file as "label" and will be of the format EXAMBLD-1, EXAMBLD-2 and so on.
- lines 9-11: Since we are using a snapshot view and "build.xml" might have changed itself, we need to update this single file before running the build.
- lines 13-18: This is where we define what changes to look for, we will look into our pre-configured build view "C:\Views\Example_build" and at the integration branch/stream.
- lines 20-27: We will invoke the build, if something has changed, every 10 minutes. We will do this by going down into our build view and executing Ant on the target "cc-build" that we created earlier on.
The remaining lines are standard CruiseControl configuration, irrespective of ClearCase.
In Use
This is really an example of some basic configuration, enough to get you up and running with CruiseControl. In reality you might want to schedule nightly builds as well as modification builds, you might only want to promote the baseline if the build actually works and so on. As a word of caution, you might not want to create a new UCM baseline every build as too many baselines can potentially slow down ClearCase; either clean out old baselines or only put the baselines down infrequently.
There are lots of additional features of ClearCase that you can potentially use here to get a really good build environment up and running. I hope this example has whetted your appetite.
