Build-Konfiguration von Groovy zu Kotlin migrieren

Mit dem Android-Gradle-Plug-in 4.0 wurde die Unterstützung für die Verwendung von Kotlin in der Gradle-Build-Konfiguration als Ersatz für Groovy hinzugefügt, die Programmiersprache, die traditionell in Gradle-Konfigurationsdateien verwendet wird.

Kotlin wird für das Schreiben von Gradle-Skripts gegenüber Groovy bevorzugt, da Kotlin besser lesbar ist und eine bessere Kompilierzeitprüfung und IDE-Unterstützung bietet.

Obwohl Kotlin derzeit eine bessere Integration in den Code-Editor von Android Studio bietet als Groovy, sind Builds mit Kotlin in der Regel langsamer als Builds mit Groovy. Berücksichtigen Sie daher die Build-Leistung, wenn Sie sich für eine Migration entscheiden.

Auf dieser Seite finden Sie grundlegende Informationen zum Konvertieren der Gradle-Build-Dateien Ihrer Android-App von Groovy in Kotlin. Eine umfassendere Migration Anleitung finden Sie in der offiziellen Gradle-Dokumentation .

Zeitachse

Ab Android Studio Giraffe verwenden neue Projekte standardmäßig die Kotlin-DSL (build.gradle.kts) für die Build-Konfiguration. Dies bietet eine bessere Bearbeitung als die Groovy-DSL (build.gradle) mit Syntaxhervorhebung, Codevervollständigung und Navigation zu Deklarationen. Weitere Informationen finden Sie unter siehe die Einführung in die Kotlin-DSL von Gradle.

Allgemeine Versicherungsbedingungen

Kotlin-DSL: Bezieht sich hauptsächlich auf die Kotlin-DSL des Android-Gradle-Plug-ins oder gelegentlich auf die zugrunde liegende Kotlin-DSL von Gradle.

In dieser Migrationsanleitung werden „Kotlin“ und „Kotlin-DSL“ austauschbar verwendet. Ebenso werden „Groovy“ und „Groovy-DSL“ austauschbar verwendet.

Benennung von Skriptdateien

Die Dateiendungen von Skriptdateien basieren auf der Sprache, in der die Build-Datei geschrieben ist:

Gradle-Build-Dateien, die in Groovy geschrieben wurden, verwenden die Dateiendung .gradle.
Gradle-Build-Dateien, die in Kotlin geschrieben wurden, verwenden die Dateiendung .gradle.kts.

Syntax konvertieren

Es gibt einige allgemeine Unterschiede in der Syntax zwischen Groovy und Kotlin. Sie müssen diese Änderungen daher in allen Ihren Build-Skripts anwenden.

Klammern zu Methodenaufrufen hinzufügen

In Groovy können Sie Klammern in Methodenaufrufen weglassen, in Kotlin sind sie jedoch erforderlich. Wenn Sie Ihre Konfiguration migrieren möchten, fügen Sie Klammern zu diesen Arten von Methodenaufrufen hinzu. Dieser Code zeigt, wie Sie eine Einstellung in Groovy konfigurieren:

compileSdkVersion 30

Das ist derselbe Code in Kotlin:

compileSdkVersion(30)

`=` zu Zuweisungsaufrufen hinzufügen

In der Groovy-DSL können Sie den Zuweisungsoperator = beim Zuweisen von Attributen weglassen, in Kotlin ist er jedoch erforderlich. Dieser Code zeigt, wie Sie Attribute in Groovy zuweisen:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Dieser Code zeigt, wie Sie Attribute in Kotlin zuweisen:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Strings konvertieren

Hier sind die String-Unterschiede zwischen Groovy und Kotlin:

Doppelte Anführungszeichen für Strings: In Groovy können Strings mit einfachen Anführungszeichen definiert werden, in Kotlin sind jedoch doppelte Anführungszeichen erforderlich.
String-Interpolation für gepunktete Ausdrücke: In Groovy können Sie für String-Interpolationen für gepunktete Ausdrücke nur das Präfix $ verwenden. In Kotlin müssen Sie die gepunkteten Ausdrücke jedoch in geschweifte Klammern setzen. In Groovy können Sie beispielsweise $project.rootDir verwenden, wie im folgenden Snippet gezeigt:
```
    myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
    
```
In Kotlin ruft der vorherige Code jedoch toString() für project und nicht für project.rootDir auf. Wenn Sie den Wert des Stammverzeichnisses abrufen möchten, setzen Sie den ${project.rootDir} Ausdruck in geschweifte Klammern:
```
    myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
    
```
Weitere Informationen finden Sie in der Kotlin-Dokumentation unter String-Vorlagen.

Dateiendungen umbenennen

Hängen Sie .kts an jede Build-Datei an, während Sie ihren Inhalt migrieren. Wählen Sie beispielsweise eine Build-Datei wie 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 weiterhin kompiliert wird.

Migrieren Sie zuerst die kleinsten Dateien, sammeln Sie Erfahrung und fahren Sie dann fort. In einem Projekt können sowohl Kotlin- als auch Groovy-Build-Dateien vorhanden sein. Nehmen Sie sich also Zeit, um die Migration sorgfältig durchzuführen.

`def` durch `val` oder `var` ersetzen

Ersetzen Sie def durch val oder var, mit denen Sie Variablen in Kotlin definieren. Dies ist eine Variablendeklaration in Groovy:

def building64Bit = false

Das ist derselbe Code in Kotlin:

val building64Bit = false

Boolesche Attribute mit `is` präfixieren

Groovy verwendet eine Logik zur Attributableitung die auf den Attributnamen basiert. Für ein boolesches Attribut foo können die abgeleiteten Methoden getFoo, setFoo oder isFoo sein. Nach der Konvertierung in Kotlin müssen Sie die Attributnamen in die abgeleiteten Methoden ändern, die von Kotlin nicht unterstützt werden. Für boolesche Elemente der buildTypes-DSL müssen Sie beispielsweise das Präfix is verwenden. Dieser Code zeigt, wie Sie boolesche Attribute in Groovy festlegen:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

Das ist derselbe Code in Kotlin. Beachten Sie, dass die Attribute das Präfix is haben.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Listen und Maps konvertieren

Listen und Maps werden in Groovy und Kotlin mit unterschiedlicher Syntax definiert. Groovy verwendet [], während Kotlin Methoden zur Erstellung von Sammlungen explizit mit listOf oder mapOf aufruft. Ersetzen Sie bei der Migration [] durch listOf oder mapOf.

So definieren Sie eine Liste in Groovy und Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

Das ist derselbe Code in Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

So definieren Sie eine Map in Groovy und Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

Das ist derselbe Code in Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Build-Typen konfigurieren

In der Kotlin-DSL sind nur die Build-Typen „Debug“ und „Release“ implizit verfügbar. Alle anderen benutzerdefinierten Build-Typen müssen manuell erstellt werden.

In Groovy können Sie die Build-Typen „Debug“, „Release“ und bestimmte andere Build-Typen verwenden, ohne sie zuerst zu erstellen. Das folgende Code-Snippet zeigt eine Konfiguration mit den debug, release, und benchmark Build Typen in Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

Wenn Sie die entsprechende Konfiguration in Kotlin erstellen möchten, müssen Sie den Build-Typ benchmark explizit erstellen.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Von „buildscript“ zu „plugins“ migrieren

Wenn Ihr Build den buildscript {} Block verwendet, um Plug-ins zum Projekt hinzuzufügen, sollten Sie ihn so umgestalten, dass stattdessen der plugins {} Block verwendet wird. Der plugins {} Block erleichtert das Anwenden von Plug-ins und es funktioniert gut mit Versionskatalogen.

Wenn Sie den Block plugins {} in Ihren Build-Dateien verwenden, kennt Android Studio den Kontext auch dann, wenn der Build fehlschlägt. Dieser Kontext hilft, Fehler in Ihren Kotlin-DSL-Dateien zu beheben, da die Studio-IDE Codevervollständigung und andere hilfreiche Vorschläge anbieten kann.

Plug-in-IDs finden

Während der buildscript {} Block die Plug-ins dem Build-Klassenpfad mit den Maven-Koordinaten des Plug-ins hinzufügt, z. B. com.android.tools.build:gradle:7.4.0, verwendet der plugins {} Block stattdessen die Plug-in-IDs.

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 mit mehreren Plug-in-IDs verwiesen werden. Wir empfehlen, die Plug-in-ID mit Namespace zu verwenden. In der folgenden Tabelle finden Sie Informationen zum Umgestalten von Kurzformen zu Plug-in-IDs mit Namespace:

Plug-in-IDs in Kurzform	Plug-in-IDs mit Namespace
`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.

Umgestaltung durchführen

Sobald Sie die IDs der verwendeten Plug-ins kennen, führen Sie die folgenden Schritte aus:

Wenn Sie noch Repositorys für Plug-ins haben, die im buildscript {} Block deklariert sind, verschieben Sie sie stattdessen in die settings.gradle Datei.
Fügen Sie die Plug-ins dem Block plugins {} in der build.gradle-Datei 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 Sie apply false.
Entfernen Sie die classpath-Einträge aus der build.gradle.kts-Datei auf oberster Ebene.
Wenden Sie die Plug-ins an, indem Sie sie dem Block plugins {} in der build.gradle-Datei auf Modulebene hinzufügen. Hier müssen Sie nur die ID des Plug-ins angeben, da die Version vom Stammprojekt übernommen wird.
Entfernen Sie den Aufruf apply plugin für das Plug-in aus der build.gradle-Datei auf Modulebene.

Bei dieser Einrichtung 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")

Dies ist eine entsprechende Einrichtung 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()
    }
}

Block „plugins“ konvertieren

Das Anwenden von Plug-ins aus dem Block plugins {} ist in Groovy und Kotlin ähnlich. Der folgende Code zeigt, wie Sie Plug-ins in Groovy anwenden, 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
   ...
}

Der folgende Code zeigt, wie Sie dasselbe in Kotlin tun:

// 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'
   ...
}

Der folgende Code zeigt, wie Sie dasselbe in Kotlin tun:

// 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 Komprimierung, Verschleierung und Optimierung aktivieren.
Wenn Sie einen Block signingConfig {} haben, lesen Sie Signaturinformationen aus Build-Dateien entfernen.
Wenn Sie projektweite Attribute verwenden, lesen Sie Projektweite Attribute konfigurieren.

Bekannte Probleme

Derzeit ist ein bekanntes Problem dass die Build-Geschwindigkeit mit Kotlin möglicherweise langsamer ist als mit Groovy.

Probleme melden

Eine Anleitung zum Bereitstellen der Informationen, die wir zur Triage Ihres Problems benötigen, finden Sie unter Details zu Fehlern in Build-Tools und Gradle. Melden Sie dann einen Fehler mit dem Google öffentlichen Tool zur Problemverfolgung.

Weitere Ressourcen

Ein funktionierendes Beispiel für Gradle-Build-Dateien, die mit Kotlin geschrieben wurden, finden Sie in der Beispiel-App Now In Android auf GitHub.

Build-Konfiguration von Groovy zu Kotlin migrieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Zeitachse

Allgemeine Versicherungsbedingungen

Benennung von Skriptdateien

Syntax konvertieren

Klammern zu Methodenaufrufen hinzufügen

= zu Zuweisungsaufrufen hinzufügen

Strings konvertieren

Dateiendungen umbenennen

def durch val oder var ersetzen

Boolesche Attribute mit is präfixieren

Listen und Maps konvertieren

Build-Typen konfigurieren

Von „buildscript“ zu „plugins“ migrieren

Plug-in-IDs finden

Umgestaltung durchführen

Block „plugins“ konvertieren

Sonstiges

Bekannte Probleme

Probleme melden

Weitere Ressourcen

Build-Konfiguration von Groovy zu Kotlin migrieren

`=` zu Zuweisungsaufrufen hinzufügen

`def` durch `val` oder `var` ersetzen

Boolesche Attribute mit `is` präfixieren