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
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
|
<!--
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>Properties and PropertyHelpers</title>
</head>
<body>
<h1>Properties</h1>
<p>Properties are key-value-pairs where Apache Ant tries to
expand <code>${key}</code> to <code>value</code> at runtime.</p>
<p>There are many tasks that can set properties, the most common one
is the <a href="Tasks/property.html">property</a> task. In
addition properties can be defined
via <a href="running.html">command line arguments</a> or similar
mechanisms from outside of Ant.</p>
<p>Normally property values can not be changed, once a property is
set, most tasks will not allow its value to be modified. In
general properties are of global scope, i.e. once they have been
defined they are available for any task or target invoked
subsequently - it is not possible to set a property in a child
build process created via
the <a href="Tasks/ant.html">ant</a>, antcall or subant tasks
and make it available to the calling build process, though.</p>
<p>Starting with Ant 1.8.0
the <a href="Tasks/local.html">local</a> task can be used to
create properties that are locally scoped to a target or
a <a href="Tasks/sequential.html">sequential</a> element like
the one of the <a href="Tasks/macrodef.html">macrodef</a>
task.</p>
<h2><a name="built-in-props">Built-in Properties</a></h2>
<p>Ant provides access to all system properties as if they had been
defined using a <code><property></code> task. For
example, <code>${os.name}</code> expands to the name of the
operating system.</p>
<p>For a list of system properties see
<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties%28%29">the Javadoc of System.getProperties</a>.
</p>
<p>In addition, Ant has some built-in properties:</p>
<pre><!-- TODO use <dl><dt><code>...</code></dt><dd>...</dd></dl> instead -->
basedir the absolute path of the project's basedir (as set
with the basedir attribute of <a href="using.html#projects"><project></a>).
ant.file the absolute path of the buildfile.
ant.version the version of Ant
ant.project.name the name of the project that is currently executing;
it is set in the name attribute of <project>.
ant.project.default-target
the name of the currently executing project's
default target; it is set via the default
attribute of <project>.
ant.project.invoked-targets
a comma separated list of the targets that have
been specified on the command line (the IDE,
an <ant> task ...) when invoking the current
project.
This property is set when the first target is executed.
So you can't use it in the implicit target (directly
under the <project> tag).
ant.java.version the JVM version Ant detected; currently it can hold
the values "1.7", "1.6", "1.5",
"1.4", "1.3" and "1.2".
ant.core.lib the absolute path of the <code>ant.jar</code> file.
</pre>
<p>There is also another property, but this is set by the launcher
script and therefore maybe not set inside IDEs:</p>
<pre>
ant.home home directory of Ant
</pre>
<p>The following property is only set if Ant is started via the
Launcher class (which means it may not be set inside IDEs
either):</p>
<pre>
ant.library.dir the directory that has been used to load Ant's
jars from. In most cases this is ANT_HOME/lib.
</pre>
<h1><a name="propertyHelper">PropertyHelpers</a></h1>
<p>Ant's property handling is accomplished by an instance of
<code>org.apache.tools.ant.PropertyHelper</code> associated with
the current Project. You can learn more about this class by
examining Ant's Java API. In Ant 1.8 the PropertyHelper class was
much reworked and now itself employs a number of helper classes
(actually instances of
the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
marker interface) to take care of discrete tasks such as property
setting, retrieval, parsing, etc. This makes Ant's property
handling highly extensible; also of interest is the
new <a href="Tasks/propertyhelper.html">propertyhelper</a>
task used to manipulate the PropertyHelper and its delegates from
the context of the Ant buildfile.
<p>There are three sub-interfaces of <code>Delegate</code> that may be
useful to implement.</p>
<ul>
<li><code>org.apache.tools.ant.property.PropertyExpander</code> is
responsible for finding the property name inside a string in the
first place (the default extracts <code>foo</code>
from <code>${foo}</code>).
<p>This is the interface you'd implement if you wanted to invent
your own property syntax - or allow nested property expansions
since the default implementation doesn't balance braces
(see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD"><code>NestedPropertyExpander</code>
in the "props" Antlib</a> for an example).</p>
</li>
<li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
is used to expand <code>${some-string}</code> into
an <code>Object</code>.
<p>This is the interface you'd implement if you want to provide
your own storage independent of Ant's project instance - the
interface represents the reading end. An example for this
would
be <code>org.apache.tools.ant.property.LocalProperties</code>
which implements storage
for <a href="Tasks/local.html">local properties</a>.</p>
<p>Another reason to implement this interface is if you wanted
to provide your own "property protocol" like
expanding <code>toString:foo</code> by looking up the project
reference foo and invoking <code>toString()</code> on it
(which is already implemented in Ant, see below).</p>
</li>
<li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
is responsible for setting properties.
<p>This is the interface you'd implement if you want to provide
your own storage independent of Ant's project instance - the
interface represents the reading end. An example for this
would
be <code>org.apache.tools.ant.property.LocalProperties</code>
which implements storage
for <a href="Tasks/local.html">local properties</a>.</p>
</li>
</ul>
<p>The default <code>PropertyExpander</code> looks similar to:</p>
<pre>
public class DefaultExpander implements PropertyExpander {
public String parsePropertyName(String s, ParsePosition pos,
ParseNextProperty notUsed) {
int index = pos.getIndex();
if (s.indexOf("${", index) == index) {
int end = s.indexOf('}', index);
if (end < 0) {
throw new BuildException("Syntax error in property: " + s);
}
int start = index + 2;
pos.setIndex(end + 1);
return s.substring(start, end);
}
return null;
}
}
</pre>
<p>The logic that replaces <code>${toString:some-id}</code> with the
stringified representation of the object with
id <code>some-id</code> inside the current build is contained in a
PropertyEvaluator similar to the following code:</p>
<pre>
public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
private static final String prefix = "toString:";
public Object evaluate(String property, PropertyHelper propertyHelper) {
Object o = null;
if (property.startsWith(prefix) && propertyHelper.getProject() != null) {
o = propertyHelper.getProject().getReference(
property.substring(prefix.length()));
}
return o == null ? null : o.toString();
}
}
</pre>
<h1>Property Expansion</h1>
<p>When Ant encounters a construct <code>${some-text}</code> the
exact parsing semantics are subject to the configured property
helper delegates.</p>
<h2><code>$$</code> Expansion</h2>
<p>In its default configuration Ant will expand the
text <code>$$</code> to a single <code>$</code> and suppress the
normal property expansion mechanism for the text immediately
following it, i.e. <code>$${key}</code> expands
to <code>${key}</code> and not <code>value</code> even though a
property named <code>key</code> was defined and had the
value <code>value</code>. This can be used to escape
literal <code>$</code> characters and is useful in constructs that
only look like property expansions or when you want to provide
diagnostic output like in</p>
<pre> <echo>$${builddir}=${builddir}</echo></pre>
<p>which will echo this message:</p>
<pre> ${builddir}=build/classes</pre>
<p>if the property <code>builddir</code> has the
value <code>build/classes</code>.</p>
<p>In order to maintain backward compatibility with older Ant
releases, a single '$' character encountered apart from a
property-like construct (including a matched pair of french
braces) will be interpreted literally; that is, as '$'. The
"correct" way to specify this literal character, however, is by
using the escaping mechanism unconditionally, so that "$$" is
obtained by specifying "$$$$". Mixing the two approaches yields
unpredictable results, as "$$$" results in "$$".</p>
<h2>Nesting of Braces</h2>
<p>In its default configuration Ant will not try to balance braces
in property expansions, it will only consume the text up to the
first closing brace when creating a property name. I.e. when
expanding something like <code>${a${b}}</code> it will be
translated into two parts:</p>
<ol>
<li>the expansion of property <code>a${b</code> - likely nothing
useful.</li>
<li>the literal text <code>}</code> resulting from the second
closing brace</li>
</ol>
<p>This means you can't use easily expand properties whose names are
given by properties, but there
are <a href="http://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
workarounds</a> for older versions of Ant. With Ant 1.8.0 and the
<a href="http://ant.apache.org/antlib/props/">the props Antlib</a>
you can configure Ant to use
the <code>NestedPropertyExpander</code> defined there if you need
such a feature.</p>
<h2>Expanding a "Property Name"</h2>
<p>In its most simple form <code>${key}</code> is supposed to look
up a property named <code>key</code> and expand to the value of
the property. Additional <code>PropertyEvaluator</code>s may
result in a different interpretation of <code>key</code>,
though.</p>
<p>The <a href="http://ant.apache.org/antlibs/props/">props
Antlib</a> provides a few interesting evaluators but there are
also a few built-in ones.</p>
<h3><a name="toString">Getting the value of a Reference with
${toString:}</a></h3>
<p>Any Ant type which has been declared with a reference can also
its string value extracted by using the <code>${toString:}</code>
operation, with the name of the reference listed after
the <code>toString:</code> text. The <code>toString()</code>
method of the Java class instance that is referenced is invoked
-all built in types strive to produce useful and relevant output
in such an instance.</p>
<p>For example, here is how to get a listing of the files in a fileset,<p>
<pre>
<fileset id="sourcefiles" dir="src" includes="**/*.java" />
<echo> sourcefiles = ${toString:sourcefiles} </echo>
</pre>
<p>There is no guarantee that external types provide meaningful
information in such a situation</p>
<h3><a name="ant.refid">Getting the value of a Reference with
${ant.refid:}</a></h3>
<p>Any Ant type which has been declared with a reference can also be
used as a property by using the <code>${ant.refid:}</code>
operation, with the name of the reference listed after
the <code>ant.refid:</code> text. The difference between this
operation and <a href="#toString"><code>${toString:}</code></a> is
that <code>${ant.refid:}</code> will expand to the referenced
object itself. In most circumstances the toString method will be
invoked anyway, for example if the <code>${ant.refid:}</code> is
surrounded by other text.</p>
<p>This syntax is most useful when using a task with attribute
setters that accept objects other than String. For example if the
setter accepts a Resource object as in</p>
<pre>
public void setAttr(Resource r) { ... }
</pre>
<p>then the syntax can be used to pass in resource subclasses
previously defined as references like</p>
<pre>
<url url="http://ant.apache.org/" id="anturl"/>
<my:task attr="${ant.refid:anturl}"/>
</pre>
<h2><a name="if+unless">If/Unless Attributes</a></h2>
<p>
The <code><target></code> element and various tasks (such as
<code><fail></code>) and task elements (such as <code><test></code>
in <code><junit></code>) support <code>if</code> and <code>unless</code>
attributes which can be used to control whether the item is run or otherwise
takes effect.
</p>
<p>
In Ant 1.7.1 and earlier, these attributes could only be property names.
The item was enabled if a property with that name was defined - even to be
the empty string or <tt>false</tt> - and disabled if the property was not
defined. For example, the following works but there is no way to override
the file existence check negatively (only positively):
</p>
<pre>
<target name="-check-use-file">
<available property="file.exists" file="some-file"/>
</target>
<target name="use-file" depends="-check-use-file" <b>if="file.exists"</b>>
<!-- do something requiring that file... -->
</target>
<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
</pre>
<p>
As of Ant 1.8.0, you may instead use property expansion; a value of
<tt>true</tt> (or <tt>on</tt> or <tt>yes</tt>) will enable the
item, while <tt>false</tt> (or <tt>off</tt> or <tt>no</tt>) will
disable it. Other values are still assumed to be property
names and so the item is enabled only if the named property is defined.
</p>
<p>
Compared to the older style, this gives you additional flexibility, because
you can override the condition from the command line or parent scripts:
</p>
<pre>
<target name="-check-use-file" <b>unless="file.exists"</b>>
<available property="file.exists" file="some-file"/>
</target>
<target name="use-file" depends="-check-use-file" <b>if="${file.exists}"</b>>
<!-- do something requiring that file... -->
</target>
<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
</pre>
<p>
Now <code>ant -Dfile.exists=false lots-of-stuff</code> will run
<code>other-unconditional-stuff</code> but not <code>use-file</code>,
as you might expect, and you can disable the condition from another script
too:
</p>
<pre>
<antcall target="lots-of-stuff">
<param name="file.exists" value="false"/>
</antcall>
</pre>
<p>
Similarly, an <code>unless</code> attribute disables the item if it is
either the name of property which is defined, or if it evaluates to a
<tt>true</tt>-like value. For example, the following allows you to define
<tt>skip.printing.message=true</tt> in <tt>my-prefs.properties</tt> with
the results you might expect:
</p>
<pre>
<property file="my-prefs.properties"/>
<target name="print-message" <b>unless="${skip.printing.message}"</b>>
<echo>hello!</echo>
</target>
</pre>
</body>
|
