diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/subant.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/subant.html | 608 |
1 files changed, 608 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/subant.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/subant.html new file mode 100644 index 00000000..424bb67e --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/subant.html @@ -0,0 +1,608 @@ +<!-- + 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 + + http://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> +<head> + <meta http-equiv="Content-Language" content="en-us"> + <title>Subant Task</title> +</head> + +<body bgcolor="#ffffff" text="#000000" link="#525D76" + alink="#525D76" vlink="#525D76"> + +<table border="0" width="100%" cellspacing="4"> + + <!-- PAGE HEADER --> + <tr> + <td> + <table border="0" width="100%"><tr> + <td valign="bottom"> + <font size="+3" face="arial,helvetica,sanserif"><strong>Subant Task</strong></font> + <br><font face="arial,helvetica,sanserif">Calls a given target for all defined sub-builds.</font> + </td> + <td> + <!-- PROJECT LOGO --> + <a href="http://ant.apache.org/"> + <img src="../images/ant_logo_large.gif" align="right" alt="Apache Ant" border="0"> + </a> + </td> + </tr></table> + </td> + </tr> + + <!-- START RIGHT SIDE MAIN BODY --> + <tr> + <td valign="top" align="left"> + + <!-- Applying task/description --> + <!-- Start Description --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + + <tr><td bgcolor="#525D76"> + <font color="#ffffff" face="arial,helvetica.sanserif"> + <a name="description"> + <strong>Description</strong></a></font> + </td></tr> + + <tr><td><blockquote> +<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><em>Since Apache Ant 1.6</em></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> + + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <!-- Subsection heading --> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif"> + <a name="Use with directories"> + <strong>Use with directories</strong></a></font> + </td></tr> + <!-- Subsection body --> + <tr><td> + <p> + subant 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 <code>/somepath/otherpath/mybuild.xml</code> + with different base directories, use the genericantfile attribute + </li> + <li>if you want to run <code>directory1/mybuild.xml</code>, <code>directory2/mybuild.xml</code>, <code>....</code>, + 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. + </li> + </ul> + + </td></tr> + </table> + + </blockquote></td></tr> + + </table> + <!-- End Description --> + + <!-- Ignore --> + + + + <!-- Start Attributes --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#525D76"> + <font color="#ffffff" face="arial,helvetica.sanserif"> + <a name="attributes"> + <strong>Parameters</strong></a></font> + </td></tr> + <tr><td><blockquote> + <table> + <tr> + <td bgcolor="#cccccc" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"><b>Attribute</b></font> + </td> + <td bgcolor="#cccccc" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"><b>Description</b></font> + </td> + <td bgcolor="#cccccc" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"><b>Type</b></font> + </td> + <td bgcolor="#cccccc" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"><b>Requirement</b></font> + </td> + </tr> + <!-- Attribute Group --> + + <!-- Attribute Group --> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">antfile</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Build file name, to use in conjunction with directories.<br> Defaults to "build.xml".<br> If <code>genericantfile</code> is set, this attribute is ignored.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">String</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left" rowspan="10"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Optional</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">buildpath</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Set the buildpath to be used to find sub-projects.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Path</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">buildpathref</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Buildpath to use, by reference.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Reference</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">failonerror</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Sets whether to fail with a build exception on error, or go on.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">boolean</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">genericantfile</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Build file path, to use in conjunction with directories.<br> Use <code>genericantfile</code>, in order to run the same build file with different basedirs.<br> If this attribute is set, <code>antfile</code> is ignored.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">File</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">inheritall</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" + face="arial,helvetica,sanserif">Corresponds to + <code><ant></code>'s + <code>inheritall</code> attribute but defaults + to false in this task..</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">boolean</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">inheritrefs</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Corresponds to <code><ant></code>'s <code>inheritrefs</code> attribute.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">boolean</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">output</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">Corresponds to <code><ant></code>'s <code>output</code> attribute.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">String</font> + </td> + </tr> + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">target</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"></font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">String</font> + </td> + </tr> + + <!-- Attribute --> + <tr> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">verbose</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif"> + Enable/ disable log messages showing when each sub-build path is entered/ exited. + The default value is false.</font> + </td> + <td bgcolor="#eeeeee" valign="top" align="left"> + <font color="#000000" size="-1" face="arial,helvetica,sanserif">boolean</font> + </td> + </tr> + + + </table> + </blockquote></td></tr> + + </table> + <!-- End Attributes --> + + <!-- Start Elements --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + + <tr><td bgcolor="#525D76"> + <font color="#ffffff" face="arial,helvetica.sanserif"> + <a name="elements"> + <strong>Parameters as nested elements</strong></a></font> + </td></tr> + + <tr><td><blockquote> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>any filesystem based <a href="../Types/resources.html#collection">resource collection</a></strong></font> + </td></tr> + <tr><td><blockquote> + This includes <code><fileset></code>, + <code><dirset></code> and <code><filelist></code> + which are the nested resource collections supported prior + to Ant 1.7. + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>dirset</strong> (org.apache.tools.ant.types.DirSet)</font> + </td></tr> + <tr><td><blockquote> + 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> + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>filelist</strong> (org.apache.tools.ant.types.FileList)</font> + </td></tr> + <tr><td><blockquote> + Adds an ordered file list to the implicit build path. <p> <em>Note that contrary to file and directory sets, file lists can reference non-existent files or directories!</em> + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>fileset</strong> (org.apache.tools.ant.types.FileSet)</font> + </td></tr> + <tr><td><blockquote> + Adds a file 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> + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>property</strong> (org.apache.tools.ant.taskdefs.Property)</font> + </td></tr> + <tr><td><blockquote> + Corresponds to <code><ant></code>'s nested <code><property></code> element. + +<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> + + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>propertyset</strong> (org.apache.tools.ant.types.PropertySet)</font> + </td></tr> + <tr><td><blockquote> + Corresponds to <code><ant></code>'s nested <code><propertyset></code> element. + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>buildpath</strong> (org.apache.tools.ant.types.Path)</font> + </td></tr> + <tr><td><blockquote> + Creates a nested build path, and add it to the implicit build path. + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>buildpathelement</strong> (org.apache.tools.ant.types.Path.PathElement)</font> + </td></tr> + <tr><td><blockquote> + Creates a nested <code><buildpathelement></code>, and add it to the implicit build path. + <!-- Ignore --> + <!-- Ignore --> + + </blockquote></td></tr> + </table> + <!-- End Element --> + + + + +<!-- manually written --> + <!-- Start Element --> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + <tr><td bgcolor="#828DA6"> + <font color="#ffffff" face="arial,helvetica.sanserif" size="-1"> + <strong>target</strong> (org.apache.tools.ant.taskdefs.Ant.TargetElement)</font> + </td></tr> + <tr><td><blockquote> + 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. + <!-- Ignore --> + <!-- Ignore --> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the called target.</td> + <td valign="top" align="center">Yes</td> + </tr> + </table> + <p><em>since Ant 1.7</em>.</p> + </blockquote></td></tr> + </table> + <!-- End Element --> +<!-- manually written end --> + + </blockquote></td></tr> + + </table> + <!-- End Elements --> + + + + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tr><td> </td></tr> + + <tr><td bgcolor="#525D76"> + <font color="#ffffff" face="arial,helvetica.sanserif"> + <a name="examples"> + <strong>Examples</strong></a></font> + </td></tr> + + <tr><td><blockquote style=""> + <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 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. + </p> +<pre> + <subant target=""> + <propertyset> + <propertyref prefix="toplevel"/> + <mapper type="glob" from="foo*" to="bar*"/> + </propertyset> + <fileset dir="." includes="*/build.xml"/> + </subant> + </pre> +<p> + 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 + </p> +<pre> + <subant target="compile" genericantfile="/opt/project/build1.xml"> + <dirset dir="." includes="projects*"/> + </subant> + </pre> +<p> + 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 + </p> + + <!-- manually written --> + <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 + + <u><b>common.xml:</b></u><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> + + <u><b>build.xml:</b></u><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> + + <u><b>modules/modA/build.xml:</b></u><br> + <project name="modA"> + <import file="../../common.xml"/> + </project> + </pre> + + <p>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. + </p> + + <pre> + <subant failonerror="false"> + <fileset dir="." includes="**/build.xml" excludes="build.xml"/> + <target name="clean"/> + <target name="build"/> + </subant> + </pre> + + <p>Does a "clean build" for each subproject.</p> + <p><b>Hint:</b> because buildfiles are plain xml, you could generate the + masterbuildfile from the common buildfile by using a XSLT transformation: + </p> + + <pre> + <xslt in="common.xml" + out="master.xml" + style="${ant.home}/etc/common2master.xsl" + /> + </pre> + + <!-- manually written --> + + </blockquote></td></tr> + + </table> + + </td> + </tr> + <!-- END RIGHT SIDE MAIN BODY --> + +</table> + +</body> +</html> |