Subant 任務

自 Apache Ant 1.6 起

說明

呼叫所有已定義子建置的特定目標。這是 Ant 的擴充功能，用於大量專案執行。如果這個任務呼叫它所屬的同一個建置檔，則不得在 target 外部使用。

subant 在內部使用 ant，因此 ant 手冊頁面中所述的許多事項也適用於此。

與目錄搭配使用

subant 可與目錄組搭配使用，以從不同的目錄執行建置。提供 2 種不同的選項

若要使用不同的基本目錄執行同一個建置檔 /somepath/otherpath/mybuild.xml，請使用 genericantfile 屬性
若要執行 directory1/mybuild.xml、directory2/mybuild.xml、...，請使用 antfile 屬性。subant 任務不會在此情況下為您設定基本目錄，因為您可以在每個建置檔中指定它。

參數

屬性	說明	類型	必要
antfile	建置檔名稱，與目錄搭配使用。	字串	否；預設為 build.xml，如果設定 `genericantfile`，則會忽略
buildpath	設定用於尋找子專案的建置路徑。	路徑	否
buildpathref	要使用的建置路徑，透過參照。	參照
failonerror	設定是否在發生錯誤時以建置例外狀況失敗，或繼續執行。	布林
genericantfile	建置檔路徑，與目錄搭配使用。使用 `genericantfile`，以便使用不同的 `basedir` 執行同一個建置檔。如果設定這個屬性，則會忽略 `antfile`。	檔案
inheritall	對應於 `<ant>` 的 `inheritall` 屬性，但在這個任務中預設為 false。	布林
inheritrefs	對應於 `<ant>` 的 `inheritrefs` 屬性。	布林
output	對應於 `<ant>` 的 `output` 屬性。	字串
target		字串
verbose	啟用/停用記錄訊息，在進入/離開每個子建置路徑時顯示。	布林	否；預設為 false

參數作為巢狀元素

任何基於檔案系統的資源集合

這包括 <fileset>、<dirset> 和 <filelist>，這些是 Ant 1.7 之前支援的巢狀資源集合。

dirset (org.apache.tools.ant.types.DirSet)

將目錄組新增至隱含的建置路徑。

請注意，目錄會以無特定順序新增至建置路徑，因此如果順序很重要，應該改用檔案清單！

filelist (org.apache.tools.ant.types.FileList)

將已排序的檔案清單新增至隱含的建置路徑。

請注意，與檔案和目錄組不同，檔案清單可以參照不存在的檔案或目錄！

fileset (org.apache.tools.ant.types.FileSet)

將檔案組新增至隱含的建置路徑。

請注意，目錄會以無特定順序新增至建置路徑，因此如果順序很重要，應該改用檔案清單！

property (org.apache.tools.ant.taskdefs.Property)

對應於 <ant> 的巢狀 <property> 元素。

當多個巢狀 <property> 元素要設定同一個名稱的屬性時，最後宣告的元素會獲勝。這是為了向後相容性，即使它與建置檔案中 <property> 任務的行為不同。

propertyset (org.apache.tools.ant.types.PropertySet)

對應於 <ant> 的巢狀 <propertyset> 元素。

buildpath (org.apache.tools.ant.types.Path)

建立巢狀建置路徑，並將其新增至隱含的建置路徑。

buildpathelement (org.apache.tools.ant.types.Path.PathElement)

建立巢狀 <buildpathelement>，並將其新增至隱含的建置路徑。

target (org.apache.tools.ant.taskdefs.Ant.TargetElement)

自 Ant 1.7 起.

您可以使用巢狀 <target> 元素指定多個目標，而不是使用目標屬性。這些目標會執行，就像 Ant 被呼叫時只有一個目標，其相依性為以指定順序指定的目標。

屬性	說明	必要
name	呼叫目標的名稱。	是

範例

這個片段建置檔案會在專案目錄的每個子目錄中執行 ant，在這些子目錄中可以找到名為 build.xml 的檔案。屬性 build.dir 在 subant 呼叫的 Ant 專案中會具有值 subant1.build。

<project name="subant" default="subant1">
    <property name="build.dir" value="subant.build"/>
    <target name="subant1">
        <subant target="">
            <property name="build.dir" value="subant1.build"/>
            <property name="not.overloaded" value="not.overloaded"/>
            <fileset dir="." includes="*/build.xml"/>
        </subant>
    </target>
</project>

這個片段建置檔案會在專案目錄的每個子目錄中執行 ant，在這些子目錄中可以找到名為 build.xml 的檔案。所有名稱以 foo 開頭的屬性都會傳遞，其名稱會變更為以 bar 開頭

<subant target="">
    <propertyset>
        <propertyref prefix="toplevel"/>
        <mapper type="glob" from="foo*" to="bar*"/>
    </propertyset>
    <fileset dir="." includes="*/build.xml"/>
</subant>

假設專案目錄的子目錄稱為 projects1、projects2、projects3，此程式碼片段會執行 /opt/project/build1.xml 的 compile 目標，將 basedir 設定為 projects1、projects2、projects3

<subant target="compile" genericantfile="/opt/project/build1.xml">
    <dirset dir="." includes="projects*"/>
</subant>

現在來看看一個稍微複雜一點，但有用的場景。假設我們有以下目錄結構

root
  |  common.xml
  |  build.xml
  |
  +-- modules
        +-- modA
        |     +-- src
        +-- modB
              +-- src

common.xml:

<project>
    <property name="src.dir"      value="src"/>
    <property name="build.dir"    value="build"/>
    <property name="classes.dir"  value="${build.dir}/classes"/>

    <target name="compile">
        <mkdir dir="${classes.dir}"/>
        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
    </target>

    <!-- more targets -->
</project>

build.xml:

<project>
    <macrodef name="iterate">
        <attribute name="target"/>
        <sequential>
            <subant target="@{target}">
                <fileset dir="modules" includes="*/build.xml"/>
            </subant>
        </sequential>
    </macrodef>

    <target name="compile">
        <iterate target="compile"/>
    </target>

    <!-- more targets -->
</project>

modules/modA/build.xml:

<project name="modA">
    <import file="../../common.xml"/>
</project>

這會在模組中產生非常小的建置檔案、可維護的建置檔案 (common.xml)，以及明確的專案結構。此外，根目錄建置檔案有能力執行所有模組的整體建置。

此工作會為每個子專案執行 clean build。

<subant failonerror="false">
    <fileset dir="." includes="**/build.xml" excludes="build.xml"/>
    <target name="clean"/>
    <target name="build"/>
</subant>

提示：由於建置檔案是純 XML，您可以使用 XSLT 轉換從共用建置檔案產生主建置檔案

<xslt in="common.xml"
      out="master.xml"
      style="${ant.home}/etc/common2master.xsl"/>