Kotlin script (KTS) is preferred over Groovy for writing Gradle scripts because Kotlin is more readable and offers better compile-time checking and IDE support. Android Gradle plugin 4.0 added support for using KTS in your Gradle build configuration.
This page provides basic information about converting your Android app's Gradle build files from Groovy to KTS. We recommend you do the steps in the order listed. See also Gradle's migration guide and Kotlin DSL Primer. If you're migrating multiple projects, start with your smallest project so you gain experience, and then continue from there.
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.
Convert the syntax
There are some general differences in syntax between Groovy and Kotlin, so you need to apply these changes throughout your build scripts.
Add parentheses to method calls
Groovy lets you to omit parentheses in method calls, while Kotlin requires them. To migrate your configuration, add parentheses to these sorts of method calls. This code shows how to configure a setting in Groovy:
compileSdkVersion 30
This is the same code written in Kotlin:
compileSdkVersion(30)
Add =
to assignment calls
The Gradle Groovy DSL lets you to omit the assignment operator =
when
assigning properties, whereas Kotlin requires it. This code shows how to
assign properties in Groovy:
java {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
This code shows how to assign properties in Kotlin:
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
Convert strings
Here are the string differences between Groovy and Kotlin:
- 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 just the
$
prefix for string interpolations on dotted expressions, but Kotlin requires that you wrap the dotted expressions with curly braces. For example, in Groovy you can use$project.rootDir
as shown in the following snippet:myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
In Kotlin, however, the preceding code calls
toString()
onproject
, not onproject.rootDir
. To get the value of the root directory, wrap the${project.rootDir}
expression with curly braces:myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
To learn more, see String templates in the Kotlin documentation.
Rename file extensions
Append .kts
to each build file as you migrate its contents. For example,
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 your
project still compiles after the migration of each build file.
Migrate your smallest files first, gain experience, and then move on. You can have a mix of KTS and Groovy build files in a project, so take your time to carefully make the move.
Replace def
with val
or var
Replace def
with val
or var
, which is
how you define variables in Kotlin.
This is a variable declaration in Groovy:
def building64Bit = false
This is the same code written in Kotlin:
val building64Bit = false
Prefix boolean properties with is
Groovy uses property deduction logic
based on the property names. For a boolean property foo
, its deduced methods
can be getFoo
, setFoo
, or isFoo
. Thus once converted to Kotlin,
you need to change the property names to the deduced methods
that are not supported by Kotlin. For example, for
buildTypes
DSL boolean elements, you need to prefix them with is
. This code
shows how to set boolean properties in Groovy:
android {
buildTypes {
release {
minifyEnabled true
shrinkResources true
...
}
debug {
debuggable true
...
}
...
The following is the same code in Kotlin. Note that the properties are prefixed
by is
.
android {
buildTypes {
getByName("release") {
isMinifyEnabled = true
isShrinkResources = true
...
}
getByName("debug") {
isDebuggable = true
...
}
...
Convert lists and maps
Lists and maps in Groovy and Kotlin are defined using different syntax. Groovy
uses []
, while Kotlin calls collection creation methods explicitly using
listOf
or mapOf
. Make sure to replace []
with listOf
or mapOf
when
migrating.
Here's how to define a list in Groovy versus Kotlin:
jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]
This is the same code written in Kotlin:
jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")
Here's how to define a map in Groovy versus Kotlin:
def myMap = [key1: 'value1', key2: 'value2']
This is the same code written in Kotlin:
val myMap = mapOf("key1" to "value1", "key2" to "value2")
Configure build types
In the Kotlin DSL only the debug and release build types are available implicitly. All other custom build types must be created manually.
In Groovy you can use the debug, release, and certain other build types without
creating them first. The following code snippet shows a configuration with the
debug
, release
, and
benchmark
build
types in Groovy.
buildTypes {
debug {
...
}
release {
...
}
benchmark {
...
}
}
To create the equivalent configuration in KTS, you must explicitly create the
benchmark
build type.
buildTypes {
debug {
...
}
release {
...
}
register("benchmark") {
...
}
}
Convert the plugins block
Applying plugins is similar in Groovy and KTS. In both KTS and
Groovy, we recommend using the plugins {}
block instead of using
the buildscript
with apply
to apply plugins.
When you use the plugins {}
block in your build files, Android Studio is
aware of the context even when the build fails. This context helps make fixes
to your KTS files because it allows the Studio IDE to perform code completion
and provide other helpful suggestions.
The following code shows how to apply plugins in Groovy when you're using Gradle Version Catalogs:
// Top-level build.gradle file
plugins {
alias libs.plugins.android.application apply false
...
}
// Module-level build.gradle file
plugins {
alias libs.plugins.android.application
...
}
The following code shows how to do the same in Kotlin:
// Top-level build.gradle.kts file
plugins {
alias(libs.plugins.android.application) apply false
...
}
// Module-level build.gradle.kts file
plugins {
alias(libs.plugins.android.application)
...
}
The following code shows how to apply plugins in Groovy when you're not using Gradle Version Catalogs:
// Top-level build.gradle file
plugins {
id 'com.android.application' version '7.3.0' apply false
...
}
// Module-level build.gradle file
plugins {
id 'com.android.application'
...
}
The following code shows how to do the same in Kotlin:
// Top-level build.gradle.kts file
plugins {
id("com.android.application") version '7.3.0' apply false
...
}
// Module-level build.gradle.kts file
plugins {
id("com.android.application")
...
}
For more details about the plugins {}
block, see Applying
plugins
in the Gradle documentation.
Miscellaneous
For Kotlin code samples for other functionalities, see the following documentation pages:
- If you have a ProGuard configuration, refer to Enable shrinking, obfuscation, and optimization.
- If you have a
signingConfig {}
block, refer to Remove signing information from your build files. - If you use project-wide properties, refer to Configure project-wide properties.
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 how to provide the info we need to triage your 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.