Introduction to CruiseControl

Filed under: build automation build scripting agile build java tools
There are 2 comments on this article.

Introduction

CruiseControl is a "framework for a continuous build process" that allows you to automate the execution of your builds and report on their results. CruiseControl was written to realise the process of Continuous Integration - an eXtreme Programming (XP) practice for frequently, integrating small changes within a project. However, CruiseControl does not dictate this process and you can use it for any project where integration builds are carried out frequently (usually at least once a day).

There are now three flavours of CruiseControl: one for Java, one for Microsoft .NETapplications (CruiseControl.NET) and one for Ruby (CruiseControl.rb). Unfortunately, these variants do not share the same code base and have different capabilities and configurations. The instructions and definitions contained in this document refer to the open source "Java" edition. This is the oldest and most mature version of CruiseControl. It can also be used for building languages other tha Java since it provides a number of different builder plugins.

The examples use Apache Ant as the build tool and Subversion as the version control provider.

Installing CruiseControl

You can download the latest version of CruiseControl from its SourceForge website. There are three types of downloads:

The Windows self installing executable.
The binary Zip file.
The source Zip file.

If you run your build processes on Windows then I recommend the self installing executable as it simplifies the installation process. If you are running Linux or UNIX then download the binary Zip file. If you choose the Windows installer then by default, CruiseControl will be installed to the directory C:\Program Files\CruiseControl, however you can select an alternate installation directory which is what I will do in this article. If you choose the binary Zip file then simply extract the contents to you chosen installation directory. In this article I will assume that you have installed CruiseControl to the following directory on Windows:

C:\JavaTools\cruisecontrol-bin-2.8.2

Or the following directory on Linux or UNIX:

/opt/javatools/cruisecontrol-bin-2.8.2

If you have chosen the Windows installer then CruiseControl can be installed as a service, to start it for the first time navigate to the Windows Services Control panel and start the service called "CruiseControl.

If you have chosen the binary Zip version then navigate to the install directory and execute the CruiseControl start-up script. On Windows this would be:

>cd C:\JavaTools\cruisecontrol-bin-2.8.2\bin
>cruisecontrol.bat

Or on Linux or UNIX:

>cd /opt/javatools/cruisecontrol-bin-2.8.2/bin
>cruisecontrol.sh

CruiseControl should start up successfully and build its sample project “connectfour”. You can examine the build results by pointing your browser at the CruiseControl dashboard – the default URL is http://servername:8080/dashboard (where servername is the name of the server where you installed CruiseControl). You should see the "connectfour" project being built and a screen similar to the following:

[CruiseControl Dashboard]

You can also examine the CruiseControl log file which is contained in the in the CruiseControl home directory (where you installed CruiseControl) and is called cruisecontrol.log.

The CruiseControl configuration file

The input to CruiseControl is also an XML configuration file. By default it is called config.xml and is located in the CruiseControl home directory. If you examine this file you will see that it is configured to build a single sample project called “connectfour”. CruiseControl is designed with a small core and a very high-level controlling implementation; most of the implementation details are delegated to plugins. There are a large number of existing plugins (see the CruiseControl configuration reference for the complete set). Since CruiseControl has been around for a long time and is used widely you will find that these plugins cover most scenarios and integrate with many products - however if you cannot find the one that you require, one of the many good thinigs about CruiseControl is that you can always write a Java class to implement your own. I have done this a couple of times before and my contributions are now part of the CruiseControl code base.

The CruiseControl configuration file can be amended to build a number of related or independent projects. Its general multi-project format is as follows:

<cruisecontrol>

<property name=…>
<plugin name=…>

<project name="project1">
    <property name=…>
    <listeners/>
    <bootstrappers/>
    <modificationset/>
    <schedule/>
    <log/>
    <publishers/>
</project>

<project name="project2">
    …
</project>
…
</cruisecontrol>

Every CruiseControl plugin takes a number of attributes; some in fact can take a significant amount. Fortunately, you can pre-configure plugins with common attributes, and then override (re-configure) them at the project level if necessary. As an example to pre-configure the <htmlemail> plugin you could place the following definition at the top of your configuration file – outside of any <project> elements:

Whenever you wanted to call this plugin from within a project you could then simply include:

However there are probably additional project specific attributes which you would set too (see the example later).

CruiseControl properties are specified and used in the same way as Ant properties; however the main difference is that they are not completely immutable. Rather, whoever sets a property last freezes its value within the scope in which it was set, for example you can override global properties with project specific properties. As an example, to create properties for the location of an installed version of Ant, you could create the following properties at the top level of your build script:

Implementing these two simple practices - pre-configuring plug-ins and re-using properties - can significantly reduce the size of your CruiseControl configuration file. Although you will undoubtedly not need to use every single CruiseControl plugin there are a common set that most projects will use. I will discuss these plugins in the section which follows, however before I do so you need to understand how CruiseControl defines its build workspace.

The CruiseControl workspace

CruiseControl is designed to execute a build from an existing version control workspace. Although you could configure CruiseControl to create a new workspace, I recommend that that you create a CruiseControl specific build workspace and reuse it to build in. In the Windows installer and binary versions of CruiseControl, build workspaces are typically held in its projects directory. Therefore, to create a new build workspace for Subversion in this workspace, you could execute a command similar to the following:

>cd C:\JavaTools\cruisecontrol-bin-2.8.2\projects
>svn co https://happybank.svn.sourceforge.net/svnroot/happybank happybank

This will create a workspace called happybank containing the latest files from the Subversion. Note HappyBank is a working reference application that you can use for testing build processes with Apache Ant.

CruiseControl Configuration

You can configure CruiseControl to schedule a build execution as frequently as you want, but you usually specify that a build be carried out only if something has changed - which obviously make sense! To achieve this there is a concept of a modification set, i.e. the changes on a project integration branch or the files committed to a repository. If files have been modified then the build will be invoked. You also specify what to do on the schedule, i.e. what build tool to call and how to call it. This is where you invoke one of CruiseControl's builders. There are a number of builders, including support for Ant, Maven, Rake as well as calling any command line executable.

.An example of a configuration file for CruiseControl is detailed below:

<cruisecontrol>

<property name="dir.javatools" value="C:\JavaTools"/>
<property name="dir.ant" value="${dir.javatools}\apache-ant-1.7.1"/>
<plugin name="htmlemail" 
    mailhost="smtp.mailhost.com"
    returnaddress="bldadmin"
    subjectprefix="[CruiseControl]: "/>

<project name="common">
    <property name="dir.project" value="projects/happybank/${project.name}"/>
    <labelincrementer defaultLabel="HBC-1" separator="-"/>
    
    <listeners>
        <currentbuildstatuslistener file="logs\${project.name}\buildstatus.txt"/>
    </listeners>
    
    <bootstrappers>
        <svnbootstrapper file="${dir.project}/build.xml"/>
        <svnbootstrapper file="${dir.project}/default.properties"/>
    </bootstrappers>
    
    <modificationset quietperiod="30">
        <svn localWorkingCopy="${dir.project}"/>
    </modificationset>

    <schedule interval="1200">
        <ant antscript="${dir.ant}/bin/ant.bat"
            antworkingdir="${dir.project}"
            buildfile="build.xml" target="junit.all"/>
    </schedule>

    <log>
        <merge file="${dir.project}/build/TESTS-*.xml"/>
    </log>

    <publishers>
        <onsuccess>
            <artifactspublisher dest="artifacts/${project.name}"
                file="${dir.project}/dist/happybank-common.jar"/>
        </onsuccess>
        <htmlemail buildresultsurl="http://localhost:8080/dashboard/build/detail/${project.name}">
            <always address="integrators@mailhost.com"/>
            <failure address="developers@mailhost.com"/>
        </htmlemail>
    </publishers>

</project>

</cruisecontrol>

There are a number of entries worthy of explanation in this example:

The <labelincrementer> on line 12, defines the format for the label that CruiseControl will generate for you. This could be used to label source code, although I don't recommend labelling each build.
The <bootstrappers> on lines 18-21 make sure that the build scripts are up to date out of Subversion before the build starts
The <modificationset> on lines 23-25 monitors the the Subversion repository for changes (based on the contents of the local working copy)
The <schedule> on lines 27-31 is defined to potentially execute every 20 minutes (1200 seconds) and if changes are found it then executes Ant using the build script build.xml with the target junit.all.
The <log> definition on lines 33-35 merges the JUnit tests results file into CruiseControls own log.
The <publishers> on lines 37-46 controls how CruiseControl reports on the results of the build. In this case a HTML formatted email will be sent when the build fails, to the email group developers, whilst an email on success or failure will be sent to the email group integrators. If the build is succesful, the build outputs are also copied to a file system location using the <artifactpublisher> plugin.

The CruiseControl Dashboard

As well as sending email notifications on build success or failure CruiseControl also has a web based dashboard where you can monitor the success or failure of all of the projects that are being built using CruiseControl. The default URL for the dashboard application is http://servername:8080/dashboard. The Dashboard application is dynamic and will refresh itself automatically. There are three tabs in the Dashboard GUI as follows:

Dashboard - a single page overview of all projects and their sucess or failure indicated by a coloured block.
Builds - a more detailed view of builds and information about running and previously executed builds. From here you can see what changes went into the build (via the modificationset), what the rest results were and further details of any errors or failures. You can also force builds to execute from here.
Administration - information about how the running environment and how the dashboard has been configured.

An example of the dashboard building the HappyBank common project is illustrated in the screenshot below:

Although the Dashboard is quite limited in functionality it is still very powerful in the information it displays. One other function of note is the link to the CC-Config tool. Clicking on this link downloads CC-Config which is a Java application that also allows you to monitor and force builds, but more importantly it gives you a graphical interface to the CruiseControl config.xml file. An example of this tool being used to configure the HappyBank common build project is illustrated in the screenshot below:

[CC-Config]

Maintenance of the config.xml has been one of the greatest weaknesses of CruiseControl acceptance and adoption in the past so this particular tool is a tremendous help for new users.

References

Comments

Great Tutorial, Helped me very much. Have a running CruiseControl set up now thanks to you. Thanks!

Hi,
I would like to check if any one implemented \"modificationset quiteperiod\" in BuildForge ?.
This feature is popular in CruiseControl am not sure how to have similar kind of functionality in BuildForge! am using BuildForge+Maven+SVN !

Any help is very much appreciated..

Modificationset in CruiseControl :

Thanks
Rafique