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 Apache Ant 1.6
subant
uses ant
internally so many things
said in ant
's manual page apply
here as well.
subant 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 |
<fileset>
,
<dirset>
and <filelist>
which are the nested resource collections supported prior
to Ant 1.7.
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!
Note that contrary to file and directory sets, file lists can reference non-existent files or directories!
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!
<ant>
's nested <property>
element.
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 so it is
different from the way <property>
tasks in build
files behave.
<ant>
's nested <propertyset>
element.
<buildpathelement>
, and add it to the implicit build path.
<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"/>