Build-Konfiguration von Groovy zu Kotlin migrieren

Mit dem Android-Gradle-Plug-in 4.0 wurde die Verwendung von Kotlin in Ihrer Gradle-Build-Konfiguration unterstützt. Es ersetzt die Programmiersprache Groovy, die bisher in Gradle-Konfigurationsdateien verwendet wird.

Kotlin wird gegenüber Groovy zum Schreiben von Gradle-Skripts bevorzugt, da Kotlin besser lesbar ist und bessere Kompilierungszeitprüfungen sowie IDE-Unterstützung bietet.

Obwohl Kotlin im Vergleich zu Groovy im Code-Editor von Android Studio derzeit eine bessere Integration bietet, sind Builds mit Kotlin tendenziell langsamer als Builds mit Groovy. Daher solltet ihr bei der Entscheidung über eine Migration die Build-Leistung berücksichtigen.

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

Zeitachse

Ab Android Studio Giraffe wird für neue Projekte 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 unter Gradle Kotlin DSL Primer.

Allgemeine Begriffe

Kotlin DSL:Bezieht sich hauptsächlich auf das Android-Gradle-Plug-in Kotlin DSL oder gelegentlich auf das zugrunde liegende Gradle Kotlin DSL.

In dieser Migrationsanleitung werden „Kotlin“ und „Kotlin DSL“ synonym verwendet. Entsprechend werden "Groovy" und "Groovy DSL" austauschbar verwendet.

Skriptdateibenennung

Die Namen der Dateiendungen von Scripts richten sich nach der Sprache, in der die Build-Datei geschrieben ist:

• Gradle-Build-Dateien, die in Groovy geschrieben sind, verwenden die Dateinamenerweiterung .gradle.
• Gradle-Build-Dateien, die in Kotlin geschrieben wurden, verwenden die Dateinamenerweiterung .gradle.kts.

Syntax konvertieren

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

Klammern zu Methodenaufrufen hinzufügen

Mit Groovy können Sie Klammern in Methodenaufrufen weglassen, während sie für Kotlin erforderlich sind. Fügen Sie dieser Art von Methodenaufrufen Klammern hinzu, um die Konfiguration zu migrieren. Dieser Code zeigt, wie eine Einstellung in Groovy konfiguriert wird:

compileSdkVersion 30

Dies ist der gleiche Code, der in Kotlin geschrieben wurde:

compileSdkVersion(30)

= zu Zuweisungsanrufen hinzufügen

In Groovy DSL können Sie beim Zuweisen von Attributen den Zuweisungsoperator = weglassen, Kotlin hingegen schon. Dieser Code zeigt, wie in Groovy Eigenschaften zugewiesen werden:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Dieser Code zeigt, wie in Kotlin Eigenschaften zugewiesen werden:

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

Strings konvertieren

Die Stringunterschiede zwischen Groovy und Kotlin sind folgende:

• Doppelte Anführungszeichen für Strings:In Groovy können Strings mit einfachen Anführungszeichen definiert werden. Bei Kotlin sind doppelte Anführungszeichen erforderlich.

• Stringinterpolation bei gepunkteten Ausdrücken:In Groovy können Sie nur das Präfix $ für Stringinterpolation bei gepunkteten Ausdrücken verwenden. Bei Kotlin müssen die Ausdrücke jedoch in geschweifte 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 ruft der vorherige Code jedoch toString() für project und nicht für project.rootDir auf. Um den Wert des Stammverzeichnisses zu erhalten, 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 Stringvorlagen.

Dateiendungen umbenennen

Hängen Sie .kts an jede Build-Datei an, wenn Sie ihren 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. Sorgen Sie dafür, dass Ihr Projekt auch nach der Migration jeder Build-Datei kompiliert wird.

Migrieren Sie zuerst Ihre kleinsten Dateien, sammeln Sie Erfahrungen und machen Sie dann weiter. Sie können in einem Projekt sowohl Kotlin- als auch Groovy-Build-Dateien haben.

def durch val oder var ersetzen

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

def building64Bit = false

Dies ist der gleiche Code, der in Kotlin geschrieben wurde:

val building64Bit = false

Booleschen Attributen is voranstellen

Groovy verwendet die Logik von Property-Abzügen, die auf den Property-Namen basieren. Für das boolesche Attribut foo können die abgeleiteten Methoden getFoo, setFoo oder isFoo sein. Daher müssen Sie nach der Konvertierung in Kotlin die Attributnamen in die abgeleiteten Methoden ändern, die von Kotlin nicht unterstützt werden. Beispielsweise müssen Sie bei buildTypes booleschen DSL-Elementen 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 den gleichen 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 Zuordnungen in Groovy und Kotlin werden mit einer anderen Syntax definiert. Groovy verwendet [], während Kotlin Methoden zum Erstellen von Sammlungen explizit mit listOf oder mapOf aufruft. Achten Sie darauf, bei der Migration [] durch listOf oder mapOf zu ersetzen.

So definierst du eine Liste in Groovy im Vergleich zu Kotlin:

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

Dies ist der gleiche Code, der in Kotlin geschrieben wurde:

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

So definierst du eine Karte in Groovy im Vergleich zu Kotlin:

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

Dies ist der gleiche 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 für die Fehlerbehebung und den 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 vorher zu erstellen. 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 buildscript {}-Block verwendet, um dem Projekt Plug-ins hinzuzufügen, sollten Sie stattdessen den plugins {}-Block verwenden. Der plugins {}-Block vereinfacht 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 wenn der Build fehlschlägt. Dieser Kontext hilft dabei, Korrekturen an Ihren Kotlin-DSL-Dateien vorzunehmen, da die Studio IDE die Codevervollständigung ausführen und andere nützliche Vorschläge machen kann.

Plug-in-IDs suchen

Während der buildscript {}-Block die Plug-ins dem Build-Klassenpfad mithilfe der Maven-Koordinaten des Plug-ins, z. B. com.android.tools.build:gradle:7.4.0, hinzufügt, 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.

Kotlin-Plug-ins können von mehreren Plug-in-IDs referenziert werden. Wir empfehlen, die Plug-in-ID für den Namespace zu verwenden und gemäß der folgenden Tabelle von der Kurzschreibweise in die Plug-in-ID mit Namespace zu refaktorieren:

Abkürzung für Plug-in-IDs	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

Außerdem können Sie im Gradle-Plug-in-Portal, im Maven Central Repository und im Google Maven-Repository nach Plug-ins suchen. Weitere Informationen zur Funktionsweise von Plug-in-IDs finden Sie unter Benutzerdefinierte Gradle-Plug-ins entwickeln.

Refaktorierung durchführen

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

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 plugins {}-Block in der Datei build.gradle der obersten 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 Datei build.gradle.kts der obersten Ebene.

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

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

Plug-in-Block konvertieren

Das Anwenden von Plug-ins aus dem plugins {}-Block erfolgt in Groovy und Kotlin ähnlich. Der folgende Code zeigt, wie Plug-ins in Groovy bei Verwendung von Versionskatalogen angewendet werden:

// 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 dies ebenfalls in Kotlin getan wird:

// 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 dies ebenfalls in Kotlin getan wird:

// 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 plugins {}-Block 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 den Abschnitt Verkleinern, Verschleierung und Optimierung aktivieren.
• Informationen zu einem signingConfig {}-Block finden Sie unter Signaturinformationen aus Build-Dateien entfernen.
• Wenn Sie projektweite Attribute verwenden, finden Sie weitere Informationen unter Projektweite Attribute konfigurieren.

Bekannte Probleme

Ein bekanntes Problem besteht derzeit darin, dass die Build-Geschwindigkeit mit Kotlin möglicherweise langsamer ist als mit Groovy.

Probleme melden

Eine Anleitung dazu, wie Sie uns die Informationen zur Verfügung stellen, die wir zum Erkennen Ihres Problems benötigen, finden Sie unter Details zu Build-Tools und Gradle-Fehlern. Melden Sie anschließend über die öffentliche Problemverfolgung von Google einen Fehler.

Weitere Informationen

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