| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <html lang="en"> |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Subant Task</title> |
| </head> |
| |
| <body> |
| <h2>Subant Task</h2> |
| <p><em>Since Apache Ant 1.6</em></p> |
| <h3 id="description">Description</h3> |
| <p>Calls a given target for all defined sub-builds. This is an extension of Ant for bulk project |
| execution. <strong>This task must not be used outside of a <code>target</code> if it invokes the |
| same build file it is part of.</strong></p> |
| |
| <p><code>subant</code> uses <code>ant</code> internally so many things said |
| in <a href="ant.html"><code>ant</code>'s manual page</a> apply here as well.</p> |
| |
| <h3 id="Use-with-directories">Use with directories</h3> |
| <p><code>subant</code> can be used with directory sets to execute a build from different |
| directories. 2 different options are offered:</p> |
| <ul> |
| <li>to run the same build file <samp>/somepath/otherpath/mybuild.xml</samp> with different base |
| directories, use the <var>genericantfile</var> attribute</li> |
| <li>if you want to |
| run <samp>directory1/mybuild.xml</samp>, <samp>directory2/mybuild.xml</samp>, <samp>...</samp>, |
| use the <var>antfile</var> attribute. The <code>subant</code> task does not set the base |
| directory for you in this case, because you can specify it in each build file.</li> |
| </ul> |
| |
| <h3 id="attributes">Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Type</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>antfile</td> |
| <td>Build file name, to use in conjunction with directories.</td> |
| <td>String</td> |
| <td>No; defaults to <q>build.xml</q>, ignored if <var>genericantfile</var> is set</td> |
| </tr> |
| <tr> |
| <td>buildpath</td> |
| <td>Set the buildpath to be used to find sub-projects.</td> |
| <td>Path</td> |
| <td rowspan="8">No</td> |
| </tr> |
| <tr> |
| <td>buildpathref</td> |
| <td>Buildpath to use, by reference.</td> |
| <td class="left">Reference</td> |
| </tr> |
| <tr> |
| <td>failonerror</td> |
| <td>Sets whether to fail with a build exception on error, or go on.</td> |
| <td class="left">boolean</td> |
| </tr> |
| <tr> |
| <td>genericantfile</td> |
| <td>Build file path, to use in conjunction with directories.<br/> Use <var>genericantfile</var>, |
| in order to run the same build file with different <var>basedir</var>s.<br/> If this attribute |
| is set, <var>antfile</var> is ignored.</td> |
| <td class="left">File</td> |
| </tr> |
| <tr> |
| <td>inheritall</td> |
| <td>Corresponds to <code><ant></code>'s <var>inheritall</var> attribute but defaults |
| to <q>false</q> in this task.</td> |
| <td class="left">boolean</td> |
| </tr> |
| <tr> |
| <td>inheritrefs</td> |
| <td>Corresponds to <code><ant></code>'s <var>inheritrefs</var> attribute.</td> |
| <td class="left">boolean</td> |
| </tr> |
| <tr> |
| <td>output</td> |
| <td>Corresponds to <code><ant></code>'s <var>output</var> attribute.</td> |
| <td class="left">String</td> |
| </tr> |
| <tr> |
| <td>target</td> |
| <td> </td> |
| <td class="left">String</td> |
| </tr> |
| <tr> |
| <td>verbose</td> |
| <td>Enable/disable log messages showing when each sub-build path is entered/exited.</td> |
| <td>boolean</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| </table> |
| <h3 id="elements">Parameters as nested elements</h3> |
| <h4>any filesystem based <a href="../Types/resources.html#collection">resource collection</a></h4> |
| <p>This includes <code><fileset></code>, <code><dirset></code> |
| and <code><filelist></code> which are the nested resource collections supported prior to Ant |
| 1.7.</p> |
| <h4><strong>dirset</strong> (org.apache.tools.ant.types.DirSet)</h4> |
| Adds a directory set to the implicit build path. |
| <p><em>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!</em></p> |
| <h4><strong>filelist</strong> (org.apache.tools.ant.types.FileList)</h4> |
| <p>Adds an ordered file list to the implicit build path.</p> |
| <p><em>Note that contrary to file and directory sets, file lists can reference non-existent files or |
| directories!</em></p> |
| <h4><strong>fileset</strong> (org.apache.tools.ant.types.FileSet)</h4> |
| <p>Adds a file set to the implicit build path.</p> |
| <p><em>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!</em></p> |
| <h4><strong>property</strong> (org.apache.tools.ant.taskdefs.Property)</h4> |
| <p>Corresponds to <code><ant></code>'s nested <code><property></code> element.</p> |
| <p>When more than one nested <code><property></code> 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 <code><property></code> tasks in build files behave.</p> |
| <h4><strong>propertyset</strong> (org.apache.tools.ant.types.PropertySet)</h4> |
| <p>Corresponds to <code><ant></code>'s nested <code><propertyset></code> element.</p> |
| <h4><strong>buildpath</strong> (org.apache.tools.ant.types.Path)</h4> |
| <p>Creates a nested build path, and add it to the implicit build path.</p> |
| <h4><strong>buildpathelement</strong> (org.apache.tools.ant.types.Path.PathElement)</h4> |
| <p>Creates a nested <code><buildpathelement></code>, and add it to the implicit build |
| path.</p> |
| <h4><strong>target</strong> (org.apache.tools.ant.taskdefs.Ant.TargetElement)</h4> |
| <p><em>Since Ant 1.7</em>.</p> |
| <p>You can specify multiple targets using nested <code><target></code> 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.</p> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>The name of the called target.</td> |
| <td>Yes</td> |
| </tr> |
| </table> |
| |
| <h3 id="examples">Examples</h3> |
| |
| <p>This snippet build file will run <kbd>ant</kbd> in each subdirectory of the project directory, |
| where a file called <samp>build.xml</samp> can be found. The property <code>build.dir</code> will |
| have the value <q>subant1.build</q> in the Ant projects called by <code>subant</code>.</p> |
| |
| <pre> |
| <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></pre> |
| |
| <p>This snippet build file will run <kbd>ant</kbd> in each subdirectory of the project directory, |
| where a file called <samp>build.xml</samp> can be found. All properties whose name starts |
| with <q>foo</q> are passed, their names are changed to start with <q>bar</q> instead</p> |
| |
| <pre> |
| <subant target=""> |
| <propertyset> |
| <propertyref prefix="toplevel"/> |
| <mapper type="glob" from="foo*" to="bar*"/> |
| </propertyset> |
| <fileset dir="." includes="*/build.xml"/> |
| </subant></pre> |
| |
| <p>Assuming the subdirs of the project dir are |
| called <samp>projects1</samp>, <samp>projects2</samp>, <samp>projects3</samp>, this snippet will |
| execute the <q>compile</q> target of <samp>/opt/project/build1.xml</samp>, setting |
| the <var>basedir</var> to <q>projects1</q>, <q>projects2</q>, <q>projects3</q></p> |
| |
| <pre> |
| <subant target="compile" genericantfile="/opt/project/build1.xml"> |
| <dirset dir="." includes="projects*"/> |
| </subant></pre> |
| |
| <p>Now a little more complex—but useful—scenario. Assume that we have a directory |
| structure like this:</p> |
| |
| <pre> |
| root |
| | common.xml |
| | build.xml |
| | |
| +-- modules |
| +-- modA |
| | +-- src |
| +-- modB |
| +-- src |
| |
| <b>common.xml:</b><br/> |
| <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> |
| |
| <b>build.xml:</b><br/> |
| <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> |
| |
| <b>modules/modA/build.xml:</b><br/> |
| <project name="modA"> |
| <import file="../../common.xml"/> |
| </project></pre> |
| |
| <p>This results in very small build files in the modules, maintainable build file |
| (<samp>common.xml</samp>) and a clear project structure. Additionally the root build file is capable |
| to run the whole build over all modules.</p> |
| |
| <p>This task performs a <q>clean build</q> for each subproject.</p> |
| |
| <pre> |
| <subant failonerror="false"> |
| <fileset dir="." includes="**/build.xml" excludes="build.xml"/> |
| <target name="clean"/> |
| <target name="build"/> |
| </subant></pre> |
| |
| <p><strong>Hint</strong>: because build files are plain XML, you could generate the master build |
| file from the common build file by using a XSLT transformation:</p> |
| |
| <pre> |
| <xslt in="common.xml" |
| out="master.xml" |
| style="${ant.home}/etc/common2master.xsl"/></pre> |
| </body> |
| </html> |