Von Kapt zu KSP migrieren

Hinweis :Kapt befindet sich jetzt im Wartungsmodus. Wir empfehlen, für alle Prozessoren, die KSP unterstützen, von Kapt zu KSP zu migrieren. In den meisten Fällen sind für diese Migration nur Änderungen an der Build-Konfiguration Ihres Projekts erforderlich.

Mit Kapt (Kotlin Annotation Processing Tool) können Sie Java-Anmerkungs-Prozessoren mit Kotlin-Code verwenden, auch wenn diese Prozessoren keine spezielle Unterstützung für Kotlin haben. Dazu werden Java-Stubs aus Ihren Kotlin-Dateien generiert, die dann von den Prozessoren gelesen werden können. Diese Stub-Generierung ist ein kostspieliger Vorgang und hat erhebliche Auswirkungen auf die Build-Geschwindigkeit.

KSP (Kotlin Symbol Processing) ist eine Kotlin-Alternative zu kapt. KSP analysiert Kotlin-Code direkt, was bis zu doppelt so schnell ist. Außerdem haben Sie ein besseres Verständnis der Kotlin-Sprachkonstrukte.

Sie können kapt und KSP während der Migration parallel in Ihrem Projekt ausführen. Die Migration kann modul- und/oder bibliotekenweise erfolgen.

Hinweis :Wenn in einem Modul noch Kapt-Prozessoren vorhanden sind, werden in diesem Modul weiterhin Stubs generiert. Das bedeutet, dass die Leistungssteigerung nur dann am größten ist, wenn alle Verwendungen von kapt aus dem Modul entfernt werden.

Hier eine Übersicht über die Migrationsschritte:

1. Bibliotheken mit KSP-Unterstützung prüfen
2. KSP-Plug-in zu Ihrem Projekt hinzufügen
3. Anmerkungs-Prozessoren durch KSP ersetzen
4. Kapt-Plug-in entfernen

Bibliotheken mit KSP-Unterstützung prüfen

Prüfen Sie zuerst, ob die von Ihnen mit kapt verwendeten Bibliotheken bereits KSP-Unterstützung haben. Das ist bei vielen gängigen Bibliotheken der Fall, darunter Dagger, Glide, Room und Moshi. Andere Bibliotheken werden derzeit um die Unterstützung erweitert.

Eine Liste der unterstützten Bibliotheken finden Sie in der Dokumentation. Alternativ können Sie auch die Dokumentation und den Issue Tracker der von Ihnen verwendeten Bibliotheken aufrufen.

Hinweis: Data Binding verwendet zwar keinen traditionell enthaltenen Bibliotheksabhängigkeit, sondern einen Anmerkungs-Prozessor, um seine Funktionen bereitzustellen, aber KSP-Unterstützung für Data Binding ist nicht geplant. Sie können die Auswirkungen von kapt auf Ihren Build verringern, indem Sie die Verwendung der Datenbindung in separate Module isolieren.

KSP-Plug-in zu Ihrem Projekt hinzufügen

Deklarieren Sie zuerst das KSP-Plug-in in der build.gradle.kts-Datei der obersten Ebene. Achten Sie darauf, dass Sie eine KSP-Version auswählen, die mit der Kotlin-Version Ihres Projekts übereinstimmt. Eine Liste der Releases finden Sie auf der GitHub-Seite der Kepler Space Telescope Mission.

Hinweis: Der erste Teil der KSP-Version muss mit der Kotlin-Version übereinstimmen, die in Ihrem Build verwendet wird. Wenn Sie beispielsweise Kotlin 2.0.21 verwenden, muss die KSP-Version eine der 2.0.21-x.y.z-Releases sein.

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.0.21-1.0.27" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.0.21-1.0.27' apply false
}

Aktivieren Sie dann KSP in der Datei build.gradle.kts auf Modulebene:

Kotlin

plugins {
    id("com.google.devtools.ksp")
}

Groovy

plugins {
    id 'com.google.devtools.ksp'
}

Anmerkungs-Prozessoren durch KSP ersetzen

Wenn KSP aktiviert ist, können Sie die Verwendung von kapt durch KSP ersetzen. Bei der überwiegenden Mehrheit der Bibliotheken müssen Sie in der Abhängigkeitsdeklaration nur „kapt“ in „ksp“ ändern, da der Anmerkungs- und KSP-Prozessor im selben Artefakt bereitgestellt werden.

Hinweis: Bei einigen Bibliotheken (z. B. Glide) müssen Sie möglicherweise auch die Abhängigkeit in ein anderes Artefakt ändern. Lesen Sie sich die Dokumentation des Anbieters durch.

Kotlin

dependencies {
    kapt("androidx.room:room-compiler:2.5.0")
    ksp("androidx.room:room-compiler:2.5.0")
}

Groovy

dependencies {
    kapt 'androidx.room:room-compiler:2.5.0'
    ksp 'androidx.room:room-compiler:2.5.0'
}

Nachdem Sie zu KSP gewechselt sind, synchronisieren und erstellen Sie Ihr Projekt, um zu sehen, ob es weiterhin richtig funktioniert.

Hier finden Sie einige häufige Probleme, auf die Sie achten sollten:

• Einige Bibliotheken unterstützen nicht genau dieselben Funktionen mit kapt und KSP. Wenn der Code nach der Migration nicht mehr funktioniert, lesen Sie die Dokumentation der Bibliothek.
• KSP bietet genauere Kotlin-Typinformationen als kapt (z. B. zur Nullbarkeit). Das bedeutet, dass KSP-Prozessoren genauere Typanforderungen haben können. Neben der Aktualisierung Ihrer Build-Dateien sind möglicherweise auch einige Änderungen am Quellcode erforderlich.
• Wenn Sie zuvor Argumente an den Anmerkungs-Prozessor übergeben haben, müssen Sie diese Argumente jetzt wahrscheinlich an KSP übergeben. Das Format der Argumente kann sich zwischen kapt und KSP unterscheiden. Weitere Informationen finden Sie in der Dokumentation zur Karten- und Standortplattform und in der Dokumentation der verwendeten Bibliothek.

Kapt-Plug-in entfernen

Wenn Ihr Modul keine Abhängigkeiten mehr von kapt enthält, entfernen Sie das kapt-Plug-in.

Hinweis: Für die Datenbindung muss außerdem kapt im Modul aktiviert sein. In Modulen, in denen die Datenbindung verwendet wird, kann kapt nicht entfernt werden.

Wenn es in einem Plugins-Block deklariert wurde:

Kotlin

plugins {
    id("org.jetbrains.kotlin.kapt")
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.kapt'
}

Wenn die Syntax „apply plugin“ mit Groovy verwendet wurde:

apply plugin: 'kotlin-kapt'

Entfernen Sie außerdem alle verbleibenden Konfigurationen im Zusammenhang mit kapt, z. B.:

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

Weitere Informationen

• KSP-Dokumentation auf Kotlinlang.org
• KSP auf GitHub
• kapt auf Kotlinlang.org ->