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 Ant 1.7.1 it is possible to load properties defined in xml according to Suns DTD, if Java5+ is present. For this the name of the file, resource or url has to end with .xml.
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).
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 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 name of the classpath resource containing properties settings in properties file format. | One of these, when not using the name attribute |
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's system path variable is set to an Ant property named "env.Path" rather than "env.PATH". |
|
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 |
relative | If set to true the relative path to basedir is set. | No (default=false) |
basedir | The basedir to calculate the relative path from. | No (default=${basedir}) |
Property
's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
<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 Ant builds using the following:
<property file="${user.home}/.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 = ${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 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 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
Example:
build.compiler=jikes deploy.server=lucky deploy.port=8080 deploy.url=http://${deploy.server}:${deploy.port}/
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()):
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 |