2009-10-21 20:39:57 +00:00
<!--
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 >
2018-02-28 07:58:59 +01:00
< p > Properties are key-value pairs where Apache Ant tries to
2009-10-21 20:39:57 +00:00
expand < code > ${key}< / code > to < code > value< / code > at runtime.< / p >
< p > There are many tasks that can set properties, the most common one
2010-05-26 20:33:51 +00:00
is the < a href = "Tasks/property.html" > property< / a > task. In
2009-10-21 20:39:57 +00:00
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
2018-02-28 07:58:59 +01:00
subsequently— it is not possible to set a property in a child
2009-10-21 20:39:57 +00:00
build process created via
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
task.< / p >
2018-02-08 22:52:33 +01:00
< h2 id = "built-in-props" > Built-in Properties< / h2 >
2009-10-21 20:39:57 +00:00
< p > Ant provides access to all system properties as if they had been
defined using a < code > < property> < / code > task. For
2018-02-28 07:58:59 +01:00
example, < samp > ${os.name}< / samp > expands to the name of the
2009-10-21 20:39:57 +00:00
operating system.< / p >
2018-02-28 07:58:59 +01:00
< 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 > .
2009-10-21 20:39:57 +00:00
< / p >
< p > In addition, Ant has some built-in properties:< / p >
2018-02-28 07:58:59 +01:00
< 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 < 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 >
< 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 >
< 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 >
2009-10-21 20:39:57 +00:00
< p > There is also another property, but this is set by the launcher
script and therefore maybe not set inside IDEs:< / p >
2018-02-28 07:58:59 +01:00
< dl >
< dt > < code > ant.home< / code > < / dt >
< dd > home directory of Ant< / dd >
< / dl >
2009-10-21 20:39:57 +00:00
< 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 >
2018-02-28 07:58:59 +01:00
< 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 >
2009-10-21 20:39:57 +00:00
2018-02-08 22:52:33 +01:00
< h1 id = "propertyHelper" > PropertyHelpers< / h1 >
2009-10-21 20:39:57 +00:00
2018-02-28 07:58:59 +01:00
< 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
2009-10-21 20:39:57 +00:00
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
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
< 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
2018-02-28 07:58:59 +01:00
first place (the default extracts < samp > foo< / samp >
from < samp > ${foo}< / samp > ).
2009-10-21 20:39:57 +00:00
< p > This is the interface you'd implement if you wanted to invent
2018-02-28 07:58:59 +01:00
your own property syntax— or allow nested property expansions
2009-10-21 20:39:57 +00:00
since the default implementation doesn't balance braces
2014-05-31 11:57:32 +02:00
(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 >
2018-02-28 07:58:59 +01:00
in the < samp > props< / samp > Antlib< / a > for an example).< / p >
2009-10-21 20:39:57 +00:00
< / li >
< li > < code > org.apache.tools.ant.PropertyHelper$PropertyEvaluator< / code >
2018-02-28 07:58:59 +01:00
is used to expand < samp > ${some-string}< / samp > into
2009-10-21 20:39:57 +00:00
an < code > Object< / code > .
< p > This is the interface you'd implement if you want to provide
2018-02-28 07:58:59 +01:00
your own storage independent of Ant's project instance— the
2009-10-21 20:39:57 +00:00
interface represents the reading end. An example for this
would
be < code > org.apache.tools.ant.property.LocalProperties< / code >
which implements storage
2010-05-26 20:33:51 +00:00
for < a href = "Tasks/local.html" > local properties< / a > .< / p >
2009-10-21 20:39:57 +00:00
< 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
2018-02-28 07:58:59 +01:00
reference < samp > foo< / samp > and invoking < code > toString()< / code > on it
2009-10-21 20:39:57 +00:00
(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
2018-02-28 07:58:59 +01:00
your own storage independent of Ant's project instance— the
2009-10-21 20:39:57 +00:00
interface represents the reading end. An example for this
would
be < code > org.apache.tools.ant.property.LocalProperties< / code >
which implements storage
2010-05-26 20:33:51 +00:00
for < a href = "Tasks/local.html" > local properties< / a > .< / p >
2009-10-21 20:39:57 +00:00
< / 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;
}
2018-02-28 07:58:59 +01:00
}< / pre >
2009-10-21 20:39:57 +00:00
2018-02-28 07:58:59 +01:00
< p > The logic that replaces < samp > ${toString:< i > some-id< / i > }< / samp > with the
2009-10-21 20:39:57 +00:00
stringified representation of the object with
2018-02-28 07:58:59 +01:00
< var > id< / var > < samp > some-id< / samp > inside the current build is contained in a
2009-10-21 20:39:57 +00:00
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) {
2009-11-05 00:45:05 +00:00
o = propertyHelper.getProject().getReference(
property.substring(prefix.length()));
2009-10-21 20:39:57 +00:00
}
return o == null ? null : o.toString();
}
2018-02-28 07:58:59 +01:00
}< / pre >
2009-10-21 20:39:57 +00:00
< h1 > Property Expansion< / h1 >
2018-02-28 07:58:59 +01:00
< p > When Ant encounters a construct < samp > ${some-text}< / samp > the
2009-10-21 20:39:57 +00:00
exact parsing semantics are subject to the configured property
helper delegates.< / p >
< h2 > < code > $$< / code > Expansion< / h2 >
2018-02-28 07:58:59 +01:00
< 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
2009-10-21 20:39:57 +00:00
diagnostic output like in< / p >
2018-02-28 07:58:59 +01:00
< pre > < echo> $${builddir}=${builddir}< /echo> < / pre >
2009-10-21 20:39:57 +00:00
2018-02-28 07:58:59 +01:00
< p > which will echo this message:< / p >
2009-10-21 20:39:57 +00:00
2018-02-28 07:58:59 +01:00
< pre > ${builddir}=build/classes< / pre >
2009-10-21 20:39:57 +00:00
< p > if the property < code > builddir< / code > has the
2018-02-28 07:58:59 +01:00
value < samp > build/classes< / samp > .< / p >
2018-02-08 22:52:33 +01:00
2009-10-21 20:39:57 +00:00
< p > In order to maintain backward compatibility with older Ant
2018-02-28 07:58:59 +01:00
releases, a single < q > $< / q > character encountered apart from a
2009-10-21 20:39:57 +00:00
property-like construct (including a matched pair of french
2018-02-28 07:58:59 +01:00
braces) will be interpreted literally; that is, as < q > $< / q > . The
2009-10-21 20:39:57 +00:00
"correct" way to specify this literal character, however, is by
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
< h2 > Nesting of Braces< / h2 >
2009-10-21 22:15:27 +00:00
< p > In its default configuration Ant will not try to balance braces
2009-10-21 20:39:57 +00:00
in property expansions, it will only consume the text up to the
first closing brace when creating a property name. I.e. when
2018-02-28 07:58:59 +01:00
expanding something like < samp > ${a${b}}< / samp > it will be
2009-10-21 20:39:57 +00:00
translated into two parts:< / p >
< ol >
2018-02-28 07:58:59 +01:00
< li > the expansion of property < samp > a${b< / samp > — likely nothing
2009-10-21 20:39:57 +00:00
useful.< / li >
2018-02-28 07:58:59 +01:00
< li > the literal text < samp > }< / samp > resulting from the second
2009-10-21 20:39:57 +00:00
closing brace< / li >
< / ol >
< p > This means you can't use easily expand properties whose names are
given by properties, but there
2018-02-28 07:58:59 +01:00
are < a href = "https://ant.apache.org/faq.html#propertyvalue-as-name-for-property" > some
2009-10-21 20:39:57 +00:00
workarounds< / a > for older versions of Ant. With Ant 1.8.0 and the
2018-02-28 07:58:59 +01:00
< a href = "https://ant.apache.org/antlib/props/" > the props Antlib< / a >
2009-10-21 20:39:57 +00:00
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 >
2018-02-28 07:58:59 +01:00
< p > In its most simple form < samp > ${key}< / samp > is supposed to look
2009-10-21 20:39:57 +00:00
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 >
2018-02-28 07:58:59 +01:00
< 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 >
2009-10-21 20:39:57 +00:00
2018-02-08 22:52:33 +01:00
< h3 id = "toString" > Getting the value of a Reference with
2018-02-28 07:58:59 +01:00
< samp > ${toString:}< / samp > < / h3 >
2009-10-21 20:39:57 +00:00
< p > Any Ant type which has been declared with a reference can also
2018-02-28 07:58:59 +01:00
its string value extracted by using the < samp > ${toString:}< / samp >
2009-10-21 20:39:57 +00:00
operation, with the name of the reference listed after
the < code > toString:< / code > text. The < code > toString()< / code >
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
< p > For example, here is how to get a listing of the files in a fileset,< p >
< pre >
2018-02-28 07:58:59 +01:00
< fileset id=" sourcefiles" dir=" src" includes=" **/*.java" />
< echo> sourcefiles = ${toString:sourcefiles} < /echo> < / pre >
2009-10-21 20:39:57 +00:00
< p > There is no guarantee that external types provide meaningful
information in such a situation< / p >
2018-02-28 07:58:59 +01:00
< h3 id = "ant.refid" > Getting the value of a Reference with < samp > ${ant.refid:}< / samp > < / h3 >
2009-10-21 20:39:57 +00:00
< p > Any Ant type which has been declared with a reference can also be
2018-02-28 07:58:59 +01:00
used as a property by using the < samp > ${ant.refid:}< / samp >
2009-10-21 20:39:57 +00:00
operation, with the name of the reference listed after
the < code > ant.refid:< / code > text. The difference between this
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
< p > This syntax is most useful when using a task with attribute
2018-02-28 07:58:59 +01:00
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 >
2009-10-21 20:39:57 +00:00
< p > then the syntax can be used to pass in resource subclasses
2010-02-25 04:29:54 +00:00
previously defined as references like< / p >
2009-10-21 20:39:57 +00:00
< pre >
2018-02-28 07:58:59 +01:00
< url url="http://ant.apache.org/" id="anturl"/>
< my:task attr="${ant.refid:anturl}"/> < / pre >
2009-10-21 20:39:57 +00:00
2018-02-08 22:52:33 +01:00
< h2 id = "if+unless" > If/Unless Attributes< / h2 >
2009-11-05 00:45:05 +00:00
< p >
2018-02-28 07:58:59 +01:00
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.
2009-11-05 00:45:05 +00:00
< / p >
< p >
2018-02-28 07:58:59 +01:00
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):
2009-11-05 00:45:05 +00:00
< / p >
< pre >
2018-02-28 07:58:59 +01:00
< 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... -->
2009-11-05 00:45:05 +00:00
< /target>
2018-02-28 07:58:59 +01:00
< target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/> < / pre >
2009-11-05 00:45:05 +00:00
< p >
2018-02-28 07:58:59 +01:00
< 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.
2009-11-05 00:45:05 +00:00
< / p >
< p >
2018-02-28 07:58:59 +01:00
Compared to the older style, this gives you additional
flexibility, because you can override the condition from the
command line or parent scripts:
2009-11-05 00:45:05 +00:00
< / p >
< pre >
2018-02-28 07:58:59 +01:00
< target name="-check-use-file" < strong > unless="file.exists"< / strong > >
< available property="file.exists" file="some-file"/>
2009-11-05 00:45:05 +00:00
< /target>
2018-02-28 07:58:59 +01:00
< target name="use-file" depends="-check-use-file" < strong > if="${file.exists}"< / strong > >
< !-- do something requiring that file... -->
2009-11-05 00:45:05 +00:00
< /target>
2018-02-28 07:58:59 +01:00
< target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/> < / pre >
2009-11-05 00:45:05 +00:00
< p >
2018-02-28 07:58:59 +01:00
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:
2009-11-05 00:45:05 +00:00
< / p >
< pre >
2018-02-28 07:58:59 +01:00
< antcall target="lots-of-stuff">
< param name="file.exists" value="false"/>
< /antcall> < / pre >
2009-11-05 00:45:05 +00:00
< p >
2018-02-28 07:58:59 +01:00
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:
2009-11-05 00:45:05 +00:00
< / p >
< pre >
2018-02-28 07:58:59 +01:00
< property file="my-prefs.properties"/>
< target name="print-message" < strong > unless="${skip.printing.message}"< / strong > >
2009-11-05 00:45:05 +00:00
< echo>hello!< /echo>
2018-02-28 07:58:59 +01:00
< /target> < / pre >
2009-11-05 00:45:05 +00:00
2009-10-21 20:39:57 +00:00
< / body >
2018-02-08 22:52:33 +01:00
< / html >
