Kevin Jensen

NAnt is a free .NET build tool based on Ant (a build tool for Java). NAnt, like Ant, is similar to Make in that it is used to generate output from your source files. But where Ant is Java-centric, NAnt is .NET-centric. NAnt has built-in support for compiling C#, VB.NET, and J# files and can use Visual Studio .NET solution files to do builds. NANt also has built-in support for NUnit and NDoc (.NET version of JUnit and JDoc, respectively).

NAnt is a useful tool for automating the build process. The build process can include tasks such as compiling source code and resource files into assemblies, running unit tests, configuring build-specific settings, and so on. The benefit of tools like NAnt is that they help automate the build process by providing enough power and flexibility to highly customize build actions for specific applications. This article provides an overview of NAnt, including its purpose, how to download and install NAnt, using NAnt, and other NAnt essentials. Read on to learn more!

What is a this thing you call Build Tool?

A “build tool” is a tool that you use to build your source code and resources files into assemblies.  We use build tools everyday in development.  Here are some tasks that are performed during the “entire” build process:

• Get latest source code from source code control (SVN/VSS/CVS).
• Configure the build (put files in specific folders based on build number).
• Compile the code
• Run Unit Tests
• Create Documentation from the source code comments
• Include non-code output files in the output of the build (images, database files, config files, etc..)
• Package the output for deployment

NAnt and other build tools allow you to automate some or all of these steps.  You can configure the build tool to kick off the processes and automate a lot of work that is usual manual and tedious.

OK So what does NAnt do?  Why is it the best?

NAnt is different.  Instead of a model where it is extended with shell-based commands, NAnt is extended using task classes.  Instead of writing shell commands, the configuration files are XML-based, calling out a target tree where various tasks get executed.  Each task is run by an object that implements a particular Task interface.

Granted, this removes some of the expressive power that is inherent in being able to construct a shell command such as ‘find . -name foo -exec rm {}’, but it gives you the ability to be cross-platform – to work anywhere and everywhere. And hey, if you really need to execute a shell command, NAnt has an <exec> task that allows different commands to be executed based on the OS it is executing on.

What is Required?

The system requirements are pretty obvious and simple.  To use Nant you need one of the following CLR’s:

• Microsoft .NET Framework 1.0
• Microsoft .NET Framework 1.1
• Microsoft .NET Framework 2.0
• Mono 1.x

Note: Additional requirements may apply to individual tasks.

NAnt uses a number of open source third party libraries.  Recent versions are included with NAnt distribution and no extra work is required to install them.  More information on these libraries are available at:

NUnit – Required for unit testing

NDoc – Required for documentation generation

SharpZipLib – Required for the zip and unzip tasks

OK So it sounds like I need it, How do I install it?

NAnt is available in either a source or binary distribution. The binary distribution is all you need to use NAnt to build your projects, including creating your own custom tasks, types and functions.

If you are upgrading NAnt from a previous version, you must never install over the top of your previous installation. Delete or rename the existing installation directory before installing the new version of NAnt.

Installing from binaries

1. Download the binary distribution archive. Either ant-bin.zip or nant-bin.tar.gz will work, the contents of each archive are the same.
2. Remove any previous versions of NAnt you may have installed.
3. Extract the contents of the archive to the location you wish to install NAnt (eg: C:\Program Files\NAnt in windows, or /usr/local/nant in Linux)
4. Depending on your environment, create a wrapper script to run NAnt:
   

   Run NAnt using Microsoft.NET

   • Create a file called nant.bat in a directory that is included in the PATH system environment variable. (eg. C:\WINDOWS).
   • Add the following to nant.bat:

     @echo off
     "C:\Program Files\NAnt\bin\NAnt.exe" %*
                             

   Run NAnt using Mono

• Windows

  • Create a file called nant.bat in a directory that is included in the PATH system environment variable. (eg. C:\WINDOWS).
  • Add the following to nant.bat:

    @echo off
    mono "C:\Program Files\NAnt\bin\NAnt.exe" %*
                                    

• Linux / Cygwin

• Create a file called nant in a suitable location in your filesystem (eg. /usr/local/bin).
• Add the following to nant:

  #!/bin/sh
  exec mono /usr/local/nant/bin/NAnt.exe "$@"
                          

• Ensure nant has permission to execute, eg:

  chmod a+x /usr/local/bin/nant
                          

5. Open a new command prompt (shell) and type nant -help. If successful, you should see a usage message displaying available command line options.
6. (optional) Download and install NAnt-contrib or other third party extensions to NAnt.

Installing from source

1. Download the source distribution archive. Either nant-src.zip or nant-src.tar.gz will work, the contents of each archive are the same.
2. Remove any previous versions of NAnt you may have installed.
3. Extract the contents of the archive to a temporary location. This should not be the location you wish to install NAnt to.
4. Open a command prompt and change into the folder you extracted the archive to.
5. Depending on your environment, build the NAnt distribution:
   

   Install NAnt using Microsoft .NET

   • GNU Make

     make install MONO= MCS=csc prefix=<i>installation-path</i>

     eg. make install MONO= MCS=csc prefix="C:\Program Files"

   • NMake

     nmake -f Makefile.nmake install prefix=<i>installation-path</i>

     eg. nmake -f Makefile.nmake install prefix="C:\Program Files"

   Install NAnt using Mono

   • GNU Make

     make install prefix=<i>installation-path</i>

     eg. make install prefix="C:\Program Files"

   • NMake

     nmake -f Makefile.nmake install MONO=mono CSC=mcs prefix=<i>installation-path</i>

     eg. nmake -f Makefile.nmake install MONO=mono CSC=mcs prefix=/usr/local/

   This will first build a bootstrap version of NAnt, and then use that to build and install the full version to <i>installation-path</i>/NAnt.

6. Follow the instructions as for a binary release from step 5.

Installed….CHECK!  Now how does it work?

NAnt is a command-line application that acts on build files that you write in XML. Each build file contains one project and any number of properties and targets. A property is a variable and a target is a set of tasks. An example is worth a thousand words, so here is Hello World as an NAnt build file:

<?xml version="1.0"?>
<project name="Hello World" default="hello">
    <property name="hello.string" value="Hello World" />
    <target name="hello" description="Echoes 'Hello World'">
        <echo message="${hello.string}" />
    </target>
</project>

NAnt looks for build files in the current directory with a .build extension. If there is more than one build file in the current directory, NAnt looks for one named default.build and, if present, uses it. You can explicitly specify the build file to use with the -buildfile:<i>&lt;filename&gt;</i> command line argument.

All NAnt build files require one (and only one) <project> tag. In the ‘Hello World’ example, the <project> tag contains the default argument. The default argument specifies which target NAnt is to execute by default. In this case, NAnt will execute the hello target by default.

The ‘Hello World’ example defines one property and one target. The property is named hello.string and its value is ‘Hello World’. (Properties don’t have to be named with periods, but often are in NAnt build files). The ‘Hello World’ example’s one target is named hello and it contains one task. The <echo> task echoes the string indicated by the message argument. The syntax ${hello.string} may be confusing at first, but this syntax is simply telling NAnt to substitute the value of the hello.string property in its place.

Assuming you named the ‘Hello World’ example build file default.build, you would simply enter nant at the command line to build it:

C:\>nant

(You could specify the ‘hello’ target on the command line (C:\> nant hello), but since this is the default target, this is unnecessary.)

How about a More Practical Example?

Here’s a build file (based on the excellent article by Giuseppe Greco, Building Projects With NAnt) that compiles a HelloWorld.cs source file. In addition to the build target, it includes a debug target. This enables you to specify whether or not this build should including debugging information:

&lt;?xml version="1.0"?&gt;<br>&lt;project name="HelloWorld" default="build"&gt;<br>&nbsp;&nbsp;&lt;property name="project.version" value="1.0" /&gt;<br>&nbsp;&nbsp;&lt;property name="project.config" value="release" /&gt;<br>&nbsp;&nbsp;&lt;target name="init"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;call target="${project.config}" /&gt;<br>&nbsp;&nbsp;&lt;/target&gt;<br>&nbsp;&nbsp;&lt;target name="debug"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="project.config" value="debug" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="build.debug" value="true" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="basedir.suffix" value="-debug" /&gt;<br>&nbsp;&nbsp;&lt;/target&gt;<br>&nbsp;&nbsp;&lt;target name="release"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="project.config" value="release" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="build.debug" value="false" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="basedir.suffix" value="-release" /&gt;<br>&nbsp;&nbsp;&lt;/target&gt;<br>&nbsp;&nbsp;&lt;target name="build" depends="init" description="compiles the source code"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="build.dir" value="${nant.project.basedir}/${nant.project.name}_${project.version}${basedir.suffix}"/&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;mkdir dir="${build.dir}" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;csc target="exe" output="${build.dir}/HelloWorld.exe" debug="${build.debug}"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;sources&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;includes name="HelloWorld.cs" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/sources&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/csc&gt;<br>&nbsp;&nbsp;&lt;/target&gt;<br>&lt;/project&gt;

Things to notice about this build file:

• There are targets for debug and release. You include these targets on the command line to specify the type of build configuration. Notice that release is the default configuration.
• The build target has a depends argument. This tells NAnt to make sure the init target is up to date before calling the build target.
• The init target calls another target explicitly. In this case, it calls either the release or debug target.
• The output is put into a directory that is named with the project version and configuration (1.0_HelloWorld-release or 1.0_HelloWorld-debug)

Assuming you have a valid HelloWord.cs file in the same directory as the build file, you can build the release version of this project just by entering nant at the command-line. This is equivalent to entering nant release build, but because project.config is set to release by default and the default target is build, this isn’t necessary.

If you want to do a debug version of this project, use the following command: nant debug build. Note that you must specify the build target in this case. If you specify any targets on the command line, NAnt ignores the default target. If you just entered nant debug, NAnt would have executed the debug target and then exited. If you notice that the debug target is called twice when doing a debug build, you can move to the head of the class. It is called first because you specify it on the command line and a second time by the init target. This is not as efficient as it could be, but I left it this way for simplicity.

Obviously we are just scratching the surface of what NAnt can do with the above example.

What is the Workflow of a Build Using NAnt?

Once you have your build file(s) written and tested, you will want to start using them for your builds. Performing a build with a build tool like NAnt usually involves these steps:

1. Set a version property in your build file to the value for the current build (you could also pass this to NAnt on the command line)
2. Get the latest source from source code control (if you do not have NAnt do this for you)
3. Run NAnt with appropriate command line targets (debug build, for example)
4. Wait for the build to complete (you can use NAnt’s <mail> task to have NAnt notify you by email when the build completes; this is useful for solutions that require especially long builds)
5. Handle any build errors. NAnt will fail if it encounters any errors. If a file fails to compile, for example, NAnt will fail. You can configure some tasks to either fail or not fail on error. The <copy> task is an example.
6. If the build succeeded, deploy the build output. (NAntContrib includes an <msi> task if you want to create .msi installation packages from NAnt.)

You can actually automate the NAnt build process using continuous integration tools like Draco.NET and CruiseControl. These tools monitor your source code and automatically perform builds when they detect changes.