Property

Property

Description

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

There are seven ways to set properties:

• By supplying both the name and one of value or location attribute.
• By supplying the name and nested text.
• 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 usedat a time. Problems might occur with the order in which properties are set, forinstance.

The value part of the properties being set, might contain references to otherproperties. 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.7.1 it is possible to load properties defined in xmlaccording to Suns DTD,if Java5+ is present. For this the name of the file, resource or url has to end with .xml.

Parameters

OpenVMS Users

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

Any OS except OpenVMS

Starting with Ant 1.8.2 if Ant detects it is running of a Java 1.5 VM (or better) 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:

• On Windows Ant will now return additional "environment variables" that correspond to the drive specific current working directories when Ant is run from the command line. The keys of these variables starts with an equals sign.
• Some users reported that some Cygwin specific variables (in particular PROMPT) was no longer present.
• On OS/2 Ant no longer returns the BEGINLIBPATH variable.

Parameters specified as nested elements

classpath

Property's classpath attribute is a PATH like structure and can also be set via a nestedclasspath element.

Examples

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

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

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

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 Antbuilds using the following:

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

since the "user.home" property is defined by the Java virtual machineto be your home directory. Where the "user.home" property resolves to inthe 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 Windowsvariants, this will most likely resolve to the user's directory in the "Documentsand Settings" or "Users" folder. Older windows variants such as Windows 98/ME are lesspredictable, 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 = ${env.ANT_HOME}"/>

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 environment="env"/>  <property file="${user.name}.properties"/>  <property file="${env.STAGE}.properties"/>  <property file="build.properties"/>

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

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

Stores the relative path in foo: projectbasedir/my/file.txt

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

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

Property Files

1. If the file is not there, nothing is printed except at -verbose loglevel. This lets you have optional configuration files for everyproject, that team members can customize.
2. The rules for this format are laid downby Sun.This makes it hard for Team Ant to field bug reports about it.
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.

Example:

build.compiler=jikesdeploy.server=luckydeploy.port=8080deploy.url=http://${deploy.server}:${deploy.port}/

Notes about environment variables

Ant runs on Java 1.2 therefore it cant use Java5 features for accessing environment variables. So it starts a command in a new process which prints the environment variables, analyzes the output and creates the properties.
There are commands for the following operating systems implemented in Execute.java (method getProcEnvCommand()):