Calls a given target for all defined sub-builds.
This is an extension
of ant for bulk project execution.
This task must not be used outside of a
target
if it invokes the same build file it is
part of.
Since Ant 1.6
Use with directoriessubant can be used with directory sets to execute a build from different directories. 2 different options are offered :
/somepath/otherpath/mybuild.xml
with different base directories, use the genericantfile attribute
directory1/mybuild.xml
, directory2/mybuild.xml
, ....
,
use the antfile attribute. The subant task does not set the base directory for you in this case, because you can specify it in each build file.
Attribute | Description | Type | Requirement |
antfile |
Build file name, to use in conjunction with directories. Defaults to "build.xml". If genericantfile is set, this attribute is ignored.
|
String | Optional |
buildpath | Set the buildpath to be used to find sub-projects. | Path | |
buildpathref | Buildpath to use, by reference. | Reference | |
failonerror | Sets whether to fail with a build exception on error, or go on. | boolean | |
genericantfile |
Build file path, to use in conjunction with directories. Use genericantfile , in order to run the same build file with different basedirs.If this attribute is set, antfile is ignored.
|
File | |
inheritall |
Corresponds to
<ant> 's
inheritall attribute but defaults
to false in this task..
|
boolean | |
inheritrefs |
Corresponds to <ant> 's inheritrefs attribute.
|
boolean | |
output |
Corresponds to <ant> 's output attribute.
|
String | |
target | String | ||
verbose | Enable/ disable log messages showing when each sub-build path is entered/ exited. The default value is false. | boolean |
This includes <fileset>
,
<dirset>
and <filelist>
which are the nested resource collections supported prior
to Ant 1.7.
Adds a directory set to the implicit build path.
Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!
Adds an ordered file list to the implicit build path.
Note that contrary to file and directory sets, file lists can reference non-existent files or directories!
Adds a file set to the implicit build path.
Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!
Corresponds to <ant>
's nested <property>
element.
Corresponds to <ant>
's nested <propertyset>
element.
Creates a nested build path, and add it to the implicit build path.
Creates a nested <buildpathelement>
, and add it to the implicit build path.
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 |
since Ant 1.7.
<project name="subant" default="subant1"> <property name="build.dir" value="subant.build"/> <target name="subant1"> <subant target=""> <property name="build.dir" value="subant1.build"/> <property name="not.overloaded" value="not.overloaded"/> <fileset dir="." includes="*/build.xml"/> </subant> </target> </project>
this snippet build file will run ant in each subdirectory of the project directory, where a file called build.xml can be found. The property build.dir will have the value subant1.build in the ant projects called by subant.
<subant target=""> <propertyset> <propertyref prefix="toplevel"/> <mapper type="glob" from="foo*" to="bar*"/> </propertyset> <fileset dir="." includes="*/build.xml"/> </subant>
this snippet build file will run ant in each subdirectory of the project directory, where a file called build.xml can be found. All properties whose name starts with "foo" are passed, their names are changed to start with "bar" instead
<subant target="compile" genericantfile="/opt/project/build1.xml"> <dirset dir="." includes="projects*"/> </subant>
assuming the subdirs of the project dir are called projects1, projects2, projects3 this snippet will execute the compile target of /opt/project/build1.xml, setting the basedir to projects1, projects2, projects3
Now a little more complex - but useful - scenario. Assume that we have a directory structure like this:
root | common.xml | build.xml | +-- modules +-- modA | +-- src +-- modB +-- src common.xml:
<project> <property name="src.dir" value="src"/> <property name="build.dir" value="build"/> <property name="classes.dir" value="${build.dir}/classes"/> <target name="compile"> <mkdir dir="${classes.dir}"/> <javac srcdir="${src.dir}" destdir="${classes.dir}"/> </target> <!-- more targets --> </project> build.xml:
<project> <macrodef name="iterate"> <attribute name="target"/> <sequential> <subant target="@{target}"> <fileset dir="modules" includes="*/build.xml"/> </subant> </sequential> </macrodef> <target name="compile"> <iterate target="compile"/> </target> <!-- more targets --> </project> modules/modA/build.xml:
<project name="modA"> <import file="../../common.xml"/> </project>
This results in very small buildfiles in the modules, maintainable buildfile (common.xml) and a clear project structure. Additionally the root buildfile is capable to run the whole build over all modules.
<subant failonerror="false"> <fileset dir="." includes="**/build.xml" excludes="build.xml"/> <target name="clean"/> <target name="build"/> </subant>
Does a "clean build" for each subproject.
Hint: because buildfiles are plain xml, you could generate the masterbuildfile from the common buildfile by using a XSLT transformation:
<xslt in="common.xml" out="master.xml" style="${ant.home}/etc/common2master.xsl" />