On a recent project I setup CruiseControl (version 2.5) as our continuous integration build tool. Some folks requested I show them how I set it up…so what better place than here.

cc is my CruiseControl work directory. Call it whatever you want. ‘myproject‘ should be replaced with your project name. The artifacts/myproject folder is where all the results of the build will be written out. The folder logs/myproject is where CruiseControl logs will be written to. These could be code coverage results, junit reports, etc. The checkout/myproject folder is where the code for your project gets checked out before a build. Never develop code from this location. The layout described above is designed for building multiple projects under CruiseControl.

Here is myproject-config.xml. This file contains all of the CruiseControl configuration. It contains things like

• how often to check the repository for changes
• if there are changes whats the build script to execute
• after a build where to put all the generated artifacts (like junit reports, etc.)
• should we send email notifications
• … so on … you get the idea. Refer to CruiseControl at SourceForge.

Here is my main config.xml which simply includes project specific config.xml files:

• Nothing much here. Simply including a project specific config file myproject-config.xml.
• I decided to have two threads for CruiseControl. If you have multiple projects under CruiseControl management then this configuration may be of interest to you. This way separate project builds will not be queuing up for threads.

Here is the project specific configuration file that is included above: myproject-config.xml:

For details on every section please refer to CruiseControl website at sourceforge.net. Some highlights:

• StarTeam is my repository of choice. CruiseControl comes with plugins for various repositories. I have in the past used it with Subversion. With StarTeam there is an extra step involved in set up. I will come to this in the end. If you are not using StarTeam then ignore StarTeam specific notes in this blog.
• In the schedule section I have scheduled CruiseControl to run every 30 minutes. Check for changes and if there are changes call my delegating build script myproject-build.xml.
  This delegating script is responsible for checking out code and triggering the actual build for the project.
• In the publishers section I define what gets copied into the artifacts folder. Note my project build ant script does most of the work here. The CruiseControl config above simply copies artifacts produced by it to the correct folders.

Next here is my delegating script.

• Very straightforward. We first use the StarTeamCheckout task to checkout changes to the checkout/myproject folder
• Finally we call the projects build script build.xml. In my case that script does a clean build, produces an ear file, runs the unit tests, generates junit reports, generates PMD code analyzer reports and Clover code coverage reports.

Thats it for configuration. I had an additional folder called webapps which you can copy as-is from the CruiseControl distribution. You can choose to maintain all of this setup in the CruiseControl install directory if you choose.

The startcc.sh script which starts CruiseControl is:

• Since I keep my CruiseControl work area separate from the distribution i have reference the distributions cruisecontrol.sh to start CruiseControl.
• -webport is used to start the embedded Jetty server on port 12000 and -jmxport to set up JMX port.

Finally I encourage you to use some monitoring client application like this Firefox plugin for CruiseControl. The plugin once configured (set the URL’s in the plugin to the web URL and JMX URL defined previously). The plugin will show up in the bottom right hand corner of your Firefox browser.

The light is green if the build is good else red. Clicking on the lights will take you to the CruiseControl home page for your projects. Here you will see a listing of all configured projects. Clicking on any will take you the the build results page for your project. You can now view all of those generated artifacts from here.

StarTeam:
If you are using StarTeam you need to do one additional piece of set up. Refer to StarTeam Setup For CC. I will repeat the steps to illustrate how I did this. I am using StarTeam 2005 (release 2).

• Download the source distribution of CruiseControl.
• Find starteam80.jar from your StarTeam client install and copy it as starteam-sdk.jar to the main/lib folder in your cruisecontrol source folder.
• Do a build to rebuild.
• Copy the main/dist/cruisecontrol.jar to your webapps/cruisecontrol/WEB-INF/lib folder.
• Now you can use my startcc.sh script to start and run CruiseControl with StarTeam.
• Again like I said before you can choose to keep the webapps folder in the same folder as the binary distribution. I just choose to keep
  everything in my cc folder.