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 Ihrer Gradle-Build-Konfiguration als Ersatz für Groovy eingeführt. Groovy ist die Programmiersprache, die traditionell in Gradle-Konfigurationsdateien verwendet wird.

Kotlin wird gegenüber Groovy zum Schreiben von Gradle-Scripts bevorzugt, da Kotlin besser lesbar ist und eine bessere Überprüfung zur Kompilierzeit 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 also die Build-Leistung, wenn Sie entscheiden, ob Sie migrieren möchten.

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

Zeitachse

Hinweis :Ab Android Studio Giraffe ist Kotlin die Standardsprache für die Build-Konfiguration. Wenn Sie AGP 8.1 und die Kotlin-DSL für die Build-Konfiguration verwenden, sollten Sie Gradle 8.1 verwenden, um die bestmögliche Leistung zu erzielen.

Ab Android Studio Giraffe wird für neue Projekte standardmäßig die Kotlin-DSL (build.gradle.kts) für die Build-Konfiguration verwendet. Das bietet eine bessere Bearbeitung als die Groovy-DSL (build.gradle) mit Syntaxhervorhebung, Codevervollständigung und Navigation zu Deklarationen. Weitere Informationen finden Sie im Gradle Kotlin DSL Primer.

Allgemeine Bedingungen

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

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

Benennung von Skriptdateien

Die Dateiendungen für Skriptdateien basieren auf 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. Sie müssen diese Änderungen also in Ihren gesamten Build-Scripts vornehmen.

Klammern zu Methodenaufrufen hinzufügen

Tipp :Fügen Sie als Erstes, noch bevor Sie die Dateiendungen ändern, Klammern in Ihren Groovy-Code ein. Das erleichtert die Umstellung auf Kotlin.

In Groovy können Sie Klammern in Methodenaufrufen weglassen, in Kotlin sind sie erforderlich. Um Ihre Konfiguration zu migrieren, fügen Sie Klammern in diese Art von Methodenaufrufen ein. Dieser Code zeigt, wie eine Einstellung in Groovy konfiguriert wird:

compileSdkVersion 30

So sieht derselbe Code in Kotlin aus:

compileSdkVersion(30)

= zu Zuweisungsaufrufen hinzufügen

Tipp :Bevor Sie Dateiendungen ändern, fügen Sie Ihrem Groovy-Code = hinzu. Das erleichtert die Umstellung auf Kotlin.

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

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Dieser Code zeigt, wie Sie in Kotlin Eigenschaften 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 Ausdrücke mit Punkten:In Groovy können Sie für String-Interpolationen für Ausdrücke mit Punkten nur das Präfix $ verwenden. In Kotlin müssen Sie die Ausdrücke mit Punkten 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 wird im vorherigen Code jedoch toString() für project und nicht für project.rootDir aufgerufen. Wenn Sie den Wert des Stammverzeichnisses abrufen möchten, 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 String-Vorlagen.

Dateiendungen umbenennen

Hängen Sie .kts an jede Build-Datei an, während 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 weiterhin kompiliert wird.

Migrieren Sie zuerst die kleinsten Dateien, sammeln Sie Erfahrung und fahren Sie dann fort. In einem Projekt können Build-Dateien in Kotlin und Groovy vorhanden sein. Nehmen Sie sich also Zeit, um die Umstellung sorgfältig vorzunehmen.

Ersetzen Sie def durch val oder var.

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

def building64Bit = false

So sieht derselbe Code in Kotlin aus:

val building64Bit = false

Boolesche Properties mit is kennzeichnen

Groovy verwendet eine Logik zur Ableitung von Attributen basierend auf den Attributnamen. Für eine boolesche Property 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 buildTypes-DSL-Elemente müssen Sie beispielsweise das Präfix is verwenden. In diesem Code wird gezeigt, wie boolesche Properties in Groovy festgelegt werden:

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

Im Folgenden sehen Sie denselben Code in Kotlin. Beachten Sie, dass den Attributen das Präfix is vorangestellt ist.

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

Listen und Karten konvertieren

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

So definieren Sie eine Liste in Groovy im Vergleich zu Kotlin:

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

So sieht derselbe Code in Kotlin aus:

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

So definieren Sie eine Karte in Groovy im Vergleich zu Kotlin:

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

So sieht derselbe Code in Kotlin aus:

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

Build-Typen konfigurieren

Im 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 vorher zu erstellen. Das folgende Code-Snippet zeigt eine Konfiguration mit den Build-Typen debug, release und benchmark 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“-Block migrieren

Wenn in Ihrem Build der Block buildscript {} verwendet wird, um dem Projekt Plug-ins hinzuzufügen, sollten Sie ihn durch den Block plugins {} ersetzen. Der plugins {}-Block erleichtert das Anwenden von Plug-ins und funktioniert gut mit Versionskatalogen.

Wenn Sie den plugins {}-Block in Ihren Build-Dateien verwenden, kennt Android Studio den Kontext auch dann, wenn der Build fehlschlägt. Dieser Kontext hilft dabei, 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 mit dem buildscript {}-Block die Plug-ins dem Build-Klassenpfad mithilfe der Maven-Koordinaten des Plug-ins hinzugefügt werden, z. B. com.android.tools.build:gradle:7.4.0, werden im plugins {}-Block die Plug-in-IDs verwendet.

Bei den meisten Plug-ins ist die Plug-in-ID der String, der beim Anwenden mit apply plugin verwendet wird. 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 Google Maven-Repository.

Auf Kotlin-Plug-ins kann über mehrere Plug-in-IDs verwiesen werden. Wir empfehlen, die Namespace-basierte Plugin-ID zu verwenden und die Kurzform anhand der folgenden Tabelle in die Namespace-basierte Plugin-ID umzugestalten:

Kurzschreibweise für 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.

Refactoring durchführen

Wenn Sie die IDs der verwendeten Plugins kennen, führen Sie die folgenden Schritte aus:

1. Wenn Sie noch Repositories für Plug-ins im buildscript {}-Block deklariert haben, verschieben Sie sie 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. Sie müssen hier 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 build.gradle.kts-Datei der obersten Ebene.

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 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 build.gradle-Datei auf Modulebene.

In diesem Beispiel wird der buildscript {}-Block 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")

So sieht die entsprechende Einrichtung mit dem plugins {}-Block aus:

// 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-ins-Block umwandeln

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

Sonstiges

Kotlin-Codebeispiele für andere Funktionen finden Sie auf den folgenden Dokumentationsseiten:

• Wenn Sie eine ProGuard-Konfiguration haben, lesen Sie den Abschnitt Shrinking, Obfuscation und Optimierung aktivieren.
• Wenn Sie einen signingConfig {}-Block haben, lesen Sie den Abschnitt Signaturinformationen aus Ihren Build-Dateien entfernen.
• Wenn Sie projektweite Attribute verwenden, lesen Sie den Abschnitt Projektweite Attribute konfigurieren.

Achtung: Obwohl Sie mit Gradle projektweite Eigenschaften auf Modulebene definieren können, sollten Sie dies vermeiden, da dadurch die Module, die diese Eigenschaften gemeinsam nutzen, gekoppelt werden. Durch die Modulkopplung wird es schwieriger, ein Modul später als eigenständiges Projekt zu exportieren. Außerdem kann Gradle keine parallele Projektausführung verwenden, um Builds mit mehreren Modulen zu beschleunigen.

Bekannte Probleme

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

Probleme melden

Eine Anleitung dazu, wie Sie die Informationen bereitstellen, die wir zur Fehlerbehebung benötigen, finden Sie unter Details zu Build-Tools und Gradle-Bugs. Melden Sie dann einen Fehler über die öffentliche Problemverfolgung von Google.

Weitere Ressourcen

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