更新 Gradle
在更新 Android Studio 时,您可能会收到一并将 Gradle 更新为最新可用版本的提示。您可以选择接受该更新,也可以根据项目的构建要求手动指定版本。
下表列出了各个 Android Gradle 插件版本所需的 Gradle 版本。为了获得最佳性能,您应使用 Gradle 和插件这两者的最新版本。
插件版本 | 所需的 Gradle 版本 |
---|---|
1.0.0 - 1.1.3 | 2.2.1 - 2.3 |
1.2.0 - 1.3.1 | 2.2.1 - 2.9 |
1.5.0 | 2.2.1 - 2.13 |
2.0.0 - 2.1.2 | 2.10 - 2.13 |
2.1.3 - 2.2.3 | 2.14.1+ |
2.3.0+ | 3.3+ |
3.0.0+ | 4.1+ |
3.1.0+ | 4.4+ |
3.2.0 - 3.2.1 | 4.6+ |
3.3.0 - 3.3.3 | 4.10.1+ |
3.4.0 - 3.4.3 | 5.1.1+ |
3.5.0 - 3.5.4 | 5.4.1+ |
3.6.0 - 3.6.4 | 5.6.4+ |
4.0.0+ | 6.1.1+ |
4.1.0+ | 6.5+ |
您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定 Gradle 版本,也可以通过在 gradle/wrapper/gradle-wrapper.properties
文件中修改 Gradle 分发引用来指定。以下示例在 gradle-wrapper.properties
文件中将 Gradle 的版本设置为 6.1.1。
...
distributionUrl = https\://services.gradle.org/distributions/gradle-6.1.1-all.zip
...
4.1.0(2020 年 8 月)
兼容性
最低版本 | 默认版本 | 备注 | |
---|---|---|---|
Gradle | 6.5 | 无 | 如需了解详情,请参阅更新 Gradle。 |
SDK Build Tools | 29.0.2 | 29.0.2 | 安装或配置 SDK Build Tools。 |
NDK | 无 | 21.1.6352462 | 安装或配置其他版本的 NDK。 |
新功能
此版本的 Android Gradle 插件包含以下新功能。
新功能
此版本的 Android Gradle 插件包含以下新功能。
Kotlin 脚本 DSL 支持
为了帮助改进 Kotlin 构建脚本用户的修改体验,现在 Android Gradle 插件 4.1 的 DSL 和 API 在一组 Kotlin 接口中与其实现类分开定义。这意味着:
- 现在,在 Kotlin 类型上明确声明了是否可为 null 和可变性。
- Kotlin API 参考文档中发布了根据这些接口生成的文档。
- 明确定义了 Android Gradle 插件的 API Surface,以使未来扩展 Android build 不那么脆弱。
重要提示:如果您已采用 KTS 构建脚本或在 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 {
mylibrary {
headers "src/main/cpp/mylibrary/include"
}
myotherlibrary {
headers "src/main/cpp/myotherlibrary/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 库和应用大小。
行为变更
从库项目中的 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.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。
4.0.0(2020 年 4 月)
此版本的 Android 插件需要使用以下工具:
-
Gradle 6.1.1。如需了解详情,请阅读有关更新 Gradle 的部分。
-
SDK Build Tools 29.0.2 或更高版本。
本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。
在以前的 Android 版本中,可以查看设备上安装的所有应用的列表。从 Android 11(API 级别 30)开始,默认情况下,应用只能访问经过过滤的已安装软件包列表。如需查看系统上更广泛的应用列表,您现在需要在应用或库的 Android 清单中添加 <queries>
元素。
Android Gradle 插件 4.1 及更高版本已与新的 <queries>
声明兼容;不过,较低的版本不兼容。如果您添加 <queries>
元素或者开始依赖于支持以 Android 11 为目标平台的库或 SDK,在构建应用时可能会遇到清单合并错误。
为了解决此问题,我们将针对 AGP 3.3 及更高版本发布一组补丁程序。如果您使用的是旧版 AGP,请升级到以下某个版本:
如果您使用的是 AGP 版本... | ...请升级到 |
---|---|
4.0.* | 4.0.1 |
3.6.* | 3.6.4 |
3.5.* | 3.5.4 |
3.4.* | 3.4.3 |
3.3.* | 3.3.3 |
如需详细了解这项新功能,请参阅 Android 11 中的软件包可见性。