编写 Gradle 插件

Android Gradle 插件 (AGP) 是 Android 应用程序的官方构建系统。它包含对编译许多不同类型源代码并将其链接到可在物理 Android 设备或模拟器上运行的应用程序的支持。

AGP 包含用于插件的扩展点，以控制构建输入并通过可以与标准构建任务集成的新的步骤扩展其功能。早期版本的 AGP 没有明确与内部实现分开的正式 API。从 7.0 版本开始，AGP 有一组您可以依赖的正式的稳定 API。

AGP API 生命周期

AGP 遵循Gradle 功能生命周期 来指定其 API 的状态

• 内部：不适用于公开使用
• 孵化：可供公开使用，但尚未最终确定，这意味着它们在最终版本中可能不向后兼容
• 公开：可供公开使用且稳定
• 已弃用：不再支持，并已由新 API 替代

弃用策略

AGP 正在发展，其中包括弃用旧 API 并将其替换为新的稳定 API 和新的领域特定语言 (DSL)。此演变将跨越多个 AGP 版本，您可以在AGP API/DSL 迁移时间表 中了解更多信息。

当 AGP API 因此迁移或其他原因而被弃用时，它们将继续在当前主要版本中可用，但会生成警告。已弃用的 API 将在随后的主要版本中完全从 AGP 中删除。例如，如果某个 API 在 AGP 7.0 中被弃用，它将在该版本中可用并生成警告。该 API 将不再在 AGP 8.0 中可用。

要查看在常见构建自定义中使用的新 API 示例，请查看Android Gradle 插件配方。它们提供了常见构建自定义的示例。您还可以在我们的参考文档中找到有关新 API 的更多详细信息。

Gradle 构建基础

本指南不涵盖整个 Gradle 构建系统。但是，它确实涵盖了帮助您与我们的 API 集成的必要概念集，并链接到主要 Gradle 文档以供进一步阅读。

我们确实假设您了解 Gradle 的基本工作原理，包括如何配置项目、编辑构建文件、应用插件和运行任务。要了解有关 AGP 方面 Gradle 基础知识，我们建议您查看配置您的构建。要了解自定义 Gradle 插件的通用框架，请参阅开发自定义 Gradle 插件。

Gradle 惰性类型词汇表

Gradle 提供了许多行为“惰性”的类型，或者有助于将繁重的计算或Task创建延迟到构建的后期阶段。这些类型是许多 Gradle 和 AGP API 的核心。以下列表包含参与惰性执行的主要 Gradle 类型及其关键方法。

Provider<T>

提供类型为T（其中“T”表示任何类型）的值，可以在执行阶段使用get()读取，或使用map()、flatMap()和zip()方法转换为新的Provider<S>（其中“S”表示某些其他类型）。请注意，在配置阶段永远不应该调用get()。

• map()：接受一个lambda并生成类型为S的Provider，Provider<S>。map()的 lambda 参数获取值T并生成值S。lambda 不会立即执行；相反，它的执行会延迟到在生成的Provider<S>上调用get()的那一刻，使整个链惰性执行。
• flatMap()：也接受一个 lambda 并生成Provider<S>，但 lambda 获取值T并生成Provider<S>（而不是直接生成值S）。当在配置时无法确定 S 并且您只能获得Provider<S>时，使用 flatMap()。实际上，如果您使用了map()并最终得到了Provider<Provider<S>>结果类型，则可能意味着您应该改用flatMap()。
• zip()：允许您组合两个Provider实例以生成一个新的Provider，其值使用一个函数计算，该函数组合来自两个输入Providers实例的值。

Property<T>

实现Provider<T>，因此它也提供类型为T的值。与Provider<T>（它是只读的）不同，您还可以为Property<T>设置值。有两种方法可以做到这一点

• 在可用时直接设置类型为T的值，无需延迟计算。
• 设置另一个Provider<T>作为Property<T>的值源。在这种情况下，仅当调用Property.get()时才会具体化值T。

TaskProvider

实现Provider<Task>。要生成TaskProvider，请使用tasks.register()而不是tasks.create()，以确保仅在需要时才惰性实例化任务。您可以使用flatMap()在创建Task之前访问Task的输出，如果您想将输出用作其他Task实例的输入，这将非常有用。

Provider 及其转换方法对于以惰性方式设置任务的输入和输出至关重要，即无需预先创建所有任务并解析值。

Provider 还承载任务依赖信息。当您通过转换Task输出创建Provider时，该Task成为Provider的隐式依赖项，并且将在解析Provider的值时创建和运行，例如当另一个Task需要它时。

以下是如何注册两个任务GitVersionTask和ManifestProducerTask的示例，同时将Task实例的创建延迟到实际需要时。将ManifestProducerTask输入值设置为从GitVersionTask输出获得的Provider，因此ManifestProducerTask隐式依赖于GitVersionTask。

// Register a task lazily to get its TaskProvider.
val gitVersionProvider: TaskProvider =
    project.tasks.register("gitVersionProvider", GitVersionTask::class.java) {
        it.gitVersionOutputFile.set(
            File(project.buildDir, "intermediates/gitVersionProvider/output")
        )
    }

...

/**
 * Register another task in the configuration block (also executed lazily,
 * only if the task is required).
 */
val manifestProducer =
    project.tasks.register(variant.name + "ManifestProducer", ManifestProducerTask::class.java) {
        /**
         * Connect this task's input (gitInfoFile) to the output of
         * gitVersionProvider.
         */
        it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
    }

只有在显式请求这两个任务时，它们才会执行。这可能作为 Gradle 调用的一部分发生，例如，如果您运行./gradlew debugManifestProducer，或者如果ManifestProducerTask的输出连接到其他一些任务并且其值变得必需。

虽然您将编写使用输入和/或生成输出的自定义任务，但 AGP 不会直接提供对其自身任务的公共访问权限。它们是实现细节，可能会因版本而异。相反，AGP 提供了 Variant API 并访问其任务的输出或构建工件，您可以读取和转换这些输出。有关更多信息，请参阅本文档中的Variant API、工件和任务。

Gradle 构建阶段

构建项目本身就是一个复杂且需要大量资源的过程，并且有各种功能（例如任务配置避免、最新检查和配置缓存功能）有助于最大限度地减少花费在可重现或不必要的计算上的时间。

为了应用其中一些优化，Gradle 脚本和插件必须在每个不同的 Gradle 构建阶段（初始化、配置和执行）期间遵守严格的规则。在本指南中，我们将重点关注配置和执行阶段。您可以在Gradle 构建生命周期指南中找到有关所有阶段的更多信息。

配置阶段

在配置阶段，将评估构建中所有项目的构建脚本，应用插件并解析构建依赖项。此阶段应用于使用 DSL 对象配置构建，以及以惰性方式注册任务及其输入。

由于配置阶段始终运行，而不管请求运行哪个任务，因此保持其精简并限制任何计算不依赖于除构建脚本本身之外的输入尤其重要。也就是说，您不应该执行外部程序或从网络读取，或者执行可以延迟到执行阶段作为适当的Task实例的长时间计算。

执行阶段

在执行阶段，将执行请求的任务及其依赖任务。具体来说，将执行用@TaskAction标记的Task类方法。在任务执行期间，您可以从输入（例如文件）中读取并通过调用Provider<T>.get()解析惰性提供程序。以这种方式解析惰性提供程序会启动一系列遵循提供程序中包含的任务依赖信息的map()或flatMap()调用。任务以惰性方式运行以具体化所需的值。

Variant API、工件和任务

Variant API 是 Android Gradle 插件中的扩展机制，它允许您操作各种选项（通常使用构建配置文件中的DSL设置），这些选项会影响 Android 构建。Variant API 还允许您访问构建创建的中间和最终工件，例如类文件、合并清单或 APK/AAB 文件。

Android 构建流程和扩展点

与 AGP 交互时，请使用专门制作的扩展点，而不是注册典型的 Gradle 生命周期回调（例如afterEvaluate()）或设置显式Task依赖项。AGP 创建的任务被视为实现细节，不会作为公共 API 公开。您必须避免尝试获取Task对象的实例或猜测Task名称，并直接向这些Task对象添加回调或依赖项。

AGP 通过以下步骤创建和执行其 Task 实例，这些实例进而生成构建工件。主要步骤包括 Variant 对象的创建，以及随后的一系列回调，允许您对构建过程中创建的某些对象进行修改。需要注意的是，所有回调都发生在 配置阶段（本页面中有描述），并且必须快速执行，将任何复杂的工作推迟到执行阶段的适当 Task 实例中。

1. DSL 解析：这是评估构建脚本的时候，在此期间，来自 android 块的 Android DSL 对象的各种属性被创建和设置。以下部分中描述的 Variant API 回调也在此阶段注册。

2. finalizeDsl()：回调，允许您在锁定组件（变体）创建之前的 DSL 对象进行修改。VariantBuilder 对象根据 DSL 对象中包含的数据创建。

3. DSL 锁定：DSL 现在已锁定，无法再进行更改。

4. beforeVariants()：此回调可以通过 VariantBuilder 影响创建哪些组件以及某些组件的属性。它仍然允许修改构建流程和生成的工件。

5. 变体创建：将要创建的组件和工件列表现已确定，无法更改。

6. onVariants()：在此回调中，您可以访问创建的 Variant 对象，并可以设置其包含的 Property 值的值或提供程序，以便延迟计算。

7. 变体锁定：Variant 对象现在已锁定，无法再进行更改。

8. 任务创建：Variant 对象及其 Property 值用于创建执行构建所需的 Task 实例。

AGP 引入了一个 AndroidComponentsExtension，它允许您为 finalizeDsl()、beforeVariants() 和 onVariants() 注册回调。此扩展程序可以通过构建脚本中的 androidComponents 块访问。

// This is used only for configuring the Android build through DSL.
android { ... }

// The androidComponents block is separate from the DSL.
androidComponents {
   finalizeDsl { extension ->
      ...
   }
}

但是，我们建议仅将构建脚本用于使用 android 块的 DSL 进行声明性配置，并将 任何自定义的命令式逻辑移动到 buildSrc 或外部插件中。您还可以查看我们 Gradle recipes GitHub 存储库中的 buildSrc 示例，了解如何在项目中创建插件。以下是如何从插件代码中注册回调的示例

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            ...
        }
    }
}

让我们更仔细地看看可用的回调以及您的插件在每个回调中可以支持的用例类型。

finalizeDsl(callback: (DslExtensionT) -> Unit)

在此回调中，您可以访问和修改通过解析构建文件中的 android 块中的信息创建的 DSL 对象。这些 DSL 对象将用于在构建的后续阶段初始化和配置变体。例如，您可以以编程方式创建新的配置或覆盖属性——但请记住，所有值都必须在配置时解析，因此它们不能依赖于任何外部输入。此回调执行完成后，DSL 对象将不再有用，您也不应再持有对它们的引用或修改其值。

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            extension.buildTypes.create("extra").let {
                it.isJniDebuggable = true
            }
        }
    }
}

beforeVariants()

在此构建阶段，您可以访问 VariantBuilder 对象，这些对象决定了将创建的变体及其属性。例如，您可以以编程方式禁用某些变体、它们的测试或仅为选定的变体更改属性的值（例如，minSdk）。与 finalizeDsl() 类似，您提供的所有值都必须在配置时解析，并且不依赖于外部输入。beforeVariants() 回调执行完成后，不得修改 VariantBuilder 对象。

androidComponents {
    beforeVariants { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

beforeVariants() 回调可以选择性地接受一个 VariantSelector，您可以通过 selector() 方法在 androidComponentsExtension 上获取它。您可以使用它根据变体的名称、构建类型或产品风格过滤参与回调调用的组件。

androidComponents {
    beforeVariants(selector().withName("adfree")) { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

onVariants()

当调用 onVariants() 时，AGP 将创建的所有工件都已决定，因此您无法再禁用它们。但是，您可以通过为 Variant 对象中的 Property 属性设置它们来修改用于任务的一些值。由于 Property 值仅在 AGP 的任务执行时才会解析，因此您可以安全地将它们连接到您自己的自定义任务的提供程序，这些任务将执行任何必要的计算，包括读取文件或网络等外部输入。

// onVariants also supports VariantSelectors:
onVariants(selector().withBuildType("release")) { variant ->
    // Gather the output when we are in single mode (no multi-apk).
    val mainOutput = variant.outputs.single { it.outputType == OutputType.SINGLE }

    // Create version code generating task
    val versionCodeTask = project.tasks.register("computeVersionCodeFor${variant.name}", VersionCodeTask::class.java) {
        it.outputFile.set(project.layout.buildDirectory.file("${variant.name}/versionCode.txt"))
    }
    /**
     * Wire version code from the task output.
     * map() will create a lazy provider that:
     * 1. Runs just before the consumer(s), ensuring that the producer
     * (VersionCodeTask) has run and therefore the file is created.
     * 2. Contains task dependency information so that the consumer(s) run after
     * the producer.
     */
    mainOutput.versionCode.set(versionCodeTask.map { it.outputFile.get().asFile.readText().toInt() })
}

将生成的源代码贡献到构建中

您的插件可以贡献几种类型的生成的源代码，例如

• 位于 java 目录中的应用程序代码
• 位于 res 目录中的 Android 资源
• 位于 resources 目录中的 Java 资源
• 位于 assets 目录中的 Android 资产

有关您可以添加的源代码的完整列表，请参阅 Sources API。

此代码片段显示了如何使用 addStaticSourceDirectory() 函数将名为 ${variant.name} 的自定义源代码文件夹添加到 Java 源代码集中。然后，Android 工具链处理此文件夹。

onVariants { variant ->
    variant.sources.java?.let { java ->
        java.addStaticSourceDirectory("custom/src/kotlin/${variant.name}")
    }
}

有关更多详细信息，请参阅 addJavaSource 食谱。

此代码片段显示了如何将包含从自定义任务生成的 Android 资源的目录添加到 res 源代码集中。其他源代码类型的过程类似。

onVariants(selector().withBuildType("release")) { variant ->
    // Step 1. Register the task.
    val resCreationTask =
       project.tasks.register<ResCreatorTask>("create${variant.name}Res")

    // Step 2. Register the task output to the variant-generated source directory.
    variant.sources.res?.addGeneratedSourceDirectory(
       resCreationTask,
       ResCreatorTask::outputDirectory)
    }

...

// Step 3. Define the task.
abstract class ResCreatorTask: DefaultTask() {
   @get:OutputFiles
   abstract val outputDirectory: DirectoryProperty

   @TaskAction
   fun taskAction() {
      // Step 4. Generate your resources.
      ...
   }
}

有关更多详细信息，请参阅 addCustomAsset 食谱。

访问和修改工件

除了允许您修改 Variant 对象上的简单属性外，AGP 还包含一个扩展机制，允许您读取或转换构建过程中生成的中间和最终工件。例如，您可以在自定义 Task 中读取最终合并的 AndroidManifest.xml 文件内容以进行分析，或者您可以将其内容完全替换为您自定义 Task 生成的清单文件的内容。

您可以在 Artifact 类的参考文档中找到当前支持的工件列表。每个工件类型都具有一些有用的属性

基数

Artifact 的基数表示其 FileSystemLocation 实例的数量，或该工件类型的文件或目录的数量。您可以通过检查其父类来获取有关工件基数的信息：具有单个 FileSystemLocation 的工件将是 Artifact.Single 的子类；具有多个 FileSystemLocation 实例的工件将是 Artifact.Multiple 的子类。

FileSystemLocation 类型

您可以通过查看其参数化的 FileSystemLocation 类型来检查 Artifact 是否表示文件或目录，该类型可以是 RegularFile 或 Directory。

支持的操作

每个 Artifact 类可以实现以下任何接口以指示其支持的操作

• Transformable：允许 Artifact 用作 Task 的输入，该 Task 对其执行任意转换并输出 Artifact 的新版本。
• Appendable：仅适用于 Artifact.Multiple 的子类工件。这意味着可以追加到 Artifact，也就是说，自定义 Task 可以创建此 Artifact 类型的新的实例，这些实例将添加到现有列表中。
• Replaceable：仅适用于 Artifact.Single 的子类工件。可替换的 Artifact 可以由一个完全新的实例替换，该实例作为 Task 的输出生成。

除了这三种修改工件的操作外，每个工件都支持 get()（或 getAll()）操作，该操作返回一个包含工件最终版本（在其上执行完所有操作后）的 Provider。

多个插件可以从 onVariants() 回调中向流水线添加任意数量的操作到工件中，AGP 将确保它们被正确地链接，以便所有任务在正确的时间运行，并且工件被正确地生成和更新。这意味着，当某个操作通过追加、替换或转换更改任何输出时，下一个操作将看到这些工件的更新版本作为输入，依此类推。

注册操作的入口点是 Artifacts 类。以下代码片段展示了如何在 onVariants() 回调中从 Variant 对象上的属性获取 Artifacts 的实例。

然后，您可以传入自定义的 TaskProvider 以获取 TaskBasedOperation 对象 (1)，并使用它通过其中一个 wiredWith* 方法 (2) 连接其输入和输出。

您需要选择的确切方法取决于您要转换的 Artifact 实现的基数和 FileSystemLocation 类型。

最后，您将 Artifact 类型传递给表示在返回的 *OperationRequest 对象上所选操作的方法，例如，toAppendTo()、toTransform() 或 toCreate() (3)。

androidComponents.onVariants { variant ->
    val manifestUpdater = // Custom task that will be used for the transform.
            project.tasks.register(variant.name + "ManifestUpdater", ManifestTransformerTask::class.java) {
                it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
            }
    // (1) Register the TaskProvider w.
    val variant.artifacts.use(manifestUpdater)
         // (2) Connect the input and output files.
        .wiredWithFiles(
            ManifestTransformerTask::mergedManifest,
            ManifestTransformerTask::updatedManifest)
        // (3) Indicate the artifact and operation type.
        .toTransform(SingleArtifact.MERGED_MANIFEST)
}

在此示例中，MERGED_MANIFEST 是一个 SingleArtifact，它是一个 RegularFile。因此，我们需要使用 wiredWithFiles 方法，该方法接受单个 RegularFileProperty 作为输入的引用，以及单个 RegularFileProperty 作为输出。在 TaskBasedOperation 类上还有其他 wiredWith* 方法，这些方法适用于 Artifact 基数和 FileSystemLocation 类型的其他组合。

要了解有关扩展 AGP 的更多信息，我们建议阅读 Gradle 构建系统手册中的以下部分

• 开发自定义 Gradle 插件
• 实现 Gradle 插件
• 开发自定义 Gradle 任务类型
• 延迟配置
• 任务配置避免