Migrer de Kapt vers KSP

Remarque :Kapt est désormais en mode de maintenance. Nous vous recommandons de migrer de Kapt vers KSP pour tous les processeurs compatibles. Dans la plupart des cas, cette migration ne nécessite que des modifications de la configuration de compilation de votre projet.

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.

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.

Remarque : S'il reste des processeurs persistants dans un module, des bouchons continueront à y être générés. Autrement dit, la majeure partie de l'amélioration des performances ne se produira que lorsque toutes les utilisations de Kapt seront supprimées du module.

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 bientôt cette possibilité.

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.

Remarque : Bien qu'il ne s'agisse habituellement pas d'une dépendance de bibliothèque qui est incluse, la liaison de données utilise également un processeur d'annotations pour fournir ses fonctionnalités. La prise en charge de KSP pour la liaison de données n'est pas prévue. Vous pouvez atténuer l'impact de Kapt sur votre build en isolant les utilisations de la liaison de données dans des modules distincts.

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.

Remarque :La première partie de la version KSP doit correspondre à la version de Kotlin utilisée dans votre build. Par exemple, si vous utilisez Kotlin 2.0.21, la version KSP doit être l'une des versions 2.0.21-x.y.z.

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
}

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.

Remarque : Certaines bibliothèques (telles que Glide) peuvent également vous obliger à remplacer la dépendance par un autre artefact. Consultez la documentation correspondante.

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.

Remarque : La liaison de données nécessite également que Kapt soit activé dans le module. Dans les modules où la liaison de données est utilisée, Kapt ne peut pas être supprimé.

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

• Documentation KSP sur Kotlinlang.org
• KSP sur GitHub
• Kapt sur Kotlinlang.org -->