從 Apache Ant 遷移建置 - Gradle 建構系統

Apache Ant 是一個在 Java 世界中歷史悠久的建置工具，至今仍被廣泛使用，儘管使用團隊的數量正在減少。雖然 Ant 很靈活，但它缺乏慣例和 Gradle 提供的許多強大功能。遷移到 Gradle 是值得的，這樣您的建置可以變得更精簡、更簡單、更快速，同時仍然保留您在使用 Ant 時所享受的靈活性。您還將受益於對多專案建置的穩健支援以及易於使用、靈活的相依性管理。

從 Ant 遷移到 Gradle 的最大挑戰在於沒有所謂標準的 Ant 建置。這使得提供具體的指示變得困難。幸運的是，Gradle 具有一些與 Ant 整合的強大功能，可以使遷移過程相對順利。從基於 Ivy 的相依性管理遷移並不困難，因為 Gradle 具有類似的模型，基於與 Ivy 相容的儲存庫一起使用的相依性配置。

我們將首先概述您在將建置從 Ant 遷移到 Gradle 時應考慮的事項，並提供一些關於如何進行的一般準則。

一般準則

當您將建置從 Ant 遷移到 Gradle 時，您應該記住您已擁有的性質以及您希望達成的目標。您想要一個 Gradle 建置，它鏡像現有的 Ant 建置結構嗎？還是您想轉向更符合 Gradle 慣例的東西？您正在尋求的主要好處是什麼？

為了更好地理解，請考慮以下相反的情境

透過 ant.importBuild() 匯入建置

此方法快速、簡單，適用於許多基於 Ant 的建置。您最終得到的建置實際上與原始 Ant 建置相同，只是您的 Ant 目標變成了 Gradle 任務。甚至目標之間的相依性也被保留下來。

缺點是您仍然在使用 Ant 建置，您必須繼續維護它。您還失去了 Gradle 慣例、其許多外掛、其相依性管理等等的優勢。您仍然可以使用增量建置資訊來增強建置，但這比正常的 Gradle 建置需要更多的努力。
慣用的 Gradle 建置

如果您想為您的建置提供長遠的保障，這就是您想要達成的目標。利用 Gradle 的慣例和外掛將產生一個更小、更易於維護的建置，其結構對於許多 Java 開發人員來說都很熟悉。您還會發現更容易利用 Gradle 的強大功能來提高建置效能。

主要的缺點是執行遷移所需的額外工作，特別是如果現有的建置很複雜並且具有許多專案間相依性。但是，這些建置通常從切換到慣用的 Gradle 中受益最多。此外，Gradle 提供了許多可以簡化遷移的功能，例如直接從 Gradle 建置中使用核心和自訂 Ant 任務的能力。

理想情況下，您希望從長遠來看最終接近第二個選項，但您不必一步到位。

接下來是一系列步驟，以幫助您決定您想要採用的方法以及如何進行

將舊的 Ant 建置和新的 Gradle 建置並排放置。

您知道 Ant 建置可以工作，因此您應該保留它，直到您確信 Gradle 建置產生所有相同的工件並且在其他方面滿足您的需求。這也意味著使用者可以嘗試 Gradle 建置，而無需建立原始碼樹的新副本。

在您準備好進行切換之前，不要嘗試更改建置的目錄和檔案結構。
開發一種機制來驗證這兩個建置產生相同的工件。

這是至關重要的一步，以確保您的部署和測試不會中斷。即使是很小的更改，例如 JAR 檔案中 manifest 檔案的內容，也可能導致問題。如果您的 Gradle 建置產生與 Ant 建置相同的輸出，這將使您和其他人對切換充滿信心，並使實施將提供最大好處的重大變更變得更容易。
決定您是否有一個多專案建置。

多專案建置通常比單專案建置更難遷移，並且需要更多的工作。我們在遷移多專案建置章節中提供了一些專門的建議來幫助您完成此過程。
找出每個專案要使用的外掛。

我們預期絕大多數 Ant 建置都是針對基於 JVM 的專案，對於這些專案，有大量的外掛提供了您所需的大部分功能。Gradle 外掛包括與 Gradle 打包在一起的核心外掛和外掛入口網站上有用的社群外掛。

即使 Java 外掛或其衍生外掛之一（例如 Java 函式庫外掛）與您的建置不太匹配，您至少也應該考慮基礎外掛以取得其生命週期任務。
匯入 Ant 建置或從頭開始建立 Gradle 建置。

此步驟在很大程度上取決於您的建置需求。如果 Gradle 外掛的選擇可以完成您的 Ant 建置所做的大部分工作，那麼建立一個不依賴 Ant 建置的全新 Gradle 建置腳本可能更有意義。您可以自己實作缺少的部件，或使用現有的 Ant 任務。

另一種方法是將 Ant 建置匯入到 Gradle 建置腳本中，並逐步取代 Ant 建置功能。這允許您在每個階段都有一個可運作的 Gradle 建置，但它需要一些工作才能使 Gradle 任務與 Ant 任務正確協同工作。您可以在使用匯入的建置中了解更多相關資訊。
為現有的目錄和檔案結構配置您的建置

Gradle 利用慣例來消除與舊建置相關聯的大量樣板程式碼，並使熟悉這些慣例的使用者更容易使用新的建置。但這並不意味著您必須遵循它們。

Gradle 提供了許多配置選項，允許高度的自訂。這些選項通常透過提供慣例的外掛來提供。例如，用於生產 Java 程式碼的標準原始碼目錄結構 — src/main/java — 由 Java 外掛提供，它允許您配置不同的原始碼路徑。許多路徑可以透過 Project 物件上的屬性來修改。
如果您願意，可以遷移到標準 Gradle 慣例

一旦您確信 Gradle 建置正在產生與 Ant 建置相同的工件和其他資源，您可以考慮遷移到標準慣例，例如原始碼目錄路徑。這樣做將允許您移除覆蓋這些慣例所需的額外配置。新團隊成員也會發現更改後更容易使用建置。

是否值得付出努力和潛在的中斷，取決於您的特定建置和團隊，這由您自己決定。

本章的其餘部分涵蓋了您在遷移期間可能會遇到的一些常見情境，例如相依性管理和使用 Ant 任務。

使用匯入的建置

使用配置快取不支援匯入 Ant 建置。您需要完成轉換為 Gradle 才能獲得快取的好處。

許多遷移的第一步將涉及使用 ant.importBuild() 匯入 Ant 建置。那麼，如何在不一次性替換所有內容的情況下轉向標準 Gradle 建置？

要記住的重要一點是，Ant 目標變成了真正的 Gradle 任務，這意味著您可以執行諸如修改它們的任務相依性、附加額外的任務動作等等操作。這允許您將本機 Gradle 任務替換為等效的 Ant 任務，並維護與其他現有任務的任何連結。

舉例來說，假設您有一個 Java 函式庫專案，您想要從 Ant 遷移到 Gradle。Gradle 建置腳本具有匯入 Ant 建置的行，現在想要使用標準 Gradle 機制來編譯 Java 原始碼檔案。但是，您想繼續使用現有的 package 任務來建立函式庫的 JAR 檔案。

以圖表形式，情境如下所示，其中每個框代表一個目標/任務

這個想法是用標準 Gradle compileJava 任務替換 Ant build 任務。此替換涉及幾個步驟

應用 Java 函式庫外掛。

這提供了圖表中顯示的 compileJava 任務。
重新命名舊的 build 任務。

名稱 build 與基礎外掛（透過 Java 函式庫外掛）提供的標準 build 任務衝突。
配置編譯以使用現有的目錄結構。

Ant 建置很可能不符合標準 Gradle 目錄結構，因此您需要告訴 Gradle 在哪裡找到原始碼檔案以及將編譯後的類別放在哪裡，以便 package 可以找到它們。
更新任務相依性。

compileJava 必須依賴 prepare，package 必須依賴 compileJava 而不是 ant_build，並且 assemble 必須依賴 package 而不是標準 Gradle jar 任務。

應用外掛就像在 Gradle 建置腳本的開頭（即在 ant.importBuild() 之前）插入 plugins {} 區塊一樣簡單。以下是如何應用 Java 函式庫外掛

範例 1. 應用 Java 函式庫外掛

build.gradle.kts

plugins {
    `java-library`
}

build.gradle

plugins {
    id 'java-library'
}

要重新命名 build 任務，請使用 AntBuilder.importBuild() 的變體，該變體接受轉換器，如下所示

範例 2. 在匯入時重新命名目標

build.gradle.kts

ant.importBuild("build.xml") { oldTargetName ->
    if (oldTargetName == "build") "ant_build" else oldTargetName  (1)
}

build.gradle

ant.importBuild('build.xml') { String oldTargetName ->
    return oldTargetName == 'build' ? 'ant_build' : oldTargetName  (1)
}

1	將 `build` 目標重新命名為 `ant_build`，並保持所有其他目標不變

在建置 Java & JVM 專案中描述了配置不同的原始碼路徑。您可以以類似的方式更改編譯後類別的輸出目錄。

例如，如果原始 Ant 建置將這些路徑儲存在 Ant 屬性中；src.dir 用於 Java 原始碼檔案，classes.dir 用於輸出。以下是如何配置 Gradle 以使用這些路徑

範例 3. 配置原始碼集

build.gradle.kts

sourceSets {
    main {
        java.setSrcDirs(listOf(ant.properties["src.dir"]))
        java.destinationDirectory = file(ant.properties["classes.dir"] ?: layout.buildDirectory.dir("classes"))
    }
}

build.gradle

sourceSets {
    main {
        java {
            srcDirs = [ ant.properties['src.dir'] ]
            destinationDirectory = file(ant.properties['classes.dir'])
        }
    }
}

您最終應該切換到專案類型的標準目錄結構，以便能夠移除此自訂。

最後一步很簡單，涉及使用 Task.dependsOn 屬性和 Task.dependsOn() 方法來分離和連結任務。該屬性適用於替換相依性，而該方法是新增到現有相依性的首選方法。

以下是範例情境所需的任務相依性配置，應在 Ant 建置匯入之後進行

範例 4. 配置任務相依性

build.gradle.kts

tasks {
    compileJava {
        dependsOn("prepare")  (1)
    }
    named("package") {
        setDependsOn(listOf(compileJava))  (2)
    }
    assemble {
        setDependsOn(listOf("package"))  (3)
    }
}

build.gradle

compileJava.dependsOn 'prepare'  (1)
tasks.named('package') { dependsOn = [ 'compileJava' ] }  (2)
assemble.dependsOn = [ 'package' ]  (3)

1	使編譯依賴 `prepare` 任務
2	將 `package` 從 `ant_build` 任務中分離出來，並使其依賴 `compileJava`
3	將 `assemble` 從標準 Gradle `jar` 任務中分離出來，並使其改為依賴 `package`

這四個步驟將成功地用 Gradle 實作替換舊的 Ant 編譯。即使是這個小小的遷移也將為您帶來 Gradle 的增量 Java 編譯的優勢，從而加快建置速度。

這是一個階段性遷移的範例。將資源處理（例如屬性檔案）和封裝與此階段的編譯一起包含進來可能更有意義。

您必須問自己的重要問題之一是在每個階段遷移多少任務。您可以一次遷移的越多越好，但風險來自 Ant 建置中會受到變更影響的自訂步驟的數量。

例如，如果 Ant 建置遵循相當標準的編譯、靜態資源、封裝和單元測試方法，那麼將所有這些一起遷移可能是值得的。但是，如果建置對編譯後的類別執行一些額外的處理，或者在處理靜態資源時執行一些獨特的操作，那麼將這些任務拆分為單獨的階段可能更值得。

管理相依性

Ant 建置通常採用以下兩種方法之一來處理二進制相依性（例如函式庫）

將它們與專案一起儲存在本地 "lib" 目錄中
使用 Apache Ivy 來管理它們

它們各自需要不同的遷移到 Gradle 的技術，但您會發現這兩種情況下的過程都很簡單。讓我們在以下章節中詳細了解每種情況。

從目錄提供相依性

當您嘗試遷移一個將其相依性儲存在檔案系統上的建置時，無論是本地還是網路，您都應該考慮是否最終想要使用遠端儲存庫遷移到託管相依性。這是因為您可以透過以下兩種方式之一將檔案系統相依性納入 Gradle 建置中

定義一個平面目錄儲存庫並使用標準相依性宣告
將檔案直接附加到適當的相依性配置 (檔案相依性)

如果您採用第一種方法，則更容易遷移到從 Maven 或與 Ivy 相容的儲存庫提供的託管相依性，但這樣做需要您的所有檔案都符合命名慣例 "<moduleName>-<version>.<extension>"。

如果您將相依性儲存在標準 Maven 儲存庫佈局中 — <repoDir>/<group>/<module>/<version> — 那麼您可以定義一個帶有 file:// URL 的自訂 Maven 儲存庫。

為了示範這兩種技術，請考慮一個專案，其 libs 目錄中具有以下函式庫 JAR

libs
├── our-custom.jar
├── awesome-framework-2.0.jar
└── utility-library-1.0.jar

檔案 our-custom.jar 沒有版本號，因此必須作為檔案相依性新增。其他兩個 JAR 符合要求的命名慣例，可以宣告為從平面目錄儲存庫檢索的常規模組相依性。

以下範例建置腳本示範了如何將所有這些函式庫納入建置中

範例 5. 宣告從檔案系統提供的相依性

build.gradle.kts

repositories {
    flatDir {
        name = "libs dir"
        dir(file("libs"))  (1)
    }
}

dependencies {
    implementation(files("libs/our-custom.jar"))  (2)
    implementation(":awesome-framework:2.0")     (3)
    implementation(":utility-library:1.0")  (3)
}

build.gradle

repositories {
    flatDir {
        name = 'libs dir'
        dir file('libs')  (1)
    }
}

dependencies {
    implementation files('libs/our-custom.jar')  (2)
    implementation ':awesome-framework:2.0'  (3)
    implementation ':utility-library:1.0'  (3)
}

1	指定包含 JAR 檔案的目錄的路徑
2	為未版本化的 JAR 宣告檔案相依性
3	使用標準相依性座標宣告相依性 — 請注意，未指定群組，但每個標識符都有一個前導 `:`，表示一個空群組

上面的範例將把 our-custom.jar、awesome-framework-2.0.jar 和 utility-library-1.0.jar 新增到 implementation 配置中，該配置用於編譯專案的程式碼。

您也可以在這些模組相依性中指定群組，即使它們實際上沒有群組。這是因為平面目錄儲存庫只是忽略此資訊。然後，如果您稍後新增一個正常的 Maven 或與 Ivy 相容的儲存庫，Gradle 將從該儲存庫而不是平面目錄儲存庫下載使用群組宣告的模組相依性。

遷移 Ivy 相依性

Apache Ivy 是一個獨立的相依性管理工具，廣泛用於 Ant。它的工作方式與 Gradle 類似。事實上，它們都允許您

定義您自己的配置
從一個配置擴展另一個配置
將相依性附加到配置
從與 Ivy 相容的儲存庫解析相依性
將工件發布到與 Ivy 相容的儲存庫

最顯著的區別是 Gradle 針對特定類型的專案具有標準配置。例如，Java 外掛定義了諸如 implementation、testImplementation 和 runtimeOnly 之類的配置。如果需要，您可以定義自己的相依性配置。

因此，從 Ivy 遷移到 Gradle 通常很簡單

將您的模組描述符中的相依性宣告轉錄到 Gradle 建置腳本的 dependencies {} 區塊中，理想情況下使用您應用的任何外掛提供的標準配置。
將您的模組描述符中的任何配置宣告轉錄到建置腳本的 configurations {} 區塊中，以用於任何無法由 Gradle 標準配置替換的自訂配置。
將解析器從您的 Ivy 設定檔轉錄到建置腳本的 repositories {} 區塊中。

有關更多資訊，請參閱關於管理相依性配置、宣告相依性和宣告儲存庫的章節。

Ivy 提供了幾個 Ant 任務來處理 Ivy 的獲取相依性過程。該過程的基本步驟包括

配置 — 應用在 Ivy 設定檔中定義的配置
解析 — 找到宣告的相依性並在必要時將它們下載到快取
檢索 — 將快取的相依性複製到另一個目錄

Gradle 的過程類似，但您不必顯式調用前兩個步驟，因為它會自動執行它們。除非您建立一個任務來執行第三個步驟，否則第三個步驟根本不會發生 — 因為 Gradle 通常直接在類別路徑中和作為組裝應用程式套件的原始碼使用相依性快取中的檔案。

讓我們更詳細地了解 Ivy 的步驟如何映射到 Gradle

配置

Gradle 的大多數與相依性相關的配置都已內建到建置腳本中，正如您在 dependencies {} 區塊等元素中看到的那樣。另一個特別重要的配置元素是 resolutionStrategy，可以從相依性配置中訪問。這提供了您可能從 Ivy 的衝突管理器獲得的許多功能，並且是控制傳遞相依性和快取的強大方法。

某些 Ivy 配置選項在 Gradle 中沒有等效項。例如，沒有鎖定策略，因為 Gradle 保證其相依性快取是並發安全的。沒有 "最新策略" 方法，因為對於衝突解決，擁有可靠的單一策略更簡單。如果選擇了 "錯誤" 版本，您可以使用強制版本或其他解析選項來覆蓋它。

有關更多資訊，請參閱關於控制傳遞相依性的章節。

解析

在建置開始時，Gradle 將自動解析您已宣告的任何相依性，並將它們下載到其快取。Gradle 在儲存庫中搜尋這些相依性，搜尋順序由宣告儲存庫的順序定義。

值得注意的是，Gradle 支援與 Ivy 相同的動態版本語法，因此您仍然可以使用諸如 1.0.+ 之類的慣例。您也可以使用特殊的 latest.integration 和 latest.release 標籤。如果您決定使用此類動態和變更相依性，您可以透過 resolutionStrategy 為它們配置快取行為。

如果您正在使用動態和/或變更相依性，您可能還想考慮相依性鎖定。這是一種使建置更可靠並確保可重現性的方法。

檢索

如前所述，Gradle 不會自動從相依性快取複製檔案。其標準任務通常直接使用這些檔案。如果您想將相依性複製到本地目錄，您可以在建置腳本中使用 Copy 任務，如下所示

範例 6. 將相依性複製到本地目錄

build.gradle.kts

tasks.register<Copy>("retrieveRuntimeDependencies") {
    into(layout.buildDirectory.dir("libs"))
    from(configurations.runtimeClasspath)
}

build.gradle

tasks.register('retrieveRuntimeDependencies', Copy) {
    into layout.buildDirectory.dir('libs')
    from configurations.runtimeClasspath
}

配置也是檔案集合，因此它可以用於 from() 配置中。您可以使用類似的技術將配置附加到編譯任務或產生文件任務。有關 Gradle 檔案 API 的更多範例和資訊，請參閱關於檔案操作的章節。

發布工件

使用 Ivy 管理相依性的專案通常也使用它將 JAR 和其他工件發布到儲存庫。如果您正在遷移這樣的建置，那麼您會很高興知道 Gradle 內建了對將工件發布到與 Ivy 相容的儲存庫的支援。

在您嘗試遷移建置的這一特定方面之前，請閱讀發布章節以了解 Gradle 的發布模型。章節範例基於 Maven 儲存庫，但相同的模型也用於 Ivy 儲存庫。

基本遷移過程如下所示

將 Ivy 發布外掛應用於您的建置
配置至少一個發布，表示將要發布的內容（如果需要，包括其他工件）
配置一個或多個儲存庫以發布工件

完成所有這些操作後，您將能夠為每個發布產生一個 Ivy 模組描述符，並將它們發布到一個或多個儲存庫。

假設您已定義了一個名為 "myLibrary" 的發布和一個名為 "myRepo" 的儲存庫。Ivy 的 Ant 任務將映射到 Gradle 任務，如下所示

<deliver> → generateDescriptorFileForMyLibraryPublication
<publish> → publishMyLibraryPublicationToMyRepoRepository

還有一個方便的 publish 任務，它將所有發布發布到所有儲存庫。如果您想將發布限制為特定儲存庫，請查看發布章節的相關部分。

關於相依性版本

預設情況下，Ivy 將在產生模組描述符時自動將相依性的動態版本替換為解析後的 "靜態" 版本。Gradle 不模仿此行為，宣告的相依性版本保持不變。

您可以使用 Nebula Ivy Resolved 外掛來複製預設的 Ivy 行為。或者，您可以自訂描述符檔案，使其包含您想要的版本。

處理自訂 Ant 任務

Ant 的優點之一是它可以相當輕鬆地建立自訂任務並將其整合到建置中。如果您有這類任務，那麼有兩個主要選項可將它們遷移到 Gradle 建置

從 Gradle 建置中使用自訂 Ant 任務
將任務重寫為自訂 Gradle 任務類型

第一個選項通常快速又簡單。如果您想要將任務整合到增量建置中，則必須使用增量建置執行階段 API。您也經常需要使用 Ant 路徑和檔案集，這可能會很不方便。

第二個選項是長遠來看較佳的選擇。Gradle 任務類型往往比 Ant 任務更簡單，因為它們不必使用基於 XML 的介面。您還可以獲得 Gradle 豐富 API 的優勢。這種方法啟用了基於類型化屬性的類型安全增量建置 API。

使用檔案

Ant 有許多用於處理檔案的任務，其中大多數都有 Gradle 對應項。與 Ant 到 Gradle 遷移的其他領域一樣，您可以從 Gradle 建置中使用這些 Ant 任務。但是，我們強烈建議盡可能遷移到原生 Gradle 結構，以便建置受益於

增量建置
更輕鬆地與建置的其他部分整合，例如依賴關係配置
更符合慣例的建置腳本

使用沒有直接對應項的 Ant 任務（例如 <checksum> 和 <chown>）可能很方便。但是，從長遠來看，將這些轉換為使用標準 Java API 或第三方程式庫的原生 Gradle 任務類型可能會更好。

以下是 Ant 建置中使用最常見的檔案相關元素，以及 Gradle 對應項

<copy> — 偏好 Gradle Copy 任務類型
<zip>（加上 Java 變體）— 偏好 Zip 任務類型（加上 Jar、War 和 Ear）
<unzip> — 偏好將 Project.zipTree() 方法與 Copy 任務搭配使用

您可以在使用檔案章節中看到 Gradle 檔案 API 的幾個範例，並了解更多相關資訊。

關於路徑和檔案集

Ant 使用類似路徑的結構和檔案集概念，讓使用者能夠處理檔案和目錄的集合。Gradle 具有更簡單、更強大的模型，該模型基於 FileCollection 和 FileTree，它們可以在建置中被視為物件。這兩種類型都允許基於 Ant 的 glob 語法進行篩選，例如 **/books_*。您可以在使用檔案章節中了解有關這些類型和 Gradle 檔案 API 其他方面的更多資訊。

如果您需要與需要 Ant 路徑和檔案集的 Ant 任務互動，您可以透過 ant 物件從建置中建構 Ant 路徑和檔案集。Ant 整合章節中有使用 <path> 和 <fileset> 的範例。還有FileCollection 上的一個方法，它會將檔案集合轉換為檔案集或類似的 Ant 類型。

遷移 Ant 屬性

Ant 使用屬性映射來儲存可以在整個建置中重複使用的值。這種方法的主要缺點是屬性值都是字串，而且屬性本身的行為類似於全域變數。

在 Gradle 中與 Ant 屬性互動

有時您會想要直接從 Gradle 建置中使用 Ant 任務，而該任務需要設定一個或多個 Ant 屬性。

如果屬於這種情況，您可以透過 ant 物件輕鬆設定這些屬性，如從 Gradle 使用 Ant 章節中所述。

Gradle 確實使用了類似的形式，即專案屬性，這是參數化建置的合理方法。這些可以從命令列、gradle.properties 檔案中設定，或透過特別命名的系統屬性和環境變數設定。

如果您有現有的 Ant 屬性檔案，您可以將其內容複製到專案的 gradle.properties 檔案中。請注意

在 gradle.properties 中設定的屬性不會覆寫建置腳本中定義的同名額外專案屬性
匯入的 Ant 任務不會自動「看到」Gradle 專案屬性 — 您必須將它們複製到 Ant 屬性映射中才能實現

另一個需要理解的重要因素是，Gradle 建置腳本使用物件導向 API，而且通常最好盡可能使用任務、來源集和其他物件的屬性。例如，以下建置腳本片段建立用於將 Javadoc 文件封裝為 JAR 和解壓縮的任務，並透過其屬性連結任務

範例 7. 使用任務屬性代替專案屬性

build.gradle.kts

val tmpDistDir = layout.buildDirectory.dir("dist")

tasks.register<Jar>("javadocJarArchive") {
    from(tasks.javadoc)  (1)
    archiveClassifier = "javadoc"
}

tasks.register<Copy>("unpackJavadocs") {
    from(zipTree(tasks.named<Jar>("javadocJarArchive").get().archiveFile))  (2)
    into(tmpDistDir)  (3)
}

build.gradle

def tmpDistDir = layout.buildDirectory.dir('dist')

tasks.register('javadocJarArchive', Jar) {
    from javadoc  (1)
    archiveClassifier = 'javadoc'
}

tasks.register('unpackJavadocs', Copy) {
    from zipTree(javadocJarArchive.archiveFile)  (2)
    into tmpDistDir  (3)
}

1	封裝所有 `javadoc` 的輸出檔案 — 相當於 `from javadoc.destinationDir`
2	使用 `javadocJar` 任務持有的 Javadoc JAR 位置
3	使用名為 `tmpDistDir` 的專案屬性來定義 'dist' 目錄的位置

從 tmpDistDir 的範例中可以看出，通常需要透過屬性定義路徑，這就是為什麼 Gradle 也提供可以附加到專案、任務和某些其他物件類型的額外屬性。

遷移多專案建置

多專案建置是遷移的特殊挑戰，因為 Ant 中沒有用於建構它們或處理專案間依賴關係的標準方法。

幸運的是，Gradle 的多專案支援可以處理相當多樣化的專案結構，並且它比 Ant 提供更強大且更有幫助的支援，用於建構和維護多專案建置。ant.importBuild() 方法還可以透明地處理 <ant> 和 <antcall> 任務，這允許分階段遷移。

以下步驟重點介紹了遷移多專案建置的建議方法

首先學習Gradle 如何配置多專案建置。
在建置的每個專案中建立 Gradle 建置腳本，將其內容設定為此行
```
ant.importBuild 'build.xml'
```
```
ant.importBuild("build.xml")
```
將 build.xml 替換為與專案對應的實際 Ant 建置檔案的路徑。如果沒有對應的 Ant 建置檔案，則將 Gradle 建置腳本留空。即使您的建置不適合此遷移方法，也請繼續執行這些步驟，看看是否仍然有方法進行分階段遷移。
建立一個設定檔，該檔案包含現在具有 Gradle 建置腳本的所有專案。

實作專案間依賴關係。

多專案建置中的某些專案將依賴於該建置中一個或多個其他專案產生的成品。這類專案需要確保它們所依賴的專案已產生其成品，並且已知這些成品的路徑。

確保產生所需的成品通常意味著透過 <ant> 任務呼叫到其他專案的建置中。遺憾的是，這會繞過 Gradle 建置，否定您對 Gradle 建置腳本所做的任何變更。您需要將使用 <ant> 任務的目標替換為 Gradle 任務依賴關係。

例如，您的 Web 專案依賴於作為同一建置一部分的「util」程式庫。「web」的 Ant 建置檔案可能具有如下目標

web/build.xml

<target name="buildRequiredProjects">
    <ant dir="${root.dir}/util" target="build"/>  (1)
</target>

root.dir 必須由建置定義

這可以由對應 Gradle 建置腳本中的專案間任務依賴關係取代，如下列範例所示，該範例假設「web」專案的「compile」任務需要預先建置「util」

web/build.gradle.kts

ant.importBuild("build.xml")

tasks {
    named<Task>("compile") {
        setDependsOn(listOf(":util:build"))
    }
}

web/build.gradle

ant.importBuild 'build.xml'

compile.dependsOn = [ ':util:build' ]

這不如 Gradle 的專案依賴關係強大或功能強大，但它解決了眼前的問題，而無需對建置進行重大變更。只需小心移除或覆寫對委派給其他子專案的任務的任何依賴關係，例如 buildRequiredProjects 任務。

識別沒有依賴於其他專案的專案，並將它們遷移到符合慣例的 Gradle 建置腳本。

遵循本指南其餘部分的建議來遷移個別專案建置。如前所述，您應盡可能使用 Gradle 標準外掛程式。這可能意味著您需要在每個建置中新增額外的複製任務，以將產生的成品複製到 Ant 建置預期的位置。
當專案僅依賴於完全遷移的 Gradle 建置的專案時，遷移專案。

此時，您應該能夠切換為使用附加到適當依賴關係配置的正確專案依賴關係。
一旦 Ant 建置的任何部分都不再依賴專案，就清理專案。

我們在步驟 5 中提到，您可能需要新增複製任務來滿足依賴 Ant 建置的需求。一旦這些建置已遷移，就不再需要這類建置邏輯，應將其移除。

在此過程結束時，您應該擁有一個 Gradle 建置，您確信它可以按應有的方式運作，並且建置邏輯比以前少得多。