| <!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>AntCall Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="antcall">AntCall</h2> |
| <h3>Description</h3> |
| |
| <p>Call another target within the same buildfile optionally specifying some properties (params in |
| this context). <strong>This task must not be used outside of a <code>target</code>.</strong></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><param></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. Properties defined on the command line can not be overridden |
| by nested <code><param></code> elements.</p> |
| |
| <p>When more than one nested <code><param></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> |
| |
| <p>Nested <a href="#reference"><code><reference></code></a> elements can 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> |
| |
| <p>When a target is invoked by <code>antcall</code>, all of its dependent targets will also be |
| called within the context of any new parameters. For example. if the target <q>doSomethingElse</q>; |
| depended on the target <q>init</q>, then the <code>antcall</code> of <q>doSomethingElse</q> will |
| call <q>init</q> during the call. Of course, any properties defined in the <code>antcall</code> |
| task or inherited from the calling target will be fixed and not overridable in the <q>init</q> |
| target—or indeed in the <q>doSomethingElse</q> target.</p> |
| |
| <p>The called target(s) are run in a new project; be aware that this means properties, references, |
| etc. set by called targets will not persist back to the calling project.</p> |
| |
| <p>If the build file changes after you've started the build, the behavior of this task is |
| undefined.</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>target</td> |
| <td>The target to execute.</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>inheritAll</td> |
| <td>If <q>true</q>, pass all properties to the new Apache 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> |
| </table> |
| |
| <h3>Note on <code>inheritRefs</code></h3> |
| |
| <p><code><antcall></code> will not override existing references, even if you |
| set <var>inheritRefs</var> to true. As the called build files is the same build file as the calling |
| one, this means it will not override any reference set via an <var>id</var> attribute at all. The |
| only references that can be inherited by the child project are those defined by |
| nested <code><reference></code> elements or references defined by tasks directly (not using |
| the <var>id</var> attribute).</p> |
| |
| <h3>Parameters specified as nested elements</h3> |
| <h4>param</h4> |
| <p>Specifies the properties to set before running the specified |
| target. See <a href="property.html">property</a> for usage guidelines.<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).</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>Examples</h3> |
| <p>The following</p> |
| <pre> |
| <target name="default"> |
| <antcall target="doSomethingElse"> |
| <param name="param1" value="value"/> |
| </antcall> |
| </target> |
| |
| <target name="doSomethingElse"> |
| <echo message="param1=${param1}"/> |
| </target></pre> |
| <p>will run the target <var>doSomethingElse</var> and echo <code>param1=value</code>, whereas</p> |
| <pre> |
| <antcall ... > |
| <reference refid="path1" torefid="path2"/> |
| </antcall></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> |