## 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 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. | 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

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

    <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 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"/>