Continuous Integration with CruiseControl

Introduction

A Continuous Integration server is a must have for any developer that wishes to increase productivity and become a better developer. In general, it gives you a good constant working copy of your application all the time. Specifically, it pinpoints problems as soon as you check in the code. It is like having another developer whose full time job is just compiling and checking your code for errors.

I am a sole developer in my full time job, and I do side work at home. Anyone who says a build server is ONLY for a team is full of it. Like I said above, having a build server is like having another developer there helping you out and pointing out problems.

There are many options for software when it comes to Continuous Integration. I use CruiseControl because:

1. It is the most popular in the open source community. 
2. It's fairly easy to setup.

Though this article may feel a little overwhelming with all the tools at hand, and I guarantee that you will have problems setting up various build files and getting all your tools to play nice, in the long run it is all worth it 1000 times over.

To get a basic understanding of how CruiseControl works, take a look at this image here. That should give you an idea of how the whole process works.

Here are the steps of the process:

1. You check your code into your SCM.
2. Your build server checks your SCM every 60 seconds for changes.
3. When a change is detected, the source code is checked out by the build server to a local directory where it is compiled by NAnt.
4. After compilation is complete, you can then run any number of tools that output XML files to be picked up by CruiseControl.
5. CruiseControl merges XML output with its output to produce the website results.
6. Voila!

Background

First, you need a dedicated box that will be your build server. It doesn't need to be a work horse, but it needs to be a little decent. At home I have an old EMachine with 512MB RAM running Windows XP and it works just fine. You will also need to install IIS and the .NET Framework SDK.

Once you have that set up, we can get into setting up the file system.

1. Create a Base Directory for All the Tools

The base directory I always use is C:\CI\. I also create a directory where all your projects will be located at. Ideally this should be outside of your CruiseControl root, by default CruiseControl buries your projects within the server directory which I personally don't like. My Projects root path C:\CI\Projects\.

2. Download and Install the Tools

CruiseControl.NET

Choose to setup the IIS virtual directory. Once installed, you can choose to install CCTray which installs an application on your local machine system tray that will periodically check the build server for broken builds. For some reason after installing cruise control, I had to go to Services and manually enable the CruiseControl Service, it wasn't automatically started.

Subversion/Source Control Access

I use Subversion, you need to have it installed so CruiseControl can grab the latest checked in code from your source code repository. If you would like to use visual sourcesafe, then there is a cruise control config for that as well as many other types of source control systems supported by CruiseControl.

CCNetConfig (thanks to Camalot Designs in the comments below)

I have not personally tried this tool yet, but as Camalot states in the comments below, it is a GUI tool for creating and editing your ccnet configuration files. One of the hardest parts of the whole cruisecontrol/nant process is setting up the XML configuration files, this should make that portion much easier.

NAnt

When it comes to building your projects you can use either MSBuild or NAnt. The only problem with using NAnt is that it cannot currently build solution (*.sln) files. This makes it much more difficult to do the entire build process with NAnt. I'm sure it can be done, but I personally never went down that route. So instead the method I used, is to have an NAnt task kick off an MSBuild. This is where nant-contrib comes in below. The MSBuild task can build your main solution file.

NAnt-Contrib

To setup NAnt-Contrib, simply copy all the assemblies from NantContrib\bin into NAnt\bin. Or you could just register the NAntContrib\bin into your PATH. NAnt-Contrib has additional NAnt tasks that people have contributed over time. A couple of them are quite useful like the <nunit> task and <msbuild> task.

NUnit

Performs unit testing on your test project using nunit-console.exe and outputs to the artifacts directory.

NCover

Checks your tests for code coverage. This MSI doesn't give you the option of the path to install to, so once you install it you should move it to your CI directory.

NCoverExplorer/NCoverExplorer Extras

This outputs a very nice NCover output page with pretty bar graphs and such.
It allows for a much better overall look of your code coverage rather than the standard text output that ncover will give you in cruise control. NCoverExplorer Extras has NAnt tasks for building the nice ncoverexplorer output. In order to set this up, simply copy NCoverExplorer.NAntTasks.dll into your NAnt\bin directory and nant will find the tasks at runtime.

Follow the instructions in NCoverExplorer.Extras\CruiseControl.Net\readme.txt which will tell you where to place the XSL files for cruisecontrol to pick them up so you get the nice output.

FxCop

Checks your code for acceptable patterns & practices guidelines. (I personally use this one with a grain of salt, although it has proven useful.)

Add files to your PATH Environment Variable

At the minimum, add the NAnt\bin\ folder to your path, it's up to you to add other tools to your path. It will make it easier in the long run to setup nant build files.

Once you are done with all of these steps, restart your computer to ensure all your applications are setup correctly and your PATH is refreshed.

3. Configure Cruise Control

Open C:\CI\CruiseControl.net\server\ccnet.config, this file has all of your projects for cruise control to monitor. It also has settings for what <task> to run when a change has been found in one of your projects, i.e.:

<tasks>
    <nant>
        <executeable>c:\ci\nant\bin\nant.exe</executeable>
        <buildfile>path\to\default.build</buildfile>
        <targetList>
            <target>all</target>
        </targetList>
    </nant>
</tasks>

Next, restart the CruiseControl service to pick up the changes we made to ccnet.config and then fire up the cruise control website and make sure our project shows up. Your project root folder should now contain a complete checkout of the code from the repository.
This is what CruiseControl will use to look for changes at whatever intervals you defined in ccnet.config.

If your code is not checked out, then you can go to "View Server Log" on the webpage to see what the problem is. Once Cruise Control sees the new project, it will make the project folder and artifacts directory and then automatically connect to your source control store and download the latest source code to the "trunk" folder.

At this point, you should be able to go to your cruise control server via a Web browser. Your project should be showing up even if it does say "fail" or "unknown", since we haven't setup our build file yet. If this isn't the case, then check all the options above before going any further because it just gets more tricky.

Now, the best piece of advice I used while learning to use NAnt, is create a *.bat file to JUST run your *.build file. This will eliminate CruiseControl out of the picture until you are sure that your project builds correctly. Then you can go ahead and try to automate the build through CruiseControl. This helps in eliminating other unknowns as well.

I usually place it in C:\CI\Projects\startnant.bat, and change the build file to run before I add a new project to cruise control so I can be sure that everything is working correctly with NAnt.

Here is a sample *.bat file:

nant.exe c:\ci\projects\united\default.build

Now for the default.build file. This is the whole shebang. Basically the easiest way to read it is look for:

<target name="all" depends="clean,get,build,tests,reporting" />

This is the order that the tasks will run in. So the tasks will run in the order:
clean - get - build - tests -reporting.

At any point if one of them fails, it will stop execution unless you have told it: failonerror="false", in which case it will continue execution.

The attached default.build file can pretty much be used for any project, just change the properties at the top to match your configuration and drop it in the project root. Then test it out with the BAT file you created before.

You'll notice that I have commented out the FxCop section at the end. This is because at the time of writing, I had not yet setup an FxCop project, but wanted to show you how to configure that section.

So at this point, you should be able to run your BAT file and see the build complete and generate a bunch of output files under the Project\artifacts\ directory. This leads us to the next section.

The last thing we have to do is tell CruiseControl to "merge" this output with its own so that the results are displayed in the cruisecontrol website.

To do this, open your ccnet.config under C:\CI\CruiseControl.NET\server\ and add the following lines:

<publishers>
  <merge>
    <files>
      <file>C:\CI\Projects\United\artifacts\*.xml</file>
      <file>E:\CI\Projects\United\artifacts\CoverageReport.xml</file>
    </files>
  </merge>
  <xmllogger />
</publishers>

Place this within your <project> node. This will merge all XML files, and a file named CoverageReport.xml into CruiseControls output.

You should now go to your Web console for CruiseControl, force a build and watch it complete. Then you can browse into the project and view all of the different reports.

Points of Interest

You WILL bang your head against the wall when trying to get this to work the first time. It took me 2 days to get it to compile the first time. Mainly because I had a poor project folder structure. With the improper folder structure, it makes it more difficult to build the solution in one shot. I would suggest making a "SharedLibs" folder in your project root to house all dependencies. This way you don't have to place them in certain areas on the build server every time you change assemblies. All of your assemblies will be in source control, under your project root. Sounds weird because you duplicate files in Source Control, but this is the easiest and suggested way to do it because you can then change dependencies on the fly.

As I said in the beginning, this is a MUST have for any developer. Team or not. It has increased my productivity and just from the simple fact of when my boss comes to me asking to see a working copy of the project, I just copy the latest source from the build server. That by itself is worth its weight in gold.

All of these tools combined are very powerful, and thanks to CruiseControl we can pull them all together in one easy to use interface. The setup is a little daunting and took me quite a while to get down to how everything works together. The key here is to read all the documentation on all the tools. Especially NAnt and CruiseControl. The power of NAnt is much further reach than what I have described here. The build file I posted is just a very basic build file to get you started. You can do many more things with nant so make sure you read the docs!

I hope this article was helpful to someone. I have been meaning to write it for a while, and I had to setup another build server at home and took the time to write this article as I stepped through the process.

Cheers!

History

• 4/28/2007 - Article first published
• 4/29/2007 - Added the CCNetConfig tool information courtesy of Camalot Designs. Thanks!