| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant Task</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="ant">Ant</a></h2> |
| <h3>Description</h3> |
| <p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p> |
| <p>When the <i>antfile</i> attribute is omitted, the file "build.xml" |
| in the supplied directory (<i>dir</i> attribute) is used.</p> |
| <p>If no target attribute is supplied, the default target of the new project is |
| used.</p> |
| <p>By default, all of the properties of the current project will be |
| available in the new project. Alternatively, you can |
| set the <i>inheritAll</i> attribute to <code>false</code> and only |
| "user" properties (i.e., those passed on the command-line) |
| will be passed to the new project. In either case, the set of |
| properties passed to the new project will override the properties that |
| are set in the new project (See also the <a href="property.html">property task</a>).</p> |
| <p>You can also set properties in the new project from the old project by |
| using nested property tags. These properties are always passed regardless of the |
| setting of <i>inheritAll</i>. This allows you to parameterize your subprojects.</p> |
| |
| <p>References to data types can also be passed to the new project, but |
| by default they are not. If you set the inheritrefs attribute to |
| true, all references will be copied, but they will not override |
| references defined in the new project.</p> |
| |
| <p>Nested <a href="#reference"><i><reference></i></a> elements |
| can also be used to copy references from the calling project to the |
| new project, optionally under a different id. References taken from |
| nested elements will override existing references in the new |
| project.</p> |
| |
| <h3>Parameters</h3> |
| <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">antfile</td> |
| <td valign="top">the buildfile to use. Defaults to |
| "build.xml". This file is expected to be a filename |
| relative to the dir attribute given.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">dir</td> |
| <td valign="top">the directory to use as a basedir for the new Ant project. |
| Defaults to the current project's basedir, unless |
| inheritall has been set to false, in which case it doesn't |
| have a default value. This will override the basedir |
| setting of the called project.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">target</td> |
| <td valign="top">the target of the new Ant project that should be executed. |
| Defaults to the new project's default target.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">output</td> |
| <td valign="top">Filename to write the ant output to. This is |
| relative to the value of the dir attribute if it has been set or |
| to the base directory of the current project otherwise. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">inheritAll</td> |
| <td valign="top">If <code>true</code>, pass all properties to the |
| new Ant project. Defaults to <code>true</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">inheritRefs</td> |
| <td valign="top">If <code>true</code>, pass all references to the |
| new Ant project. Defaults to <code>false</code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> <h4>property</h4> |
| <p>See the description of the <a href="property.html">property |
| task</a>. Note that the <code>refid</code> attribute points to a |
| reference in the calling project, not in the new one.</p> |
| |
| <h4><a name="reference">reference</a></h4> |
| <p>Used to chose references that shall be copied into the new project, |
| optionally changing their id.</p> |
| |
| <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">refid</td> |
| <td valign="top">The id of the reference in the calling project.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">torefid</td> |
| <td valign="top">The id of the reference in the new project.</td> |
| <td valign="top" align="center">No, defaults to the value of refid.</td> |
| </tr> |
| </table> |
| |
| <h3>Basedir of the new project</h3> |
| |
| <p>The basedir value of the new project is affected by the two |
| attributes dir and inheritall, see the following table for |
| details:</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>dir attribute</b></td> |
| <td valign="top"><b>inheritAll attribute</b></td> |
| <td valign="top"><b>new project's basedir</b></td> |
| </tr> |
| <tr> |
| <td valign="top">value provided</td> |
| <td valign="top">true</td> |
| <td valign="top">value of dir attribute</td> |
| </tr> |
| <tr> |
| <td valign="top">value provided</td> |
| <td valign="top">false</td> |
| <td valign="top">value of dir attribute</td> |
| </tr> |
| <tr> |
| <td valign="top">omitted</td> |
| <td valign="top">true</td> |
| <td valign="top">basedir of calling project (the one whose build |
| file contains the <ant> task).</td> |
| </tr> |
| <tr> |
| <td valign="top">omitted</td> |
| <td valign="top">false</td> |
| <td valign="top">basedir attribute of the <project> element |
| of the new project</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| <pre> |
| <ant antfile="subproject/subbuild.xml" dir="subproject" target="compile"/> |
| |
| <ant dir="subproject"/> |
| |
| <ant antfile="subproject/property_based_subbuild.xml"> |
| <property name="param1" value="version 1.x"/> |
| <property file="config/subproject/default.properties"/> |
| </ant> |
| |
| <ant inheritAll="false" antfile="subproject/subbuild.xml"> |
| <property name="output.type" value="html"/> |
| </ant> |
| </pre> |
| |
| <p>The build file of the calling project defines some |
| <code><path></code> elements like this:</p> |
| |
| <pre> |
| <path id="path1"> |
| ... |
| </> |
| <path id="path2"> |
| ... |
| </> |
| </pre> |
| |
| <p>and the called build file (<code>subbuild.xml</code>) also defines |
| a <code><path></code> with the id <code>path1</code>, but |
| <code>path2</code> is not defined:</p> |
| |
| <pre> |
| <ant antfile="subbuild.xml" inheritrefs="true" /> |
| </pre> |
| |
| <p>will not override <code>subbuild</code>'s definition of |
| <code>path1</code>, but make the parent's definition of |
| <code>path2</code> available in the subbuild.</p> |
| |
| <pre> |
| <ant antfile="subbuild.xml" /> |
| </pre> |
| |
| <p>as well as</p> |
| |
| <pre> |
| <ant antfile="subbuild.xml" inheritrefs="false" /> |
| </pre> |
| |
| <p>will neither override <code>path1</code> nor copy |
| <code>path2</code>.</p> |
| |
| <pre> |
| <ant antfile="subbuild.xml" inheritrefs="false" > |
| <reference refid="path1" /> |
| </ant> |
| </pre> |
| |
| <p>will override <code>subbuild</code>'s definition of |
| <code>path1</code>.</p> |
| |
| <pre> |
| <ant antfile="subbuild.xml" inheritrefs="false" > |
| <reference refid="path1" torefid="path2" /> |
| </ant> |
| </pre> |
| |
| <p>will copy the parent's definition of <code>path1</code> into the |
| new project using the id <code>path2</code>.</p> |
| |
| <hr> |
| <p align="center">Copyright © 2000-2002 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |
