Subant Task

Since Apache Ant 1.6

Description

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.

subant uses ant internally so many things said in ant's manual page apply here as well.

Use with directories

subant can be used with directory sets to execute a build from different directories. 2 different options are offered:

to run the same build file /somepath/otherpath/mybuild.xml with different base directories, use the genericantfile attribute
if you want to run 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.

Parameters

Attribute	Description	Type	Required
antfile	Build file name, to use in conjunction with directories.	String	No; defaults to build.xml, ignored if `genericantfile` is set
buildpath	Set the buildpath to be used to find sub-projects.	Path	No
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 `basedir`s. 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.	boolean	No; default is false

Parameters as nested elements

any filesystem based resource collection

This includes <fileset>, <dirset> and <filelist> which are the nested resource collections supported prior to Ant 1.7.

dirset (org.apache.tools.ant.types.DirSet)

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!

filelist (org.apache.tools.ant.types.FileList)

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!

fileset (org.apache.tools.ant.types.FileSet)

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!

property (org.apache.tools.ant.taskdefs.Property)

Corresponds to <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.

propertyset (org.apache.tools.ant.types.PropertySet)

Corresponds to <ant>'s nested <propertyset> element.

buildpath (org.apache.tools.ant.types.Path)

Creates a nested build path, and add it to the implicit build path.

buildpathelement (org.apache.tools.ant.types.Path.PathElement)

Creates a nested <buildpathelement>, and add it to the implicit build path.

target (org.apache.tools.ant.taskdefs.Ant.TargetElement)

Since Ant 1.7.

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

Examples

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.

<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. All properties whose name starts with foo are passed, their names are changed to start with bar instead

<subant target="">
    <propertyset>
        <propertyref prefix="toplevel"/>
        <mapper type="glob" from="foo*" to="bar*"/>
    </propertyset>
    <fileset dir="." includes="*/build.xml"/>
</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

<subant target="compile" genericantfile="/opt/project/build1.xml">
    <dirset dir="." includes="projects*"/>
</subant>

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 build files in the modules, maintainable build file (common.xml) and a clear project structure. Additionally the root build file is capable to run the whole build over all modules.

This task performs a clean build for each subproject.

<subant failonerror="false">
    <fileset dir="." includes="**/build.xml" excludes="build.xml"/>
    <target name="clean"/>
    <target name="build"/>
</subant>

Hint: because build files are plain XML, you could generate the master build file from the common build file by using a XSLT transformation:

<xslt in="common.xml"
      out="master.xml"
      style="${ant.home}/etc/common2master.xsl"/>