| <!-- |
| 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 properly when the first target is executed. |
| If you use it in the implicit target (directly |
| under the <project> 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.. |
| ant.java.version the JVM version Ant detected; currently it can hold |
| the values "9", "1.8", |
| "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> |