Property

Description

Sets a property (by name and value), or set of properties (from file or resource) in the project. Properties are case sensitive.

Properties are immutable: whoever sets a property first freezes it for the rest of the build; they are most definitely not variables.

There are seven ways to set properties:

Although combinations of these ways are possible, only one should be used at a time. Problems might occur with the order in which properties are set, for instance.

The value part of the properties being set might contain references to other properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file.

A list of predefined properties can be found here.

Since Apache Ant 1.8.0, it is possible to load properties defined in XML according to Sun DTD, when running on Java 5+. For this the name of the file, resource or url has to end with .xml.

Parameters

Attribute Description Required
name the name of the property to set. No
value the value of the property. One of these or nested text, when the name attribute is set
location Sets the property to the absolute filename of the given file. If the value of this attribute is an absolute path, it is left unchanged (with / and \ characters converted to the current platforms conventions). Otherwise it is taken as a path relative to the project's basedir and expanded.
refid Reference to an object defined elsewhere. Only yields reasonable results for references to path-like structures or properties.
resource the name of the classpath resource containing properties settings in properties file format. One of these, unless the name attribute is set
file the location of the properties file to load.
url a URL containing properties-format settings.
environment the prefix to use when retrieving environment variables. Thus if you specify environment=myenv you will be able to access OS-specific environment variables via property names myenv.PATH or myenv.TERM. Note that if you supply a property name with a final . it will not be doubled; i.e. environment=myenv. will still allow access of environment variables through myenv.PATH and myenv.TERM. This functionality is currently only implemented on select platforms. Feel free to send patches to increase the number of platforms on which this functionality is supported ;-).
Note also that properties are case-sensitive, even if the environment variables on your operating system are not; e.g. Windows 2000 or later system path variable is set to an Ant property named env.Path rather than env.PATH.
runtime the prefix to use when retrieving runtime properties. Thus if you specify runtime=myrt you will be able to access runtime values corresponding to methods in the Runtime class via property names myrt.availableProcessors, myrt.maxMemory, myrt.totalMemory or myrt.freeMemory. Note that if you supply a property name with a final . it will not be doubled; i.e. runtime=myrt. will still allow access of runtime properties as e.g. myrt.maxMemory.
Note also that the property values are snapshots taken at the point in time when the property has been executed. Since Ant 1.10.4
classpath the classpath to use when looking up a resource. No
classpathref the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere.. No
prefix Prefix to apply to properties loaded using file, resource, or url. A . is appended to the prefix if not specified. No
prefixValues Whether to apply the prefix when expanding the right hand side of properties loaded using file, resource, or url. Since Ant 1.8.2 No; default is false
relative If set to true the relative path to basedir is set. Since Ant 1.8.0 No; default is false
basedir The basedir to calculate the relative path from. Since Ant 1.8.0 No; default is project's basedir

OpenVMS Users

With the environment attribute this task will load all defined logicals on an OpenVMS system. Logicals with multiple equivalence names get mapped to a property whose value is a comma separated list of all equivalence names. If a logical is defined in multiple tables, only the most local definition is available (the table priority order being PROCESS, JOB, GROUP, SYSTEM).

Any OS except OpenVMS

Since Ant 1.8.2, if Ant detects it is running on a Java 5 or newer, Ant will use System.getenv() rather than its own OS dependent native implementation. For some OSes this causes minor differences when compared to older versions of Ant. For a full list see Bugzilla Issue 49366. In particular:

Parameters specified as nested elements

classpath

Property's classpath attribute is a path-like structure and can also be set via a nested classpath element.

Examples

Set the property foo.dist to the value dist.

<property name="foo.dist" value="dist"/>

Set the property foo.dist to the value dist.

<property name="foo.dist">dist</property>

Read a set of properties from a file called foo.properties.

<property file="foo.properties"/>

Read a set of properties from the address https://www.mysite.com/bla/props/foo.properties.

<property url="https://www.mysite.com/bla/props/foo.properties"/>

Read a set of properties from a resource called foo.properties.

<property resource="foo.properties"/>

Note that you can reference a global properties file for all of your Ant builds using the following:

<property file="${user.home}/.ant-global.properties"/>

since the user.home property is defined by JVM to be your home directory. Where the user.home property resolves to in the file system depends on the operating system version and the JVM implementation. On Unix based systems, this will map to the user's home directory. On modern Windows variants, this will most likely resolve to the user's directory in the Documents and Settings or Users folder. Older Windows variants such as Windows 98/ME are less predictable, as are other operating system/JVM combinations.

Read the system environment variables and stores them in properties, prefixed with env. Note that this only works on select operating systems. Two of the values are shown being echoed.

<property environment="env"/>
<echo message="Number of Processors = ${env.NUMBER_OF_PROCESSORS}"/>
<echo message="ANT_HOME is set to = ${env.ANT_HOME}"/>

This buildfile uses the properties defined in build.properties. Regarding to the environment variable STAGE some or all values could be overwritten, e.g. having STAGE=test and a test.properties you have special values for that (like another name for the test server). Finally all these values could be overwritten by personal settings with a file per user.

<property environment="env"/>
<property file="${user.name}.properties"/>
<property file="${env.STAGE}.properties"/>
<property file="build.properties"/>

Store the relative path in foo: ../my/file.txt

<property name="foo" location="my/file.txt" relative="true" basedir=".."/>

Store the relative path in foo: cvs/my/file.txt

<property name="foo" location="my/file.txt" relative="true" basedir="cvs"/>

Property files

As stated, this task will load in a properties file stored in the file system, or as a resource on a classpath. Here are some interesting facts about this feature

  1. If the file is not there, nothing is printed except at -verbose log level. This lets you have optional configuration files for every project, that team members can customize.
  2. The rules for this format match java.util.Properties.
  3. Trailing spaces are not stripped. It may have been what you wanted.
  4. Want unusual characters? Escape them \u0456 or \" style.
  5. Ant Properties are expanded in the file
  6. If you want to expand properties defined inside the same file and you use the prefix attribute of the task, you must use the same prefix when expanding the properties or set prefixValues to true.

In-file property expansion is very cool. Learn to use it.

Example:

build.compiler=jikes
deploy.server=lucky
deploy.port=8443
deploy.url=https://${deploy.server}:${deploy.port}/

Notes about environment variables

When Ant started to support setting properties from environment variables it ran on Java 1.2 where System.getEnv didn't work. So we decided to start a command in a new process which prints the environment variables, analyzes the output and creates the properties. With Ant 1.9.0 when we started to require Java 5 we switched back to System.getEnv even though it returned different results on some platforms. The commands described below are still used on OpenVMS or if System.getEnv throws an exception.

There are commands for the following operating systems implemented in Execute.java (method getProcEnvCommand()):

OS command
os/2 cmd /c set
windows
* win9x command.com /c set
* other cmd /c set
z/os /bin/env OR /usr/bin/env OR env (depending on read rights)
unix /bin/env OR /usr/bin/env OR env (depending on read rights)
netware env
os/400 env
openvms show logical