如何优雅地扩展 AGP 插件？-六虎

前语

咱们在项目中常常需求扩展AGP插件，比方重命名APK，校验Manifest文件，对项目中的图片做统一压缩等操作。
总得来说，咱们需求对AGP插件编译过程中的中心产品(即Artifact)做一些操作，但是老版的AGP并没有供给相关的API，导致咱们需求去查看相关的代码的详细完结，并经过反射等手法获取对应产品。

本文主要介绍旧版AGP插件在扩展方面存在的问题，并介绍新版Variant API与Artifact API的运用，经过简练高雅的办法扩展AGP插件

本文主要内容是对《社区说：扩展 Android 构建流程 – 根据新版 Variant/Artifact APIs》视频学习的输出，感兴趣的同学能够直接查看视频，链接在文末

现在存在的问题

内部完结没有与`API`分离

旧版 AGP 没有与内部完结明确分隔的官方 API，导致用户运用时常常依靠了内部的详细完结，在开发AGP插件时，咱们常常直接依靠于com.android.tools.build:gradle:x.x.x。

为此从 7.0 版别开始，AGP 将供给一组安稳的官方 API，即com.android.tools.build:gradle-api:x.x.x。理论上说，在编写插件时，现在主张仅依靠 gradle-api 工件，以便仅运用揭露的接口和类。

开发插件时依靠`Task`的详细完结

因为旧版AGP没有供给对应的API获取相应产品，咱们一般需求先了解是哪个Task处理了相关的资源，然后查看该Task的详细完结，经过相关API或许反射手法获取对应的产品。

比方咱们要开发一个校验Manifest文件的插件，在旧版AGP中需求经过以下办法处理:

    def processManifestTask: ManifestProcessorTask = project.tasks.getByName("process${variant.name.capitalize()}Manifest")
    processManifestTask.doLast {
        logger.warn("main manifest: " + taskCompat.mainManifest)
        logger.warn("manifestOutputDirectory: " + taskCompat.manifestOutputDirectory)
        //...
    }    
}

这种写法主要有几个问题：

成本较高，开发时需求了解相应Task的详细完结
AGP晋级时相应Task的完结常常会发生变化，因而每次晋级都需求做一系列的适配作业

总得来说，体系会将 AGP 创立的使命视为完结细节，不会作为公共 API 揭露。您有必要避免测验获取 Task 目标的实例或猜想 Task 名称，以及直接向这些 Task 目标添加回调或依靠项。

`Variant API`介绍

关于Variant API，咱们首要了解一下什么是Variant?
Variant官网翻译为变体，看起来不太好了解。其实Variant就是buildType与Flavor的组合，如下所示，2个buildType与2个Flavor能够组合出4个Variant

Variant API 是 AGP 中的扩展机制，可让您操作build.gradle中的各种装备。您还能够经过 Variant API 访问构建期间创立的中心产品和终究产品，例如类文件、兼并后的Manifest或 APK/AAB 文件。

`Android`构建流程和扩展点

AGP 主要经过以下几步来创立和履行其 Task 实例

DSL 解析：发生在体系评估 build 脚本时，以及创立和设置 android 代码块中的 Android DSL 目标的各种特点时。后面几部分中介绍的 Variant API 回调也是在此阶段注册的。
finalizeDsl()：您能够经过此回调在 DSL 目标因组件（变体）创立而被确定之前对其进行更改。VariantBuilder 目标是根据 DSL 目标中包含的数据创立的。
DSL 确定：DSL 现已被确定，无法再进行更改。
beforeVariants()：此回调可经过 VariantBuilder 影响体系会创立哪些组件以及所创立组件的部分特点。它还支撑对 build 流程和生成的工件进行修正。
变体创立：将要创立的组件和工件列表现已最后确定，无法更改。
onVariants()：在此回调中，您能够访问已创立的 Variant 目标，您还能够为它们包含的 Property值设置值或Provider，以进行延迟计算。
变体确定：变体目标现已被确定，无法再进行更改。
使命已创立：运用 Variant 目标及其 Property 值创立履行 build 所必需的 Task 实例。

总得来说，为咱们供给了3个回调办法，它们各自的运用场景如上图所示，比较老版别的Variant API，新版别的生命周期区分的愈加明晰详尽

`Artifact API`介绍

Artifact即产品，Artifact API即咱们获取中心产品或许终究产品的API，经过Artifact API咱们能够对中心产品进行增修正查操作而不必关心详细的完结

每个Artifact类都能够完结以下任一接口，以表明自己支撑哪些操作：

Transformable：答应将 Artifact 作为输入，供在该接口上履行任意转换并输出新版 Artifact 的 Task 运用。
Appendable：仅适用于作为 Artifact.Multiple 子类的工件。它意味着能够向 Artifact 附加内容，也就是说，自定义 Task 能够创立此 Artifact 类型的新实例，这些实例将添加到现有列表中。
Replaceable：仅适用于作为 Artifact.Single 子类的工件。可替换的 Artifact 能够被作为 Task 输出生成的全新实例替换。

除了支撑上述三种工件修正操作之外，每个工件还支撑 get()（或 getAll()）操作；该操作会返回 Provider 以及该产品的终究版别（在对产品的一切操作均完结之后）。

`Get`操作

Get操作能够获得产品的终究版别(在对产品的一切操作完结之后)，比方你想要查看merged manifest文件，能够经过以下办法完结

abstract class VerifyManifestTask: DefaultTask() {
    @get:InputFile
    abstract val mergedManifest: RegularFileProperty
    @TaskAction
    fun taskAction() {
        val mergedManifestFile = mergedManifest.get().asFile 
        // ... verify manifest file content ...
    }
}
androidComponents {
    onVariants { 
    	// 注册Task
        project.tasks.register<VerifyManifestTask>("${name}VerifyManifest") {
        	// 获取merged_manifest并给Task设值
            mergedManifest.set(artifacts.get(ArtifactType.MERGED_MANIFEST))
        }
    }
}

如上所示，经过以上办法，不需求知道依靠于哪个Task，也不需求了解Task的详细完结，就能够轻松获取MERGED_MANIFEST的内容

`Transformation`操作

Transformation即改换操作，它能够把原有产品作为输入值，进行改换后将结果作为输出值，并传递给下一个改换

下面咱们来看一个将Manifest的VersionCode替换为git head的改换示例:

// 获取git head的Task
abstract class GitVersionTask: DefaultTask() {
    @get:OutputFile
    abstract val gitVersionOutputFile: RegularFileProperty
    @TaskAction
    fun taskAction() {
        val process = ProcessBuilder("git", "rev-parse --short HEAD").start()
        val error = process.errorStream.readBytes().decodeToString()
        if (error.isNotBlank()) {
            throw RuntimeException("Git error : ${'$'}error")
        }
        var gitVersion = process.inputStream.readBytes().decodeToString()
        gitVersionOutputFile.get().asFile.writeText(gitVersion)
    }
}
// 修正Manifest的Task
abstract class ManifestTransformerTask: DefaultTask() {
    @get:InputFile
    abstract val gitInfoFile: RegularFileProperty
    @get:InputFile
    abstract val mergedManifest: RegularFileProperty
    @get:OutputFile
    abstract val updatedManifest: RegularFileProperty
    @TaskAction
    fun taskAction() {
        val gitVersion = gitInfoFile.get().asFile.readText()
        var manifest = mergedManifest.get().asFile.readText()
        manifest = manifest.replace(
                "android:versionCode=\"1\"", 
                "android:versionCode=\"${gitVersion}\"")
        updatedManifest.get().asFile.writeText(manifest)
    }
}
// 注册Task
androidComponents {
    onVariants {
        // 创立git Version Task Provider
        val gitVersion = tasks.register<GitVersionTask>("gitVersion") {
            gitVersionOutputFile.set(
                    File(project.buildDir, "intermediates/git/output"))
        }
        // 创立修正Manifest的Task
        val manifestUpdater = tasks.register<ManifestTransformerTask>("${name}ManifestUpdater") {       
                // 把GitVersionTask的结果设置给gitInfoFile                  
                gitInfoFile.set(
                    gitVersion.flatMap(GitVersionTask::gitVersionOutputFile)
                )
        }
        // manifestUpdater Task 与 AGP 进行衔接
        artifacts.use(manifestUpdater)
            .wiredWithFiles(
                    ManifestTransformerTask::mergedManifest,
                    ManifestTransformerTask::updatedManifest)
           .toTransform(ArtifactType.MERGED_MANIFEST)  
    }
}

经过以上操作，就能够把git head的值替换Manifest中的内容，能够注意到manifestUpdater依靠于gitVersion，但咱们却没有写dependsOn相关的逻辑。
这是因为它们都是TaskProvider类型，TaskPrOVIDER还带着有使命依靠项信息。当您经过flatmap一个 Task 的输出来创立 Provider 时，该 Task 会成为相应Provider 的隐式依靠项，不管 Provider 的值在何时进行解析（例如当另一个 Task 需求它时），体系都要会创立并运行该 Task。

同理，咱们也主动隐式依靠了process${variant.name.capitalize()}Manifest这个Task

`Append`操作

Append 仅与运用 MultipleArtifact 润饰的产品类型相关。因为此类类型表示为 Directory 或 RegularFile 的列表，因而使命能够声明将附加到列表的输出。

// 声明Task
abstract class SomeProducer: DefaultTask() {
    @get:OutputFile
    abstract val output: RegularFileProperty
    @TaskAction
    fun taskAction() {
        val outputFile = output.get().asFile 
        // … write file content …
    }
}
// 注册Task
androidComponents {
    onVariants { 
        val someProducer = project.tasks.register<SomeProducer>("${name}SomeProducer") {
              // ... configure your task as needed ...
        }
        artifacts.use(someProducer)
            .wiredWith(SomeProducerTask::output)
            .toAppendTo(ArtifactType.MANY_ARTIFACT)
    }
}

`Creation`操作

此操效果一个新的 Artifact 替换当时的Artifact，丢弃一切曾经的Artifact。这是一个“输出”操作，其中使命声明自己是产品的唯一供给者。如果有多个使命将自己声明为产品供给者，则最后一个将获胜。

例如，自定义使命或许不运用内置清单兼并，而是经过代码写入一个新的。

// 声明Task
abstract class ManifestFileProducer: DefaultTask() {
    @get:OutputFile
    abstract val outputManifest: RegularFileProperty
    @TaskAction
    fun taskAction() {
        val mergedManifestFile = outputManifest.get().asFile 
        // ... write manifest file content ...
    }
}
// 注册Task
androidComponents {
    onVariants { 
        val manifestProducer = project.tasks.register<ManifestProducerTask>("${name}ManifestProducer") {
            //… configure your task as needed ...
        }
        artifacts.use(manifestProducer)
            .wiredWith(ManifestProducerTask::outputManifest)
            .toCreate(ArtifactType.MERGED_MANIFEST)
    }
}

`Artifact API`的问题

Artifact API现在的问题就在于支撑的产品类型还有限，只要以下几种

SingleArtifact.APK
SingleArtifact.MERGED_MANIFEST
SingleArtifact.OBFUSCATION_MAPPING_FILE
SingleArtifact.BUNDLE
SingleArtifact.AAR
SingleArtifact.PUBLIC_ANDROID_RESOURCES_LIST
SingleArtifact.METADATA_LIBRARY_DEPENDENCIES_REPORT
MultipleArtifact.MULTIDEX_KEEP_PROGUARD
MultipleArtifact.ALL_CLASSES_DIRS
MultipleArtifact.ALL_CLASSES_JARS
MultipleArtifact.ASSETS

还有很多常用的中心产品如MERGED_RES，MERGED_NATIVE_LIBS等都还不支撑，因而在现阶段还是不可避免的运用老版别的API来获取这些资源

总结

新版Variant API经过专心于产品而不是Task，自定义插件或构建脚本能够安全地扩展 AGP 插件，而不受构建流程更改或Task完结等内部细节的支配。开发者不需求知道要修正的产品依靠于哪个Task，也不需求知道Task的详细完结，能够有效降低咱们开发与晋级Gradle插件的成本。

虽然现在新版Variant API支撑的获取的中心产品类型还有限，但这也应该能够确定是AGP插件扩展将来的方向了。在AGP8.0中，旧版 Variant API将被废弃，而在AGP9.0中，旧版Vaiant API将被删去，并将移除对私有内部 AGP 类的访问权限，因而现在应该是时分了解一下新版Variant API的运用了~

示例代码

本文一切代码可见：github.com/android/gra…

参考资料

New APIs in the Android Gradle Plugin
社区说｜扩展 Android 构建流程 – 根据新版 Variant/Artifact APIs
扩展 Android Gradle 插件

如何优雅地扩展 AGP 插件？

前语

现在存在的问题

内部完结没有与API分离

开发插件时依靠Task的详细完结

Variant API介绍

Android构建流程和扩展点

Artifact API介绍

Get操作

Transformation操作

Append操作

Creation操作

Artifact API的问题

总结

示例代码

参考资料

相关文章

cocoapods 小技能：只安装新添加的库，已更新的库忽略

深度学习中丢弃法原理及实现(基于pytorch)

LiteFlow v2.9.4发布！一款能让你系统支持热更新，编排，脚本编写逻辑的国产规则引擎框架

独立开发多人（远程）协作经验分享

作者信息