Migrate your build configuration from Groovy to KTS

Android Gradle plugin 4.0 added support for using Kotlin script (KTS) in your Gradle build configuration as a replacement for Groovy, the programming language traditionally used in Gradle configuration files.

In the future, KTS will be preferred over Groovy for writing Gradle scripts because Kotlin is more readable and offers better compile-time checking and IDE support.

Although KTS currently offers better integration in Android Studio’s code editor when compared to Groovy, builds using KTS tend to be slower than builds using Groovy, so migrating to KTS should be considered with build performance in mind.

This page provides basic information about converting your Android app’s Gradle build files from Groovy to KTS.

For a more comprehensive migration guide, see Gradle’s official documentation.

Common terms

KTS: Refers to Kotlin script, a flavor of the Kotlin language used by Gradle in build configuration files. Kotlin script is Kotlin code that can be run from the command line.

Kotlin DSL: Refers primarily to the Android Gradle plugin Kotlin DSL or, occasionally, to the underlying Gradle Kotlin DSL.

In the context of migrating from Groovy, the terms “KTS” and “Kotlin DSL” may be used interchangeably. In other words, converting an Android project from Groovy to KTS or from Groovy to the Kotlin DSL is effectively the same.

Script file naming

  • Gradle build files written in Groovy use the .gradle file name extension.
  • Gradle build files written in Kotlin use the .gradle.kts file name extension.

Migrating one file at a time

Because you can combine Groovy and KTS build files in a project, a simple way to start converting your project to KTS is to select a simple build file, like settings.gradle, rename it to settings.gradle.kts, and convert its contents to KTS. Then make sure that your project still compiles after a migration of each build file.

Common pitfalls

  • Double quotes for strings. While Groovy allows strings to be defined using single quotes, Kotlin requires double quotes.
  • String interpolation on dotted expressions. In Groovy, you can use the $ prefix for string interpolation on dotted expressions, such as $project.rootDir in the following snippet:

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

    In Kotlin, however, the code above will call toString() on project, not on project.rootDir. To get the value of the root directory, wrap the entire variable with curly braces:

    myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
    
  • Variable assignments. Some assignments that worked in Groovy are now setters (or "addX" for lists, collections, etc.) because the properties are read-only vals in Kotlin.

Explicit and implicit buildTypes

In the Kotlin DSL, certain buildTypes, such as debug and release,are available implicitly. Other buildTypes, however, must be created manually.

In Groovy, for example, you might have debug, release, and staging buildTypes:

Groovy

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

In KTS, only the debug and release buildTypes are available implicitly, while staging must be created:

KTS

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

Use the plugins block

Applying plugins is similar in Groovy and KTS. In both languages, use the plugins block to add plugins.

When you use the plugins block in your build files, the IDE is aware of the context even when the build fails. This context is helpful for making fixes to your KTS files because it allows the IDE to perform code completion and provide other helpful suggestions.

This code in Groovy...

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

...becomes the following in KTS:

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

For more details about the plugins block, see Gradle’s migration guide.

Note: The plugins block only resolves plugins available in the Gradle plugin portal or a custom repository specified using a pluginManagement block. Plugins that come from buildScript dependencies that aren’t available in the plugin portal must be applied using apply in Kotlin. For example:

apply(plugin = "kotlin-android")

For more information, see the Gradle docs.

More resources

For a working example of Gradle build files written with KTS, see the IOSched sample app on GitHub.

Known issues

The following are known issues:

  • The Project Structure editor doesn’t expand constants defined in the buildSrc folder that are used for library names or versions.
  • At present, build speed may be slower with KTS than with Groovy.

How to report issues

For instructions on providing reproduction steps, see Report a bug: Details for build tools and Gradle bugs. Then, file a bug using the Google public issue tracker.