Migrer de Kapt vers KSP

Kapt (l'outil de traitement des annotations Kotlin) vous permet d'utiliser des processeurs d'annotations Java avec du code Kotlin, même si ces processeurs ne sont pas spécifiquement compatibles avec Kotlin. Pour ce faire, des bouchons Java (que les processeurs peuvent ensuite lire) sont générés à partir de vos fichiers Kotlin. Cette génération de bouchons est une opération coûteuse et a un impact significatif sur la vitesse de compilation.

Le traitement des symboles Kotlin, ou KSP (Kotlin Symbol Processing), est une alternative à Kapt conçue pour le langage Kotlin. KSP analyse directement le code Kotlin, ce qui est jusqu'à deux fois plus rapide. Il comprend également mieux les constructions du langage Kotlin.

Kapt est désormais en mode de maintenance. C'est pourquoi nous vous recommandons de migrer de Kapt vers KSP dans la mesure du possible. Dans la plupart des cas, cette migration ne nécessite que des modifications de la configuration de compilation de votre projet.

Vous pouvez exécuter Kapt et KSP ensemble dans votre projet pendant la migration. La migration peut être effectuée module par module, bibliothèque par bibliothèque.

Voici, dans les grandes lignes, la procédure de migration :

  1. Vérifier que les bibliothèques que vous utilisez prennent en charge KSP
  2. Ajouter le plug-in KSP à votre projet
  3. Remplacer les processeurs d'annotation par KSP
  4. Supprimer le plug-in Kapt

Vérifier que les bibliothèques que vous utilisez prennent en charge KSP

Pour commencer, vérifiez si les bibliothèques que vous utilisez avec Kapt sont déjà compatibles avec KSP. C'est le cas de nombreuses bibliothèques populaires (y compris Dagger, Glide, Room et Moshi). D'autres offrent une nouvelle compatibilité.

Vous pouvez consulter la liste des bibliothèques compatibles dans la documentation, ou vous reporter à la documentation et à l'outil de suivi des problèmes des bibliothèques que vous utilisez.

Ajouter le plug-in KSP à votre projet

Commencez par déclarer le plug-in KSP dans votre fichier build.gradle.kts de premier niveau. Veillez à choisir une version de KSP alignée sur la version Kotlin de votre projet. Vous trouverez une liste des versions sur la page GitHub de KSP.

Kotlin

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

Groovy

plugins {
    id 'com.google.devtools.ksp' version '1.8.10-1.0.9' apply false
}

Ensuite, activez KSP dans votre fichier build.gradle.kts au niveau du module:

Kotlin

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

Groovy

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

Remplacer les processeurs d'annotation par KSP

Lorsque KSP est activé, vous pouvez commencer à remplacer les utilisations de Kapt par KSP. Pour une grande majorité des bibliothèques, il suffit de remplacer Kapt par KSP lors de la déclaration de la dépendance, car leur processeur d'annotations et leur processeur KSP sont transmis dans le même artefact.

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'
}

Après être passé à KSP, synchronisez et créez votre projet pour voir s'il fonctionne toujours comme prévu.

Voici quelques problèmes courants à éviter :

  • Certaines bibliothèques n'acceptent pas exactement le même ensemble de fonctionnalités avec Kapt et KSP. Si votre code ne fonctionne plus après la migration, consultez la documentation de la bibliothèque.
  • KSP dispose d'informations plus précises sur les types Kotlin que Kapt (par exemple, sur la possibilité de valeur nulle), ce qui signifie que les processeurs KSP peuvent être plus précis sur les exigences relatives aux types. Cela peut nécessiter des corrections dans le code source, en plus de la mise à jour de vos fichiers de compilation.
  • Si vous avez déjà transmis des arguments au processeur d'annotations, vous devrez probablement les transmettre à KSP. Notez que le format des arguments peut différer entre Kapt et KSP. Pour en savoir plus, consultez la documentation sur KSP et la documentation de la bibliothèque que vous utilisez.

Supprimer le plug-in Kapt

Une fois que vous n'avez plus de dépendances à kapt dans votre module, supprimez le plug-in Kapt.

Si elle a été déclarée dans un bloc "plugins" :

Kotlin

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

Groovy

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

Si elle utilisait la syntaxe "apply plugin" avec Groovy:

apply plugin: 'kotlin-kapt'

Vous devez également supprimer toute configuration restante liée à Kapt, par exemple :

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy


kapt {
    correctErrorTypes true
    useBuildCache true
}

Ressources supplémentaires