Auto-Building: Getting things done with NAnt

When you think about it, “doing the auto-build” comprises several steps, only one of which is the actual build. Sure, you want to compile your code, but you also want other things to happen. You want to make sure you’re compiling the right code, and that you’re doing it in the right environment.

A typical set of actions for a (windows applicaion) build might be:

• Create a working directory (or empty it if it already exists)
• Pull the right code for the application from source control
• Edit the config file to alter some settings to how you want them in the built version.
• Set the build number and build date so that once the code is built it’s easy to see what build it is.
• Compile the code
• Apply any tests to the code
• Take the newly-build MSI and ZIP it up together with a readme file and a install guide.
• Rename the ZIP to reflect the date and build number, and move it to your build repository

It isn’t good enough just to be able to build the code – if those are all the steps you have to go through each time you want a new build, then those are the things you need to be able to automate.

This is where NAnt comes in. NAnt is like a big, automated toolbox of useful functions. It works by reading XML configuration files which tell it what to do. For instance, if you want to copy a file from one place to another, renaming it along the way, then in your configuration file you’d have some like this:

<copy
file=”myfile.txt”
tofile=”mycopy.txt” />

What’s even handier is that there are exactly the sort of functions you’re going to need to get an auto-build done. There are functions for clearing a directory, functions for getting code out of source control, functions for editing config files to apply certain settings. There’s even functions for installing or uninstalling Windows Services – handy if what you’re building happens to be a service. And if all else fails, there’s always the <exec> tasks: which executes whatever you want.

Before you go any further, I encourage you to glance down the list of available functions for NAnt as it will give you a real feel for what it can do. You should also look at the list of functions available in NAnt Contrib.

A word about NAnt and NAnt Contrib. Basically, NAnt Contrib is the overflow carpark for NAnt. It contains a bunch of features that, for whatever reason, haven’t made it into the main NAnt release yet. There’s nothing wrong with them – in fact some of the most useful features are there. However, this does mean that if you want to use them (which you almost certainly will) you’ll need to do a little work in make sure that NAnt can see them. Have a read of the install guide that comes with your version of NAnt Contrib to work out what to do (it’s basically a case of dropping files into your NAnt installation). Throughout my posts I refer freely to functions that may exist in NAnt Contrib rather than main NAnt installation.

Installing NAnt is very easy. Basically, you just download and extract the latest version somewhere on your computer. NAnt is a command line tool. The lists of instructions are called build files and are XML. Each file can contain multiple targets. A target is a unique piece of work, such as, PrepareEnvironment. Each target can then have multiple tasks – the actual functions performed. You may also want to add your NAnt folder into your system PATH environment variable: this will ensure that NAnt will run anywhere. This isn’t nessecary, but you’ll find it makes your like a lot easier when you’re creating and testing build files: which won’t be in your NAnt folder.

For full details on getting started with NAnt, including a fuller installation guide and handy information, see the NAnt Fundamentals page.

I would recommend splitting your build file into the following targets:

• Prepare/Clean
• Get
• Build
• Test
• Publish

You may not know exactly what you’re going to do with each section yet: for instance, you may not have a clear idea about Test and Publish. That’s OK – leave the targets in for now but empty. That way, you can always go back later and fill them in without having to re-write how your build process works.

For each section, work out what you need to happen, then go and find the appropriate task for it. You may also see a task that you think will add value that you hadn’t even thought about.

This is the nitty-gritty of build-automation. It’s the coal face: the actual work of doing the build. It’s necessary to do this, from the command line, before we can enjoy some of the benefits that it will bring. Don’t worry: the end-goal doesn’t involve you typing command line entries in order kick off a build!