本页记录了 Android Gradle 插件 (AGP) 废弃和移除情况,并说明了如何相应地更新代码。
API 废弃和移除情况跟踪说明
下表从 AGP 版本方面总结了各个 AGP API 的废弃时间和移除时间。
API | 在其中遭到废弃的 AGP 版本 | 在其中遭到移除的 AGP 版本 |
---|---|---|
Component.setAsmFramesComputationMode |
7.2 | |
Component.transformClassesWith |
7.2 | |
RenderScript | 7.2 | |
Transform | 7.2 | 8.0 |
AGP 8.0
以下是 AGP 8.0 的重要 API 更新。
移除了 Transform API
从 AGP 8.0 开始,Transform API 将被移除。这意味着,软件包 com.android.build.api.transform
中的所有类都会被移除。
Transform API 即将被移除,以提高 build 的性能。使用 Transform API 的项目会强制 AGP 对 build 使用优化程度不够的流程,从而导致构建时间大幅增加。同时也很难使用 Transform API 以及将其与其他 Gradle 功能结合使用;这些替代 API 可让您更轻松地扩展 AGP,而不会引起性能问题或 build 正确性问题。
替代 API
Transform API 没有单一的替代 API,每个用例都会有新的针对性 API。所有替代 API 都位于 androidComponents
{}
代码块中,在 AGP 7.2 中均有提供。
支持转换字节码
如需转换字节码,请使用 Instrumentation API。对于库,您只能为本地项目类注册插桩;对于应用和测试,您既可以选择仅为本地类注册插桩,也可以选择为所有类(包括本地和远程依赖项)注册插桩。为了使用此 API,每个类上的插桩都是独立运行的,并且对类路径中其他类的访问会受到限制(如需了解详情,请参见 createClassVisitor()
)。此限制提高了完整 build 和增量 build 的性能,并使得 API Surface 变得简单。每个库一旦准备就绪,即会进行并行插桩;而不是在所有编译完成后进行插桩。此外,如果是在单个类中做出更改,则意味着只有受影响的类必须在增量 build 中重新进行插桩。如需查看 Instrumentation API 使用方法的示例,请参阅使用 ASM 转换类 AGP 配方。
支持向应用添加生成的类
如需向应用添加其他生成的类,请将 Artifacts API 与 MultipleArtifact.ALL_CLASSES_DIRS
结合使用。具体而言,请将以下代码段
artifacts.use(TaskProvider)
.wiredWith(...)
.toAppend(Artifact.Multiple)
与 MultipleArtifact.ALL_CLASSES_DIRS
结合使用,以将其他生成的目录附加到项目类。Artifacts API 会自动为您的自定义任务选择专属的输出位置。有关如何使用此 API 的示例,请参阅 addToAllClasses 配方。
支持基于整个程序分析的转换
如需实现基于整个程序分析的转换,可以在单个任务中一起转换所有类。请谨慎使用此方法,因为它比使用 Instrumentation API 所���来的构建性能成本要高得多。如果您的插件会使用此 API,建议您按 build 类型选择启用转换,以便应用开发者针对开发 build 停用该转换。
为了注册可将所有类一起转换的任务,Android Gradle 插件 7.4 引入了 Artifacts.forScope API。如需转换当前项目中的所有类,请使用 Artifacts.forScope.PROJECT
。如需转换当前项目、导入的项目和所有外部依赖项中的所有类,请使用 Artifacts.forScope.ALL
。以下代码展示了如何使用 Artifacts.forScope.ALL
注册一项将所有类一起转换的任务:
variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
.use(taskProvider)
.toTransform(
ScopedArtifact.CLASSES,
ModifyClassesTask::allJars,
ModifyClassesTask::allDirectories,
ModifyClassesTask::output,
)
有关如何使用此 API 的示例,请参阅 modifyProjectClasses 配方;有关如何向 Android build 类型注册自定义扩展的示例,请参阅 customizeAgpDsl 配方。
如果您的用例不在任何 AndroidComponents API 的涵盖范围内,请提交 bug。
一些常用插件已转变为使用这些新 API,包括 Firebase Performance Monitoring 插件(1.4.1 与 AGP 8.0 兼容)和 Hilt Gradle 插件(2.40.1 与 AGP 8.0 兼容)。AGP 升级助理也会帮助项目开发者根据需要升级常用插件。
如果您是通过第三方插件使用 Transform API,请告知作者其插件需要更新,才能与适用于 AGP 8.0 的新 API 一起使用。
AGP 7.2
以下是 AGP 7.2 的重要 API 更新。
废弃了 RenderScript
从 AGP 7.2 开始,RenderScript API 已被废弃。它们将继续正常运行,但会产生警告,并将在未来的 AGP 版本中被彻底移除。有关如何从 RenderScript 过渡的指南,请参阅从 RenderScript 迁移。
废弃了 Component.transformClassesWith
和 Component.setAsmFramesComputationMode
从 AGP 7.2 开始,类字节码插桩 API Component.transformClassesWith
和 Component.setAsmFramesComputationMode
已被废弃。它们已移至新块 Component.instrumentation
,其中包含与配置插桩进程相关的所有 API。如需继续使用这些插桩功能,请改用新块中的相应 API,如以下代码段所示:
androidComponents {
onVariants(selector().all(), {
instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
InstrumentationScope.Project) { params ->
params.x = "value"
}
instrumentation.setAsmFramesComputationMode(
COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
)
})
}