NAnt Task

Runs a NAnt script.

tip

See Using CruiseControl.NET with NAnt for more information on working with NAnt and CruiseControl.Net.

tip

To see build progress information in the CCNet 1.5 WebDashboard remove any listener arguments from <buildArgs> and leave the <listener> property on the default value.

Version

Available from version 1.0

Examples

Minimalist example

1<nant />

Full example

 1<nant>
 2  <executable>c:\fromcvs\myrepo\myproject\tools\nant\nant.exe</executable>
 3  <baseDirectory>c:\fromcvs\myrepo\myproject</baseDirectory>
 4  <buildArgs>-D:cvs.executable=c:\putty\cvswithplinkrsh.bat</buildArgs>
 5  <nologo>false</nologo>
 6  <buildFile>cruise.build</buildFile>
 7  <logger>My.Other.XmlLogger</logger>
 8  <targetList>
 9    <target>run</target>
10  </targetList>
11  <buildTimeoutSeconds>1200</buildTimeoutSeconds>
12</nant>

Configuration Elements

Element Description Type Required Default Version
buildArgs Any arguments to pass through to NAnt (e.g to specify build properties). String No None 1.0
buildFile The name of the build file to run, relative to the baseDirectory. String No Default build field in the working directory 1.0
buildTimeoutSeconds The maximum number of seconds that the build may take. If the build process takes longer than this period, it will be killed. Specify this value as zero to disable process timeouts. Int32 No 600 1.0
baseDirectory The directory to run the NAnt process in. If relative, is a subdirectory of the Project Working Directory. String No Project working directory 1.0
description Description used for the visualisation of the buildstage, if left empty the process name will be shown. String No The task/publisher name. 1.5
dynamicValues The dynamic values to use for the task. Dynamic Values array No None 1.5
environment A set of environment variables set for commands that are executed.
Each variable should be specified as
1<variable name="name" value="value" />

.
Environment Variable array No
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 No nant 1.0
listener The NAnt listener to use. String No NAnt.Core.DefaultLogger 1.5
logger The NAnt logger to use. String No NAnt.Core.XmlLogger 1.0
nologo Whether to use the -nologo argument when calling NAnt. Boolean No true 1.0
priority The priority class of the spawned process. String - one of:
* Normal
* Idle
* High
* RealTime
* BelowNormal
* AboveNormal
No Normal 1.5
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 array No Default build target 1.0

Notes

NAnt output in Xml

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.

warning

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.

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.

Integration Properties

Label Description Example Version
CCNetArtifactDirectory The project artifact directory (as an absolute path) C:\Program Files\CruiseControl.NET\Server\MyProject\Artifacts 1.0
CCNetBuildCondition 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 1.0
CCNetBuildDate The date of the build (in yyyy-MM-dd format) 2005-08-10 1.0
CCNetBuildTime The time of the start of the build (in HH:mm:ss format) 08:45:12 1.0
CCNetFailureTasks The list of name of tasks which have contributed to the current build failure. When the description of the task is filled in, this will be shown. Exec Task 1.7
CCNetFailureUsers The list of users who have contributed modifications to a sequence of builds that has failed. John, Smith 1.0
CCNetIntegrationStatus The status of the current integration. Could be Success, Failure, Exception or Unknown Success 1.0
CCNetLabel The label used to identify the CCNet build. This label is generated by the CCNet labeller. 1.0.2.120 1.0
CCNetLastIntegrationStatus The status of the previous integration. Could be Success, Failure, Exception or Unknown Success 1.0
CCNetListenerFile View build progress : task output that shows how far the build is c:\Project\Artifact\listener.xml 1.4.0
CCNetModifyingUsers The list of users who have contributed to the current build only Smith 1.0
CCNetNumericLabel Contains the label as an integer if conversion is possible, otherwise zero. 1 1.0
CCNetProject The name of the CCNet project that is being integrated. MyProject 1.0
CCNetProjectUrl The URL where the project is located http://myhost/ccnet/server/ 1.0
CCNetRequestSource The source of the integration request; this will generally be the name of the trigger that raised the request. IntervalTrigger 1.1.0
CCNetUser The user who forced the build. If security is off, or the build is not forced, then this will not be set. John Doe 1.5.0
CCNetWorkingDirectory The project working directory (as an absolute path) C:\Program Files\CruiseControl.NET\Server\MyProject\WorkingDirectory 1.0
1<target name="test.unit" depends="compile" description="runs unit tests">
2  <nunit2>
3    <formatter type="Xml" usefile="false" />
4    <test assemblyname="${build.dir}\${core.dll}" fork="true" />
5    <test assemblyname="${build.dir}\${console.exe}" fork="true" />
6  </nunit2>
7</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..

1<build>
2  <property name="outputType" value="Plain" />
3  <!-- ... -->
4  <formatter type="${outputType}" usefile="false" />
5  <!-- ... -->
6</build>

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

1<nant>
2  <!-- ... -->
3  <buildArgs>"-DoutputType=Xml"</buildArgs>
4  <!-- ... -->
5</nant>

Accessing CruiseControl.NET build labels in NAnt

CCNet will pass the current build label to NAnt via the NAnt property CCNetLabel. 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 an example NAnt script demonstrating how to do this:

 1<target name="dist.publish" depends="dist">
 2  <ifnot propertyexists="CCNetLabel">
 3    <fail message="CCNetLabel property not set, so can't create labelled distribution files" />
 4  </ifnot>
 5  <property name="publish.dir" value="D:\download-area\CCNet-Builds\${CCNetLabel}" />
 6  <mkdir dir="${publish.dir}" />
 7  <copy todir="${publish.dir}">
 8    <fileset basedir="dist">
 9      <includes name="*" />
10    </fileset>
11  </copy>
12</target>

Automatically Generated

Documentation generated on Sunday, 1 Sep 2013 at 7:07:21 AM