<!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>MacroDef Task</title>
</head>
<body>
<h2 id="macrodef">MacroDef</h2>
<p><em>Since Apache Ant 1.6</em></p>
<h3>Description</h3>
<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>
<h3>Note</h3>
<p>You can also use <em>prior defined</em> attributes for <var>default</var> values in other
attributes. See the examples.</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>name</td>
<td>The name of the new definition.</td>
<td>Yes</td>
</tr>
<tr>
<td>uri</td>
<td>
The uri that this definition should live in.
</td>
<td>No</td>
</tr>
<tr>
<td>description</td>
<td>A description of the macrodef
(for documentation purposes only).
</td>
<td>No</td>
</tr>
<tr>
<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>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>attribute</h4>
<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>
<h5>Parameters</h5>
<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 new attribute</td>
<td>Yes</td>
</tr>
<tr>
<td>default</td>
<td>The default value of the attribute.</td>
<td>No</td>
</tr>
<tr>
<td>description</td>
<td>This contains a description of the attribute. <em>Since Ant 1.6.1</em></td>
<td>No</td>
</tr>
<tr>
<td>doubleexpanding</td>
<td>Controls whether or not property references in the attribute are expanded twice or just
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>
<td>No; default is <q>true</q></td>
</tr>
</table>
<h4>element</h4>
<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>
<h5>Parameters</h5>
<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 element.</td>
<td>Yes</td>
</tr>
<tr>
<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>
</tr>
<tr>
<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>
</tr>
<tr>
<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>
</tr>
</table>
<h4>text</h4>
<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>
<h5>Parameters</h5>
<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 text attribute.</td>
<td>Yes</td>
</tr>
<tr>
<td>optional</td>
<td>If <q>true</q> nested text in the macro is optional.</td>
<td>No; default is <q>false</q></td>
</tr>
<tr>
<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>
</tr>
<tr>
<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>
</tr>
</table>
<h3>Examples</h3>
<p>The following example defined a task called testing and runs it.</p>
<pre>
<macrodef name="testing">
<attribute name="v" default="NOT SET"/>
<element name="some-tasks" optional="yes"/>
<sequential>
<echo>v is @{v}</echo>
<some-tasks/>
</sequential>
</macrodef>
<testing v="This is v">
<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
from the <a href="http://ant-contrib.sourceforge.net/" target="_top">ant-contrib</a>
project.</p>
<pre>
<macrodef name="call-cc">
<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}">
<compiler refid="compiler.options"/>
<cc-elements/>
</cc>
</sequential>
</macrodef></pre>
<p>This then can be used as follows:</p>
<pre>
<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>
</call-cc></pre>
<p>The following fragment shows <code><call-cc></code>, but this time using an implicit
element and with the <var>link</var> and <var>target.dir</var> arguments having default
values.</p>
<pre>
<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}">
<compiler refid="compiler.options"/>
<cc-elements/>
</cc>
</sequential>
</macrodef></pre>
<p>This then can be used as follows, note that <code><cc-elements></code> is not
specified.</p>
<pre>
<call-cc target="unittests">
<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>
</pre>
<p>The following shows the use of the <code>text</code> element.</p>
<pre>
<macrodef name="echotest">
<text name="text"/>
<sequential>
<echo>@{text}</echo>
</sequential>
</macrodef>
<echotest>
Hello world
</echotest>
</pre>
<p>The following uses a prior defined attribute for setting the default value of another. The
output would be <code class="output">one=test two=test</code>. If you change the order of
lines *1 and *2 the output would be <code class="output">one=test two=@{one}</code>, because
while processing the <var>two</var>-line the value for <var>one</var> is not set.</p>
<pre>
<macrodef name="test">
<attribute name="one"/> <strong>*1</strong>
<attribute name="two" default="@{one}"/> <strong>*2</strong>
<sequential>
<echo>one=@{one} two=@{two}</echo>
</sequential>
</macrodef>
<test one="test"/></pre>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
8fad0817607a09309c3e5b12a09dac58
>
files
>
98
