|
|
@@ -0,0 +1,326 @@ |
|
|
|
|
|
<!-- |
|
|
|
|
|
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 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="CoreTasks/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="CoreTasks/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="CoreTasks/local.html">local</a> task can be used to |
|
|
|
|
|
create properties that are locally scoped to a target or |
|
|
|
|
|
a <a href="CoreTasks/sequential.html">sequential</a> element like |
|
|
|
|
|
the one of the <a href="CoreTasks/macrodef.html">macrodef</a> |
|
|
|
|
|
task.</p> |
|
|
|
|
|
|
|
|
|
|
|
<a name="built-in-props"><h2>Built-in Properties</h2></a> |
|
|
|
|
|
|
|
|
|
|
|
<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://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>. |
|
|
|
|
|
</p> |
|
|
|
|
|
|
|
|
|
|
|
<p>In addition, Ant has some built-in properties:</p> |
|
|
|
|
|
<pre> |
|
|
|
|
|
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. |
|
|
|
|
|
ant.java.version the JVM version Ant detected; currently it can hold |
|
|
|
|
|
the values "1.2", "1.3", |
|
|
|
|
|
"1.4", "1.5" and "1.6". |
|
|
|
|
|
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> |
|
|
|
|
|
|
|
|
|
|
|
<a name="propertyHelper"><h1>PropertyHelpers</h1></a> |
|
|
|
|
|
|
|
|
|
|
|
<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="CoreTasks/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="http://svn.apache.org/viewvc/ant/antlibs/props/trunk/src/main/org/apache/ant/props/NestedPropertyExpander.java?view=log"><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="CoreTasks/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="CoreTasks/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 ballance 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> |
|
|
|
|
|
|
|
|
|
|
|
<a name="toString"><h3>Getting the value of a Reference with |
|
|
|
|
|
${toString:}</h3></a> |
|
|
|
|
|
|
|
|
|
|
|
<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 |
|
|
|
|
|
preciously defined as references like</p> |
|
|
|
|
|
<pre> |
|
|
|
|
|
<url url="http://ant.apache.org/" id="anturl"/> |
|
|
|
|
|
<my:task attr="${ant.refid:anturl}"/> |
|
|
|
|
|
</pre> |
|
|
|
|
|
|
|
|
|
|
|
</body> |
Stefan Bodewig