Von Kapt zu KSP migrieren

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.

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.

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.

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.

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.

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