Migrate your build configuration from Groovy to KTS

Stay organized with collections Save and categorize content based on your preferences.

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 consider build performance when deciding whether to migrate to KTS.

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” can be used interchangeably. In other words, converting an Android project from Groovy to KTS or from Groovy to the Kotlin DSL is the same thing.

Script file naming

Script file extension names are based on the language the build file is written in:

  • 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.

Migrate one file at a time

Because you can combine Groovy and KTS build files in a project, you can convert your project to KTS one file at a time. Select a build file, like the settings.gradle file. Rename the file to settings.gradle.kts and convert the file's contents to KTS.

Make sure that your project still compiles after the migration of each build file.

Common pitfalls

Some common pitfalls of migrating files include:

  • 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 preceding code calls 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 because the properties are read-only vals in Kotlin.

Explicit and implicit build types

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

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

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

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

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

Apply plugins

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.

The following code is written in Groovy:

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

This is the same code written in Kotlin:

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.

For example:

apply(plugin = "kotlin-android")

For more information about applying the plugins block with the buildScript block, see the Gradle docs.

Known issues

At present, a known issue is that build speed might be slower with KTS than with Groovy

How to report issues

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

More resources

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