Kotlin Academy · Leçon

Intégrer des processeurs KSP dans une compilation Gradle

Configurez KSP dans Gradle, ajoutez les sources générées et déboguez la sortie du processeur.

Intégrer des processeurs KSP dans une compilation Gradle est une leçon Kotlin Academy gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Kotlin Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Kotlin Academy comprend 4 leçons au total.

Structure multimodule

Une configuration KSP typique comporte au moins deux modules : :annotation (qui contient vos classes d’annotations) et :processor (qui contient le SymbolProcessor). Le module consommateur applique le module d’extension KSP et déclare les dépendances ksp et implementation.

Application du module d’extension KSP

Dans le module consommateur, dans build.gradle.kts :

plugins {
    kotlin("jvm")  // or android, multiplatform
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

Déclaration de la dépendance ksp

Utilisez la configuration ksp (et non implementation) pour ajouter un processeur KSP. Le processeur s’exécute uniquement lors de la compilation et n’est pas inclus dans l’artefact final :

dependencies {
    implementation(project(":annotation"))
    ksp(project(":processor"))
}

Répertoires des sources générées

KSP écrit les fichiers générés sous build/generated/ksp/<sourceSet>/kotlin/. Le module d’extension KSP ajoute automatiquement ces répertoires à l’ensemble de sources Kotlin ; les classes générées sont donc accessibles à votre code sans configuration manuelle.

Transmission d’options au processeur

Transmettez des options de compilation de Gradle à votre processeur au moyen de ksp { arg("key", "value") }. Lisez-les dans le processeur au moyen de environment.options["key"] :

// build.gradle.kts (consumer)
ksp {
    arg("generateMocks", "true")
    arg("outputPackage", "com.example.generated")
}

Lecture des options dans le processeur

Dans la méthode SymbolProcessorProvider.create(), accédez aux options depuis l’environnement :

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        val genMocks = environment.options["generateMocks"] == "true"
        return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
    }
}

Compilations incrémentielles

KSP suit les dépendances entre les entrées et les sorties. Associez chaque fichier généré à ses symboles sources lors de l’appel à codeGenerator.createNewFile(). KSP ignore ensuite le retraitement lorsque aucune des entrées suivies n’a été modifiée.

val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)

KSP avec Android

Pour les projets Android, remplacez kapt par ksp dans les déclarations du module d’extension et des dépendances. Utilisez des configurations tenant compte des variantes, comme kspDebug ou kspRelease, si le comportement du processeur doit varier selon le type de compilation.

KSP avec Kotlin Multiplatform

Dans un projet KMP, appliquez le module d’extension KSP et utilisez add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) ou la forme abrégée kspCommonMainMetadata, kspJvmMain, etc., selon les cibles prises en charge par votre processeur.

Affichage des fichiers générés

Après avoir exécuté ./gradlew build (ou kspKotlin / kspDebugKotlin pour Android), examinez build/generated/ksp/. IntelliJ et Android Studio marquent ces dossiers comme des sources générées et permettent de naviguer des utilisations vers les déclarations générées.

Débogage d’un processeur

Exécutez la tâche Gradle avec --debug ou ajoutez jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") à la configuration ksp afin d’attacher un débogueur distant à la JVM de traitement des annotations.

Vérification rapide

Quelle configuration Gradle permet d’ajouter un processeur KSP qui s’exécute lors de la compilation, mais qui n’est pas inclus dans le chemin de classes d’exécution ?

Récapitulatif : intégrer KSP à une compilation Gradle

Points essentiels :

Appliquez le module d’extension com.google.devtools.ksp ; ajoutez le processeur avec la dépendance ksp()
Les sources générées sont placées dans build/generated/ksp/ et ajoutées automatiquement à l’ensemble de sources
Transmettez les options depuis Gradle au moyen de ksp { arg() } ; lisez-les au moyen de environment.options
Utilisez Dependencies avec createNewFile() pour obtenir des recompilations incrémentielles précises
Fonctionne avec Android (configurations par variante) et Kotlin Multiplatform

Questions Fréquemment Posées

La leçon « Intégrer des processeurs KSP dans une compilation Gradle » est-elle gratuite ?

Oui — le texte complet de « Intégrer des processeurs KSP dans une compilation Gradle » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Kotlin Academy, passe à CoddyKit PRO. Le cours Kotlin Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Intégrer des processeurs KSP dans une compilation Gradle » ?

Configurez KSP dans Gradle, ajoutez les sources générées et déboguez la sortie du processeur. Tu pratiques Kotlin Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Kotlin Academy ?

Aucune expérience préalable n'est requise. Kotlin Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Intégrer des processeurs KSP dans une compilation Gradle » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Kotlin Academy ?

Oui. Chaque leçon Kotlin Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

KSP ou KAPT : pourquoi KSP est plus rapide
Écrire votre premier SymbolProcessor
Générer des fichiers source Kotlin avec KotlinPoet
Intégrer des processeurs KSP dans une compilation Gradle

← Retour à Kotlin Academy