Introduction
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 Build Tool?
As its name suggest, NAnt, or any tool labeled a "build tool" is a tool that you use to build your source code and resource
files into assemblies. Sounds obvious? Maybe, but what is
involved in making a build? Here are some common tasks you might
perform when doing a build (your builds might exclude some of these
steps or include additional steps):
Get the latest source from source code control
Configure the build (you probably want to put the output of the
build into a directory that identifies the version of the software,
the build number, and whether or not this is a debug build)
Compile the code
Run unit tests
Create documentation from source code comments
Include non-code output files in the output of the build
(images, .aspx files, configuration files, etc)
Package the output for deployment
Build tools enable you to automate all these steps. Instead of
manually running commands and copying files, you can set everything up
in a build tool and have it all run automatically.
Why use NAnt?
Why use NAnt? Of course you can build from within Visual Studio, but
as described above, build tools like NAnt offer you much more power
and flexibility. For starters, NAnt doesn't require Visual Studio .NET.
As long as you have the .NET Framework, you can do builds. Here is a
partial list of things you can do with NAnt:
Use its built-in support for CVS updates and checkouts to
automatically get the latest source files
Use it to configure builds
Use it to compile .NET languages, including C#, VB.Net and J#
Use it's built in support for NUnit to automatically run unit tests
Use it's built in support for NDoc to automatically create
documentation from source code comments (currently C# only)
Use it to copy non-code output files to the build directory
Use it to package builds into .zip files (or even .msi files)
for deployment
Additionally, NAnt is extensible. It allows you to write your own
tasks (tasks are described later in this article) or to use
the <script> task to embed any .NET code into your build files.
An example of NAnt's capabilities were demonstrated in a project I recently worked on.
In this project I needed it to be built for development,
stage, and production environments and the configuration data
(connection string, for example) differed for each environment. I used
NAnt to do the builds and used the <style> task to transform XML files
with XSLT to generate the various Web.config and App.config files. A
much better solution than editing configuration files by hand for each
environment.
Downloading and Installing NAnt
NAnt is available for free from http://nant.sourceforge.net. Follow
these steps to download and install NAnt:
From http://nant.sourceforge.net, click the link for the
current stable release. Your browser displays the NAnt project
on sourceforge.net.
Click the link for the build that you want (at the time of this
writing, the latest stable build is nant-0.84.zip).
Click the download icon next to the mirror closest to you. You
should be prompted for a location to save the .zip file. If not, click
the link at the top of the page.
Save the .zip file.
Unzip the file and save its contents to a suitable location (I
use C:\nant-0.84).
Update your PATH environment variable to include <nant
dir>\bin (for my setup, that's C:\nant-0.84\bin).
That's it. Open a command window and enter: nant -help to verify
that everything is set up properly. If you see the NAnt help screen, the PATH environment variable is setup
correctly.
One note: NAnt may be configured out of the box to use a different .NET
Framework version than you would like. For example, NAnt 0.84 is
configured to use .NET Framework version 1.0 by default. If you only
have version 1.1 of the .NET Framework installed on your machine and
you try running NANT 0.84 on a task that requires the framework, you
will get an error similar to this one:
[csc] C:\WINDOWS\Microsoft.NET\Framework\v1.0.3705\csc.exe failed to start.
The system cannot find the file specified
To change the default framework version, you need to edit
NAnt.exe.config in the <nant dir>\bin directory. Change the default
argument in the platform tag to the .NET Framework version you would
like to use as the default. The following example sets the default
Framework to use to 1.1:
In the event that you want to use a different .NET Framework version
in one of your build files, you can override his setting by setting
the nant.settings.currentframework property:
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:
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:<filename> 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:
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. Check out the links in the Where Can I Get More
Information section at the end of this article to see more examples
of what you can do with NAnt.
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:
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)
Get the latest source from source code control (if you do not
have NAnt do this for you)
Run NAnt with appropriate command line targets (debug build,
for example)
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)
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.
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. Continuous integration is outside the scope of this
article, but check out the Where Can I get More Information? section
at the end of this article for some links to get more information on
continuous integration.
What about MSBuild?
Ant was such a good idea that NAnt was created for .NET developers.
Microsoft recognized a good idea when it saw it and have announced
their own build tool called MS Build (due to ship with the .NET
Framework redistributable starting with Longhorn). It's hard to
speculate on MS Build since it hasn't been release yet, but it looks
promising. Like NAnt, MS Build will use XML files to specify targets
and will be extensible (you will be able to create your own tasks). MS
Build also addresses one shortcoming of NAnt: MS Build promises to be
tightly integrated into Visual Studio .NET. In fact, MS Build will be
integral to Visual Studio: project files will actually be MS Build
files.
So does this spell the end for NAnt? Well, maybe, eventually, MS Build
could make NAnt redundant. But in the near-term, MS Build is unlikely
to offer the breadth of built-in tasks that NAnt does. I don't see
Microsoft including tasks for checking source out of CVS, for example.
Even if MS Build ends up eclipsing NAnt, the two build tools will be
more similar than different, so it is still worth learning NAnt now
since you will be able to leverage your NAnt skills when MS Build
becomes available.
Where Can I get More Information?
This article is a short introduction to NAnt. For more information on
NAnt, including complete reference information for all NAnt tasks,
check out NAnt's homepage at sourceforge http://nant.sourceforge.net
and the NAnt Wiki and the
NAnt Usage articles.
