CruiseControl.NET : NAnt Task

This page last changed on May 10, 2005 by gtackley@thoughtworks.com.

Examples

Minimalist Example:

<nant />

Full example:

<nant>
  <executable>c:\fromcvs\myrepo\myproject\tools\nant\nant.exe</executable>
  <baseDirectory>c:\fromcvs\myrepo\myproject</baseDirectory>
  <buildArgs>-D:cvs.executable=c:\putty\cvswithplinkrsh.bat</buildArgs>
  <nologo>false</nologo>
  <buildFile>cruise.build</buildFile>
  <logger>My.Other.XmlLogger</logger>
  <targetList>
    <target>run</target>
  </targetList>
  <buildTimeoutSeconds>1200</buildTimeoutSeconds>
</nant>

Configuration Elements:

Node	Description	Type	Required	Default
executable	The path of the version of nant.exe you want to run. If this is relative, then must be relative to either (a) the base directory, (b) the CCNet Server application, or (c) if the path doesn't contain any directory details then can be available in the system or application's 'path' environment variable	string	false	`nant.exe`
baseDirectory	The directory to run the NAnt process in. If relative, is a subdirectory of the Project Working Directory	string	false	Project Working Directory
buildFile	The name of the build file to run, relative to the baseDirectory.	string	false	no build file specified (NAnt will use the default build file in the working directory)
buildArgs	Any arguments to pass through to NAnt (e.g to specify build properties)	string	false	no args specified
nologo	Whether to use the `-nologo` argument when calling NAnt	boolean	false	true
logger	The NAnt logger to use. If you are using a version of NAnt prior to 0.8.3, you may need to specify this as SourceForge.NAnt.XmlLogger.	string	false	NAnt.Core.XmlLogger
buildTimeoutSeconds	Number of seconds to wait before assuming that the process has hung and should be killed.	int	false	600 (10 minutes)
targetList	A list of targets to be called. CruiseControl.NET does not call NAnt once for each target, it uses the NAnt feature of being able to specify multiple targets.	string list	false	no targets specified (NAnt will use the build's default target

CruiseControl.NET expects NAnt to generate its output as Xml so that the build results can be parsed and rendered appropriately. To accomplish this, CruiseControl.NET will, by default, launch NAnt using the "-logger:NAnt.Core.XmlLogger" argument. If you want to override this behaviour, specify the logger property in the NAntBuilder configuration in the ccnet.config file. If this element is specified but is empty then NAnt will be started with the default logger (though this may cause some problems for CCNet). It is also possible to instruct NAnt to log its output to an Xml file and then merge the file into the build using the File Merge Task.

NOTE: the configuration of which NAnt logger to use was orginally specified in the ccnet.exe.config file. This has now been deprecated, and the "NAnt.Logger" element in the <appSettings> section can now be removed.

Source Control and NAnt

While CruiseControl.NET will detect modifications for you it will not check out changes. It is up to you to add targets to your nant script to do that for you. So, first you need to create a 'bootstrap' build file that is used to get the latest changes to your source tree whenever an update is comitted. A good place to put this build file is in the same directory as your project's normal buildfile. This bootstrap file should do 2 things:

Get the latest code from source control
Call the appropriate target in the actual project build file

The following is an example for a project under CVS control (it assumes that a propery called 'cvs.executable' is passed in from CruiseControl.NET - you can do this in the build/buildArgs section of the ccnet.config file):

<project name="ccnetlaunch" default="go">
  <target name="go" depends="update,build"/>
  <target name="update">
    <ifnot propertyexists="cvs.executable">
        <fail message="cvs.executable property not set, so can't update" />
    </ifnot>
    <echo message="CVS Executable at [${cvs.executable}]" />
    <exec 
        basedir="." 
        program="${cvs.executable}" 
        commandline="-q update -P -d" 
    />
  </target>
  <target name="build">
    <nant 
        buildfile="myproject.build" 
        target="ContinuousIntegration" 
        inheritall="true"
    />
  </target>
</project>

NOTE: The bootstrap buildfile above only updates the buildserver's local copy of your project's source. Before you even run CruiseControl.NET for the first time you need to checkout your project to the location on your machine where CruiseControl.NET will build it.

NUnit and NAnt

CruiseControl.NET uses xsl to process the build log and produce html for display on the web page. Since xml is so easy to parse the nunit2 task in NAnt can produce xml output. The tasks must be configured to do that in order for test results to show up on the web page. Typically this is done by adding a formatter element to the nunit2 task and setting the type to be "Xml". Additionally the usefile flag of the formatter element must be set to "false". If it isn't the nunit2 task will try and save the output to a file and not write it out to the build log.

<target name="test.unit" depends="compile" description="runs unit tests">
	<nunit2>
		<formatter type="Xml" usefile="false"/>
		<test assemblyname="${build.dir}\${core.dll}" fork="true"/>
		<test assemblyname="${build.dir}\${console.exe}" fork="true"/>
	</nunit2>
</target>

It would be pretty tedious for developers to read the xml output when they run the build locally. Define a property for the build output type and set it to "Plain" and use the property in the formatter element..

<property name="outputType" value="Plain"/>
	...
	<formatter type="${outputType}" usefile="false"/>
	...

Then in the ccnet.config file pass in a different value for outputType.

<nant>
	...
	<buildArgs>"-DoutputType=Xml"</buildArgs>
	...
</nant>

Accessing CruiseControl.NET build labels in NAnt

CCNet will pass the current build label to NAnt via the NAnt property "ccnet.label". This means that you can access use this property to, for example, archive the newly built assemblies in a folder with the same name as the build label (this is what we do on CCNetLive . Here's some example NAnt script demonstrating how to do this:

<target name="dist.publish" depends="dist">
	<ifnot propertyexists="ccnet.label">
		<fail message="ccnet.label property not set, so can't create labelled distribution files" />
	</ifnot>	
	<property name="publish.dir" value="D:\download-area\CCNet-Builds\${ccnet.label}" />

	<mkdir dir="${publish.dir}" />
	<copy todir="${publish.dir}">
		<fileset basedir="dist">
			<includes name="*"/>
		</fileset>
	</copy>			
</target>

CCNet also passes a series of other properties to NAnt:

Label Description Example
ccnet.label The label used to identify the CCNet build. This label is generated by the CCNet labeller. 1.0.2.120
ccnet.buildcondition The condition used to trigger the build, indicating if the build was triggered by new modifications or if it was forced. Legal values are: "IfModificationExists" or "ForceBuild" ForceBuild
ccnet.working.directory The project working directory c:\program files\CruiseControl.NET\Server\MyProject\WorkingDirectory
ccnet.artifact.directory The project artifact directory c:\program files\CruiseControl.NET\Server\MyProject\Artifacts

NOTE: the "label-to-apply" property has been deprecated and will be removed in future versions of CCNet. It has now been replaced by the "ccnet.label" property.

Document generated by Confluence on Jun 26, 2005 17:22

Examples

Configuration Elements:

NAnt output in Xml

Source Control and NAnt

NUnit and NAnt

Accessing CruiseControl.NET build labels in NAnt