Subant Task

Subant Task Calls a given target for all defined sub-builds. |

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 Ant 1.6

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