Kotlin Academy · Lección

Integrar procesadores KSP en una compilación de Gradle

Configure KSP en Gradle, añada las fuentes generadas y depure la salida del procesador.

Integrar procesadores KSP en una compilación de Gradle es una lección gratuita de Kotlin Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Kotlin Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Kotlin Academy incluye 4 lecciones en total.

Estructura de varios módulos

Una configuración típica de KSP tiene al menos dos módulos: :annotation (contiene las clases de anotación) y :processor (contiene el SymbolProcessor). El módulo consumidor aplica el complemento de KSP y declara las dependencias ksp y implementation.

Aplicación del complemento de KSP

En el build.gradle.kts del módulo consumidor:

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

Declaración de la dependencia ksp

Utilice la configuración ksp (no implementation) para añadir un procesador de KSP. El procesador se ejecuta únicamente durante la compilación y no se incluye en el artefacto final:

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

Directorios de código fuente generado

KSP escribe los archivos generados en build/generated/ksp/<sourceSet>/kotlin/. El complemento de KSP añade automáticamente estos directorios al conjunto de código fuente de Kotlin, por lo que las clases generadas son visibles para su código sin configuración manual.

Transmisión de opciones al procesador

Transmita opciones en tiempo de compilación desde Gradle al procesador mediante ksp { arg("key", "value") }. Léalas en el procesador mediante environment.options["key"]:

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

Lectura de opciones en el procesador

En el método SymbolProcessorProvider.create(), acceda a las opciones desde el entorno:

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

Compilaciones incrementales

KSP realiza un seguimiento de las dependencias entre entradas y salidas. Asocie cada archivo generado con sus símbolos de origen al llamar a codeGenerator.createNewFile(). De este modo, KSP omite el reprocesamiento cuando ninguna de las entradas supervisadas ha cambiado.

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

KSP con Android

En proyectos de Android, sustituya kapt por ksp tanto en las declaraciones del complemento como en las de las dependencias. Utilice configuraciones específicas de la variante, como kspDebug o kspRelease, si necesita que el comportamiento del procesador difiera entre los tipos de compilación.

KSP con Kotlin Multiplatform

En un proyecto de KMP, aplique el complemento de KSP y utilice add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) o las formas abreviadas kspCommonMainMetadata, kspJvmMain, etc., según los destinos compatibles con su procesador.

Visualización de archivos generados

Después de ejecutar ./gradlew build (o kspKotlin / kspDebugKotlin para Android), inspeccione build/generated/ksp/. IntelliJ y Android Studio marcan estas carpetas como fuentes generadas y permiten navegar desde los usos hasta las declaraciones generadas.

Depuración de un procesador

Ejecute la tarea de Gradle con --debug o añada jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") a la configuración de ksp para conectar un depurador remoto a la JVM de procesamiento de anotaciones.

Comprobación rápida

¿Qué configuración de Gradle se utiliza para añadir un procesador de KSP que se ejecuta durante la compilación, pero no se incluye en el classpath de ejecución?

Recapitulación: integración de KSP en una compilación de Gradle

Conclusiones clave:

Aplique el complemento com.google.devtools.ksp; añada el procesador con la dependencia ksp()
El código fuente generado se coloca en build/generated/ksp/ y se añade automáticamente al conjunto de código fuente
Transmita opciones desde Gradle mediante ksp { arg() }; léalas mediante environment.options
Utilice Dependencies con createNewFile() para obtener compilaciones incrementales precisas
Es compatible con Android (configuraciones por variante) y Kotlin Multiplatform

Preguntas frecuentes

¿La lección «Integrar procesadores KSP en una compilación de Gradle» es gratis?

Sí — el texto completo de «Integrar procesadores KSP en una compilación de Gradle» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Kotlin Academy, actualiza a CoddyKit PRO. El curso de Kotlin Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Integrar procesadores KSP en una compilación de Gradle»?

Configure KSP en Gradle, añada las fuentes generadas y depure la salida del procesador. Practicas Kotlin Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Kotlin Academy?

No se requiere experiencia previa. Kotlin Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Integrar procesadores KSP en una compilación de Gradle»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Kotlin Academy?

Sí. Cada lección de Kotlin Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

KSP frente a KAPT: por qué KSP es más rápido
Escribir su primer SymbolProcessor
Generar archivos fuente de Kotlin con KotlinPoet
Integrar procesadores KSP en una compilación de Gradle

← Volver a Kotlin Academy