从 Apache Ant 迁移构建 - Gradle 构建系统

Apache Ant 是一个在 Java 世界中历史悠久的构建工具，虽然使用它的团队数量正在减少，但它仍然被广泛使用。尽管它灵活，但它缺乏约定和 Gradle 提供的许多强大功能。迁移到 Gradle 是值得的，这样你的构建可以变得更精简、更简单、更快，同时仍然保留你使用 Ant 所享有的灵活性。你还将受益于对多项目构建的强大支持和易于使用、灵活的依赖管理。

从 Ant 迁移到 Gradle 的最大挑战是没有所谓的标准 Ant 构建。这使得提供具体说明变得困难。幸运的是，Gradle 具有一些与 Ant 的出色集成功能，可以使过程相对顺利。从基于 Ivy 的依赖管理迁移并不困难，因为 Gradle 有一个基于依赖配置的类似模型，它与 Ivy 兼容的仓库一起工作。

我们将首先概述从 Ant 迁移构建到 Gradle 时应考虑的事项，并提供一些关于如何进行的一般准则。

一般准则

当你将构建从 Ant 迁移到 Gradle 时，你应该记住你已经拥有的东西的性质以及你希望达到的目标。你想要一个镜像现有 Ant 构建结构的 Gradle 构建吗？还是想转向更符合 Gradle 习惯的东西？你正在寻找的主要好处是什么？

为了更好地理解，请考虑以下相互对立的场景：

通过 ant.importBuild() 导入的构建

这种方法快速、简单，适用于许多基于 Ant 的构建。你最终会得到一个与原始 Ant 构建基本相同的构建，只是你的 Ant 目标变成了 Gradle 任务。甚至目标之间的依赖关系也得以保留。

缺点是你仍然在使用 Ant 构建，你必须继续维护它。你还会失去 Gradle 的约定、许多插件、其依赖管理等等的优势。你仍然可以使用增量构建信息来增强构建，但这比正常的 Gradle 构建需要更多的努力。
一个符合 Gradle 习惯的构建

如果你想让你的构建具有未来性，那么这就是你想要达到的目标。利用 Gradle 的约定和插件将使构建更小、更易于维护，并且结构对许多 Java 开发人员来说都很熟悉。你还会发现更容易利用 Gradle 的强大功能来提高构建性能。

主要缺点是执行迁移需要额外的工作，特别是如果现有构建很复杂并且有许多项目间依赖。然而，这些构建通常从切换到惯用的 Gradle 中受益最大。此外，Gradle 提供了许多可以简化迁移的功能，例如能够直接从 Gradle 构建中使用核心和自定义 Ant 任务。

从长远来看，你理想上希望接近第二种选择，但你不必一蹴而就。

以下是一系列步骤，可帮助你决定要采取的方法以及如何进行：

将旧的 Ant 构建和新的 Gradle 构建并排放置。

你知道 Ant 构建是有效的，所以你应该保留它，直到你确信 Gradle 构建能产生所有相同的构件并满足你的需求。这也意味着用户可以尝试 Gradle 构建，而无需创建源代码树的新副本。

在准备好切换之前，不要尝试更改构建的目录和文件结构。
开发一种机制来验证两个构建产生相同的构件。

这是确保你的部署和测试不被破坏的关键一步。即使是细微的更改，例如 JAR 中清单文件的内容，也可能导致问题。如果你的 Gradle 构建产生与 Ant 构建相同的输出，这将为你和其他人切换提供信心，并使实施能带来最大收益的重大更改变得更容易。
决定你是否有多项目构建。

多项目构建通常比单项目构建更难迁移，并且需要更多的工作。我们在迁移多项目构建部分提供了专门的建议来帮助你完成此过程。
确定每个项目要使用的插件。

我们预计绝大多数 Ant 构建都用于基于 JVM 的项目，为此有大量插件提供了你所需的大部分功能。Gradle 插件包括与 Gradle 打包在一起的核心插件和插件门户上的有用社区插件。

即使 Java 插件或其衍生插件（例如 Java 库插件）与你的构建不完全匹配，你也应该至少考虑 Base 插件的生命周期任务。
导入 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 源文件。但是，你想继续使用创建库 JAR 文件的现有 package 任务。

以图表形式表示，此场景如下所示，每个框代表一个目标/任务：

想法是用标准的 Gradle compileJava 任务替换 Ant build 任务。此替换涉及几个步骤：

应用 Java 库插件。

这提供了图表中所示的 compileJava 任务。
重命名旧的 build 任务。

名称 build 与 Base Plugin（通过 Java Library Plugin）提供的标准 build 任务冲突。
配置编译以使用现有目录结构。

Ant 构建很有可能不符合标准的 Gradle 目录结构，因此你需要告诉 Gradle 在哪里找到源文件以及在哪里放置编译后的类，以便 package 可以找到它们。
更新任务依赖项。

compileJava 必须依赖于 prepare，package 必须依赖于 compileJava 而不是 ant_build，并且 assemble 必须依赖于 package 而不是标准的 Gradle jar 任务。

应用插件就像在 Gradle 构建脚本开头插入一个 plugins {} 块一样简单，即在 ant.importBuild() 之前。以下是如何应用 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 兼容仓库提供的托管依赖项会更容易，但这要求所有文件都符合命名约定“-.”。

如果你将依赖项存储在标准的 Maven 仓库布局中 — /// — 那么你可以定义一个带有 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 {} 块中，最好使用你应用的任何插件提供的标准配置。
对于不能被 Gradle 标准配置替换的任何自定义配置，将模块描述符中的所有配置声明转录到构建脚本的 configurations {} 块中。
将 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 任务：

→ generateDescriptorFileForMyLibraryPublication
→ publishMyLibraryPublicationToMyRepoRepository

还有一个方便的 publish 任务，它将所有发布发布到所有仓库。如果你想限制发布到特定的仓库，请查阅发布章节的相关部分。

关于依赖版本

默认情况下，Ivy 会在生成模块描述符时自动将依赖项的动态版本替换为已解析的“静态”版本。Gradle 不模仿此行为，声明的依赖项版本保持不变。

你可以通过使用 Nebula Ivy Resolved Plugin 来复制默认的 Ivy 行为。或者，你可以自定义描述符文件，使其包含你想要的版本。

处理自定义 Ant 任务

Ant 的优点之一是创建自定义任务并将其集成到构建中相当容易。如果你有这样的任务，那么将它们迁移到 Gradle 构建有两种主要选择：

从 Gradle 构建使用自定义 Ant 任务
将任务重写为自定义 Gradle 任务类型

第一种选择通常快速而简单。如果你想将任务集成到增量构建中，你必须使用增量构建运行时 API。你还经常需要处理 Ant 路径和文件集，这可能不方便。

第二种选择从长远来看更可取。Gradle 任务类型通常比 Ant 任务更简单，因为它们不必与基于 XML 的接口一起工作。你还会获得 Gradle 丰富 API 的好处。这种方法支持基于类型化属性的类型安全增量构建 API。

使用文件

Ant 有许多用于处理文件的任务，其中大部分都有 Gradle 等价物。与 Ant 到 Gradle 迁移的其他领域一样，你可以从 Gradle 构建中使用这些 Ant 任务。但是，我们强烈建议尽可能迁移到原生 Gradle 构造，以便构建受益于：

增量构建
更容易与构建的其他部分集成，例如依赖配置
更符合习惯的构建脚本

使用没有直接等价物的 Ant 任务（例如和）可能会很方便。但是，从长远来看，最好将这些任务转换为使用标准 Java API 或第三方库的原生 Gradle 任务类型。

以下是 Ant 构建中最常用的文件相关元素，以及它们的 Gradle 等价物：

— 首选 Gradle Copy 任务类型
(以及 Java 变体) — 首选 Zip 任务类型 (以及 Jar、War 和 Ear)
— 最好使用 Project.zipTree() 方法和 Copy 任务

你可以在使用文件一章中看到几个 Gradle 文件 API 的示例并了解更多信息。

关于路径和文件集

Ant 使用路径状结构和文件集的概念，使用户能够处理文件和目录的集合。Gradle 有一个更简单、更强大的模型，基于 FileCollection 和 FileTree，它们可以在构建中被视为对象。这两种类型都允许基于 Ant 的 glob 语法进行过滤，例如 **/books_*。你可以在使用文件一章中了解有关这些类型和 Gradle 文件 API 其他方面的更多信息。

如果你需要与需要 Ant 路径和文件集的 Ant 任务进行交互，可以通过 ant 对象在你的构建中构建它们。Ant 集成章节有使用和的示例。还有 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() 方法也透明地处理和任务，这允许分阶段迁移。

以下步骤突出显示了迁移多项目构建的建议方法：

首先学习 Gradle 如何配置多项目构建。
在构建的每个项目中创建一个 Gradle 构建脚本，并将其内容设置为此行：
```
ant.importBuild 'build.xml'
```
```
ant.importBuild("build.xml")
```
将 build.xml 替换为与项目对应的实际 Ant 构建文件的路径。如果没有对应的 Ant 构建文件，则将 Gradle 构建脚本留空。即使你的构建不适合这种迁移方法，也请继续执行这些步骤，看看是否仍有分阶段迁移的方法。
创建 settings 文件，其中包含所有现在具有 Gradle 构建脚本的项目。

实现项目间依赖。

你的多项目构建中的某些项目将依赖于该构建中一个或多个其他项目产生的构件。此类项目需要确保它们所依赖的项目已经产生了它们的构件，并且知道这些构件的路径。

确保所需构件的生成通常意味着通过任务调用其他项目的构建。不幸的是，这绕过了 Gradle 构建，从而抵消了你对 Gradle 构建脚本所做的任何更改。你需要用 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 构建，并且构建逻辑比以前少得多。