Von Kapt zu KSP migrieren

Hinweis: Kapt befindet sich jetzt im Wartungsmodus. Wir empfehlen, für alle unterstützten Prozessoren 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-Annotation-Prozessoren mit Kotlin-Code verwenden, auch wenn diese Prozessoren keine spezielle Unterstützung für Kotlin bieten. Dazu werden Java-Stubs aus Ihren Kotlin-Dateien generiert, die die Prozessoren dann lesen können. Diese Stub-Generierung ist ein aufwendiger Vorgang und hat erhebliche Auswirkungen auf die Build-Geschwindigkeit.

KSP (Kotlin Symbol Processing) ist eine Kotlin-spezifische Alternative zu kapt. KSP analysiert Kotlin-Code direkt, was bis zu zweimal 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 Modul für Modul und Bibliothek für Bibliothek erfolgen.

Hinweis: Wenn in einem Modul noch kapt-Prozessoren vorhanden sind, werden in diesem Modul weiterhin Stubs generiert. Das bedeutet, dass die Leistungsverbesserung erst dann eintritt, wenn alle Verwendungen von kapt aus dem Modul entfernt wurden.

Hier ein Überblick über die Migrationsschritte:

1. Prüfen, ob die von Ihnen verwendeten Bibliotheken KSP unterstützen
2. KSP-Plug-in zum Projekt hinzufügen
3. Anmerkungsprozessoren durch KSP ersetzen
4. kapt-Plug-in entfernen

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

Prüfen Sie zuerst, ob die Bibliotheken, die Sie mit kapt verwenden, bereits KSP unterstützen. Dies ist bei vielen beliebten Bibliotheken der Fall (einschließlich 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 den Issue Tracker der von Ihnen verwendeten Bibliotheken aufrufen.

Hinweis: Auch wenn es sich nicht um eine herkömmliche Programmbibliotheksabhängigkeit handelt, verwendet Datenbindung ebenfalls einen Annotation Processor, um seine Funktionalität bereitzustellen. Eine KSP-Unterstützung für Datenbindung ist nicht geplant. Sie können die Auswirkungen von kapt auf Ihren Build minimieren, indem Sie die Verwendung von Datenbindung in separaten Modulen isolieren.

KSP-Plug-in zum Projekt hinzufügen

Deklarieren Sie zuerst das KSP-Plug-in in der build.gradle.kts-Datei auf oberster 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'
}

Anmerkungsprozessoren durch KSP ersetzen

Wenn KSP aktiviert ist, können Sie damit 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.

Hinweis: Bei einigen Bibliotheken (z. B. Glide) müssen Sie möglicherweise auch die Abhängigkeit zu einem anderen Artefakt ändern. Lesen Sie die entsprechende Dokumentation.

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 prüfen, ob es weiterhin ordnungsgemäß funktioniert.

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

• Einige Bibliotheken unterstützen nicht genau dieselben Funktionen mit kapt und KSP. Wenn Ihr Code nach der Migration nicht mehr funktioniert, lesen Sie die Dokumentation der Bibliothek.
• KSP bietet genauere Kotlin-Typinformationen als kapt (z. B. zur Null-Zulässigkeit). Das bedeutet, dass KSP-Prozessoren Typanforderungen genauer verarbeiten können. Dazu müssen Sie möglicherweise nicht nur Ihre Build-Dateien aktualisieren, sondern auch einige Korrekturen am 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 von Ihnen verwendeten Bibliothek.

kapt-Plug-in entfernen

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

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

Wenn sie 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'

Sie sollten auch alle verbleibenden Konfigurationen im Zusammenhang mit kapt entfernen, z. B.:

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

Zusätzliche Ressourcen

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