Android Gradle 插件 4.1.0（2020 年 8 月）

兼容性

	最低版本	默认版本	备注
Gradle	6.5	N/A	如需了解详情，请参阅更新 Gradle。
SDK Build Tools	29.0.2	29.0.2	安装或配置 SDK Build Tools。
NDK	N/A	21.1.6352462	安装或配置其他版本的 NDK。

此版本的 Android 插件需要使用以下工具：

• Gradle 6.5. 如需了解详情，请阅读有关更新 Gradle 的部分。

• SDK Build Tools 29.0.2 或更高版本。

此版本中的默认 NDK 版本为 21.1.6352462。如要安装其他 NDK 版本，请参阅安装特定版本的 NDK。

新功能

此版本的 Android Gradle 插件包含以下新功能。

Kotlin 脚本 DSL 支持

为了帮助提升 Kotlin 构建脚本用户的修改体验，现在 Android Gradle 插件 4.1 的 DSL 和 API 在一组 Kotlin 接口中与其实现类分开定义。这意味着：

• 现在，在 Kotlin 类型上明确声明了是否可为 null 和可变性。
• Kotlin API 参考文档中发布了根据这些接口生成的文档。
• 明确定义了 Android Gradle 插件的 API 接口，使未来扩展的 Android build 更加稳定。

重要提示：如果您已采用 KTS build 脚本或在 buildSrc 中使用 Kotlin，这样可能会因某些错误而导致源代码兼容性被破坏，这些错误在以前的版本中原本表现为运行时错误。

在 DSL 中设计为改变的集合类型现在一律定义为：

val collection: MutableCollectionType

这意味着，对于以前支持 DSL 的某些集合，无法再在 Kotlin 脚本中编写以下代码：

collection = collectionTypeOf(...)

不过，一律支持改变集合，因此 collection += … 和 collection.add(...) 现在应处处适用。

如果您在升级使用 Android Gradle 插件 Kotlin API 和 DSL 的项目时发现任何问题，请报告错误。

从 AAR 导出 C/C++ 依赖项

Android Gradle 插件 4.0 添加了将 Prefab 软件包导入 AAR 依赖项的功能。在 AGP 4.1 中，现在可以将外部原生 build 中的库导出到 Android 库项目的 AAR 中。

如需导出原生库，请将以下代码添加到库项目的 build.gradle 文件的 android 代码块中：

buildFeatures {
    prefabPublishing true
}


prefab {
    <var>mylibrary</var&;gt {
      headers "src/main/cpp/<var>mylibrary</var>/include"
    }
<var>myotherlibrary</var> {
    headers "src/main/cpp/<var>myotherlibrary</var>/include"
}

}
     
buildFeatures {
    prefabPublishing = true
}


prefab {
    create("<var>mylibrary</var>") {
      headers = "src/main/cpp/<var>mylibrary</var>/include"
    }
create("<var>myotherlibrary</var>") {
    headers = "src/main/cpp/<var>myotherlibrary</var>/include"
}

}
      

在本例中，您的 ndk-build 或 CMake 外部原生 build 中的 mylibrary 和 myotherlibrary 库会打包到您的 build 生成的 AAR 中，并且各自会将头文件从指定的目录导出到依赖于它们的项。

注意：对于 Android Gradle 插件 4.0 及更高版本的用户，导入预构建原生库的配置设置已发生更改。如需了解详情，请参阅 4.0 版本说明。

R8 对 Kotlin 元数据的支持

Kotlin 使用 Java 类文件中的自定义元数据标识 Kotlin 语言结构。R8 现在支持维护和重新编写 Kotlin 元数据，以完全支持缩减使用 kotlin-reflect 功能的 Kotlin 库和应用大小。

如需保留 Kotlin 元数据，请添加以下保留规则：

-keep class kotlin.Metadata { *; }


-keepattributes RuntimeVisibleAnnotations

这将指示 R8 保留直接保留的所有类的 Kotlin 元数据。

如需了解详情，请参阅 Medium 上的借助 R8 缩减使用 Kotlin 反射功能的 Kotlin 库和应用大小{:.external}。

调试 build 中的断言

当您使用 Android Gradle 插件 4.1.0 及更高版本构建应用的调试版本时，内置编译器 (D8) 会重写应用代码以在编译时启用断言，因此您要始终将断言检查置于启用状态。

行为变更

移除了 Android Gradle 插件构建缓存

AGP 构建缓存已在 AGP 4.1 中移除。AGP 构建缓存之前在 AGP 2.3 中引入，对 Gradle 构建缓存起到了补充的作用；在 AGP 4.1 中，AGP 构建缓存已完全被 Gradle 构建缓存所取代。此次变更不会影响构建时间。

cleanBuildCache 任务以及 android.enableBuildCache 和 android.buildCacheDir 属性已被废弃，将在 AGP 7.0 中移除。android.enableBuildCache 属性目前不起任何作用，而 android.buildCacheDir 属性和 cleanBuildCache 任务在 AGP 7.0 之前将一直发挥作用，用于删除任何现有的 AGP 构建缓存内容。

使用代码缩减的应用的大小显著减小

从此版本开始，默认不再保留 R 类中的字段。这样一来，启用代码缩减的应用的 APK 大小将会显著减少。这应该不会导致行为变更，除非您通过反射功能访问 R 类；如果您通过反射功能访问 R 类，就必须针对这些 R 类添加保留规则。

android.namespacedRClass 属性已重命名为 android.nonTransitiveRClass

实验性标记 android.namespacedRClass 已重命名为 android.nonTransitiveRClass。

此标志在 gradle.properties 文件中设置，可启用每个库的 R 类的命名空间，以便其 R 类仅包含库本身中声明的资源，而不包含库的依赖项中的任何资源，从而缩减相应库的 R 类大小。

Kotlin DSL：coreLibraryDesugaringEnabled 已重命名

Kotlin DSL 编译选项 coreLibraryDesugaringEnabled 已更改为 isCoreLibraryDesugaringEnabled。如需详细了解此标记，请参阅 Java 8+ API 脱糖支持 (Android Gradle 插件 4.0.0+)。

从库项目中的 BuildConfig 类中移除了版本属性

仅对于库项目而言，BuildConfig.VERSION_NAME 和 BuildConfig.VERSION_CODE 属性已从生成的 BuildConfig 类中移除，因为这些静态值过去并不反映应用版本代码和名称的最终值，因此具有误导性。此外，这些值过去在清单合并期间会被舍弃。

在将来的 Android Gradle 插件版本中，versionName 和 versionCode 属性也会从库的 DSL 中移除。目前，无法从库子项目自动获取应用版本代码/名称。

对于应用模块而言，没有发生变化，您仍然可以在 DSL 中为 versionCode 和 versionName 赋值，这些值将传播到应用的清单和 BuildConfig 字段。

设置 NDK 路径

您可以使用模块的 build.gradle 文件中的 android.ndkPath 属性设置本地 NDK 安装的路径。

android {
  ndkPath "your-custom-ndk-path"
}

android {
  ndkPath = "your-custom-ndk-path"
}

如果您将此属性与 android.ndkVersion 属性一起使用，则此路径必须包含与 android.ndkVersion 匹配的 NDK 版本。

库单元测试行为变更

我们更改了如何编译和运行库单元测试的行为。库的单元测试现在针对库本身的编译/运行时类编译和运行，使得单元测试以与外部子项目相同的方式使用库。此配置通常会使测试效果更好。

在某些情况下，使用数据绑定的库单元测试可能会遇到缺少 DataBindingComponent 或 BR 类的情况。这些测试需要移植到 androidTest 项目中的插桩测试，因为在单元测试中针对这些类编译和运行可能会生成错误的输出。

废弃了 io.fabric Gradle 插件

io.fabric Gradle 插件已废弃，与 Android Gradle 插件版本 4.1 不兼容。如需详细了解已废弃的 Fabric SDK 以及如何迁移到 Firebase Crashlytics SDK，请参阅升级到 Firebase Crashlytics SDK。