Build-Konfiguration von Groovy zu Kotlin migrieren

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

Hinweis :Kotlin ist die Standardsprache für die Build-Konfiguration, beginnend mit Android Studio Giraffe. Wenn Sie AGP 8.1 und Kotlin DSL für die Build-Konfiguration verwenden, sollten Sie Gradle 8.1 verwenden.

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

Tipp: Fügen Sie Ihrem Groovy-Code zuerst Klammern hinzu, noch bevor Sie die Dateiendung ändern. Das erleichtert die Konvertierung in Kotlin.

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

Tipp :Fügen Sie dem Groovy-Code = hinzu, bevor Sie die Dateiendung ändern. Das erleichtert die Konvertierung in Kotlin.

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ür project aufgerufen, nicht für project.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:

1. Wenn Sie noch Repositories für Plug-ins haben, die im Block buildscript {} deklariert sind, verschieben Sie diese stattdessen in die Datei settings.gradle.

2. Fügen Sie die Plug-ins dem Block plugins {} in der Datei build.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 Sie apply false.

3. Entfernen Sie die classpath-Einträge aus der übergeordneten Datei build.gradle.kts.

4. Wenden Sie die Plug-ins an, indem Sie sie dem Block plugins {} in der Datei build.gradle auf Modulebene hinzufügen. Sie müssen hier nur die Plug-in-ID angeben, da die Version vom Stammprojekt übernommen wird.

5. Entfernen Sie den Aufruf apply plugin für das Plug-in aus der Datei build.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.

Achtung :Mit Gradle können Sie zwar projektweite Attribute auf Modulebene definieren, sollten dies jedoch vermeiden, da die Module mit diesen Attributen verknüpft werden. Durch die Modulkopplung wird das spätere Exportieren eines Moduls als eigenständiges Projekt erschwert. Außerdem wird verhindert, dass Gradle die parallele Projektausführung nutzt, um Builds mit mehreren Modulen zu beschleunigen.

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.