Properties

[This is preliminary documentation and subject to change.]

Contents

1 Introduction
2 Naming rules
3 Built-in Properties
3.1 Framework related Properties
3.2 Platform related Properties
4 Read-only Properties
5 Global Properties
6 Examples

1 Introduction

A project can have a set of properties.  These might be set in the buildfile by the <property> task, or might be set outside NAnt.  A property has a name and a value. Properties may be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. Properties may also be used in expressions.

2 Naming rules

A property name is a string of the following characters:

In addition, a valid property name must start with a letter or an underscore and must end with a letter, digit or an uderscore.

Examples of valid property names include:

The following property names are not valid in NAnt:

3 Built-in Properties

NAnt has these built-in properties:

Property Description
nant.version Deprecated. The version of NAnt.
nant.filename Deprecated. The full path to the NAnt assembly.
nant.location Deprecated. The base directory of the NAnt assembly.
nant.project.basedir Deprecated. The absolute path of the project's basedir.
nant.project.buildfile Deprecated. The absolute path of the buildfile.
nant.project.name Deprecated. The name of the project.
nant.project.default Deprecated. The name of the project's default target.
nant.onsuccess The name of a target to be executed when the build succeeds.
nant.onfailure The name of a target to be executed when the build fails.

3.1 Framework related Properties:

Property Description
nant.settings.currentframework The current target framework, eg. 'net-1.0'.
nant.settings.currentframework.description Deprecated. Description of the current target framework.
nant.settings.currentframework.frameworkdirectory Deprecated. The framework directory of the current target framework.
nant.settings.currentframework.sdkdirectory Deprecated. The framework SDK directory of the current target framework.
nant.settings.currentframework.frameworkassemblydirectory Deprecated. The framework assembly directory of the current target framework.
nant.settings.currentframework.runtimeengine Deprecated. The runtime engine of the current target framework if used eg. mono.exe.

3.2 Platform related Properties:

Property Description
nant.platform.name Deprecated. The name of the platform on which NAnt is currently running - either win32 or unix.
nant.platform.win32 Deprecated. Holds the value true if NAnt is running on the win32 platform; otherwise, false.
nant.platform.unix Deprecated. Holds the value true if NAnt is running on the unix platform; otherwise, false.

4 Read-only Properties

A property can be explicitly marked read-only by setting the "readonly" attribute on the <property> task to true.

The value of a read-only property cannot be modified after it has been set.

When attempting to override a read-only property using the <property> task, the new value will be ignored and a warning message will be output in the build log. Attempting to override read-only properties using any other means (eg. other tasks) will result in a build failure.

Note: properties set on the command-line are always read-only.

5 Global Properties

Properties that should be accessible to all build files on a system can be defined in the <properties> node of the NAnt configuration file (NAnt.exe.config).

By changing the value of the property in the NAnt configuration file, the updated value will be accessible to all build files on the system:

    <?xml version="1.0"?>
    <configuration>
        ...
        <nant>
            ...
            <properties>
                <!-- properties defined here are accessible to all build files -->
                <property name="company.name" value="Foo Ltd." readonly="true" />
            </properties>
        </nant>
    </configuration>
        

Individual build files can then use this property:

    <?xml version="1.0"?>
    <project name="test">
        <echo message="Company: ${company.name}" />
    </project>
        

The output of this build is:

    [echo] Company: Foo Ltd.
        

6 Examples

The following build file demonstrates the use of property expansion:

    <?xml version="1.0"?>
    <project name="Property Test" default="test" basedir=".">
        <property name="project.name" value="PropertyTest"/>
        <property name="project.version" value="1.0.0"/>
        <target name="test">
            <echo message="Building ${project.name}-${project.version}"/>
        </target>
    </project>
        

The output of this build is:

    [echo] Building PropertyTest-1.0.0
        

The following build file demonstrates the use of properties in expressions. It evaluates the length of the property project.name and displays it.

    <?xml version="1.0"?>
    <project name="Expression Test" default="test" basedir=".">
        <property name="project.name" value="Expression Test"/>
        <target name="test">
            <echo message="Project name consists of ${string::get-length(project.name)} characters."/>
        </target>
    </project>
        

The output of this build is:

   [echo] Project name consists of 15 characters.
        

See Also