第一次提交
This commit is contained in:
dengtongyu committed
commit
8121362a03
4412 files changed
+1091845
No files matched your search
@@ -0,0 +1,294 @@
|
||||
<!--
|
||||
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.
|
||||
-->
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<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>
|
||||
Reference in new issue
Block a user