mirror of
https://github.com/apache/ant.git
synced 2025-05-18 22:14:47 +00:00
3a4980e3c4
find . -type f -exec sed -i "s/http:\/\/www.apache.org\/licenses\/LICENSE-2.0/https:\/\/www.apache.org\/licenses\/LICENSE-2.0/" {} \;
361 lines
14 KiB
HTML
361 lines
14 KiB
HTML
<!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>Ant Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h2 id="ant">Ant</h2>
|
|
<h3>Description</h3>
|
|
|
|
<p>Runs Apache Ant on a supplied buildfile. This can be used to build subprojects. <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>When the <var>antfile</var> attribute is omitted, the file <samp>build.xml</samp> in the supplied
|
|
directory (<var>dir</var> 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 <var>inheritAll</var> attribute to <q>false</q> 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</a>
|
|
task).</p>
|
|
|
|
<p>You can also set properties in the new project from the old project by using
|
|
nested <code>property</code> tags. These properties are always passed to the new project and any
|
|
project created in that project regardless of the setting of <var>inheritAll</var>. This allows you
|
|
to parameterize your subprojects.</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 though it is
|
|
different from the way <code><property></code> tasks in build files behave.</p>
|
|
|
|
<p>Properties defined on the command line cannot be overridden by
|
|
nested <code><property></code> elements. <em>Since Ant 1.8.0</em>, the same is true for
|
|
nested structures of <code><ant></code> tasks: if a build file <var>A</var>
|
|
invokes <var>B</var> via an <code><ant></code> task setting a property with a
|
|
nested <code><property></code> element and <var>B</var> contains an <code><ant></code>
|
|
tasks invoking <var>C</var>, <var>C</var> will see the value set in <var>A</var>, even
|
|
if <var>B</var> used a nested <code><property></code> element as well.</p>
|
|
|
|
<p>References to data types can also be passed to the new project, but by default they are not. If
|
|
you set the <var>inheritrefs</var> attribute to <q>true</q>, all references will be copied, but they
|
|
will not override references defined in the new project.</p>
|
|
|
|
<p>Nested <a href="#reference"><code><reference></code></a> elements can also be used to copy
|
|
references from the calling project to the new project, optionally under a different <var>id</var>.
|
|
References taken from nested elements will override existing references that have been defined
|
|
outside of targets in the new project—but not those defined inside of targets.</p>
|
|
|
|
<h3>Parameters</h3>
|
|
<table class="attr">
|
|
<tr>
|
|
<th scope="col">Attribute</th>
|
|
<th scope="col">Description</th>
|
|
<th scope="col">Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>antfile</td>
|
|
<td>the buildfile to use. This file is expected to be a filename relative to the <var>dir</var>
|
|
attribute given.</td>
|
|
<td>No; defaults to <q>build.xml</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>dir</td>
|
|
<td>the directory to use as a <var>basedir</var> for the new Ant project
|
|
(unless <var>useNativeBasedir</var> is set to <q>true</q>). This will override
|
|
the <var>basedir</var> setting of the called project.<br/> Also serves as the directory to
|
|
resolve the <var>antfile</var> and <var>output</var> attribute's values (if any).
|
|
</td>
|
|
<td>No; defaults to the current project's <var>basedir</var>, unless <var>inheritall</var> has
|
|
been set to <q>false</q>, in which case it doesn't have a default value</td>
|
|
</tr>
|
|
<tr>
|
|
<td>target</td>
|
|
<td>the target of the new Ant project that should be executed.</td>
|
|
<td>No; defaults to the new project's default target</td>
|
|
</tr>
|
|
<tr>
|
|
<td>output</td>
|
|
<td>Filename to write the Ant output to. This is relative to the value of the <var>dir</var>
|
|
attribute if it has been set or to the <var>basedir</var> of the current project otherwise.
|
|
</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>inheritAll</td>
|
|
<td>If <q>true</q>, pass all properties to the new Ant project.</td>
|
|
<td>No; defaults to <q>true</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>inheritRefs</td>
|
|
<td>If <q>true</q>, pass all references to the new Ant project.</td>
|
|
<td>No; defaults to <q>false</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>useNativeBasedir</td>
|
|
<td>If set to <q>true</q>, the child build will use the same <var>basedir</var> as it would have
|
|
used when run from the command line (i.e. the <var>basedir</var> one would expect when looking
|
|
at the child build's buildfile). <em>Since Ant 1.8.0</em></td>
|
|
<td>No; defaults to <q>false</q></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
<h4>property</h4>
|
|
<p>See the description of the <a href="property.html">property</a> task.<br/> These properties
|
|
become equivalent to properties you define on the command line. These are special properties and
|
|
they will always get passed down, even through additional <code><*ant*></code> tasks
|
|
with <var>inheritAll</var> set to <q>false</q> (see above).<br/> Note that the <var>refid</var>
|
|
attribute points to a reference in the calling project, not in the new one.</p>
|
|
|
|
<h4 id="reference">reference</h4>
|
|
<p>Used to choose references that shall be copied into the new project, optionally changing
|
|
their <var>id</var>.</p>
|
|
|
|
<table class="attr">
|
|
<tr>
|
|
<th scope="col">Attribute</th>
|
|
<th scope="col">Description</th>
|
|
<th scope="col">Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>refid</td>
|
|
<td>The <var>id</var> of the reference in the calling project.</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>torefid</td>
|
|
<td>The <var>id</var> of the reference in the new project.</td>
|
|
<td>No; defaults to the value of <var>refid</var></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>propertyset</h4>
|
|
|
|
<p><em>Since Ant 1.6</em>.</p>
|
|
|
|
<p>You can specify a set of properties to be copied into the new project
|
|
with <a href="../Types/propertyset.html">propertyset</a>s.</p>
|
|
|
|
<h4>target</h4>
|
|
<p><em>Since Ant 1.6.3</em>.</p>
|
|
|
|
<p>You can specify multiple targets using nested <code><target></code> elements instead of
|
|
using the <var>target</var> 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>Basedir of the new project</h3>
|
|
|
|
<p>If you set <var>useNativeBasedir</var> to true, the <var>basedir</var> of the new project will be
|
|
whatever the <var>basedir</var> attribute of the <code><project></code> element of the new
|
|
project says (or the new project's directory if the there is no <var>basedir</var>
|
|
attribute)—no matter what any other attribute of this task says and no matter how deeply
|
|
nested into levels of <code><ant></code> invocations this task lives.</p>
|
|
|
|
<p>If you haven't set <var>useNativeBasedir</var> or set it to <q>false</q>, the following rules
|
|
apply:</p>
|
|
|
|
<p>The <var>basedir</var> value of the new project is affected by the two attributes, <var>dir</var>
|
|
and <var>inheritall</var>, as well as the <code><ant></code> task's history. The current
|
|
behaviour is known to be confusing but cannot be changed without breaking backwards compatibility in
|
|
subtle ways.</p>
|
|
|
|
<p>If the <code><ant></code> task is in a "top level" build file, i.e. the project containing
|
|
the <code><ant></code> task has not itself been invoked as part of a
|
|
different <code><ant></code> (or <code><antcall></code>) task "higher up", the following
|
|
table shows the details:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th scope="col"><var>dir</var> attribute</th>
|
|
<th scope="col"><var>inheritAll</var> attribute</th>
|
|
<th scope="col">new project's <var>basedir</var></th>
|
|
</tr>
|
|
<tr>
|
|
<td>value provided</td>
|
|
<td><q>true</q></td>
|
|
<td>value of <var>dir</var> attribute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>value provided</td>
|
|
<td><q>false</q></td>
|
|
<td>value of <var>dir</var> attribute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>true</q></td>
|
|
<td><var>basedir</var> of calling project (the one whose build
|
|
file contains the <code><ant></code> task).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>false</q></td>
|
|
<td><var>basedir</var> attribute of the <code><project></code> element
|
|
of the new project</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If on the other hand the <code><ant></code> task is already nested into another invocation,
|
|
the parent invocation's settings affect the outcome of the <var>basedir</var> value. The current
|
|
task's <var>dir</var> attribute will always win, but if the <var>dir</var> attribute has been
|
|
omitted an even more complex situation arises:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th scope="col">parent <var>dir</var> attribute</th>
|
|
<th scope="col">parent <var>inheritAll</var> attribute</th>
|
|
<th scope="col">current <var>inheritAll</var> attribute</th>
|
|
<th scope="col">new project's <var>basedir</var></th>
|
|
</tr>
|
|
<tr>
|
|
<td>value provided</td>
|
|
<td>any</td>
|
|
<td>any</td>
|
|
<td>value of parent's <var>dir</var> attribute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>true</q></td>
|
|
<td><q>true</q></td>
|
|
<td><var>basedir</var> of parent project (the one whose build file called the build file that
|
|
contains the current <code><ant></code> task).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>true</q></td>
|
|
<td><q>false</q></td>
|
|
<td><var>basedir</var> of parent project (the one whose build file called the build file that
|
|
contains the current <code><ant></code> task).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>false</q></td>
|
|
<td><q>true</q></td>
|
|
<td><var>basedir</var> of calling project (the one whose build file contains the
|
|
current <code><ant></code> task).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>omitted</td>
|
|
<td><q>false</q></td>
|
|
<td><q>false</q></td>
|
|
<td><var>basedir</var> attribute of the <code><project></code> element of the new
|
|
project</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If you add even deeper levels of nesting, things get even more complicated and you need to apply
|
|
the above table recursively.</p>
|
|
|
|
<p>If the <var>basedir</var> of the outermost build has been specified as a property on the command
|
|
line (i.e. <kbd>-Dbasedir=some-value</kbd> or a <kbd>-propertyfile</kbd> argument) the value
|
|
provided will get an even higher priority. For any <code><ant></code> task that doesn't
|
|
specify a <var>dir</var> attribute, the new project's <var>basedir</var> will be the value specified
|
|
on the command line—no matter how deeply nested into layers of build files the task may
|
|
be.</p>
|
|
|
|
<p>The same happens if the <var>basedir</var> is specified as a nested <code><property></code>
|
|
of an <code><ant></code> task. The <var>basedir</var> of build files started at deeper levels
|
|
will be set to the specified value of the property element unless the corresponding Ant tasks set
|
|
the <var>dir</var> attribute explicitly.</p>
|
|
|
|
<h3>Examples</h3>
|
|
<p>These are different ways of using the task:</p>
|
|
<pre>
|
|
<ant antfile="subproject/subbuild.xml" 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>These lines invoke the same build file:</p>
|
|
<pre>
|
|
<ant antfile="sub1/sub2/build.xml"/>
|
|
<ant antfile="sub2/build.xml" dir="sub1"/>
|
|
<ant antfile="build.xml" dir="sub1/sub2"/></pre>
|
|
|
|
<p>The build file of the calling project defines some <code><path></code> elements like
|
|
this:</p>
|
|
|
|
<pre>
|
|
<path id="path1">
|
|
...
|
|
</path>
|
|
<path id="path2">
|
|
...
|
|
</path></pre>
|
|
|
|
<p>and the called build file (<samp>subbuild.xml</samp>) also defines a <code><path></code>
|
|
with the <var>id</var> <samp>path1</samp>, but <samp>path2</samp> is not defined; then</p>
|
|
|
|
<pre><ant antfile="subbuild.xml" inheritrefs="true"/></pre>
|
|
|
|
<p>will not override <samp>subbuild</samp>'s definition of <samp>path1</samp>, but make the parent's
|
|
definition of <samp>path2</samp> available in the <samp>subbuild</samp>, whereas</p>
|
|
|
|
<pre><ant antfile="subbuild.xml"/></pre>
|
|
|
|
<p>as well as</p>
|
|
|
|
<pre><ant antfile="subbuild.xml" inheritrefs="false"/></pre>
|
|
|
|
<p>will neither override <samp>path1</samp> nor copy <samp>path2</samp>, while</p>
|
|
|
|
<pre>
|
|
<ant antfile="subbuild.xml" inheritrefs="false">
|
|
<reference refid="path1"/>
|
|
</ant></pre>
|
|
|
|
<p>will override <samp>subbuild</samp>'s definition of <samp>path1</samp>, and</p>
|
|
|
|
<pre>
|
|
<ant antfile="subbuild.xml" inheritrefs="false">
|
|
<reference refid="path1" torefid="path2"/>
|
|
</ant></pre>
|
|
|
|
<p>will copy the parent's definition of <samp>path1</samp> into the new project using
|
|
the <var>id</var> <samp>path2</samp>.</p>
|
|
|
|
</body>
|
|
</html>
|