Configuring CruiseControl for use with ClearCase UCM
by Kevin A. Lee - mail: kevin.lee@buildmeister.com
Introduction
In this post I will discuss how to configure CruiseControl to work with UCM - the ClearCase best practice usage model. Until recently, ClearCase UCM users have had to make use of the CruiseControl <clearcase> plugin which uses Base ClearCase and reports on element versions only not UCM activities and their contents. However, as of CruiseControl 2.4.0, there is now a new <ucm> plugin that can be used for UCM and which I will describe how to use. Note that this plugin requires ClearCase 2003.00.00 or later to work correctly.
In this example, I 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"; I will also assume that the integration stream "Example_Int" is going to monitored for changes. Example_Int is actually the branch type, not the stream name if you happened to rename your stream.
Configure project build file
A project build file is your Ant "build.xml" file or equivalent that describes the targets and tasks that your build is to run. The project build file and its relationship with CruiseControl was discussed in detail here. I will assume that the Ant build target to be invoked in this project build file is called "integration"
Configure CruiseControl config file
To configure CruiseControl to monitor our UCM environment and call this project build file on any changes, you would create a "config.xml" file similar to the following:
1: <plugin name="labelincrementer"
2: classname="net.sourceforge.cruisecontrol.labelincrementers.FormattedLabelIncrementer"/>
3:
4: <plugin name="ucm"
5: classname="net.sourceforge.cruisecontrol.sourcecontrols.UCM"/>
6:
7: <project name="Example">
8: <dateformat format="dd/MM/yyyy HH:mm:ss"/>
9: <labelincrementer defaultLabel="EXAM_1_INT"/>
10: <listeners>
11: <currentbuildstatuslistener file="logs\Example\buildstatus.txt"/>
12: </listeners>
13: <bootstrappers>
14: <clearcasebootstrapper
15: file="build.xml"
16: viewPath="C:\Views\Example_build\Example"/>
17: </bootstrappers>
18: <modificationset>
19: <ucm stream="Example_Int"
20: viewpath="C:\Views\Example_build\Example"
21: contributors="true"/>
22: </modificationset>
23: <schedule interval="600">
24: <ant antscript="C:\Views\java_tools\JavaTools\bin\ant.bat"
25: antWorkingDir="C:\Views\Example_build\Example"
26: buildfile="C:\Views\Example_build\Example\build.xml"
27: target="integration"/>
28: </schedule>
29: <log>
30: <merge file="C:\Views\Example_build\Example\build\TESTS-.xml"/>
31: </log>
32: <publishers>
33: <htmlemail mailhost="smtp.mailhost.com"
34: returnaddress="bldadmin"
35: spamwhilebroken="true"
36: subjectprefix="[CruiseControl]: "
37: buildresultsurl="true"/>
38: </htmlemail>
39: </publishers>
40: </project>
Note on lines 19-22 that the <ucm> sourcecontrol plugin is being called. This takes a number of parameters: the UCM stream (which is used to query the underlying Base ClearCase branch), the path into a view to check for changes and whether contributor activities should be reported on or not. Contributor activities are those that have been "delivered" from a child stream into an integration activity. Also line 9, shows how to use the FormattedLabelIncrementer plugin to create a label that is consistent with ClearCase conventions.
stream is actually the branch type, not the stream name if you happened to rename your stream.
Configure ClearQuest reporting
If you are using ClearQuest as well you can additionally navigate from each UCM modification in the CruiseControl Build Results web to the ClearQuest record that is associated with it. The CruiseControl XSL files have already been populated with sufficient logic to achieve this, however you will need to configure them appropriately for your own ClearQuest environment. To do so, edit the file modifications.xsl, which is in the directory reporting/jsp/webcontent/xsl in the source distribution or the webapps/cruisecontrol/xsl directory of the binary distribution. You will need to change the following variables:
- cqserver - the name of your ClearQuest server
- cqschema - the name of your ClearQuest schema
- cqdb - the name of your ClearQuest database
- cqlogin - the name of an example user to login as
- cqpassword - the password of the example user
Note that for security reasons, you might want to grant this example user read-only privileges. However you could also remove the login logic from the XSL file so that the user has to login each time. A demo of how this integration works can be seen here
As part of the <publishers> I was wanting to use the <clearcasebaselinepublisher> on success. The issue is it uses a default name for the baseline and in most sites that I work they force a baseline naming standard to make it unique across the entrie pvob. Thismeans you cannot set the baseline name at all. I cant use this publisher at these sites. Is there any way to sepcify that I dont want to have any baseline name and therefore allow the baseline to be created using the ClearCase standard for these sites or controling what baseline name is used?
I have tried using the execute command to do the same thing via command line which works except when you run as part of CruiseControl. The baseline is created but it stops looking for modifcations and hangs on the create baseline command. Like its waiting for a return that never happens. I tried this using perl as well so I could ensure we get a return code but I get the same result. This is all to work around the above problem anyway.