Build-Konfiguration von Groovy zu Kotlin migrieren

Mit Version 4.0 des Android-Gradle-Plug-ins wird jetzt die Verwendung von Kotlin im Gradle-Build unterstützt. Konfiguration als Ersatz für die Programmiersprache Groovy die normalerweise in Gradle-Konfigurationsdateien verwendet werden.

Beim Schreiben von Gradle-Skripts wird Kotlin gegenüber Groovy bevorzugt, da Kotlin verbesserte Lesbarkeit und bietet eine bessere Prüfung der Kompilierungszeit sowie IDE-Unterstützung.

Kotlin bietet derzeit eine bessere Integration in den Code von Android Studio. Im Vergleich zu Groovy sind Builds mit Kotlin tendenziell langsamer mit Groovy erstellen. Berücksichtigen Sie daher die Build-Leistung, wenn Sie zu migrieren.

Diese Seite enthält grundlegende Informationen zur Umwandlung der Gradle-Build-Dateien von Groovy bis Kotlin Für eine umfassendere Migration finden Sie in der Gradle-Dokumentation offizielle Dokumentation.

Zeitachse

Ab Android Studio Giraffe wird für neue Projekte Kotlin DSL verwendet (build.gradle.kts) standardmäßig für die Build-Konfiguration. Dies bietet eine bessere als bei der Groovy DSL (build.gradle) mit Syntax Hervorhebung, Codevervollständigung und Navigation zu Deklarationen. Weitere Informationen sieh dir die Gradle Kotlin DSL Primer

Allgemeine Begriffe

Kotlin DSL:Bezieht sich in erster Linie auf das Android-Gradle-Plug-in Kotlin DSL. oder gelegentlich zu den zugrunde liegenden Gradle Kotlin DSL

In diesem Migrationsleitfaden „Kotlin“ und „Kotlin DSL“ werden austauschbar verwendet. Bei "Groovy" und "Groovy DSL", werden austauschbar verwendet.

Benennung von Skriptdateien

Namen von Skript-Dateiendungen basieren auf der Sprache, in der die Build-Datei geschrieben wird. in:

  • In Groovy geschriebene Gradle-Build-Dateien verwenden die Dateiendung .gradle.
  • In Kotlin geschriebene Gradle-Build-Dateien verwenden den Dateinamen .gradle.kts .

Syntax konvertieren

Es gibt einige allgemeine Syntaxunterschiede zwischen Groovy und Kotlin. Sie müssen diese Änderungen also auf alle Ihre Build-Skripts anwenden.

Klammern zu Methodenaufrufen hinzufügen

Mit Groovy können Sie Klammern in Methodenaufrufen weglassen, Kotlin erfordert . Um Ihre Konfiguration zu migrieren, müssen Sie für diese Art von Methodenaufrufen. 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

In Groovy DSL können Sie den Zuweisungsoperator = weglassen, wenn Zuweisen von Eigenschaften, während Kotlin dies erfordert. Dieser Code zeigt, wie Sie Weisen Sie Eigenschaften in Groovy zu:

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 in einfachen Anführungszeichen definiert werden. Für Kotlin ist doppelte Anführungszeichen.

  • Stringinterpolation bei gepunkteten Ausdrücken: In Groovy können Sie Folgendes verwenden: nur das Präfix $ für Stringinterpolationen bei gepunkteten Ausdrücken. In Kotlin müssen die Ausdrücke jedoch in geschweiften Klammern gesetzt werden. In Groovy können Sie beispielsweise $project.rootDir, wie im folgenden Snippet gezeigt:

        myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"

    In Kotlin wird mit dem vorherigen Code jedoch toString() für project, nicht auf project.rootDir. Um den Wert zu erhalten des Stammverzeichnisses, verpacken Sie den Ausdruck ${project.rootDir} mit geschweiften Klammern:

        myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"

    Weitere Informationen finden Sie unter Stringvorlagen in der Kotlin-Dokumentation.

Dateiendungen umbenennen

Hängen Sie .kts an jede Build-Datei an, wenn Sie deren Inhalt migrieren. Beispiel: wählen Sie eine Build-Datei aus, z. B. die Datei settings.gradle. Benennen Sie die Datei um in settings.gradle.kts und konvertieren Sie den Inhalt der Datei in Kotlin. Achten Sie darauf, wird das Projekt nach der Migration der einzelnen Build-Dateien immer noch kompiliert.

Migrieren Sie zuerst Ihre kleinsten Dateien, sammeln Sie Erfahrung und machen Sie dann weiter. Sie können In einem Projekt gibt es sowohl Kotlin- als auch Groovy-Build-Dateien. den Schritt vorsichtig.

Ersetzen Sie „def“ durch „val“ oder „var“

Ersetzen Sie def durch val oder var. wie Variablen in Kotlin definiert werden. 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 Logik für den Immobilienabzug. basierend auf den Eigenschaftsnamen. Die abgeleiteten Methoden des booleschen Attributs foo kann getFoo, setFoo oder isFoo sein. Nach der Konvertierung in Kotlin müssen Sie die Eigenschaftsnamen in die abgeleiteten Methoden die von Kotlin nicht unterstützt werden. Beispiel: buildTypes Boolesche DSL-Elemente verwenden, müssen Sie ihnen 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. Beachten Sie, dass den Eigenschaften von is.

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. Cool verwendet [], während Kotlin Methoden zum Erstellen von Sammlungen explizit mit listOf oder mapOf. Ersetzen Sie [] durch listOf oder mapOf, wenn bei der Migration.

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. implizit. 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 erstellen können. Das folgende Code-Snippet zeigt eine Konfiguration mit der debug, release und benchmark-Build in Groovy eingeben.

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

Um die entsprechende Konfiguration in Kotlin zu erstellen, müssen Sie die Methode Build-Typ benchmark.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Von Buildscript zum Plug-in-Block migrieren

Wenn Ihr Build die Methode buildscript {} zum Hinzufügen von Plug-ins zum Projekt blockieren, sollten Sie eine Refaktorierung vornehmen, um die plugins {} blockieren. Der plugins {}-Block vereinfacht die Anwendung von Plug-ins eignet sich gut für Versionskataloge herunterladen.

Wenn Sie den plugins {}-Block in Ihren Build-Dateien verwenden, Android Studio erkennt den Kontext auch dann, wenn der Build fehlschlägt. Dieser Kontext Korrekturen an Ihren Kotlin-DSL-Dateien vornehmen, da die Studio-IDE auf diese Weise eine Codevervollständigung durchführen und weitere hilfreiche Vorschläge machen.

Plug-in-IDs suchen

Der buildscript {}-Block fügt die Plug-ins dem Build-Klassenpfad mithilfe von die Maven-Koordinaten des Plug-ins, z. B. com.android.tools.build:gradle:7.4.0, Der plugins {}-Block verwendet 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 Die folgenden Plug-in-IDs sind beispielsweise Teil der Android-Gradle-Plug-in:

  • com.android.application
  • com.android.library
  • com.android.lint
  • com.android.test

Die vollständige Liste der Plug-ins finden Sie in der Google Maven-Repository.

Auf Kotlin-Plug-ins kann von mehreren Plug-in-IDs verwiesen werden. Wir empfehlen die Verwendung des Namespace-Plug-in-ID und refaktorieren von der Kurzschreibweise zu einer Plug-in-ID mit einem Namespace folgende 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 auf der Gradle-Plug-in-Portal das Maven Central Repository und die Google Maven-Repository. Gelesen Benutzerdefinierte Gradle-Plug-ins entwickeln um mehr über die Funktionsweise von Plug-in-IDs zu erfahren.

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 buildscript {} deklariert sind blockieren, verschieben Sie sie in die settings.gradle -Datei stattdessen.

  2. Fügen Sie die Plug-ins dem Block plugins {} auf oberster Ebene hinzu build.gradle-Datei. Sie müssen die ID und die Version des Plug-ins hier. Wenn das Plug-in keine auf das Stammprojekt anwenden möchten, 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 in den plugins {}-Block im Datei build.gradle auf Modulebene. Sie müssen nur die ID hier, da die Version vom Stammprojekt übernommen wird.

  5. Entfernen Sie den Aufruf apply plugin für das Plug-in auf Modulebene build.gradle-Datei.

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:

// 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 nicht mit Versionskatalogen:

// 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 zur plugins {}-Blockade finden Sie unter Anwenden von Plug-ins in der Gradle-Dokumentation.

Sonstiges

Kotlin-Codebeispiele für andere Funktionen finden Sie hier: Dokumentationsseiten:

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 du uns die Informationen zur Verfügung stellst, die wir benötigen, um dein Problem zu erkennen, findest du unter Details zu Build-Tools und Gradle-Programmen Gehen Sie dann so vor: können Sie den Fehler über das öffentliche Problemverfolgung.

Weitere Ressourcen

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