| <!DOCTYPE html> |
| <!-- |
| 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 |
| |
| https://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 lang="en"> |
| |
| <head> |
| <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 run time.</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>, <a href="Tasks/antcall.html">antcall</a> |
| or <a href="Tasks/subant.html">subant</a> tasks and make it available to the calling build |
| process, though.</p> |
| |
| <p><em>Since Ant 1.8.0</em> 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 id="built-in-props">Built-in Properties</h2> |
| |
| <p>Ant provides access to all system properties as if they had been defined using |
| a <code><property></code> task. For example, <samp>${os.name}</samp> expands to the name |
| of the operating system.</p> |
| |
| <p>For a list of system properties, |
| see <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties--" |
| target="_top">the javadoc of System.getProperties</a>. |
| </p> |
| |
| <p>In addition, Ant has some built-in properties:</p> |
| <dl> |
| <dt><code>basedir</code></dt> |
| <dd>the absolute path of the project's basedir (as set with |
| the <var>basedir</var> attribute |
| of <a href="using.html#projects"><project></a>).</dd> |
| <dt><code>ant.file</code></dt> |
| <dd>the absolute path of the buildfile.</dd> |
| <dt><code>ant.version</code></dt> |
| <dd>the version of Ant</dd> |
| <dt><code>ant.project.name</code></dt> |
| <dd>the name of the project that is currently executing; it is set in the <var>name</var> |
| attribute of <code><project></code>.</dd> |
| <dt><code>ant.project.default-target</code></dt> |
| <dd>the name of the currently executing project's default target; it is set via |
| the <var>default</var> attribute of <code><project></code>.</dd> |
| <dt><code>ant.project.invoked-targets</code></dt> |
| <dd>a comma-separated list of the targets that have been specified (on the command line, inside |
| of an IDE, by an <code><ant></code> task, etc...) when invoking the current |
| project.<br/>This property is set properly when the first target is executed. If you use it in |
| the implicit target (directly under the <code><project></code> tag) the list will be |
| empty if no target has been specified while it will contain the project's default target in |
| this case for tasks nested into targets.</dd> |
| <dt><code>ant.java.version</code></dt> |
| <dd>the JVM version Ant detected; currently it can hold the |
| values <q>9</q>, <q>1.8</q>, <q>1.7</q>, <q>1.6</q>, <q>1.5</q>, <q>1.4</q>, <q>1.3</q> |
| and <q>1.2</q>.</dd> |
| <dt><code>ant.core.lib</code></dt> |
| <dd>the absolute path of the <samp>ant.jar</samp> file.</dd> |
| </dl> |
| |
| <p>There is also another property, but this is set by the launcher script and therefore maybe not |
| set inside IDEs:</p> |
| <dl> |
| <dt><code>ant.home</code></dt> |
| <dd>home directory of Ant</dd> |
| </dl> |
| |
| <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> |
| <dl> |
| <dt><code>ant.library.dir</code></dt> |
| <dd>the directory that has been used to load Ant's jars from. In most cases this |
| is <samp>ANT_HOME/lib</samp>.</dd> |
| </dl> |
| |
| <h1 id="propertyHelper">PropertyHelpers</h1> |
| |
| <p>Ant's property handling is accomplished by an instance |
| of <code class="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 |
| <code class="code">PropertyHelper</code> class was much reworked and now itself employs a number |
| of helper classes (actually instances of |
| the <code class="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> |
| |
| <p>There are three sub-interfaces of <code class="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 <samp>foo</samp> |
| from <samp>${foo}</samp>). |
| |
| <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://gitbox.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD" |
| target="_top"><code class="code">NestedPropertyExpander</code> in the <samp>props</samp> Antlib</a> for |
| an example).</p> |
| </li> |
| |
| <li><code class="code">org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code> is used to |
| expand <samp>${some-string}</samp> 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 class="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 <samp>foo</samp> and invoking <code class="code">toString()</code> on it (which is |
| already implemented in Ant, see below).</p> |
| </li> |
| |
| <li><code class="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 writing end. An example for |
| this would be <code class="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 class="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 <samp>${toString:<i>some-id</i>}</samp> with the stringified |
| representation of the object with <var>id</var> <samp><i>some-id</i></samp> inside the current |
| build is contained in a <code class="code">PropertyEvaluator</code> 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 <samp>${some-text}</samp> 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 <q>$$</q> to a single <q>$</q> and |
| suppress the normal property expansion mechanism for the text immediately following it, |
| i.e., <samp>$${key}</samp> expands to <samp>${key}</samp> and not <code>value</code> even though |
| a property named <code>key</code> was defined and had the value <samp>value</samp>. This can be |
| used to escape literal <q>$</q> 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 class="output">${builddir}=build/classes</pre> |
| |
| <p>if the property <code>builddir</code> has the value <samp>build/classes</samp>.</p> |
| |
| <p>In order to maintain backward compatibility with older Ant releases, a single <q>$</q> |
| character encountered apart from a property-like construct (including a matched pair of french |
| braces) will be interpreted literally, that is, as <q>$</q>. The "correct" way to specify this |
| literal character, however, is by using the escaping mechanism unconditionally, so |
| that <q>$$</q> is obtained by specifying <q>$$$$</q>. Mixing the two approaches yields |
| unpredictable results, as <q>$$$</q> results in <q>$$</q>.</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 <samp>${a${b}}</samp> it will be translated into two parts:</p> |
| |
| <ol> |
| <li>the expansion of property <samp>a${b</samp>—likely nothing useful.</li> |
| <li>the literal text <samp>}</samp> resulting from the second closing brace</li> |
| </ol> |
| |
| <p>This means you can't use easily expand properties whose names are stored in properties, but |
| there are <a href="https://ant.apache.org/faq.html#propertyvalue-as-name-for-property" |
| target="_top">some workarounds</a> for older versions of Ant. <em>Since Ant 1.8.0</em> using |
| the <a href="https://ant.apache.org/antlibs/props/" target="_top">props Antlib</a> you can |
| configure Ant to use the <code class="code">NestedPropertyExpander</code> defined there if you |
| need such a feature.</p> |
| |
| <h2>Expanding a Property Reference</h2> |
| |
| <p>In its most simple form <samp>${key}</samp> 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="https://ant.apache.org/antlibs/props/" target="_top">props Antlib</a> provides a |
| few interesting evaluators but there are also a few built-in ones.</p> |
| |
| <h3 id="toString">Getting the value of a Reference with <samp>${toString:}</samp></h3> |
| |
| <p>Any Ant type item which has been declared with a reference can also its string value extracted |
| by using the <samp>${toString:}</samp> operation, with the name of the reference listed after |
| the <code>toString:</code> text. The <code class="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 id="ant.refid">Getting the value of a Reference with <samp>${ant.refid:}</samp></h3> |
| |
| <p>Any Ant type item which has been declared with a reference can also be used as a property by |
| using the <samp>${ant.refid:}</samp> operation, with the name of the reference listed after |
| the <code>ant.refid:</code> text. The difference between this operation |
| and <a href="#toString"><samp>${toString:}</samp></a> is that <samp>${ant.refid:}</samp> will |
| expand to the referenced object itself. In most circumstances |
| the <code class="code">toString()</code> method will be invoked anyway, for example if |
| the <samp>${ant.refid:}</samp> is surrounded by other text.</p> |
| |
| <p>This syntax is most useful when using a task with attribute setters that accept objects other |
| than <code class="code">String</code>. For example, if the setter accepts |
| a <code class="code">Resource</code> 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="https://ant.apache.org/" id="anturl"/> |
| <my:task attr="${ant.refid:anturl}"/></pre> |
| |
| <h2 id="if+unless">If/Unless Attributes</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 <var>if</var> and <var>unless</var> 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 <q>false</q>—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" <strong>if="file.exists"</strong>> |
| <!-- do something requiring that file... --> |
| </target> |
| <target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre> |
| <p> |
| <em>Since Ant 1.8.0</em>, you may instead use property expansion; a value of <q>true</q> |
| (or <q>on</q> or <q>yes</q>) will enable the item, while <q>false</q> (or <q>off</q> |
| or <q>no</q>) 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" <strong>unless="file.exists"</strong>> |
| <available property="file.exists" file="some-file"/> |
| </target> |
| <target name="use-file" depends="-check-use-file" <strong>if="${file.exists}"</strong>> |
| <!-- do something requiring that file... --> |
| </target> |
| <target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre> |
| <p> |
| Now <kbd>ant -Dfile.exists=false lots-of-stuff</kbd> will run <q>other-unconditional-stuff</q> |
| but not <q>use-file</q>, 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 <var>unless</var> attribute disables the item if it is either the name of property |
| which is defined, or if it evaluates to a <q>true</q>-like value. For example, the following |
| allows you to define <code>skip.printing.message=true</code> in <samp>my-prefs.properties</samp> |
| with the results you might expect: |
| </p> |
| <pre> |
| <property file="my-prefs.properties"/> |
| <target name="print-message" <strong>unless="${skip.printing.message}"</strong>> |
| <echo>hello!</echo> |
| </target></pre> |
| |
| </body> |
| </html> |