2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
http://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.
|
|
|
|
|
-->
|
2003-08-14 12:48:10 +00:00
|
|
|
<html>
|
2004-04-20 14:45:26 +00:00
|
|
|
|
2003-08-14 12:48:10 +00:00
|
|
|
<head>
|
2018-01-22 23:52:21 +01:00
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2007-05-02 06:15:35 +00:00
|
|
|
<title>MacroDef Task</title>
|
2003-08-14 12:48:10 +00:00
|
|
|
</head>
|
2004-04-20 14:45:26 +00:00
|
|
|
|
2003-08-14 12:48:10 +00:00
|
|
|
<body>
|
2004-04-20 14:45:26 +00:00
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="macrodef">MacroDef</h2>
|
2018-03-04 15:17:41 +01:00
|
|
|
<p><em>Since Apache Ant 1.6</em></p>
|
2003-08-14 12:48:10 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>This defines a new task using a <code><sequential></code> nested task as a
|
|
|
|
|
template. Nested elements <code><attribute></code> and <code><element></code> are
|
|
|
|
|
used to specify attributes and elements of the new task. These get substituted into
|
|
|
|
|
the <code><sequential></code> task when the new task is run.</p>
|
2004-04-20 14:45:26 +00:00
|
|
|
<h3>Note</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>You can also use <em>prior defined</em> attributes for <var>default</var> values in other
|
|
|
|
|
attributes. See the examples.</p>
|
2003-08-14 12:48:10 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-14 12:48:10 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The name of the new definition.</td>
|
|
|
|
|
<td>Yes</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>uri</td>
|
|
|
|
|
<td>
|
2003-08-14 12:48:10 +00:00
|
|
|
The uri that this definition should live in.
|
|
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
2006-06-12 16:04:49 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>description</td>
|
|
|
|
|
<td>A description of the macrodef
|
2006-06-12 16:04:49 +00:00
|
|
|
(for documentation purposes only).
|
|
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2006-06-12 16:04:49 +00:00
|
|
|
</tr>
|
2005-04-21 09:49:55 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>backtrace</td>
|
|
|
|
|
<td>This controls the error traceback if there is an error detected when running the
|
|
|
|
|
macro. If this is set to <q>true</q>, there will be an error trackback, if <q>false</q>
|
|
|
|
|
there will be none. <em>Since Ant 1.7</em>.</td>
|
|
|
|
|
<td>No; default <q>true</q></td>
|
2005-04-21 09:49:55 +00:00
|
|
|
</tr>
|
2003-08-14 12:48:10 +00:00
|
|
|
</table>
|
2018-02-28 07:58:59 +01:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
2003-08-15 09:33:45 +00:00
|
|
|
<h4>attribute</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>This is used to specify attributes of the new task. The values of the attributes get
|
|
|
|
|
substituted into the templated task. The attributes will be required attributes unless a
|
|
|
|
|
default value has been set.</p>
|
|
|
|
|
<p>This attribute is placed in the body of the templated task using a notation similar to the
|
|
|
|
|
Ant property notation—<code>@{attribute name}</code>. (May be remembered as "put the
|
|
|
|
|
substitution AT this location").</p>
|
|
|
|
|
<p>The escape sequence <code>@@</code> is used to escape <code>@</code>. This
|
|
|
|
|
allows <code>@{x}</code> to be placed in the text without substitution of <code>x</code> by
|
|
|
|
|
using <code>@@{x}</code>. This corresponds to the <code>$$</code> escape sequence for
|
|
|
|
|
properties.</p>
|
|
|
|
|
<p>The case of the attribute is ignored, so <code>@{myAttribute}</code> is treated the same
|
|
|
|
|
as <code>@{MyAttribute}</code>.</p>
|
2018-03-05 21:01:42 +01:00
|
|
|
<h5>Parameters</h5>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-14 12:48:10 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The name of the new attribute</td>
|
|
|
|
|
<td>Yes</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>default</td>
|
|
|
|
|
<td>The default value of the attribute.</td>
|
|
|
|
|
<td>No</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
2004-01-08 17:34:57 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>description</td>
|
|
|
|
|
<td>This contains a description of the attribute. <em>Since Ant 1.6.1</em></td>
|
|
|
|
|
<td>No</td>
|
2004-01-08 17:34:57 +00:00
|
|
|
</tr>
|
2012-02-23 22:15:43 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>doubleexpanding</td>
|
|
|
|
|
<td>Controls whether or not property references in the attribute are expanded twice or just
|
2018-03-08 07:43:53 +01:00
|
|
|
once. See the <a href="https://ant.apache.org/faq.html#macrodef-property-expansion"
|
|
|
|
|
target="_top">FAQ</a> for details. <em>Since Ant 1.8.3</em></td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; default is <q>true</q></td>
|
2012-02-23 22:15:43 +00:00
|
|
|
</tr>
|
2003-08-14 12:48:10 +00:00
|
|
|
</table>
|
|
|
|
|
<h4>element</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>This is used to specify nested elements of the new task. The contents of the nested elements
|
|
|
|
|
of the task instance are placed in the templated task at the tag name.</p>
|
|
|
|
|
<p>The case of the <code>element</code> name is ignored.</p>
|
2018-03-05 21:01:42 +01:00
|
|
|
<h5>Parameters</h5>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-14 12:48:10 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The name of the element.</td>
|
|
|
|
|
<td>Yes</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>optional</td>
|
|
|
|
|
<td>If <q>true</q> this nested element is optional.</td>
|
|
|
|
|
<td>No; default is <q>false</q>—the nested element is required in the new task</td>
|
2003-08-14 12:48:10 +00:00
|
|
|
</tr>
|
2004-05-27 14:38:46 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>implicit</td>
|
|
|
|
|
<td>If <q>true</q> this nested element is implicit. This means that any nested elements of
|
|
|
|
|
the <code>macrodef</code> instance will be placed in the element indicated by the name of
|
|
|
|
|
this element. There can only be one element if an element is implicit. <em>Since Ant
|
|
|
|
|
1.6.2</em></td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2004-05-27 14:38:46 +00:00
|
|
|
</tr>
|
2004-01-08 17:34:57 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>description</td>
|
|
|
|
|
<td>This contains a description informing the user what the contents of the element are
|
|
|
|
|
expected to be. <em>Since Ant 1.6.1</em></td>
|
|
|
|
|
<td>No</td>
|
2004-01-08 17:34:57 +00:00
|
|
|
</tr>
|
2003-08-14 12:48:10 +00:00
|
|
|
</table>
|
2004-01-27 17:43:25 +00:00
|
|
|
<h4>text</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>This is used to specify the treatment of text contents of the macro invocation. If this
|
|
|
|
|
element is not present, then any nested text in the macro invocation will be an error. If
|
|
|
|
|
the <code>text</code> element is present, then the name becomes an attribute that gets set to
|
|
|
|
|
the nested text of the macro invocation. <em>Since Ant 1.6.1</em>.</p>
|
|
|
|
|
<p>The case of the <code>text</code> name is ignored.</p>
|
2018-03-05 21:01:42 +01:00
|
|
|
<h5>Parameters</h5>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2004-01-27 17:43:25 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2004-01-27 17:43:25 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The name of the text attribute.</td>
|
|
|
|
|
<td>Yes</td>
|
2004-04-20 15:42:34 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>optional</td>
|
|
|
|
|
<td>If <q>true</q> nested text in the macro is optional.</td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2004-04-20 15:42:34 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>trim</td>
|
|
|
|
|
<td>If <q>true</q>, the nested text is trimmed of white space.</td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2004-04-20 15:42:34 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>description</td>
|
|
|
|
|
<td>This contains a description informing the user what the nested text of the macro is
|
|
|
|
|
expected to be.</td>
|
|
|
|
|
<td>No</td>
|
2004-04-20 15:42:34 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
2004-04-20 14:45:26 +00:00
|
|
|
|
2003-08-14 12:48:10 +00:00
|
|
|
<h3>Examples</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The following example defined a task called testing and runs it.</p>
|
|
|
|
|
<pre class="code">
|
2003-08-14 12:48:10 +00:00
|
|
|
<macrodef name="testing">
|
2018-02-28 07:58:59 +01:00
|
|
|
<attribute name="v" default="NOT SET"/>
|
|
|
|
|
<element name="some-tasks" optional="yes"/>
|
|
|
|
|
<sequential>
|
|
|
|
|
<echo>v is @{v}</echo>
|
|
|
|
|
<some-tasks/>
|
|
|
|
|
</sequential>
|
2003-08-14 12:48:10 +00:00
|
|
|
</macrodef>
|
|
|
|
|
|
|
|
|
|
<testing v="This is v">
|
2018-02-28 07:58:59 +01:00
|
|
|
<some-tasks>
|
|
|
|
|
<echo>this is a test</echo>
|
|
|
|
|
</some-tasks>
|
|
|
|
|
</testing></pre>
|
|
|
|
|
<p>The following fragment defines a task called <code><call-cc></code> which take the
|
|
|
|
|
attributes <var>target</var>, <var>link</var> and <var>target.dir</var> and the nested
|
|
|
|
|
element <code>cc-elements</code>. The body of the task uses the <code><cc></code> task
|
2018-03-08 07:43:53 +01:00
|
|
|
from the <a href="http://ant-contrib.sourceforge.net/" target="_top">ant-contrib</a>
|
|
|
|
|
project.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre class="code">
|
2003-08-14 12:48:10 +00:00
|
|
|
<macrodef name="call-cc">
|
2018-02-28 07:58:59 +01:00
|
|
|
<attribute name="target"/>
|
|
|
|
|
<attribute name="link"/>
|
|
|
|
|
<attribute name="target.dir"/>
|
|
|
|
|
<element name="cc-elements"/>
|
|
|
|
|
<sequential>
|
|
|
|
|
<mkdir dir="${obj.dir}/@{target}"/>
|
|
|
|
|
<mkdir dir="@{target.dir}"/>
|
|
|
|
|
<cc link="@{link}" objdir="${obj.dir}/@{target}"
|
|
|
|
|
outfile="@{target.dir}/@{target}">
|
2003-08-14 12:48:10 +00:00
|
|
|
<compiler refid="compiler.options"/>
|
|
|
|
|
<cc-elements/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</cc>
|
|
|
|
|
</sequential>
|
|
|
|
|
</macrodef></pre>
|
|
|
|
|
<p>This then can be used as follows:</p>
|
|
|
|
|
<pre class="code">
|
2003-08-14 12:48:10 +00:00
|
|
|
<call-cc target="unittests" link="executable"
|
|
|
|
|
target.dir="${build.bin.dir}">
|
|
|
|
|
<cc-elements>
|
|
|
|
|
<includepath location="${gen.dir}"/>
|
|
|
|
|
<includepath location="test"/>
|
|
|
|
|
<fileset dir="test/unittest" includes = "**/*.cpp"/>
|
|
|
|
|
<fileset dir="${gen.dir}" includes = "*.cpp"/>
|
|
|
|
|
<linker refid="linker-libs"/>
|
|
|
|
|
</cc-elements>
|
2018-02-28 07:58:59 +01:00
|
|
|
</call-cc></pre>
|
|
|
|
|
<p>The following fragment shows <call-cc>, but this time using an implicit element and
|
|
|
|
|
with the <var>link</var> and <var>target.dir</var> arguments having default values.</p>
|
|
|
|
|
<pre class="code">
|
2004-05-27 14:38:46 +00:00
|
|
|
<macrodef name="call-cc">
|
|
|
|
|
<attribute name="target"/>
|
|
|
|
|
<attribute name="link" default="executable"/>
|
|
|
|
|
<attribute name="target.dir" default="${build.bin.dir}"/>
|
|
|
|
|
<element name="cc-elements" implicit="yes"/>
|
|
|
|
|
<sequential>
|
|
|
|
|
<mkdir dir="${obj.dir}/@{target}"/>
|
|
|
|
|
<mkdir dir="@{target.dir}"/>
|
|
|
|
|
<cc link="@{link}" objdir="${obj.dir}/@{target}"
|
|
|
|
|
outfile="@{target.dir}/@{target}">
|
2018-02-28 07:58:59 +01:00
|
|
|
<compiler refid="compiler.options"/>
|
|
|
|
|
<cc-elements/>
|
2004-05-27 14:38:46 +00:00
|
|
|
</cc>
|
|
|
|
|
</sequential>
|
2018-02-28 07:58:59 +01:00
|
|
|
</macrodef></pre>
|
|
|
|
|
<p>This then can be used as follows, note that <cc-elements> is not specified.</p>
|
|
|
|
|
<pre class="code">
|
2009-07-14 04:12:35 +00:00
|
|
|
<call-cc target="unittests">
|
2004-05-27 14:38:46 +00:00
|
|
|
<includepath location="${gen.dir}"/>
|
|
|
|
|
<includepath location="test"/>
|
|
|
|
|
<fileset dir="test/unittest" includes = "**/*.cpp"/>
|
|
|
|
|
<fileset dir="${gen.dir}" includes = "*.cpp"/>
|
|
|
|
|
<linker refid="linker-libs"/>
|
|
|
|
|
</call-cc>
|
2018-02-28 07:58:59 +01:00
|
|
|
</pre>
|
|
|
|
|
<p>The following shows the use of the <code>text</code> element.</p>
|
|
|
|
|
<pre class="code">
|
2004-01-27 17:43:25 +00:00
|
|
|
<macrodef name="echotest">
|
2004-05-07 18:00:43 +00:00
|
|
|
<text name="text"/>
|
2004-01-22 16:33:16 +00:00
|
|
|
<sequential>
|
|
|
|
|
<echo>@{text}</echo>
|
|
|
|
|
</sequential>
|
|
|
|
|
</macrodef>
|
|
|
|
|
<echotest>
|
|
|
|
|
Hello world
|
|
|
|
|
</echotest>
|
2018-02-28 07:58:59 +01:00
|
|
|
</pre>
|
|
|
|
|
<p>The following uses a prior defined attribute for setting the default value of another. The
|
|
|
|
|
output would be <code>one=test two=test</code>. If you change the order of lines *1 and *2 the
|
|
|
|
|
output would be <code>one=test two=@{one}</code>, because while processing
|
|
|
|
|
the <var>two</var>-line the value for <var>one</var> is not set.</p>
|
|
|
|
|
<pre class="code">
|
2005-03-23 18:48:59 +00:00
|
|
|
<macrodef name="test">
|
2018-02-28 07:58:59 +01:00
|
|
|
<attribute name="one"/> <strong>*1</strong>
|
|
|
|
|
<attribute name="two" default="@{one}"/> <strong>*2</strong>
|
2004-04-20 14:45:26 +00:00
|
|
|
<sequential>
|
|
|
|
|
<echo>one=@{one} two=@{two}</echo>
|
|
|
|
|
</sequential>
|
2005-03-23 18:48:59 +00:00
|
|
|
</macrodef>
|
2018-02-28 07:58:59 +01:00
|
|
|
<test one="test"/></pre>
|
2006-09-11 20:22:51 +00:00
|
|
|
|
2003-08-14 12:48:10 +00:00
|
|
|
</body>
|
2004-05-07 18:00:43 +00:00
|
|
|
</html>
|
