mirror of
https://github.com/apache/ant.git
synced 2025-05-18 05:54:48 +00:00
3a4980e3c4
find . -type f -exec sed -i "s/http:\/\/www.apache.org\/licenses\/LICENSE-2.0/https:\/\/www.apache.org\/licenses\/LICENSE-2.0/" {} \;
295 lines
11 KiB
HTML
295 lines
11 KiB
HTML
<!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>
|