Runs Apache Ant on a supplied buildfile. This can be used to build subprojects. This
task must not be used outside of a target if it invokes the same build file it is part
of.
When the antfile attribute is omitted, the file build.xml in the supplied directory (dir attribute) is used.
If no target attribute is supplied, the default target of the new project is used.
By default, all of the properties of the current project will be available in the new project.
Alternatively, you can set the inheritAll attribute to false
and only
"user" properties (i.e., those passed on the command-line) will be passed to the new
project. In either case, the set of properties passed to the new project will override the
properties that are set in the new project (See also the property
task).
You can also set properties in the new project from the old project by using
nested property tags. These properties are always passed to the new project and any
project created in that project regardless of the setting of inheritAll. This allows you
to parameterize your subprojects.
When more than one nested <property> element would set a property of the same
name, the one declared last will win. This is for backwards compatibility reasons even though it is
different from the way <property> tasks in build files behave.
Properties defined on the command line cannot be overridden by
nested <property> elements. Since Ant 1.8.0, the same is true for
nested structures of <ant> tasks: if a build file A
invokes B via an <ant> task setting a property with a
nested <property> element and B contains an <ant>
tasks invoking C, C will see the value set in A, even
if B used a nested <property> element as well.
References to data types can also be passed to the new project, but by default they are not. If
you set the inheritrefs attribute to true
, all references will be copied, but they
will not override references defined in the new project.
Nested <reference> elements can also be used to copy
references from the calling project to the new project, optionally under a different id.
References taken from nested elements will override existing references that have been defined
outside of targets in the new project—but not those defined inside of targets.
| Attribute | Description | Required |
|---|---|---|
| antfile | the buildfile to use. This file is expected to be a filename relative to the dir attribute given. | No; defaults to build.xml |
| dir | the directory to use as a basedir for the new Ant project
(unless useNativeBasedir is set to true). This will override the basedir setting of the called project. Also serves as the directory to resolve the antfile and output attribute's values (if any). |
No; defaults to the current project's basedir, unless inheritall has
been set to false, in which case it doesn't have a default value |
| target | the target of the new Ant project that should be executed. | No; defaults to the new project's default target |
| output | Filename to write the Ant output to. This is relative to the value of the dir attribute if it has been set or to the basedir of the current project otherwise. | No |
| inheritAll | If true, pass all properties to the new Ant project. |
No; defaults to true |
| inheritRefs | If true, pass all references to the new Ant project. |
No; defaults to false |
| useNativeBasedir | If set to true, the child build will use the same basedir as it would have used when run from the command line (i.e. the basedir one would expect when looking at the child build's buildfile). Since Ant 1.8.0 |
No; defaults to false |
See the description of the property task.
These properties
become equivalent to properties you define on the command line. These are special properties and
they will always get passed down, even through additional <*ant*> tasks
with inheritAll set to false
(see above).
Note that the refid
attribute points to a reference in the calling project, not in the new one.
Used to choose references that shall be copied into the new project, optionally changing their id.
| Attribute | Description | Required |
|---|---|---|
| refid | The id of the reference in the calling project. | Yes |
| torefid | The id of the reference in the new project. | No; defaults to the value of refid |
Since Ant 1.6.
You can specify a set of properties to be copied into the new project with propertysets.
Since Ant 1.6.3.
You can specify multiple targets using nested <target> elements instead of
using the target attribute. These will be executed as if Ant had been invoked with a
single target whose dependencies are the targets so specified, in the order specified.
| Attribute | Description | Required |
|---|---|---|
| name | The name of the called target. | Yes |
If you set useNativeBasedir to true, the basedir of the new project will be
whatever the basedir attribute of the <project> element of the new
project says (or the new project's directory if the there is no basedir
attribute)—no matter what any other attribute of this task says and no matter how deeply
nested into levels of <ant> invocations this task lives.
If you haven't set useNativeBasedir or set it to false
, the following rules
apply:
The basedir value of the new project is affected by the two attributes, dir
and inheritall, as well as the <ant> task's history. The current
behaviour is known to be confusing but cannot be changed without breaking backwards compatibility in
subtle ways.
If the <ant> task is in a "top level" build file, i.e. the project containing
the <ant> task has not itself been invoked as part of a
different <ant> (or <antcall>) task "higher up", the following
table shows the details:
| dir attribute | inheritAll attribute | new project's basedir |
|---|---|---|
| value provided | true |
value of dir attribute |
| value provided | false |
value of dir attribute |
| omitted | true |
basedir of calling project (the one whose build
file contains the <ant> task). |
| omitted | false |
basedir attribute of the <project> element
of the new project |
If on the other hand the <ant> task is already nested into another invocation,
the parent invocation's settings affect the outcome of the basedir value. The current
task's dir attribute will always win, but if the dir attribute has been
omitted an even more complex situation arises:
| parent dir attribute | parent inheritAll attribute | current inheritAll attribute | new project's basedir |
|---|---|---|---|
| value provided | any | any | value of parent's dir attribute |
| omitted | true |
true |
basedir of parent project (the one whose build file called the build file that
contains the current <ant> task). |
| omitted | true |
false |
basedir of parent project (the one whose build file called the build file that
contains the current <ant> task). |
| omitted | false |
true |
basedir of calling project (the one whose build file contains the
current <ant> task). |
| omitted | false |
false |
basedir attribute of the <project> element of the new
project |
If you add even deeper levels of nesting, things get even more complicated and you need to apply the above table recursively.
If the basedir of the outermost build has been specified as a property on the command
line (i.e. -Dbasedir=some-value or a -propertyfile argument) the value
provided will get an even higher priority. For any <ant> task that doesn't
specify a dir attribute, the new project's basedir will be the value specified
on the command line—no matter how deeply nested into layers of build files the task may
be.
The same happens if the basedir is specified as a nested <property>
of an <ant> task. The basedir of build files started at deeper levels
will be set to the specified value of the property element unless the corresponding Ant tasks set
the dir attribute explicitly.
These are different ways of using the task:
<ant antfile="subproject/subbuild.xml" target="compile"/> <ant dir="subproject"/> <ant antfile="subproject/property_based_subbuild.xml"> <property name="param1" value="version 1.x"/> <property file="config/subproject/default.properties"/> </ant> <ant inheritAll="false" antfile="subproject/subbuild.xml"> <property name="output.type" value="html"/> </ant>
These lines invoke the same build file:
<ant antfile="sub1/sub2/build.xml"/> <ant antfile="sub2/build.xml" dir="sub1"/> <ant antfile="build.xml" dir="sub1/sub2"/>
The build file of the calling project defines some <path> elements like
this:
<path id="path1">
...
</path>
<path id="path2">
...
</path>
and the called build file (subbuild.xml) also defines a <path>
with the id path1, but path2 is not defined; then
<ant antfile="subbuild.xml" inheritrefs="true"/>
will not override subbuild's definition of path1, but make the parent's definition of path2 available in the subbuild, whereas
<ant antfile="subbuild.xml"/>
as well as
<ant antfile="subbuild.xml" inheritrefs="false"/>
will neither override path1 nor copy path2, while
<ant antfile="subbuild.xml" inheritrefs="false"> <reference refid="path1"/> </ant>
will override subbuild's definition of path1, and
<ant antfile="subbuild.xml" inheritrefs="false"> <reference refid="path1" torefid="path2"/> </ant>
will copy the parent's definition of path1 into the new project using the id path2.