巨集定義任務 - Ant 繁體中文

巨集定義

自 Apache Ant 1.6 起

說明

這會使用嵌套的 <sequential> 任務作為範本，定義一個新的任務。嵌套元素 <attribute> 和 <element> 用於指定新任務的屬性和元素。當執行新任務時，這些會被替換到 <sequential> 任務中。

注意

您也可以使用先前定義的屬性，作為其他屬性中的 預設 值。請參閱範例。

參數

屬性	說明	必要
name	新定義的名稱。	是
uri	此定義應存在的 uri。	否
description	巨集定義的說明（僅供文件使用）。	否
backtrace	如果在執行巨集時偵測到錯誤，這會控制錯誤追蹤。如果設為 true，會產生錯誤追蹤；如果設為 false，則不會產生。自 Ant 1.7 起。	否；預設 true

指定為嵌套元素的參數

attribute

這用於指定新任務的屬性。屬性的值會替換到範本任務中。除非已設定預設值，否則這些屬性會是必要的屬性。

此屬性會使用類似 Ant 屬性表示法的表示法置於範本任務的主體中—@{屬性名稱}。（可以記為「在此位置 AT 替換」）。

跳脫序列 @@ 用於跳脫 @。這允許 @{x} 置於文字中，而不使用 @@{x} 替換 x。這對應於屬性的 $$ 跳脫序列。

屬性名稱不分大小寫，因此 @{myAttribute} 與 @{MyAttribute} 的處理方式相同。

參數

屬性	說明	必要
name	新屬性的名稱	是
default	屬性的預設值。	否
description	這包含屬性的說明。自 Ant 1.6.1 起	否
doubleexpanding	控制屬性參照在屬性中是否展開兩次或僅一次。有關詳細資訊，請參閱常見問題。自 Ant 1.8.3 起	否；預設為 true

element

這用於指定新工作的新增元件。工作實例的新增元件內容會置於標籤名稱的範本工作中。

element 名稱的大小寫會被忽略。

參數

屬性	說明	必要
name	元件名稱。	是
選用	如果為 true，則此新增元件為選用。	否；預設為 false，表示新工作中需要新增元件
implicit	如果為 true，則此新增元件為隱含。這表示 `macrodef` 實例的任何新增元件都會置於此元件名稱所指示的元件中。如果元件為隱含，則只能有一個元件。自 Ant 1.6.2 起	否；預設為 false
description	包含說明，告知使用者預期元件內容為何。自 Ant 1.6.1 起	否

text

這用於指定巨集呼叫的文字內容處理方式。如果沒有此元件，則巨集呼叫中的任何新增文字都會是錯誤。如果存在 text 元件，則名稱會變成屬性，並設定為巨集呼叫的新增文字。自 Ant 1.6.1 起。

text 名稱的大小寫會被忽略。

參數

屬性	說明	必要
name	文字屬性的名稱。	是
選用	如果為 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"/>