Kotlin Academy · Lezione

Integrare i processori KSP in una build Gradle

Configuri KSP in Gradle, aggiunga le sorgenti generate ed esegua il debug dell'output del processore.

Integrare i processori KSP in una build Gradle è una lezione Kotlin Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Kotlin Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Kotlin Academy include 4 lezioni in totale.

Struttura multimodulo

Una configurazione KSP tipica comprende almeno due moduli: :annotation (contiene le classi delle annotazioni) e :processor (contiene il SymbolProcessor). Il modulo consumer applica il plugin KSP e dichiara le dipendenze ksp e implementation.

Applicazione del plugin KSP

Nel build.gradle.kts del modulo consumer:

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

Dichiarazione della dipendenza ksp

Utilizzi la configurazione ksp (non implementation) per aggiungere un processore KSP. Il processore viene eseguito solo in fase di compilazione e non viene incluso nell'artefatto finale:

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

Directory dei sorgenti generati

KSP scrive i file generati in build/generated/ksp/<sourceSet>/kotlin/. Il plugin KSP aggiunge automaticamente queste directory al source set Kotlin, quindi le classi generate sono visibili al codice senza configurazione manuale.

Passaggio delle opzioni al processore

Passi le opzioni in fase di compilazione da Gradle al processore tramite ksp { arg("key", "value") }. Le legga nel processore tramite environment.options["key"]:

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

Lettura delle opzioni nel processore

Nel metodo SymbolProcessorProvider.create(), acceda alle opzioni dall'ambiente:

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

Build incrementali

KSP tiene traccia delle dipendenze tra input e output. Associ ogni file generato ai relativi simboli sorgente quando chiama codeGenerator.createNewFile(). KSP eviterà così di rielaborare i file quando nessuno degli input monitorati è cambiato.

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

KSP con Android

Nei progetti Android, sostituisca kapt con ksp sia nelle dichiarazioni del plugin sia in quelle delle dipendenze. Utilizzi configurazioni specifiche per la variante, come kspDebug o kspRelease, se deve differenziare il comportamento del processore tra i diversi tipi di build.

KSP con Kotlin Multiplatform

In un progetto KMP, applichi il plugin KSP e utilizzi add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) oppure la notazione abbreviata kspCommonMainMetadata, kspJvmMain e così via, a seconda delle destinazioni supportate dal processore.

Visualizzazione dei file generati

Dopo aver eseguito ./gradlew build (oppure kspKotlin / kspDebugKotlin per Android), esamini build/generated/ksp/. IntelliJ e Android Studio contrassegnano queste cartelle come sorgenti generate e consentono di passare dagli utilizzi alle dichiarazioni generate.

Debug di un processore

Esegua il task Gradle con --debug oppure aggiunga jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") alla configurazione ksp per collegare un debugger remoto alla JVM di elaborazione delle annotazioni.

Verifica rapida

Quale configurazione Gradle si utilizza per aggiungere un processore KSP che viene eseguito in fase di compilazione, ma non viene incluso nel classpath di runtime?

Riepilogo: integrazione di KSP in una build Gradle

Punti chiave:

Applichi il plugin com.google.devtools.ksp; aggiunga il processore con la dipendenza ksp()
I sorgenti generati vengono inseriti in build/generated/ksp/ e aggiunti automaticamente al source set
Passi le opzioni da Gradle tramite ksp { arg() }; le legga tramite environment.options
Utilizzi Dependencies con createNewFile() per ricostruzioni incrementali accurate
Funziona con Android (configurazioni per variante) e Kotlin Multiplatform

Domande Frequenti

La lezione «Integrare i processori KSP in una build Gradle» è gratuita?

Sì — il testo completo di «Integrare i processori KSP in una build Gradle» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Kotlin Academy, passa a CoddyKit PRO. Il corso Kotlin Academy include 4 lezioni in totale.

Cosa imparerò in «Integrare i processori KSP in una build Gradle»?

Configuri KSP in Gradle, aggiunga le sorgenti generate ed esegua il debug dell'output del processore. Eserciti Kotlin Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Kotlin Academy?

Non è richiesta alcuna esperienza precedente. Kotlin Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Integrare i processori KSP in una build Gradle»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Kotlin Academy?

Sì. Ogni lezione Kotlin Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

KSP e KAPT: perché KSP è più veloce
Scrivere il primo SymbolProcessor
Generare file sorgente Kotlin con KotlinPoet
Integrare i processori KSP in una build Gradle

← Torna a Kotlin Academy