Extending CruiseControl by Modifying the Build Results Web

The preceding section illustrated how to generate an XML baseline release report and transform it into HTML. You could use this report as your release notes or publish it to your own internal project Web site. The CruiseControl Build Results web is one form of project Web site. Since you can also configure CruiseControl to automate the generation of your baselines, why not go to the next logical step and modify the Build Results web to display the baseline report too? Figure 9.4 shows the type of output you might want to achieve.

Figure 9.4. CruiseControl ClearCase baseline report

This section describes the process to customize the CruiseControl Build Results web to achieve exactly this.

Generating an XML Baseline Report

First you need to modify the Ant target that CruiseControl executes for you (as part of your Integration Builds) to create a baseline and baseline report. Assuming that you want to use an Ant target called integration-baseline to achieve this, you would add or modify the following target in your project's Ant build.xml file:

<target name="integration-baseline" description="Integration Build and Baseline"     depends="update-view, clean, junit-all, dist, javadoc">     <cc-apply-bl basename="${label}"         component="${name.build.component}"/>     <ca:ccblreport         baselineselector="${name.build.component}_${label} @${name.project-vob}"         outfile="build/ccblreport.xml"/> </target>

This target makes use of the fact that the build label created by CruiseControl is passed to the build script via the property ${label}. First, all the dependencies are executed for the target, such as compilation and unit testing. When this is complete, a predefined Ant macro (as in Chapter 5, "Apache Ant Best Practices") called <cc-apply-bl> is executed to apply the baseline. Finally, the <ccblreport> task from clearantlib (as used in the preceding section) is executed using the full name of this baseline, and the XML output is placed in the file build/ ccblreport.xml.

Merging the XML Baseline Report into the CruiseControl Log

To present the ClearCase baseline report from the CruiseControl Build Results web, you need to merge the contents of the generated XML baseline report into CruiseControl's own build log. Fortunately, there is a simple mechanism to achieve thisCruiseControl's <merge> plug-in. This plug-in was used in Chapter 6, "Running Your Build Scripts," to merge the results of JUnit test runs. To allow it to merge the contents of the baseline report file, you would change the CruiseControl config.xml as follows:

<project name="RatlBankModel_int">     ...     <schedule interval="600">         <ant antWorkingDir="${dir.ratlbankmod}"          buildfile="${dir.ratlbankmod}/build.xml"          target="integration-baseline"/>     </schedule>     <log>         <merge file="${dir.ratlbankmod}/build/ccblreport.xml"/>          ...      </log>     ... </project>

This example also illustrates the Ant integration-baseline target being executed via the Ant builder. With this in place, whenever this project is executed, the contents of the generated ccblreport.xml file are placed in the CruiseControl build log. To verify this, you can go to the CruiseControl Build Results web and click the XML Log File tab for a build generated using the integration-baseline target. You should see output similar to that shown in Figure 9.5.

Figure 9.5. CruiseControl XML log file

Now that the CruiseControl build log contains the required content, the Build Results web can be customized to display this information.

Adding a ClearCase Tab to the CruiseControl Build Results Web

To change the CruiseControl Build Results web, navigate to the directory where you extracted the CruiseControl source distribution. The only files that need changes are the "presentation" files (JSP or XSL files). These are all contained in this directory:

reporting/jsp/webcontent

If you enter this directory, you should see a collection of .jsp files and directories, as shown in Figure 9.6.

Figure 9.6. CruiseControl Build Results web directory

First, edit the main.jsp file to add a new tab for ClearCase:

... <cruisecontrol:tab name="xmlLogFile" label="XML Log File" >   <%@ include file="xmllog.jsp" %> </cruisecontrol:tab> <cruisecontrol:tab name="ClearCase" label="ClearCase" >   <%@ include file="clearcase.jsp" %> </cruisecontrol:tab> <cruisecontrol:tab name="metrics" label="Metrics" >   <%@ include file="metrics.jsp" %> </cruisecontrol:tab> ...

This example also shows the context of the change to illustrate the order in which the tabs are generated. You can specify your own order if desired and also call this tab whatever you like. I call it ClearCase. The important point is that it refers to a .jsp file called clearcase.jsp. This JSP file initiates the transformation of the CruiseControl log file. Create this file as shown in Listing 9.2.

Listing 9.2. clearcase.jsp File

<%@ taglib uri="/WEB-INF/cruisecontrol-jsp11.tld" prefix="cruisecontrol"%> <cruisecontrol:xsl xslFile="/xsl/clearcase.xsl"/>

Note that this file refers to an XSLT transformation file called clearcase.xsl, which will be created next.

Creating an XSLT Stylesheet

Next an XSLT stylesheet needs to be created to transform the part of the CruiseControl build log that contains the ClearCase baseline information. First, however, to simplify the content of this stylesheet, it is best to place the CSS style definitions in CruiseControl's own CSS file. This file is located in the css directory and is called cruisecontrol.css. Open this file and add the following two lines at the bottom:

[View full width]
.clearcase tr th { font:normal 68% verdana,arial,helvetica; color:#000000; font-weight:  bold; text-align:left; background:#a6caf0; } .clearcase tr td { font:normal 68% verdana,arial,helvetica; color:#000000; background :#eeeee0; }

These two lines basically specify a clearcase look and feel for HTML tables. Next, create an XSLT file called clearcase.xsl in the xsl directory, as shown in Listing 9.3.

Listing 9.3. clearcase.xsl File

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output omit-xml-declaration="yes" method="html"/> <xsl:template match="cruisecontrol">   <xsl:call-template name="baselines"/> </xsl:template> <!-- Baseline Details --> <xsl:template name="baselines">   <xsl:for-each select="baseline">     <table  cellpadding="5" cellspacing="2" width="100%">       <th colspan="2" align="left" font="+1">Baseline Details</th>       <tr valign="top">         <td>Name:</td> <td><xsl:value-of select="@name"/></td>       </tr>       <tr valign="top">         <td>Created:</td> <td><xsl:value-of select="@date"/></td>       </tr>       <tr valign="top">         <td>Created by:</td> <td><xsl:value-of select="@author"/></td>       </tr>       <tr valign="top">         <td>Status:</td> <td><xsl:value-of select="@status"/></td>       </tr>       <tr valign="top">         <td>Level:</td> <td><xsl:value-of select="@level"/></td>       </tr>     </table>     <xsl:call-template name="details"/>   </xsl:for-each> </xsl:template> <!-- Activity Details --> <xsl:template name="details">   <table  border="0" cellpadding="5" cellspacing="2" width="100%">     <tr>       <th align="left">Name</th>       <th align="left">Created</th>       <th align="left">Created by</th>       <th align="left">Headline</th>     </tr>     <xsl:for-each select="activity">       <xsl:sort select="@date" order="descending"/>         <tr>           <td><xsl:value-of select="@name"/></td>           <td><xsl:value-of select="@date"/></td>           <td><xsl:value-of select="@author"/></td>           <td><xsl:value-of select="@headline"/></td>         </tr>       <xsl:for-each select="contributor">         <tr >           <td style="background: #dddde0" align="right"><xsl:value-of select="@name"/></td>           <td style="background: #dddde0"><xsl:value-of select="@date"/></td>           <td style="background: #dddde0"><xsl:value-of select="@author"/></td>           <td style="background: #dddde0"><xsl:value-of select="@headline"/></td>         </tr>       </xsl:for-each>     </xsl:for-each>   </table> </xsl:template> </xsl:stylesheet>

Note that this example is almost identical to Listing 9.1.

Deploying the Modified Build Results Web

To deploy the Build Results web, you should first recompile the application and then deploy it using Tomcat. The process to achieve this is described in detail at the beginning of Chapter 7. The only difference is that you need to "undeploy" the existing Build Results web first. You do this by clicking the Undeploy link next to the cruisecontrol application, as shown in Figure 9.7.

Figure 9.7. Tomcat Web Application Manager

With the new CruiseControl Build Results web now deployed, the next time an Integration Build and baseline is invoked, you should now have an automatically populated ClearCase tab, as shown in Figure 9.4 at the beginning of this section.

If you find that no content is displayed on this tab, first check that a new UCM baseline has been created. (If you force a build in CruiseControl and no new activities are created, unless you force it to UCM will not create a new baseline.) Next, check that the ccblreport.xml has been generated successfully in your build view and has some content. Finally, check that this file has been successfully merged into the CruiseControl build log by clicking the XML Log File tab in the Build Results web.

Further Customizations

This section has described a relatively straightforward customization of CruiseControl. However, this is really just a start; there are always more possibilities. For example, you might want to modify the ClearCase baseline report so that each activity name is an HTML link. That way, when you click the link, you are taken to a ClearQuest database to find more detailed information about it. The most important thing to note is that the information recorded in CruiseControl is static; it essentially captures information on a build baseline at a particular point in time. For example, a baseline's promotion level probably will change over time. However, if you visit the Build Results web, the baseline's promotion level will be as it was at the point the build was carried out.

Another issue is that to be able to generate the report on the build's contents, from a ClearCase point of view a new baseline must be created. However, you might not want to create a baseline for every buildparticularly Integration Builds. In this case, how can you retrieve information on what the build actually consumed or produced? Fortunately, ClearCase has an additional capability to achieve this called build auditing, as discussed in the next section.