You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

antcall.html 7.6 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>AntCall Task</title>
  20. </head>
  21. <body>
  22. <h2><a name="antcall">AntCall</a></h2>
  23. <h3>Description</h3>
  24. <p>Call another target within the same buildfile optionally
  25. specifying some properties (params in this context). <strong>This
  26. task must not be used outside of a <code>target</code>.</strong></p>
  27. <p>By default, all of the properties of the current project will be
  28. available in the new project. Alternatively, you can
  29. set the <i>inheritAll</i> attribute to <code>false</code> and only
  30. &quot;user&quot; properties (i.e., those passed on the command-line)
  31. will be passed to the new project. In either case, the set of
  32. properties passed to the new project will override the properties that
  33. are set in the new project (See also the <a href="property.html">property task</a>).</p>
  34. <p>You can also set properties in the new project from the old project
  35. by using nested param tags. These properties are always passed
  36. to the new project and any project created in that project
  37. regardless of the setting of <i>inheritAll</i>. This allows you to
  38. parameterize your subprojects. Properties defined on the command line
  39. can not be overridden by nested <code>&lt;param&gt;</code> elements.</p>
  40. <p>When more than one nested <code>&lt;param&gt;</code> element
  41. would set a property of the same name, the one declared last will
  42. win. This is for backwards compatibility reasons even so it is
  43. different from the way <code>&lt;property&gt;</code> tasks in build
  44. files behave.</p>
  45. <p>Nested <a href="#reference"><i><code>&lt;reference&gt</code>;</i></a> elements can
  46. be used to copy references from the calling project to the new
  47. project, optionally under a different id. References taken from
  48. nested elements will override existing references that have been
  49. defined outside of targets in the new project - but not those defined
  50. inside of targets.</p>
  51. <p>
  52. When a target is invoked by antcall, all of its dependent targets will
  53. also be called within the context of any new parameters. For example. if
  54. the target &quot;doSomethingElse&quot; depended on the target &quot;init&quot;, then the
  55. <i>antcall</i> of &quot;doSomethingElse&quot; will call &quot;init&quot; during the call.
  56. Of course, any properties defined in the antcall task or inherited from the calling target
  57. will be fixed and not overridable in the init task--or indeed in the &quot;doSomethingElse&quot; task.
  58. </p>
  59. <p>The called target(s) are run in a new project; be aware that this
  60. means properties, references, etc. set by called targets will not
  61. persist back to the calling project.</p>
  62. <p>If the build file changes after you've started the build, the
  63. behavior of this task is undefined.</p>
  64. <h3>Parameters</h3>
  65. <table border="1" cellpadding="2" cellspacing="0">
  66. <tr>
  67. <td valign="top"><b>Attribute</b></td>
  68. <td valign="top"><b>Description</b></td>
  69. <td align="center" valign="top"><b>Required</b></td>
  70. </tr>
  71. <tr>
  72. <td valign="top">target</td>
  73. <td valign="top">The target to execute.</td>
  74. <td valign="top" align="center">Yes</td>
  75. </tr>
  76. <tr>
  77. <td valign="top">inheritAll</td>
  78. <td valign="top">If <code>true</code>, pass all properties to the new Ant
  79. project. Defaults to <code>true</code>.
  80. </td>
  81. <td align="center" valign="top">No</td>
  82. </tr>
  83. <tr>
  84. <td valign="top">inheritRefs</td>
  85. <td valign="top">If <code>true</code>, pass all references to the
  86. new Ant project. Defaults to <code>false</code>.</td>
  87. <td align="center" valign="top">No</td>
  88. </tr>
  89. </table>
  90. <h3>Note on <code>inheritRefs</code></h3>
  91. <p><code>&lt;antcall&gt;</code> will not override existing references,
  92. even if you set <code>inheritRefs</code> to true. As the called build
  93. files is the same build file as the calling one, this means it will
  94. not override any reference set via an <code>id</code> attribute at
  95. all. The only references that can be inherited by the child project
  96. are those defined by nested <code>&lt;reference&gt;</code> elements or
  97. references defined by tasks directly (not using the <code>id</code>
  98. attribute).</p>
  99. <h3>Parameters specified as nested elements</h3>
  100. <h4>param</h4>
  101. <p>Specifies the properties to set before running the specified target. See <a
  102. href="property.html">property</a> for usage guidelines.<br>
  103. These properties become equivalent to properties you define on
  104. the command line. These are special properties and they will always get passed
  105. down, even through additional <code>&lt;*ant*&gt;</code> tasks with inheritall set to
  106. false (see above).
  107. </p>
  108. <h4><a name="reference">reference</a></h4>
  109. <p>Used to choose references that shall be copied into the new project,
  110. optionally changing their id.</p>
  111. <table border="1" cellpadding="2" cellspacing="0">
  112. <tr>
  113. <td valign="top"><b>Attribute</b></td>
  114. <td valign="top"><b>Description</b></td>
  115. <td align="center" valign="top"><b>Required</b></td>
  116. </tr>
  117. <tr>
  118. <td valign="top">refid</td>
  119. <td valign="top">The id of the reference in the calling project.</td>
  120. <td valign="top" align="center">Yes</td>
  121. </tr>
  122. <tr>
  123. <td valign="top">torefid</td>
  124. <td valign="top">The id of the reference in the new project.</td>
  125. <td valign="top" align="center">No, defaults to the value of refid.</td>
  126. </tr>
  127. </table>
  128. <h4>propertyset</h4>
  129. <p>You can specify a set of properties to be copied into the new
  130. project with <a
  131. href="../CoreTypes/propertyset.html">propertyset</a>s.</p>
  132. <p><em>since Ant 1.6</em>.</p>
  133. <h4>target</h4>
  134. <p>You can specify multiple targets using nested <code>&lt;target&gt;</code> elements
  135. instead of using the target attribute. These will be executed as if
  136. Ant had been invoked with a single target whose dependencies are the
  137. targets so specified, in the order specified.</p>
  138. <table border="1" cellpadding="2" cellspacing="0">
  139. <tr>
  140. <td valign="top"><b>Attribute</b></td>
  141. <td valign="top"><b>Description</b></td>
  142. <td align="center" valign="top"><b>Required</b></td>
  143. </tr>
  144. <tr>
  145. <td valign="top">name</td>
  146. <td valign="top">The name of the called target.</td>
  147. <td valign="top" align="center">Yes</td>
  148. </tr>
  149. </table>
  150. <p><em>since Ant 1.6.3</em>.</p>
  151. <h3>Examples</h3>
  152. <blockquote><pre>
  153. &lt;target name=&quot;default&quot;&gt;
  154. &lt;antcall target=&quot;doSomethingElse&quot;&gt;
  155. &lt;param name=&quot;param1&quot; value=&quot;value&quot;/&gt;
  156. &lt;/antcall&gt;
  157. &lt;/target&gt;
  158. &lt;target name=&quot;doSomethingElse&quot;&gt;
  159. &lt;echo message=&quot;param1=${param1}&quot;/&gt;
  160. &lt;/target&gt;
  161. </pre></blockquote>
  162. <p>Will run the target 'doSomethingElse' and echo 'param1=value'.</p>
  163. <blockquote><pre>
  164. &lt;antcall ... &gt;
  165. &lt;reference refid=&quot;path1&quot; torefid=&quot;path2&quot;/&gt;
  166. &lt;/antcall&gt;
  167. </pre></blockquote>
  168. <p>will copy the parent's definition of <code>path1</code> into the
  169. new project using the id <code>path2</code>.</p>
  170. </body>
  171. </html>