SpiderLogic.com

Cruise Control V2.0

Al Wick

I have been using cruise control for almost a year now. It provides a great addition to our development process. Cruise Control is built on the concept of Contiuous Integration where you are testing the integration build with each developer's checkin to your source control system. Cruise control can be setup to check for updates to your source control system and perform ant tasks based on the checkins. It is written in Java so it is portable to whatever operating system you wish to run it on.

This article will explain how we converted to the new version and how we have configured it to work on our development team. Our development team is spread over two companies, so our email notification goes out to two separate email suffixes. We are also running cruise control against multiple projects. We are using CVS as our code repository.

Why Upgrade?

The new version fixes a number of problems we were having with the old version. For instance, the compile output is now part of the generated xml and can be included in the web results.

In addition, there have been several enhancements like being able to send the html output instead of having to be directed to a web page. There is now only one configuration file defined in xml format and fewer tasks required in your ant build file.

Installing Cruise Control

Cruise control is a sourceforge project and may be downloaded here.
Extract the zip file into a directory of your choice. I put mine in the c:\java directory
You have to build the file, by executing the build.bat file in the main subdirectory. The build will put a cruisecontrol.jar file in the dist sub-directory

Setting up Cruise Control

These are the steps I used to setup our build process. We are using CVS for our version control system.

Create a root directory for your build(s). I created a c:\build directory.
Use CVS to checkout our project. In this case it is project6. The checkout creates a project6 sub-directory in the c:\build directory.
Create the config.xml file that has the cruise control configuration information in it.

If you are upgrading, you can run the upgrader:
java -jar cruisecontrol.jar -upgrade buildfile propertiesfile configfile projectname
My configuration file is cruisecontrol.xml.
Copy the cruisecontrol.bat file into the build directory
Create a runProject6.bat file that runs the project6 configuration from the cruisecontrol.xml file. This bat file needs to set the ccdir environment variable to the install directory for cruisecontrol. The bat file will also pass in the correct project name to the cruisecontrol.bat file for our project.

set
ccdir=C:\java\cruisecontrol-2-0-1\main
cruisecontrol.bat -projectname cmic_project6 -configfile
cruisecontrol.xml

The Build Loop

The build loop is a very important concept to cruise control. The build loop refers to the process of running a daemon that wakes up on a timed interval to look for changes checked in by one or more developers, logging the build status, and sending email notification.

Scheduling

Cruise Control is configured to run periodically to look for changes and do it's thing. The schedule element is used to define the amount of time to wait between running. It also defines which ant targets to execute in your build script if changes are found (see how detected below). The ant targets are defined to be executed based on how many times cruise control has run previously. This will allow you to do a clean build every nth time cruise control runs if you wish.

Change Detection

Changes are detected by getting a list of changes from the version control system since the last time Cruise Control ran. The properties for connecting are found in the modificationset element. The detection of changes is what will trigger Cruise Control to go on with it's process. If no changes are detected, Cruise Control will sleep for the schedule interval amount of time.

The quite period refers to an amount of time that has to have occurred since the last checkin to wait before executing the build loop. This allows developers that may be in the middle of checking things in, finish what they are doing.

Notifying Users

Cruise Control will notify the developers when the build loop has finished. The build loop will finish if either the build is successful or the build fails. If the build is successful, all developers that checked stuff in will be notified. If the build fails, all developers are notified. Notification is configured using the publishers element.

Cruise Control will retry the build after some period of time and send out notification to developers based on a success/fail. On subsequent builds, all developers are again notified of failure and success notification is only sent to the developers involved in checking code in. Cruise Control can be configured to send updates to all developers upon a successful build after a failed one.

Displaying Results

Results of builds can be emailed as html messages or as a link to web page. The results can show compile messages, junit output, a list of files changes and by whom, and other nifty items.

The Configuration File

The cofiguration file is used to control the build loop. The configuration file in in xml format.

Full Config file

Here we will go through actually setting up a configuration file for a project. This is the full cruisecontrol.xml file that I have created for my project.

<cruisecontrol>
   <project name="cmic_project6">
      <bootstrappers>
         <currentbuildstatusbootstrapper
file="project6_currentbuild.txt" />
        <cvsbootstrapper cvsroot=":pserver:awick@k2:/cvsroot"
                       file="project6/build.xml" />
      </bootstrappers>
      <modificationset quietperiod="180"
dateformat="yyyy-MMM-dd HH:mm:ss">
         <cvs cvsroot=":pserver:awick@k2:/cvsroot"
              localworkingcopy="project6"/>
      </modificationset>
      <schedule interval="600" intervaltype="relative">
         <ant buildfile="project6/build.xml"
target="integration.clean" multiple="5" />
         <ant buildfile="project6/build.xml"
target="integration" multiple="1" />
      </schedule>
      <log dir="project6_logs">
         <merge dir="project6/junit"/>
      </log>
      <publishers>
         <currentbuildstatuspublisher
file="project6_currentbuild.txt" />
         <email mailhost="our-mail-host"
                returnaddress="awick@spiderlogic.com"
                defaultsuffix="@spiderlogic.com"
               
buildresultsurl="http://k2:8080/project6/buildresults">
            <always address="buildmasters" />
            <failure address="developers" />
            <map alias="developer1"
address="developer1@othercompany.com" />
            <map alias="developer2"
address="developer2@othercompany.com" />
            <map alias="buildmasters" address="awick" />
            <map alias="developers" address="awick,
localdeveloper, developer1, developer2" />
         </email>
      </publishers>
   </project>
</cruisecontrol>

In the following sections, I will break down the full file into sections.

Project

Each project is defined using the project tag. There may be several projects defined in a single configuration file.

<cruisecontrol>
  <project name="cmic_project6">
    ..... Stuff....
  </project>
</cruisecontrol>

The name of the project is cmic_project6 and is used when starting cruise control to identify the project to run.

NOTE: If you are using sub-directories, you cannot name your project the same as the subdirectory since cruise control creates a serialized project object file with the project name.

Bootstrappers

Bootstrapers are files that need to be updated before the build takes place.

<bootstrappers>
   <currentbuildstatusbootstrapper
file="project6_currentbuild.txt" />
   <cvsbootstrapper cvsroot=":pserver:awick@k2:/cvsroot"
                    file="project6/build.xml" />
</bootstrappers>

Here we have two bootstrappers. The first one is for the current status file. This tells cruise control when the last run was. The second is the ant build script. We want to update before calling in case there were changes.

Modificationset

The modificationset is where you define the parameters for determining if there are any changes to the repository since the last time cruise control ran. You also can define a different location for the project files and the quiet period. The localworkingcopy attribute tells cruise control where to look for the project code you checked out. In our case it is the project6 sub-directory. The quite period refers to the amount of time since the last time someone checked stuff in to wait before doing a build. This allows for people to finish checking stuff in before the build process executes.

<modificationset
quietperiod="180" dateformat="yyyy-MMM-dd HH:mm:ss">
   <cvs cvsroot=":pserver:awick@k2:/cvsroot"
        localworkingcopy="project6"/>
</modificationset>

Here we are telling cruise control to wait 180 seconds past the last checkin to run. We are also definining the local directory and cvs information so the process may look for updated files.

Schedule

This element is used to define when to run the build loop and which ant target(s) to execute on the build file for each run.

<schedule interval="600"
intervaltype="relative">
   <ant buildfile="project6/build.xml"
target="integration.clean" multiple="5" />
   <ant buildfile="project6/build.xml" target="integration"
multiple="1" />
</schedule>

Log

The log element describes where the log output is to go for the build loop. You may also include locations to other files or directories to be merged into the log file. This is very useful for merging in the results of unit tests.

<log dir="project6_logs">
   <merge dir="project6/junit"/>
</log>

Here we are putting the output log file into a project6_logs directory and merging in the junit results from the project6/junit sub-directory.

Publishers

Publishers are used to define where the output of the build should be put. They may also define who to notify and in which format to notify them.

<publishers>
   <currentbuildstatuspublisher
file="project6_currentbuild.txt" />
         <email mailhost="our-mail-host"
                returnaddress="awick@spiderlogic.com"
                defaultsuffix="@spiderlogic.com"
               
buildresultsurl="http://k2:8080/project6/buildresults">
            <always address="buildmasters" />
            <failure address="developers" />
            <map alias="developer1"
address="developer1@othercompany.com" />
            <map alias="developer2"
address="developer2@othercompany.com" />
            <map alias="buildmasters" address="awick" />
            <map alias="developers" address="awick,
localdeveloper, developer1, developer2" />
         </email>
</publishers>

In this case we are going to send email notification to buildmasters alias each time cruise control runs the build cycle on new or updated code. The developers alias will get sent an email whenever the build is broken. The buildmasasters alias and any developers that have checkins will be notified if the build is successful.

Note: Cruise control uses the cvs username as the name of the developer and will check for an alias with that username. If noone is found with an alias, it append the defaultsufffix to the username and send an email.

Configuring Web Application

Within the Cruise Control download, there is a web application that can be used to display the build results. This may be found in the reporting/jsp sub-directory.

Updating Properties

You will want to update the web.xml file in the WEB-INF sub-directory to point to directories/files for your project.

Property	Value	Example Value
logDir	The location of the logs directory	c:\build\project6_builds
currentBuildStatusFile	The location of the last run status file	project6_currentbuild.txt

Building the distribution

You will then want to run the build.bat file in the jsp directory to build the .war file.

You can then use the war file to publish to your favorite servlet container. In my case I copied it into the webapps directory of my Tomcat installation and restarted Tomcat.

NOTE: for this application I made the war file project6.war so that the url would match the url in the cruisecontrol.xml file. buildresultsurl="http://k2:8080/project6/buildresults"

Conclusion

Cruise control offers a great automated process around verifying the state of your code. Version 2.0 offers a lot more flexibility and options. The documentation for the configuration file is pretty good. With the help of this article you are now able to better understand the configuration and use of Cruise Control for your project.