Property Task

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 six ways to set properties:

By supplying both the name and value attribute.
By supplying both the name and refid attribute.
By setting the file attribute with the filename of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties, with the same rules about how non-ISO8859-1 characters must be escaped.
By setting the url attribute with the url from which to load the properties. This url must be directed to a file that has the format as defined by the file used in the class java.util.Properties.
By setting the resource attribute with the resource name of the property file to load. A resource is a property file on the current classpath, or on the specified classpath.
By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable.

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.

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).

Parameters

Attribute	Description	Required
name	the name of the property to set.	No
value	the value of the property.	One of these, when using the name attribute
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 resource name of the property file.	One of these, when not using the name attribute
file	the filename of the property file .
url	the url from which to read properties.
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. ie 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 this functionality is supported on ;). Note also that properties are case sensitive, even if the environment variables on your operating system are not, e.g. it will be ${env.Path} not /Users/antoine/opt/apache-tomcat-6.0.2/bin:/Users/antoine/opt/maven-2.0.4/bin:/Users/antoine/opt/ant/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin on Windows 2000.
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` or `resource`. A "." is appended to the prefix if not specified.	No

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

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

sets the property foo.dist to the value "dist".

  <property file="foo.properties"/>

reads a set of properties from a file called "foo.properties".

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

reads a set of properties from the address "http://www.mysite.com/bla/props/foo.properties".

  <property resource="foo.properties"/>

reads a set of properties from a resource called "foo.properties".

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

  <property file="/Users/antoine/.ant-global.properties"/>

since the "user.home" property is defined by the Java virtual machine 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" folder. Older windows variants such as Windows 98/ME are less predictable, as are other operating system/JVM combinations.

  <property environment="env"/>
  <echo message="Number of Processors = ${env.NUMBER_OF_PROCESSORS}"/>
  <echo message="ANT_HOME is set to = /Users/antoine/dev/asf/ant-core/bootstrap"/>

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

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.
The rules for this format are laid down by Sun. This makes it hard for Team Ant to field bug reports about it.
Trailing spaces are not stripped. It may have been what you wanted.
Want unusual characters? Escape them \u0456 or \" style.
Ant Properties are expanded in the file.

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

Example:

build.compiler=jikes
deploy.server=lucky
deploy.port=8080
deploy.url=http://${deploy.server}:${deploy.port}/