将构建配置从 Groovy 迁移到 KTS

Android Gradle 插件 4.0 支持在 Gradle 构建配置中使用 Kotlin 脚本 (KTS),用于替代 Groovy(过去在 Gradle 配置文件中使用的编程语言)。

将来,KTS 会比 Groovy 更适合用于编写 Gradle 脚本,因为采用 Kotlin 编写的代码可读性更高,并且 Kotlin 提供了更好的编译时检查和 IDE 支持。

虽然与 Groovy 相比,KTS 当前能更好地在 Android Studio 的代码编辑器中集成,但采用 KTS 的构建速度往往比采用 Groovy 慢,因此在迁移到 KTS 时应考虑构建性能。

本页介绍了有关将 Android 应用的 Gradle build 文件从 Groovy 转换为 KTS 的基本信息。

如需查看更全面的迁移指南,请参阅 Gradle 的官方文档

常用术语

KTS:是指 Kotlin 脚本,这是 Gradle 在构建配置文件中使用的一种 Kotlin 语言形式。Kotlin 脚本是可从命令行运行的 Kotlin 代码。

Kotlin DSL:主要是指 Android Gradle 插件 Kotlin DSL,有时也指底层 Gradle Kotlin DSL

在讨论从 Groovy 迁移时,术语“KTS”和“Kotlin DSL”可以互换使用。换句话说,“将 Android 项目从 Groovy 转换为 KTS”与“将 Android 项目从 Groovy 转换为 Kotlin DSL”实际上是一个意思。

脚本文件命名

  • 用 Groovy 编写的 Gradle build 文件使用 .gradle 文件扩展名。
  • 用 Kotlin 编写的 Gradle build 文件使用 .gradle.kts 文件扩展名。

一次迁移一个文件

由于您可以在项目中结合使用 Groovy build 文件和 KTS build 文件,因此将项目转换为 KTS 的一个简单方法是先选择一个简单的 build 文件(例如 settings.gradle),将其重命名为 settings.gradle.kts,然后将其内容转换为 KTS。之后,确保您的项目在迁移每个 build 文件之后仍然可以编译。

常见误区

  • 用于定义字符串的双引号。Groovy 允许使用单引号来定义字符串,而 Kotlin 则要求使用双引号。
  • 基于句点表达式的字符串插值。在 Groovy 中,您可以使用 $ 前缀来表示基于句点表达式的字符串插值,例如以下代码段中的 $project.rootDir

    myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
    

    但在 Kotlin 中,上述代码将对 project(而非 project.rootDir)调用 toString()。如需获取根目录的值,请使用大括号括住整个变量:

    myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
    
  • 变量分配。一些在 Groovy 中适用的分配方式现在会被视作 setter(或者,对于列表、集合等,则适用“addX”),因为属性在 Kotlin 中是只读的。

显式和隐式 buildTypes

在 Kotlin DSL 中,某些 buildTypes(如 debugrelease,)是隐式提供的。但是,其他 buildTypes 则必须手动创建。

例如,在 Groovy 中,您可能有 debugreleasestaging buildTypes

Groovy

buildTypes
  debug {
    ...
  }
  release {
    ...
  }
  staging {
    ...
  }

在 KTS 中,仅 debugrelease buildTypes 是隐式提供的,而 staging 则必须由您手动创建:

KTS

buildTypes
  getByName("debug") {
    ...
  }
  getByName("release") {
    ...
  }
  create("staging") {
    ...
  }

使用 plugins 代码块

在 Groovy 和 KTS 中应用插件的方式是类似的。在这两种语言中,使用 plugins 代码块添加插件。

如果您在 build 文件中使用 plugins 代码块,IDE 将能够获知相关上下文信息,即使在构建失败时也是如此。IDE 可使用这些信息执行代码补全并提供其他实用建议,从而帮助您解决 KTS 文件中存在的问题。

Groovy 中的以下代码…

plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'kotlin-kapt'
    id 'androidx.navigation.safeargs.kotlin'
  }

…在 KTS 中变为以下代码:

plugins {
    id("com.android.application")
    id("kotlin-android")
    id("kotlin-kapt")
    id("androidx.navigation.safeargs.kotlin")
 }

如需详细了解 plugins 代码块,请参阅 Gradle 的迁移指南

注意plugins 代码块仅解析 Gradle 插件门户中提供的插件或使用 pluginManagement 代码块指定的自定义存储库中提供的插件。如果插件来自插件门户中不存在的 buildScript 依赖项,那么这些插件在 Kotlin 中就必须使用 apply 才能应用。例如:

apply(plugin = "kotlin-android")

如需了解详情,请参阅 Gradle 文档

更多资源

如需查看用 KTS 编写的 Gradle build 文件的可运行示例,请参阅 GitHub 上的 IOSched 示例应用

已知问题

以下是已知问题:

  • Project Structure 编辑器不会展开在 buildSrc 文件夹中定义的用于库名称或版本的常量。
  • 目前,采用 KTS 的构建速度可能比采用 Groovy 慢。

如何报告问题

有关提供重现步骤的说明,请参阅报告 bug:关于构建工具和 Gradle bug 的详细信息。然后,使用 Google 公开问题跟踪器来提交 bug。