宏定义任务 - Ant 中文

MacroDef

自 Apache Ant 1.6 起

描述

这使用一个<sequential>嵌套任务作为模板来定义一个新的任务。嵌套元素<attribute>和<element>用于指定新任务的属性和元素。当运行新任务时，这些元素会被替换到<sequential>任务中。

注意

您也可以使用先前定义的属性为其他属性的默认值。请参阅示例。

参数

属性	描述	必需
name	新定义的名称。	是
uri	此定义应该所在的 uri。	否
description	宏定义的描述（仅用于文档目的）。	否
backtrace	这控制了在运行宏时检测到错误时的错误回溯。如果设置为true，则会有错误回溯，如果设置为false，则不会有错误回溯。自 Ant 1.7 起。	否；默认值为true

作为嵌套元素指定的参数

attribute

这用于指定新任务的属性。属性的值会被替换到模板化的任务中。除非设置了默认值，否则这些属性将是必需的属性。

此属性使用类似于 Ant 属性表示法的符号放置在模板化任务的主体中——@{attribute name}。（可以记住为“将替换放在这个位置”）。

转义序列@@用于转义@。这允许@{x}放置在文本中而不会将x替换，方法是使用@@{x}。这对应于属性的$$转义序列。

属性的大小写被忽略，因此@{myAttribute}与@{MyAttribute}的处理方式相同。

参数

属性	描述	必需
name	新属性的名称	是
default	属性的默认值。	否
description	这包含对属性的描述。自 Ant 1.6.1 起	否
doubleexpanding	控制属性引用在属性中是扩展两次还是只扩展一次。有关详细信息，请参阅常见问题解答。自 Ant 1.8.3 起	否；默认值为true

element

这用于指定新任务的嵌套元素。任务实例的嵌套元素的内容将放置在模板化任务中的标签名称处。

element名称的大小写被忽略。

参数

属性	描述	必需
name	元素的名称。	是
optional	如果为true，则此嵌套元素是可选的。	否；默认值为false——新任务中需要嵌套元素
implicit	如果为true，则此嵌套元素是隐式的。这意味着`macrodef`实例的任何嵌套元素都将放置在由此元素的名称指示的元素中。如果元素是隐式的，则只能有一个元素。自 Ant 1.6.2 起	否；默认值为false
description	这包含一个描述，告知用户元素的内容应该是什么。自 Ant 1.6.1 起	否

text

这用于指定宏调用的文本内容的处理方式。如果此元素不存在，则宏调用中的任何嵌套文本都将是错误。如果text元素存在，则名称将成为一个属性，该属性被设置为宏调用的嵌套文本。自 Ant 1.6.1 起。

text名称的大小写被忽略。

参数

属性	描述	必需
name	文本属性的名称。	是
optional	如果为true，则宏中的嵌套文本是可选的。	否；默认值为false
trim	如果为true，则嵌套文本将被修剪掉空白。	否；默认值为false
description	这包含一个描述，告知用户宏的嵌套文本应该是什么。	否

示例

以下示例定义了一个名为 testing 的任务并运行它。

<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>

以下片段定义了一个名为<call-cc>的任务，它接受属性target、link和target.dir以及嵌套元素cc-elements。任务的主体使用来自ant-contrib项目的<cc>任务。

<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>

然后可以按如下方式使用它

<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>

以下片段显示了<call-cc>，但这次使用了一个隐式元素，并且link和target.dir参数具有默认值。

<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>

然后可以按如下方式使用它，请注意没有指定<cc-elements>。

<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>

以下显示了text元素的使用。

<macrodef name="echotest">
   <text name="text"/>
   <sequential>
      <echo>@{text}</echo>
   </sequential>
</macrodef>
<echotest>
   Hello world
</echotest>

以下使用先前定义的属性来设置另一个属性的默认值。输出将是one=test two=test。如果您更改*1 和 *2 行的顺序，输出将是one=test two=@{one}，因为在处理two行时，one的值尚未设置。

<macrodef name="test">
   <attribute name="one"/>                     *1
   <attribute name="two" default="@{one}"/>    *2
   <sequential>
      <echo>one=@{one}   two=@{two}</echo>
   </sequential>
</macrodef>
<test one="test"/>