Mit Version 4.0 des Android-Gradle-Plug-ins wird die Verwendung von Kotlin in Ihrer Gradle-Build-Konfiguration als Ersatz für Groovy unterstützt, die Programmiersprache, die bisher in Gradle-Konfigurationsdateien verwendet wird.
Beim Schreiben von Gradle-Skripts wird Kotlin gegenüber Groovy bevorzugt, da Kotlin besser lesbar ist und eine bessere Prüfung bei der Kompilierungszeit sowie IDE-Unterstützung bietet.
Obwohl Kotlin derzeit im Vergleich zu Groovy eine bessere Integration in den Code-Editor von Android Studio bietet, sind Builds mit Kotlin tendenziell langsamer als Builds mit Groovy. Berücksichtigen Sie daher bei der Entscheidung, ob Sie eine Migration vornehmen, die Build-Leistung.
Auf dieser Seite finden Sie grundlegende Informationen zum Konvertieren der Gradle-Build-Dateien Ihrer Android-App von Groovy in Kotlin. Eine ausführlichere Migrationsanleitung finden Sie in der offiziellen Gradle-Dokumentation.
Zeitleiste
Ab Android Studio Giraffe wird in neuen Projekten standardmäßig Kotlin DSL (build.gradle.kts
) für die Build-Konfiguration verwendet. Dies bietet eine bessere Bearbeitung als Groovy DSL (build.gradle
) mit Syntaxhervorhebung, Codevervollständigung und Navigation zu Deklarationen. Weitere Informationen finden Sie in der Gradle Kotlin DSL Primer App.
Allgemeine Begriffe
Kotlin DSL:Bezieht sich in erster Linie auf das Android-Gradle-Plug-in Kotlin DSL oder gelegentlich auf die zugrunde liegende Gradle Kotlin DSL.
In dieser Migrationsanleitung werden „Kotlin“ und „Kotlin DSL“ synonym verwendet. "Groovy" und "Groovy DSL" werden ebenfalls synonym verwendet.
Benennung von Skriptdateien
Die Namen von Skript-Dateiendungen basieren auf der Sprache, in der die Build-Datei geschrieben ist:
- In Groovy geschriebene Gradle-Build-Dateien verwenden die Dateiendung
.gradle
. - In Kotlin geschriebene Gradle-Build-Dateien verwenden die Dateiendung
.gradle.kts
.
Syntax konvertieren
Es gibt einige allgemeine Syntaxunterschiede zwischen Groovy und Kotlin, sodass Sie diese Änderungen auf alle Ihre Build-Skripts anwenden müssen.
Klammern zu Methodenaufrufen hinzufügen
Mit Groovy können Sie Klammern in Methodenaufrufen weglassen, in Kotlin sind sie jedoch erforderlich. Fügen Sie bei diesen Arten von Methodenaufrufen Klammern hinzu, um Ihre Konfiguration zu migrieren. Dieser Code zeigt, wie Sie eine Einstellung in Groovy konfigurieren:
compileSdkVersion 30
Dies ist derselbe Code, der in Kotlin geschrieben wurde:
compileSdkVersion(30)
=
zu Zuweisungsanrufen hinzufügen
In Groovy DSL können Sie den Zuweisungsoperator =
beim Zuweisen von Attributen weglassen. Für Kotlin ist dies jedoch erforderlich. Dieser Code zeigt, wie Properties in Groovy zugewiesen werden:
java {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
Dieser Code zeigt, wie Eigenschaften in Kotlin zugewiesen werden:
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
Strings konvertieren
Im Folgenden sind die Stringunterschiede zwischen Groovy und Kotlin aufgeführt:
- Doppelte Anführungszeichen für Strings:Bei Groovy können Strings mit einfachen Anführungszeichen definiert werden, bei Kotlin sind jedoch doppelte Anführungszeichen erforderlich.
-
Stringinterpolation bei gepunkteten Ausdrücken:In Groovy können Sie für Stringinterpolationen bei gepunkteten Ausdrücken nur das Präfix
$
verwenden. In Kotlin müssen die Ausdrücke jedoch in geschweiften Klammern gesetzt werden. In Groovy können Sie beispielsweise$project.rootDir
verwenden, wie im folgenden Snippet gezeigt:myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
In Kotlin wird mit dem vorherigen Code
toString()
jedoch fürproject
aufgerufen, nicht fürproject.rootDir
. Um den Wert des Stammverzeichnisses zu erhalten, setzen Sie den Ausdruck${project.rootDir}
in geschweifte Klammern:myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
Weitere Informationen finden Sie in der Kotlin-Dokumentation unter Stringvorlagen.
Dateiendungen umbenennen
Hängen Sie .kts
an jede Build-Datei an, wenn Sie deren Inhalt migrieren. Wählen Sie beispielsweise eine Build-Datei wie die Datei settings.gradle
aus. Benennen Sie die Datei in settings.gradle.kts
um und konvertieren Sie den Inhalt der Datei in Kotlin. Achten Sie darauf, dass Ihr Projekt nach der Migration jeder Build-Datei noch kompiliert wird.
Migrieren Sie zuerst Ihre kleinsten Dateien, sammeln Sie Erfahrung und machen Sie dann weiter. Sie können in einem Projekt sowohl Kotlin- als auch Groovy-Build-Dateien verwenden. Nehmen Sie sich daher die Zeit, die Migration sorgfältig durchzuführen.
Ersetzen Sie „def
“ durch „val
“ oder „var
“
Ersetzen Sie def
durch val
oder var
. So können Sie Variablen in Kotlin definieren.
Dies ist eine Variablendeklaration in Groovy:
def building64Bit = false
Dies ist derselbe Code, der in Kotlin geschrieben wurde:
val building64Bit = false
Booleschen Attributen das Präfix is
voranstellen
Groovy verwendet auf den Property-Namen eine Logik für den Property-Abzug. Bei einem booleschen Attribut foo
können die abgeleiteten Methoden getFoo
, setFoo
oder isFoo
sein. Nach der Konvertierung in Kotlin müssen Sie daher die Attributnamen in die abgeleiteten Methoden ändern, die von Kotlin nicht unterstützt werden. Bei booleschen DSL-Elementen vom Typ buildTypes
müssen Sie ihnen beispielsweise das Präfix is
voranstellen. Dieser Code zeigt, wie boolesche Eigenschaften in Groovy festgelegt werden:
android {
buildTypes {
release {
minifyEnabled true
shrinkResources true
...
}
debug {
debuggable true
...
}
...
Im Folgenden sehen Sie denselben Code in Kotlin. Den Attributen ist is
vorangestellt.
android {
buildTypes {
getByName("release") {
isMinifyEnabled = true
isShrinkResources = true
...
}
getByName("debug") {
isDebuggable = true
...
}
...
Listen und Karten konvertieren
Listen und Karten in Groovy und Kotlin werden mit unterschiedlicher Syntax definiert. Groovy verwendet []
, während Kotlin Methoden zum Erstellen von Sammlungen explizit mit listOf
oder mapOf
aufruft. Ersetzen Sie bei der Migration []
durch listOf
oder mapOf
.
So definieren Sie eine Liste in Groovy oder Kotlin:
jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]
Dies ist derselbe Code, der in Kotlin geschrieben wurde:
jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")
So definieren Sie eine Karte in Groovy oder Kotlin:
def myMap = [key1: 'value1', key2: 'value2']
Dies ist derselbe Code, der in Kotlin geschrieben wurde:
val myMap = mapOf("key1" to "value1", "key2" to "value2")
Build-Typen konfigurieren
In Kotlin DSL sind nur die Build-Typen Debug und Release verfügbar. Alle anderen benutzerdefinierten Build-Typen müssen manuell erstellt werden.
In Groovy können Sie den Debug-, Release- und bestimmte andere Build-Typen verwenden, ohne sie vorher erstellen zu müssen. Das folgende Code-Snippet zeigt eine Konfiguration mit den Build-Typen debug
, release
und benchmark
in Groovy.
buildTypes {
debug {
...
}
release {
...
}
benchmark {
...
}
}
Um die entsprechende Konfiguration in Kotlin zu erstellen, müssen Sie den Build-Typ benchmark
explizit erstellen.
buildTypes {
debug {
...
}
release {
...
}
register("benchmark") {
...
}
}
Von Buildscript zum Plug-in-Block migrieren
Wenn Ihr Build den Block buildscript {}
verwendet, um dem Projekt Plug-ins hinzuzufügen, sollten Sie refaktorieren, um stattdessen den Block plugins {}
zu verwenden. Der Block plugins {}
erleichtert das Anwenden von Plug-ins und funktioniert gut mit Versionskatalogen.
Wenn Sie den plugins {}
-Block in Ihren Build-Dateien verwenden, erkennt Android Studio den Kontext auch dann, wenn der Build fehlschlägt. Dieser Kontext hilft bei Korrekturen Ihrer DSL-Dateien in Kotlin, da die Studio-IDE damit die Codevervollständigung ausführen und weitere hilfreiche Vorschläge machen kann.
Plug-in-IDs suchen
Der buildscript {}
-Block fügt die Plug-ins mithilfe der Maven-Koordinaten des Plug-ins (z. B. com.android.tools.build:gradle:7.4.0
) in den Build-Klassenpfad ein, während im Block plugins {}
stattdessen die Plug-in-IDs verwendet werden.
Bei den meisten Plug-ins ist die Plug-in-ID der String, der verwendet wird, wenn Sie sie mit apply plugin
anwenden. Die folgenden Plug-in-IDs sind beispielsweise Teil des Android-Gradle-Plug-ins:
com.android.application
com.android.library
com.android.lint
com.android.test
Die vollständige Liste der Plug-ins finden Sie im Maven-Repository von Google.
Auf Kotlin-Plug-ins kann von mehreren Plug-in-IDs verwiesen werden. Wir empfehlen die Verwendung der Namespace-Plug-in-ID und die Refaktorierung von der Kurzschreibweise in die Namespace-Plug-in-ID gemäß der folgenden Tabelle:
Kurzschreibweise Plug-in-IDs | Namespace-Plug-in-IDs |
---|---|
kotlin |
org.jetbrains.kotlin.jvm |
kotlin-android |
org.jetbrains.kotlin.android |
kotlin-kapt |
org.jetbrains.kotlin.kapt |
kotlin-parcelize |
org.jetbrains.kotlin.plugin.parcelize |
Sie können auch im Gradle-Plug-in-Portal, im Maven Central Repository und im Maven-Repository von Google nach Plug-ins suchen. Weitere Informationen zur Funktionsweise von Plug-in-IDs finden Sie unter Benutzerdefinierte Gradle-Plug-ins entwickeln.
Refaktorierung ausführen
Führen Sie die folgenden Schritte aus, sobald Sie die IDs der verwendeten Plug-ins kennen:
Wenn Sie noch Repositories für Plug-ins haben, die im Block
buildscript {}
deklariert sind, verschieben Sie diese stattdessen in die Dateisettings.gradle
.Fügen Sie die Plug-ins dem Block
plugins {}
in der Dateibuild.gradle
auf oberster Ebene hinzu. Hier müssen Sie die ID und die Version des Plug-ins angeben. Wenn das Plug-in nicht auf das Stammprojekt angewendet werden muss, verwenden Sieapply false
.Entfernen Sie die
classpath
-Einträge aus der übergeordneten Dateibuild.gradle.kts
.Wenden Sie die Plug-ins an, indem Sie sie dem Block
plugins {}
in der Dateibuild.gradle
auf Modulebene hinzufügen. Sie müssen hier nur die Plug-in-ID angeben, da die Version vom Stammprojekt übernommen wird.Entfernen Sie den Aufruf
apply plugin
für das Plug-in aus der Dateibuild.gradle
auf Modulebene.
Bei dieser Konfiguration wird beispielsweise der Block buildscript {}
verwendet:
// Top-level build.gradle file
buildscript {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
dependencies {
classpath("com.android.tools.build:gradle:7.4.0")
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
...
}
}
// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")
Diese Einrichtung entspricht einer Konfiguration mit dem Block plugins {}
:
// Top-level build.gradle file
plugins {
id 'com.android.application' version '7.4.0' apply false
id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
...
}
// Module-level build.gradle file
plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
...
}
// settings.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
Plug-in-Block konvertieren
Das Anwenden von Plug-ins aus dem plugins {}
-Block funktioniert in Groovy und Kotlin ähnlich.
Der folgende Code zeigt, wie Plug-ins in Groovy angewendet werden, wenn Sie Versionskataloge verwenden:
// Top-level build.gradle file
plugins {
alias libs.plugins.android.application apply false
...
}
// Module-level build.gradle file
plugins {
alias libs.plugins.android.application
...
}
Im folgenden Code sehen Sie, wie Sie dies in Kotlin tun können:
// 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)
...
}
Der folgende Code zeigt, wie Sie Plug-ins in Groovy anwenden, wenn Sie keine Versionskataloge verwenden:
// 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'
...
}
Im folgenden Code sehen Sie, wie Sie dies in Kotlin tun können:
// 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")
...
}
Weitere Informationen zum Block plugins {}
finden Sie in der Gradle-Dokumentation unter Plug-ins anwenden.
Sonstiges
Kotlin-Codebeispiele für andere Funktionen finden Sie auf den folgenden Dokumentationsseiten:
- Wenn Sie eine ProGuard-Konfiguration haben, lesen Sie Verkleinerung, Verschleierung und Optimierung aktivieren.
- Wenn Sie einen
signingConfig {}
-Block haben, lesen Sie den Abschnitt Signaturinformationen aus Build-Dateien entfernen. - Wenn Sie projektweite Attribute verwenden, finden Sie weitere Informationen unter Projektweite Attribute konfigurieren.
Bekannte Probleme
Derzeit ist ein bekanntes Problem, dass die Build-Geschwindigkeit mit Kotlin unter Umständen langsamer ist als mit Groovy.
Probleme melden
Eine Anleitung dazu, wie wir die Informationen angeben, die wir zum Erkennen des Problems benötigen, finden Sie unter Details zu Build-Tools und Gradle-Fehlern. Melden Sie dann den Fehler über die öffentliche Problemverfolgung von Google.
Weitere Informationen
Ein funktionierendes Beispiel für Gradle-Build-Dateien, die mit Kotlin geschrieben wurden, finden Sie in der Beispiel-App „Now In Android“ auf GitHub.