匯入

描述

將另一個建置檔案匯入目前專案。

執行時，它會選擇適當的 ProjectHelper 來解析匯入的檔案，使用與啟動時執行的演算法相同。然後，選取的 ProjectHelper 執行個體將負責實際解析匯入的檔案。

注意如上所述，此任務高度依賴 ProjectHelper 實作，本身並未執行任何工作。如果您已將 Apache Ant 設定為使用非 Ant 預設的 ProjectHelper，此任務可能會或可能不會運作。

在僅使用 Ant 預設專案幫手的常見使用案例中，它基本上就像Ant 常見問答集所說明的實體包含，就好像匯入的檔案包含在匯入檔案中，減去最上層的 <project> 標籤。

import 任務只能用作頂層任務。這表示它不能用於目標。

還有兩個進一步的功能面向與此任務有關，而實體包含無法做到

• 目標覆寫
• 特殊屬性

目標覆寫

如果主檔案中的目標也存在於至少一個匯入檔案中，則主檔案中的目標優先。

因此，如果我匯入例如包含名為 builddocs 的專案的 docsbuild.xml 檔案，其中包含 docs 目標，我可以在我的主建置檔案中定義 docs 目標，而那是將被呼叫的目標。這使得保留相同的目標名稱變得容易，因此覆寫的目標仍會被任何其他目標（在主建置檔案或匯入的建置檔案中）呼叫，而這些目標是其相依性，具有不同的實作。docsbuild.xml 中的目標可透過名稱 builddocs.docs 使用。這讓新的實作可以呼叫舊目標，因此透過在目標之前或之後呼叫的任務來增強目標。

如果您使用任務的 as 屬性，其值將用於為覆寫的目標名稱加上前綴，而不是 project 標籤的 name 屬性。

特殊屬性

匯入檔案會視為存在於主建置檔中。這很易於理解，但這使得它們無法參照相對於其路徑的檔案和資源。因此，對於每個匯入檔案，Ant 會新增一個包含匯入建置檔路徑的屬性。使用此路徑，匯入的建置檔可以保留資源，並能夠相對於其位置參照它們。

因此，如果我匯入例如名為 builddocs 的 docsbuild.xml 檔案，我可以取得其路徑為 ant.file.builddocs，類似於主建置檔的 ant.file 屬性。

請注意，builddocs 不是檔案名稱，而是匯入的 project 標籤中存在的 name 屬性。

如果匯入的檔案沒有 name 屬性，則不會設定 ant.file.projectname 屬性。

自 Ant 1.8.0 起，此任務也可以從 URL 或類別路徑資源（實際上是 URL）匯入資源。如果您需要知道目前的建置檔案來源是檔案或 URL，您可以查詢屬性 ant.file.type.projectname（使用與上述相同的範例 ant.file.type.builddocs），其值為 file 或 url。

解析匯入檔案的檔案

假設您的主建置檔名為 importing.xml，它匯入位於檔案系統中任何位置的建置檔 imported.xml，而 imported.xml 從 imported.properties 讀取一組屬性

<!-- importing.xml -->
<project name="importing" basedir="." default="...">
  <import file="${path_to_imported}/imported.xml"/>
</project>

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <property file="imported.properties"/>
</project>

然而，此程式碼片段會解析 importing.xml 的 basedir 的 imported.properties，因為 Ant 會忽略 imported.xml 的 basedir。使用 imported.properties 的正確方法是

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <dirname property="imported.basedir" file="${ant.file.imported}"/>
  <property file="${imported.basedir}/imported.properties"/>
</project>

如上所述，ant.file.imported 會儲存建置腳本的路徑，該腳本定義稱為 imported 的專案（簡而言之，它會儲存 imported.xml 的路徑），而 <dirname> 會取得其目錄。此技術也允許 imported.xml 作為獨立檔案使用（不用匯入其他專案）。

上述說明僅適用於實際從檔案匯入而非從 URL 匯入的匯入檔案。對於使用相對於匯入檔案的資源從 URL 匯入的檔案，您需要使用可以處理非檔案資源的任務。若要建立相對資源，您會使用類似以下的內容

<loadproperties>
  <url baseUrl="${ant.file.imported}"
       relativePath="imported.properties"/>
</loadproperties>

參數

以巢狀元素指定參數

任何 資源 或資源集合

自 Ant 1.8.0 起

將匯入指定的資源。

範例

<import file="../common-targets.xml"/>

從父目錄中的 common-targets.xml 檔案匯入目標。

<import file="${deploy-platform}.xml"/>

匯入由屬性 deploy-platform 定義的專案

<import>
  <javaresource name="common/targets.xml">
    <classpath location="common.jar"/>
  </javaresource>
</import>

從 jar 檔案 common.jar 中的目錄 common 內的 targets.xml 檔案匯入目標。

<import> 與 <include> 有何不同？

簡短版本：如果您打算覆寫目標，請使用 import，否則請使用 include。

使用 import 時，匯入的目標最多可以使用兩個名稱：沒有任何前置字元的「一般」名稱，以及可能帶有前置字元的名稱（as 屬性的值，或匯入專案的 name 屬性，如果有的話）。

使用 include 時，包含的目標只能使用帶有前置字元的形式。

使用 import 時，匯入目標的 depends 屬性保持不變，即使用「一般」名稱，並允許您覆寫相依性清單中的目標。

使用 include 時，無法覆寫包含的目標，且其 depends 屬性會重新寫入，以便使用帶有前置字元的名稱。這允許包含檔案的撰寫者控制作為相依性一部分而呼叫的目標。

可以使用不同的前置字元多次 include 同一個檔案；無法多次 import 同一個檔案。

範例

nested.xml 應為

<project>
  <target name="setUp">
    <property name="prop" value="in nested"/>
  </target>

  <target name="echo" depends="setUp">
    <echo>prop has the value ${prop}</echo>
  </target>
</project>

在 import 中使用時，如下所示

<project default="test">
  <target name="setUp">
    <property name="prop" value="in importing"/>
  </target>

  <import file="nested.xml" as="nested"/>

  <target name="test" depends="nested.echo"/>
</project>

執行建置檔案會發出

setUp:

nested.echo:
     [echo] prop has the value in importing

test:

當使用 include 時，就像在

<project default="test">
  <target name="setUp">
    <property name="prop" value="in importing"/>
  </target>

  <include file="nested.xml" as="nested"/>

  <target name="test" depends="nested.echo"/>
</project>

執行目標建置檔案會發出

nested.setUp:

nested.echo:
     [echo] prop has the value in nested

test:

而且包含的建置檔案中不會有任何名為 echo 的目標。