## Subant Task

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

Since Apache Ant 1.6

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

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

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.

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