Build-Konfiguration von Groovy zu Kotlin migrieren

Das Android Gradle-Plug-in 4.0 unterstützt die Verwendung von Kotlin in Ihrer Gradle-Build-Konfiguration als Ersatz für Groovy, die Programmiersprache, die traditionell in Gradle-Konfigurationsdateien verwendet wird.

Kotlin wird für das Schreiben von Gradle-Scripts gegenüber Groovy bevorzugt, da Kotlin besser lesbar ist und eine bessere Überprüfung zur Kompilierungszeit sowie IDE-Unterstützung bietet.

Kotlin bietet derzeit im Vergleich zu Groovy eine bessere Einbindung in den Code-Editor von Android Studio. Builds mit Kotlin sind jedoch in der Regel langsamer als Builds mit Groovy. Berücksichtigen Sie daher die Buildleistung, wenn Sie sich für eine Migration entscheiden.

Auf dieser Seite finden Sie grundlegende Informationen zum Konvertieren der Gradle-Builddateien Ihrer Android-App von Groovy in Kotlin. Eine ausführlichere Migrationsanleitung finden Sie in der offiziellen Gradle-Dokumentation.

Zeitachse

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

Ab Android Studio Giraffe wird für neue Projekte standardmäßig die 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 im Gradle Kotlin DSL Primer.

Gängige Begriffe

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

In diesem Migrationsleitfaden werden „Kotlin“ und „Kotlin DSL“ synonym verwendet. Ebenso werden „Groovy“ und „Groovy DSL“ synonym verwendet.

Benennung von Scriptdateien

Die Namen der Scriptdateiendung basieren auf der Sprache, in der die Build-Datei geschrieben ist:

• In Groovy geschriebene Gradle-Build-Dateien verwenden die Dateiendung .gradle.
• Gradle-Build-Dateien, die in Kotlin geschrieben wurden, haben 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 allen Build-Scripts anwenden.

Klammern zu Methodenaufrufen hinzufügen

Tipp :Fügen Sie Ihrem Groovy-Code als ersten Schritt, noch bevor Sie die Dateiendungen ändern, Klammern hinzu. Das erleichtert die Umstellung auf Kotlin.

Mit Groovy können Sie Klammern in Methodenaufrufen weglassen, in Kotlin sind sie jedoch erforderlich. Wenn Sie Ihre Konfiguration migrieren möchten, fügen Sie diesen Methodenaufrufen Klammern hinzu. In diesem Code wird gezeigt, wie eine Einstellung in Groovy konfiguriert wird:

compileSdkVersion 30

Das ist derselbe Code in Kotlin:

compileSdkVersion(30)

= zu Zuweisungsanrufen hinzufügen

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

In der Groovy-DSL können Sie den Zuweisungsoperator = beim Zuweisen von Eigenschaften weglassen, in Kotlin ist er jedoch erforderlich. In diesem Code wird gezeigt, wie Sie Eigenschaften in Groovy zuweisen:

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

Hier sind die Unterschiede zwischen Groovy- und Kotlin-Strings:

• 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.

• Stringinterpolation bei Punktausdrücken: In Groovy können Sie für Stringinterpolationen bei Punktausdrücken nur das Präfix $ verwenden. In Kotlin müssen Sie die Punktausdrü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 wird mit dem Code oben jedoch toString() auf project aufgerufen, nicht auf project.rootDir. 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 Stringvorlagen.

Dateiendungen umbenennen

Fügen Sie jeder Build-Datei .kts an, während Sie den 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 werden kann.

Migrieren Sie zuerst die kleinsten Dateien, sammeln Sie Erfahrung und fahren Sie dann fort. 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

Das ist derselbe Code in Kotlin:

val building64Bit = false

Boolesche Properties mit is beginnen

Groovy verwendet auf den Property-Namen eine Logik für den Property-Abzug. Für eine boolesche Property foo können getFoo, setFoo oder isFoo als abgeleitete Methoden verwendet werden. Nach der Konvertierung in Kotlin müssen Sie daher die Attributnamen in die abgeleiteten Methoden ändern, die von Kotlin nicht unterstützt werden. Boolesche Elemente der buildTypes DSL müssen beispielsweise mit is vorangestellt werden. 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 die Properties mit is beginnen.

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 und 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 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 Kotlin DSL sind nur die Build-Typen Debug und Release verfügbar. Alle anderen benutzerdefinierten Buildtypen müssen manuell erstellt werden.

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

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

Wenn Sie die entsprechende Konfiguration in Kotlin erstellen möchten, müssen Sie den Buildtyp 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. Mit dem Block plugins {} lassen sich Plugins einfacher anwenden und er funktioniert gut mit Versionskatalogen.

Wenn Sie den Block plugins {} in Ihren Build-Dateien verwenden, ist Android Studio auch dann über den Kontext informiert, wenn der Build fehlschlägt. Dieser Kontext hilft Ihnen, Fehler in Ihren Kotlin-DSL-Dateien zu beheben, da die Studio IDE Code vervollständigen und andere hilfreiche Vorschläge machen kann.

Plug-in-IDs ermitteln

Im Block buildscript {} werden die Plug-ins dem Build-Classpath mithilfe der Maven-Koordinaten des Plug-ins hinzugefügt, z. B. com.android.tools.build:gradle:7.4.0. Im Block plugins {} werden stattdessen die Plug-in-IDs verwendet.

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 Plug-in-Liste finden Sie im Maven-Repository von Google.

Auf Kotlin-Plug-ins kann über mehrere 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:

Kurzzeichen 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.

Refaktorierung ausfü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 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. 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 build.gradle.kts-Datei.

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

In 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")

Hier 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()
    }
}

Plug-in-Block konvertieren

Das Anwenden von Plug-ins aus dem plugins {}-Block ist in Groovy und Kotlin ähnlich. Im folgenden Code wird gezeigt, 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
   ...
}

Im folgenden Code wird gezeigt, wie das in Kotlin funktioniert:

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

Im folgenden Code wird gezeigt, 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'
   ...
}

Im folgenden Code wird gezeigt, wie das in Kotlin funktioniert:

// 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 den Hilfeartikel Komprimierung, Verschleierung und Optimierung aktivieren.
• Wenn die Datei den Block signingConfig {} enthält, lesen Sie den Hilfeartikel Signaturinformationen aus Build-Dateien entfernen.
• Wenn Sie projektweite Properties verwenden, lesen Sie den Hilfeartikel Projektweite Properties konfigurieren.

Achtung: In Gradle können Sie zwar projektweite Eigenschaften auf Modulebene definieren, sollten dies aber vermeiden, da die Module, die diese Eigenschaften teilen, dadurch gekoppelt werden. Die Modulkopplung erschwert es, ein Modul später als eigenständiges Projekt zu exportieren, und verhindert, dass Gradle die parallele Projektausführung verwendet, 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 Sie die Informationen zur Fehlerbehebung bereitstellen, finden Sie unter Details zu Build-Tools und Gradle-Fehlern. Melden Sie den Fehler dann über den öffentlichen Issue Tracker von Google.

Weitere Ressourcen

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