# 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:

- letters (`A-Z`, `a-z`),
- digits (`0-9`),
- underscore characters (`_`),
- dash characters (`-`),
- dot 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:

- `propertyname`
- `property.name.with.dots`
- `property-name-with-dashes`
- `property.name-with.both-dots.and-dashes`
- `__prop---3-erty__`
- `__prop.1...erty__`
- `property1`
- `property1.0`
- `property2.0.0`
- `_property-2-1__`
- `property-1-name_`
- `property-1.0-name`

The following property names are not valid in NAnt:

- `!@#!@$!@` (contains illegal characters)
- `.aaaaa` (starts with a dot)
- `-aaaaa` (starts with a dash)
- `1aaaaa` (starts with a digit)
- `aaaaa.aaa.a.a.a.a-` (ends with a dash)
- `aaaaa.aaa.a.a.a.a.` (ends with a dot)

## 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

- <property>
- <sysinfo>
- <tstamp>