1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Property Task</title>
</head>
<body>
<h2><a name="property">Property</a></h2>
<h3>Description</h3>
<p>Sets a <a href="../using.html#properties">property</a>
(by name and value), or set of properties (from file or
resource) in the project. Properties are case sensitive.</p>
Properties are immutable: whoever sets a property first freezes it for the
rest of the build; they are most definitely not variables.
<p>There are seven ways to set properties:</p>
<ul>
<li>By supplying both the <i>name</i> and one of <i>value</i> or <i>location</i> attribute.</li>
<li>By supplying the <i>name</i> and nested text.</li>
<li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>
<li>By setting the <i>file</i> 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.</li>
<li>By setting the <i>url</i> 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.</li>
<li>By setting the <i>resource</i> 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.</li>
<li>By setting the <i>environment</i> 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.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>A list of predefined properties can be found <a
href="../properties.html#built-in-props">here</a>.</p>
<p>Since Apache Ant 1.8.0 it is possible to load properties defined in xml
according to <a href="http://java.sun.com/dtd/properties.dtd">Suns DTD</a>,
if Java5+ is present. For this the name of the file, resource or url has
to end with <tt>.xml</tt>.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">the name of the property to set.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">value</td>
<td valign="top">the value of the property.</td>
<td valign="middle" align="center" rowspan="3">One of these or
nested text, when using the name attribute</td>
</tr>
<tr>
<td valign="top">location</td>
<td valign="top">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.</td>
</tr>
<tr>
<td valign="top">refid</td>
<td valign="top"><a href="../using.html#references">Reference</a> to an object
defined elsewhere. Only yields reasonable results for references
to <a href="../using.html#path">PATH like structures</a> or properties.</td>
</tr>
<tr>
<td valign="top">resource</td>
<td valign="top"> the name of the classpath resource containing
properties settings in properties file format.</td>
<td valign="middle" align="center" rowspan="4">One of these, when
<b>not</b> using the name attribute</td>
</tr>
<tr>
<td valign="top">file</td>
<td valign="top">the location of the properties file to load.</td>
</tr>
<tr>
<td valign="top">url</td>
<td valign="top">a url containing properties-format settings.</td>
</tr>
<tr>
<td valign="top">environment</td>
<td valign="top">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 <a href="#notes-env">select platforms</a>. Feel free to send patches to increase the
number of platforms on which this functionality is supported ;).<br>
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".</td>
</tr>
<tr>
<td valign="top">classpath</td>
<td valign="top">the classpath to use when looking up a resource.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">classpathref</td>
<td valign="top">the classpath to use when looking up a resource,
given as <a href="../using.html#references">reference</a> to a <code><path></code> defined
elsewhere..</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">prefix</td>
<td valign="top">Prefix to apply to properties loaded using <code>file</code>,
<code>resource</code>, or <code>url</code>.
A "." is appended to the prefix if not specified.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">prefixValues</td>
<td valign="top">Whether to apply the prefix when expanding the
right hand side of properties loaded using <code>file</code>,
<code>resource</code>, or <code>url</code>.
<em>Since Ant 1.8.2</em></td>
<td align="center" valign="top">No (default=<tt>false</tt>)</td>
</tr>
<tr>
<td valign="top">relative</td>
<td valign="top">If set to <tt>true</tt> the relative path
to <tt>basedir</tt> is set. <em>Since Ant 1.8.0</em></td>
<td align="center" valign="top">No (default=<tt>false</tt>)</td>
</tr>
<tr>
<td valign="top">basedir</td>
<td valign="top">The basedir to calculate the relative path
from. <em>Since Ant 1.8.0</em></td>
<td align="center" valign="top">No (default=<tt>${basedir}</tt>)</td>
</tr>
</table>
<h4>OpenVMS Users</h4>
<p>With the <code>environment</code> 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).
</p>
<h4>Any OS except OpenVMS</h4>
<p>Starting with Ant 1.8.2 if Ant detects it is running of a Java 1.5
VM (or better) Ant will use <code>System.getenv</code> 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 <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=49366">Bugzilla
Issue 49366</a>. In particular:</p>
<ul>
<li>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.</li>
<li>Some users reported that some Cygwin specific variables (in
particular PROMPT) was no longer present.</li>
<li>On OS/2 Ant no longer returns the BEGINLIBPATH variable.</li>
</ul>
<h3>Parameters specified as nested elements</h3>
<h4>classpath</h4>
<p><code>Property</code>'s <i>classpath</i> attribute is a <a
href="../using.html#path">PATH like structure</a> and can also be set via a nested
<i>classpath</i> element.</p>
<h3>Examples</h3>
<pre> <property name="foo.dist" value="dist"/></pre>
<p>sets the property <code>foo.dist</code> to the value "dist".</p>
<pre> <property name="foo.dist">dist</property></pre>
<p>sets the property <code>foo.dist</code> to the value "dist".</p>
<pre> <property file="foo.properties"/></pre>
<p>reads a set of properties from a file called "foo.properties".</p>
<pre> <property url="http://www.mysite.com/bla/props/foo.properties"/></pre>
<p>reads a set of properties from the address "http://www.mysite.com/bla/props/foo.properties".</p>
<pre> <property resource="foo.properties"/></pre>
<p>reads a set of properties from a resource called "foo.properties".</p>
<p>Note that you can reference a global properties file for all of your Ant
builds using the following:</p>
<pre> <property file="${user.home}/.ant-global.properties"/></pre>
<p>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" or "Users" folder. Older windows variants such as Windows 98/ME are less
predictable, as are other operating system/JVM combinations.</p>
<pre>
<property environment="env"/>
<echo message="Number of Processors = ${env.NUMBER_OF_PROCESSORS}"/>
<echo message="ANT_HOME is set to = ${env.ANT_HOME}"/>
</pre>
<p>reads the system environment variables and stores them in properties, prefixed with "env".
Note that this only works on <em>select</em> operating systems.
Two of the values are shown being echoed.
</p>
<pre>
<property environment="env"/>
<property file="${user.name}.properties"/>
<property file="${env.STAGE}.properties"/>
<property file="build.properties"/>
</pre>
<p>This buildfile uses the properties defined in <tt>build.properties</tt>. Regarding to the
environment variable <tt>STAGE</tt> some or all values could be overwritten, e.g. having
<tt>STAGE=test</tt> and a <tt>test.properties</tt> 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.</p>
<pre>
<property name="foo" location="my/file.txt" relative="true" basedir=".."/>
</pre>
<p>Stores the relative path in <tt>foo</tt>: projectbasedir/my/file.txt</p>
<pre>
<property name="foo" location="my/file.txt" relative="true" basedir="cvs"/>
</pre>
<p>Stores the relative path in <tt>foo</tt>: ../my/file.txt</p>
<h3>Property Files</h3>
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
<ol>
<li>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.
<li>The rules for this format match <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load%28java.io.InputStream%29">java.util.Properties</a>.</li>
<li>Trailing spaces are not stripped. It may have been what you wanted.</li>
<li>Want unusual characters? Escape them \u0456 or \" style.</li>
<li>Ant Properties are expanded in the file</li>
<li>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 <code>prefixValues</code> to true.</li>
</ol>
In-file property expansion is very cool. Learn to use it.
<p>
Example:
<pre>
build.compiler=jikes
deploy.server=lucky
deploy.port=8080
deploy.url=http://${deploy.server}:${deploy.port}/
</pre>
<a name="notes-env"></a>
<h3>Notes about environment variables</h3>
<p>
Ant runs on Java 1.2 therefore it cannot 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. <br>
There are commands for the following operating systems implemented in
<a href="https://git-wip-us.apache.org/repos/asf?p=ant.git;a=blob;f=src/main/org/apache/tools/ant/taskdefs/Execute.java;hb=24e5a0e881dba01a6f012c4a271b743946412a0d">
Execute.java</a> (method <tt>getProcEnvCommand()</tt>):
<table>
<tr>
<th>OS</th>
<th>command</th>
</tr>
<tr>
<td> os/2 </td>
<td> cmd /c set </td>
</tr>
<tr>
<td colspan="2"> windows </td>
</tr>
<tr>
<td> * win9x </td>
<td> command.com /c set </td>
</tr>
<tr>
<td> * other </td>
<td> cmd /c set </td>
</tr>
<tr>
<td> z/os </td>
<td> /bin/env <b>OR</b> /usr/bin/env <b>OR</b> env <i>(depending on read rights)</i> </td>
</tr>
<tr>
<td> unix </td>
<td> /bin/env <b>OR</b> /usr/bin/env <b>OR</b> env <i>(depending on read rights)</i> </td>
</tr>
<tr>
<td> netware </td>
<td> env </td>
</tr>
<tr>
<td> os/400 </td>
<td> env </td>
</tr>
<tr>
<td> openvms </td>
<td> show logical </td>
</tr>
</table>
</p>
</body>
</html>
|
