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 hinzugefügt, die Programmiersprache, die traditionell in Gradle-Konfigurationsdateien verwendet wird.

Kotlin wird beim Schreiben von Gradle-Skripts gegenüber Groovy bevorzugt, da Kotlin besser lesbar ist und eine bessere Prüfung zur Kompilierzeit sowie IDE-Unterstützung bietet.

Obwohl Kotlin im Vergleich zu Groovy derzeit eine bessere Integration in den Code-Editor von Android Studio bietet, 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 Migrationsanleitung finden Sie in der offiziellen Dokumentation von Gradle.

Zeitachse

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 Bearbeitungsumgebung als die Groovy DSL (build.gradle) mit Syntaxhervorhebung, Codevervollständigung und Navigation zu Deklarationen. Weitere Informationen finden Sie in der Einführung in die Kotlin-DSL von Gradle.

Gängige Begriffe

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“ synonym verwendet. Ebenso werden „Groovy“ und „Groovy DSL“ synonym verwendet.

Benennung von Skriptdateien

Die Dateiendungen von Skriptdateien hängen von der Sprache ab, in der die Build-Datei geschrieben ist:

  • In Groovy geschriebene Gradle-Build-Dateien haben die Dateiendung .gradle.
  • In Kotlin geschriebene Gradle-Build-Dateien haben die Dateiendung .gradle.kts.

Syntax konvertieren

Es gibt einige allgemeine Syntaxunterschiede zwischen Groovy und Kotlin. Sie müssen diese Änderungen daher in allen Build-Scripts vornehmen.

Klammern zu Methodenaufrufen hinzufügen

In Groovy können Sie Klammern in Methodenaufrufen weglassen, während sie in Kotlin erforderlich sind. Fügen Sie diesen Methodenaufrufen Klammern hinzu, um Ihre Konfiguration zu migrieren. Dieser Code zeigt, wie eine Einstellung in Groovy konfiguriert wird:

compileSdkVersion 30

Dies ist derselbe Code in Kotlin:

compileSdkVersion(30)

= zu Aufgabenvorschlägen hinzufügen

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

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Dieser Code zeigt, wie Properties in Kotlin zugewiesen werden:

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 bei Ausdrücken mit Punkten: In Groovy können Sie für String-Interpolationen bei Ausdrücken mit Punkten einfach 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 ruft der vorherige Code jedoch toString() für project auf, nicht für project.rootDir. Um den Wert des Stammverzeichnisses abzurufen, 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 templates.

Dateiendungen umbenennen

Hängen Sie .kts an jede Build-Datei an, während Sie deren Inhalte 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 die kleinsten Dateien, sammeln Sie Erfahrungen und fahren Sie dann fort. Sie können in einem Projekt eine Mischung aus Kotlin- und Groovy-Build-Dateien verwenden. Nehmen Sie sich also Zeit für die Umstellung.

Ersetzen Sie def durch val oder var.

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

def building64Bit = false

Dies ist derselbe Code in Kotlin:

val building64Bit = false

Präfix für boolesche Attribute mit is

Groovy verwendet eine Logik zur Ableitung von Properties, die auf den Property-Namen 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. Beispielsweise müssen Sie booleschen DSL-Elementen von buildTypes das Präfix is voranstellen. In diesem Code wird gezeigt, wie boolesche Attribute in Groovy festgelegt werden:

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

Der folgende Code ist derselbe 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. 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 im Vergleich zu Kotlin:

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

Dies ist derselbe Code in Kotlin:

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

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

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

Dies 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 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 {
   ...
 }
}

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 in Ihrem Build der Block buildscript {} verwendet wird, um dem Projekt Plug-ins hinzuzufügen, sollten Sie ihn so refaktorieren, dass stattdessen der Block plugins {} verwendet wird. Der Block plugins {} erleichtert die Anwendung von Plug-ins und funktioniert gut mit Versionskatalogen.

Wenn Sie den plugins {}-Block in Ihren Build-Dateien verwenden, kennt Android Studio außerdem den Kontext, auch wenn der Build fehlschlägt. Dieser Kontext hilft bei der Behebung von Fehlern in Ihren Kotlin-DSL-Dateien, da die Studio-IDE so Codevervollständigung und andere hilfreiche Vorschläge machen kann.

Plug-in-IDs finden

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

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

Kurzschreibweise 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

Sie können auch im Gradle Plugin 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 im Block buildscript {} deklariert haben, verschieben Sie sie stattdessen in die Datei settings.gradle.

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

  4. Wenden Sie die Plug-ins an, indem Sie sie dem plugins {}-Block in der build.gradle-Datei 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 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()
    }
}

Plug-in-Block konvertieren

Das Anwenden von Plug-ins aus dem plugins {}-Block 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 plugins {}-Block finden Sie in der Gradle-Dokumentation unter Applying plugins.

Sonstiges

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

Bekannte Probleme

Ein bekanntes Problem ist, 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 Bearbeitung Ihres Problems benötigen, finden Sie unter Details zu Build-Tools und Gradle-Fehlern. Melden Sie dann einen Fehler über den öffentlichen Issue Tracker von Google.

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.