Von Kapt zu KSP migrieren

Mit Kapt (Kotlin Annotation Processing Tool) können Sie Java-Annotation Processors mit Kotlin-Code verwenden, auch wenn diese Processors keine spezifische Unterstützung für Kotlin bieten. Dazu werden Java-Stubs aus Ihren Kotlin-Dateien generiert, die die Prozessoren dann lesen können. Die Stub-Generierung ist ein aufwendiger Vorgang und hat erhebliche Auswirkungen auf die Build-Geschwindigkeit.

KSP (Kotlin Symbol Processing) ist eine Kotlin-basierte Alternative zu kapt. KSP analysiert Kotlin-Code direkt, was bis zu 2-mal schneller ist. Außerdem versteht es Kotlin-Sprachkonstrukte besser.

Sie können kapt und KSP während der Migration gleichzeitig in Ihrem Projekt ausführen. Die Migration kann modulweise oder bibliotheksweise erfolgen.

Hier finden Sie eine Übersicht über die Migrationsschritte:

  1. Prüfen, ob die verwendeten Bibliotheken KSP unterstützen
  2. KSP-Plug-in zu Ihrem Projekt hinzufügen
  3. Annotationsprozessoren durch KSP ersetzen
  4. KAPT-Plug-in entfernen

Prüfen, ob die verwendeten Bibliotheken KSP unterstützen

Prüfen Sie zuerst, ob die Bibliotheken, die Sie mit kapt verwenden, bereits KSP unterstützen. Das ist bei vielen beliebten Bibliotheken der Fall, darunter Dagger, Glide, Room und Moshi. Andere Bibliotheken werden nach und nach unterstützt.

Eine Liste der unterstützten Bibliotheken finden Sie in der Dokumentation. Sie können auch die Dokumentation und die Problemverfolgung 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. Eine Liste der Releases finden Sie auf der KSP-GitHub-Seite.

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.3.4" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.3.4' 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'
}

Annotationsprozessoren durch KSP ersetzen

Wenn KSP aktiviert ist, können Sie beginnen, die Verwendung von kapt durch KSP zu ersetzen. Bei den meisten Bibliotheken muss dazu nur „kapt“ in der Abhängigkeitsdeklaration in „ksp“ geändert werden, da der Annotationsprozessor und der KSP-Prozessor im selben Artefakt enthalten sind.

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 auf KSP umgestellt haben, synchronisieren und erstellen Sie Ihr Projekt, um zu sehen, ob es weiterhin richtig funktioniert.

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

  • Einige Bibliotheken unterstützen mit kapt und KSP nicht genau dieselben Funktionen. Wenn Ihr Code nach der Migration nicht mehr funktioniert, sehen Sie in der Dokumentation der Bibliothek nach.
  • KSP enthält genauere Kotlin-Typinformationen als kapt (z. B. zur Nullable-Eigenschaft). Daher können KSP-Prozessoren Typanforderungen genauer angeben. Dazu müssen Sie möglicherweise nicht nur Ihre Build-Dateien aktualisieren, sondern auch einige Korrekturen an Ihrem Quellcode vornehmen.
  • Wenn Sie zuvor Argumente an den Annotationsprozessor ü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 KSP-Dokumentation und in der Dokumentation der verwendeten Bibliothek.

KAPT-Plug-in entfernen

Wenn Sie in Ihrem Modul keine Abhängigkeiten mehr mit kapt haben, entfernen Sie das KAPT-Plug-in.

Wenn sie in einem „plugins“-Block deklariert wurde:

Kotlin

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

Groovy

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

Wenn die apply-Plug-in-Syntax 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
}

Zusätzliche Ressourcen