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.

macrodef.html 12 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368
  1. <html>
  2. <head>
  3. <meta http-equiv="Content-Language" content="en-us"></meta>
  4. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  5. <title>MacroDef Task</title>
  6. <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
  7. <style type="text/css">
  8. <!--
  9. .code { background: #EFEFEF; margin-top: }
  10. -->
  11. </style>
  12. </head>
  13. <body>
  14. <h2><a name="macrodef">MacroDef</a></h2>
  15. <h3>Description</h3>
  16. <p>
  17. This defines a new task using a <code>&lt;sequential&gt;</code>
  18. nested task as a template. Nested elements <code>&lt;attribute&gt;</code> and
  19. <code>&lt;element&gt;</code> are used to specify attributes and elements of
  20. the new task. These get substituted into the <code>&lt;sequential&gt;</code>
  21. task when the new task is run.
  22. </p>
  23. <h3>Note</h3>
  24. <p>
  25. You can also use <i>prior defined</i> attributes for default-values in
  26. other attributes. See the examples.
  27. </p>
  28. <p>
  29. <em>since Ant 1.6</em>
  30. </p>
  31. <h3>Parameters</h3>
  32. <table border="1" cellpadding="2" cellspacing="0">
  33. <tr>
  34. <td valign="top"><b>Attribute</b></td>
  35. <td valign="top"><b>Description</b></td>
  36. <td align="center" valign="top"><b>Required</b></td>
  37. </tr>
  38. <tr>
  39. <td valign="top">name</td>
  40. <td valign="top">The name of the new definition.</td>
  41. <td valign="top" align="center">Yes</td>
  42. </tr>
  43. <tr>
  44. <td valign="top">uri</td>
  45. <td valign="top">
  46. The uri that this definition should live in.
  47. </td>
  48. <td valign="top" align="center">No</td>
  49. </tr>
  50. <tr>
  51. <td valign="top">description</td>
  52. <td valign="top">A description of the macrodef
  53. (for documentation purposes only).
  54. </td>
  55. <td valign="top" align="center">No</td>
  56. </tr>
  57. <tr>
  58. <td valign="top">backtrace</td>
  59. <td valign="top">
  60. This controls the error traceback if they is an
  61. error detected when running the macro. If this is
  62. set to true, there will be an error trackback, if false
  63. there will not be one. <em>Since Ant 1.7</em>.
  64. </td>
  65. <td valign="top" align="center">No; default <em>true</em></td>
  66. </tr>
  67. </table>
  68. <h3>Parameters specified as nested elements</h3>
  69. <h4>attribute</h4>
  70. <p>
  71. This is used to specify attributes of the new task. The values
  72. of the attributes get substituted into the templated task.
  73. The attributes will be required attributes unless a default
  74. value has been set.
  75. </p>
  76. <p>
  77. This attribute is placed in the body of the templated
  78. task using a notation similar to the ant property notation
  79. - @{attribute name}. (May be remembered as "put the substitution
  80. AT this location").
  81. </p>
  82. <p>
  83. The escape sequence @@ is used to escape @. This allows @{x} to be
  84. placed in the text without substitution of x by using @@{x}.
  85. This corresponds to the $$ escape sequence for properties.
  86. </p>
  87. <p>
  88. The case of the attribute is ignored, so @{myAttribute} is treated the
  89. same as @{MyAttribute}.
  90. </p>
  91. <h3>Parameters</h3>
  92. <table border="1" cellpadding="2" cellspacing="0">
  93. <tr>
  94. <td valign="top"><b>Attribute</b></td>
  95. <td valign="top"><b>Description</b></td>
  96. <td align="center" valign="top"><b>Required</b></td>
  97. </tr>
  98. <tr>
  99. <td valign="top">name</td>
  100. <td valign="top">The name of the new attribute</td>
  101. <td valign="top" align="center">Yes</td>
  102. </tr>
  103. <tr>
  104. <td valign="top">default</td>
  105. <td valign="top">
  106. The default value of the attribute.
  107. </td>
  108. <td valign="top" align="center">No</td>
  109. </tr>
  110. <tr>
  111. <td valign="top">description</td>
  112. <td valign="top">
  113. This contains a description of the attribute.
  114. <em>since ant 1.6.1</em>
  115. </td>
  116. <td valign="top" align="center">No</td>
  117. </tr>
  118. </table>
  119. <h4>element</h4>
  120. <p>
  121. This is used to specify nested elements of the new task.
  122. The contents of the nested elements of the task instance
  123. are placed in the templated task at the tag name.
  124. </p>
  125. <p>
  126. The case of the element name is ignored.
  127. </p>
  128. <h3>Parameters</h3>
  129. <table border="1" cellpadding="2" cellspacing="0">
  130. <tr>
  131. <td valign="top"><b>Attribute</b></td>
  132. <td valign="top"><b>Description</b></td>
  133. <td align="center" valign="top"><b>Required</b></td>
  134. </tr>
  135. <tr>
  136. <td valign="top">name</td>
  137. <td valign="top">The name of the element</td>
  138. <td valign="top" align="center">Yes</td>
  139. </tr>
  140. <tr>
  141. <td valign="top">optional</td>
  142. <td valign="top">
  143. If true this nested element is optional. Default is
  144. false - i.e the nested element is required in
  145. the new task.
  146. </td>
  147. <td valign="top" align="center">No</td>
  148. </tr>
  149. <tr>
  150. <td valign="top">implicit</td>
  151. <td valign="top">
  152. If true this nested element is implicit. This means that
  153. any nested elements of the macrodef instance will be placed
  154. in the element indicated by the name of this element.
  155. There can only be one element if an element is implicit.
  156. The default value is false. <em>since ant 1.6.2</em>
  157. </td>
  158. <td valign="top" align="center">No</td>
  159. </tr>
  160. <tr>
  161. <td valign="top">description</td>
  162. <td valign="top">
  163. This contains a description
  164. informing the user what the contents of the element are expected to be.
  165. <em>since ant 1.6.1</em>
  166. </td>
  167. <td valign="top" align="center">No</td>
  168. </tr>
  169. </table>
  170. <h4>text</h4>
  171. <p>
  172. This is used to specify the treatment of text contents of the macrodef.
  173. If this element is not present, then any nested text in the macro
  174. will be an error. If the text element is present, then the name
  175. becomes an attribute that gets set to the nested text of the macro.
  176. <em>Since ant 1.6.1.</em>
  177. </p>
  178. <p>
  179. The case of the text name is ignored.
  180. </p>
  181. <h3>Parameters</h3>
  182. <table border="1" cellpadding="2" cellspacing="0">
  183. <tr>
  184. <td valign="top"><b>Attribute</b></td>
  185. <td valign="top"><b>Description</b></td>
  186. <td align="center" valign="top"><b>Required</b></td>
  187. </tr>
  188. <tr>
  189. <td valign="top">name</td>
  190. <td valign="top">The name of the text attribute</td>
  191. <td valign="top" align="center">Yes</td>
  192. </tr>
  193. <tr>
  194. <td valign="top">optional</td>
  195. <td valign="top">
  196. If true nested text in the macro is optional, default is "false".
  197. </td>
  198. <td valign="top" align="center">No</td>
  199. </tr>
  200. <tr>
  201. <td valign="top">trim</td>
  202. <td valign="top">
  203. If true, the nested text is trimmed of white space,
  204. default is "false".
  205. </td>
  206. <td valign="top" align="center">No</td>
  207. </tr>
  208. <tr>
  209. <td valign="top">description</td>
  210. <td valign="top">
  211. This contains a description
  212. informing the user what the nested text of the macro is expected
  213. to be.
  214. </td>
  215. <td valign="top" align="center">No</td>
  216. </tr>
  217. </table>
  218. <h3>Examples</h3>
  219. <p>
  220. The following example defined a task called testing and
  221. runs it.
  222. </p>
  223. <blockquote>
  224. <pre class=code>
  225. &lt;macrodef name="testing"&gt;
  226. &lt;attribute name="v" default="NOT SET"/&gt;
  227. &lt;element name="some-tasks" optional="yes"/&gt;
  228. &lt;sequential&gt;
  229. &lt;echo&gt;v is @{v}&lt;/echo&gt;
  230. &lt;some-tasks/&gt;
  231. &lt;/sequential&gt;
  232. &lt;/macrodef&gt;
  233. &lt;testing v="This is v"&gt;
  234. &lt;some-tasks&gt;
  235. &lt;echo&gt;this is a test&lt;/echo&gt;
  236. &lt;/some-tasks&gt;
  237. &lt;/testing&gt;
  238. </pre>
  239. </blockquote>
  240. <p>
  241. The following fragment defines a task called <code>&lt;call-cc&gt;</code> which
  242. take the attributes "target", "link" and "target.dir" and the
  243. nested element "cc-elements". The body of the task
  244. uses the <code>&lt;cc&gt;</code> task from the
  245. <a href="http://ant-contrib.sourceforge.net/">ant-contrib</a> project.
  246. </p>
  247. <blockquote>
  248. <pre class="code">
  249. &lt;macrodef name="call-cc"&gt;
  250. &lt;attribute name="target"/&gt;
  251. &lt;attribute name="link"/&gt;
  252. &lt;attribute name="target.dir"/&gt;
  253. &lt;element name="cc-elements"/&gt;
  254. &lt;sequential&gt;
  255. &lt;mkdir dir="${obj.dir}/@{target}"/&gt;
  256. &lt;mkdir dir="@{target.dir}"/&gt;
  257. &lt;cc link="@{link}" objdir="${obj.dir}/@{target}"
  258. outfile="@{target.dir}/@{target}"&gt;
  259. &lt;compiler refid="compiler.options"/&gt;
  260. &lt;cc-elements/&gt;
  261. &lt;/cc&gt;
  262. &lt;/sequential&gt;
  263. &lt;/macrodef&gt;
  264. </pre>
  265. </blockquote>
  266. <p>
  267. This then can be used as follows:
  268. </p>
  269. <blockquote>
  270. <pre class="code">
  271. &lt;call-cc target="unittests" link="executable"
  272. target.dir="${build.bin.dir}"&gt;
  273. &lt;cc-elements&gt;
  274. &lt;includepath location="${gen.dir}"/&gt;
  275. &lt;includepath location="test"/&gt;
  276. &lt;fileset dir="test/unittest" includes = "**/*.cpp"/&gt;
  277. &lt;fileset dir="${gen.dir}" includes = "*.cpp"/&gt;
  278. &lt;linker refid="linker-libs"/&gt;
  279. &lt;/cc-elements&gt;
  280. &lt;/call-cc&gt;
  281. </pre>
  282. </blockquote>
  283. <p>
  284. The following fragment shows &lt;call-cc&gt;, but this time
  285. using an implicit element and with the link and target.dir arguments
  286. having default values.
  287. </p>
  288. <blockquote>
  289. <pre class="code">
  290. &lt;macrodef name="call-cc"&gt;
  291. &lt;attribute name="target"/&gt;
  292. &lt;attribute name="link" default="executable"/&gt;
  293. &lt;attribute name="target.dir" default="${build.bin.dir}"/&gt;
  294. &lt;element name="cc-elements" implicit="yes"/&gt;
  295. &lt;sequential&gt;
  296. &lt;mkdir dir="${obj.dir}/@{target}"/&gt;
  297. &lt;mkdir dir="@{target.dir}"/&gt;
  298. &lt;cc link="@{link}" objdir="${obj.dir}/@{target}"
  299. outfile="@{target.dir}/@{target}"&gt;
  300. &lt;compiler refid="compiler.options"/&gt;
  301. &lt;cc-elements/&gt;
  302. &lt;/cc&gt;
  303. &lt;/sequential&gt;
  304. &lt;/macrodef&gt;
  305. </pre>
  306. </blockquote>
  307. <p>
  308. This then can be used as follows, note that &lt;cc-elements&gt;
  309. is not specified.
  310. </p>
  311. <blockquote>
  312. <pre class="code">
  313. &lt;call-cc target="unittests"/&gt;
  314. &lt;includepath location="${gen.dir}"/&gt;
  315. &lt;includepath location="test"/&gt;
  316. &lt;fileset dir="test/unittest" includes = "**/*.cpp"/&gt;
  317. &lt;fileset dir="${gen.dir}" includes = "*.cpp"/&gt;
  318. &lt;linker refid="linker-libs"/&gt;
  319. &lt;/call-cc&gt;
  320. </pre>
  321. </blockquote>
  322. <p>
  323. The following shows the use of the <code>text</code> element.
  324. </p>
  325. <blockquote>
  326. <pre class="code">
  327. &lt;macrodef name="echotest"&gt;
  328. &lt;text name="text"/&gt;
  329. &lt;sequential&gt;
  330. &lt;echo&gt;@{text}&lt;/echo&gt;
  331. &lt;/sequential&gt;
  332. &lt;/macrodef&gt;
  333. &lt;echotest&gt;
  334. Hello world
  335. &lt;/echotest&gt;
  336. </pre>
  337. </blockquote>
  338. <p>
  339. The following uses a prior defined attribute for setting the
  340. default value of another. The output would be
  341. <tt>one=test two=test</tt>. If you change the order of lines
  342. *1 and *2 the output would be <tt>one=test two=@{one}</tt>,
  343. because while processing the <i>two</i>-line the value for
  344. <i>one</i> is not set.
  345. </p>
  346. <blockquote>
  347. <pre class="code">
  348. &lt;macrodef name="test"&gt;
  349. &lt;attribute name="one"/&gt; <b>*1</b>
  350. &lt;attribute name="two" default="@{one}"/&gt; <b>*2</b>
  351. &lt;sequential&gt;
  352. &lt;echo&gt;one=@{one} two=@{two}&lt;/echo&gt;
  353. &lt;/sequential&gt;
  354. &lt;/macrodef&gt;
  355. &lt;test one="test"/&gt;
  356. </pre>
  357. </blockquote>
  358. <hr>
  359. <p align="center">Copyright &copy; 2003-2006 The Apache Software
  360. Foundation. All rights Reserved.</p>
  361. </body>
  362. </html>