diff options
| author | Gintas Grigelionis <gintas@apache.org> | 2018-03-08 07:43:53 +0100 |
|---|---|---|
| committer | Gintas Grigelionis <gintas@apache.org> | 2018-03-08 07:44:27 +0100 |
| commit | 97d81a726de13c369cc6b22ef1e6532df7b3d112 (patch) | |
| tree | 1e809d841f4bf7f712a77f9f54500d10e28331d4 /manual/properties.html | |
| parent | f02565dbd10c894620cf65501bd63326ecea9301 (diff) | |
| download | ant-97d81a726de13c369cc6b22ef1e6532df7b3d112.tar.gz | |
Added target attribute for external links
(the web is no longer frame-friendly…)
Diffstat (limited to 'manual/properties.html')
| -rw-r--r-- | manual/properties.html | 353 |
1 files changed, 150 insertions, 203 deletions
diff --git a/manual/properties.html b/manual/properties.html index a8439a8d6..224d9a3b8 100644 --- a/manual/properties.html +++ b/manual/properties.html @@ -25,67 +25,61 @@ <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 + <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>, <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> + 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> + <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>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--">the javadoc of System.getProperties</a>. + 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> + <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 <project>.</dd> + <dd>the name of the project that is currently executing; it is set in the <var>name</var> + attribute of <project>.</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> + <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 (the IDE, an <code><ant></code> task - ...) 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> + <dd>a comma separated list of the targets that have been specified on the command line (the IDE, + an <code><ant></code> task ...) 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> @@ -94,83 +88,69 @@ <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> + <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> + <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> + <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>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 + 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> + 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>Delegate</code> that may be - useful to implement.</p> + <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 <samp>foo</samp> + <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://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 <samp>props</samp> Antlib</a> for an example).</p> + <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" + target="_top"><code>NestedPropertyExpander</code> in the <samp>props</samp> Antlib</a> for + an example).</p> </li> - <li><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>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>toString()</code> on it - (which is already implemented in Ant, see below).</p> + <li><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>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>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. + <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> + <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> @@ -195,10 +175,9 @@ public class DefaultExpander implements PropertyExpander { } }</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>some-id</samp> inside the current build is contained in a - PropertyEvaluator similar to the following code:</p> + <p>The logic that replaces <samp>${toString:<i>some-id</i>}</samp> with the stringified + representation of the object with <var>id</var> <samp>some-id</samp> inside the current build is + contained in a PropertyEvaluator similar to the following code:</p> <pre> public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { @@ -215,22 +194,17 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <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> + <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> + <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> @@ -238,65 +212,50 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <pre>${builddir}=build/classes</pre> - <p>if the property <code>builddir</code> has the - value <samp>build/classes</samp>.</p> + <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> + <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> + <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> + <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 - given by properties, but there - are <a href="https://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="https://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> + <p>This means you can't use easily expand properties whose names are given by 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. With Ant 1.8.0 and + the <a href="https://ant.apache.org/antlib/props/" target="_top">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 <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>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/">props Antlib</a> - provides a few interesting evaluators but there are - also a few built-in ones.</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> + <h3 id="toString">Getting the value of a Reference with <samp>${toString:}</samp></h3> - <p>Any Ant type 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>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>Any Ant type 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>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> @@ -304,49 +263,42 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <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> + <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 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>toString</code> - method will be invoked anyway, for example if - the <samp>${ant.refid:}</samp> is surrounded by other text.</p> + <p>Any Ant type 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>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 String. For example, if - the setter accepts a Resource object as in</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> + <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 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. + 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): + 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"> @@ -357,16 +309,14 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { </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. + <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: + 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>> @@ -377,9 +327,8 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { </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 <q>other-unconditional-stuff</q> but not <q>use-file</q>, as - you might expect, and you can disable the condition from another + Now <code>ant -Dfile.exists=false lots-of-stuff</code> 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> @@ -387,12 +336,10 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <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: + 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"/> |