Migra de kapt a KSP

Nota: Kapt ahora está en modo de mantenimiento, y te recomendamos que migres de kapt a KSP para todos los procesadores que lo admitan. En la mayoría de los casos, esta migración solo requiere cambios en la configuración de compilación del proyecto.

Kapt (la herramienta de procesamiento de anotaciones de Kotlin) te permite usar procesadores de anotaciones Java con código Kotlin, incluso si esos procesadores no tienen compatibilidad específica con Kotlin. Para hacerlo, se generan stubs de Java de los archivos Kotlin que los procesadores pueden leer. La generación de stub es una operación costosa y tiene un impacto significativo en la velocidad de compilación.

KSP (Procesamiento de Símbolos de Kotlin) es una alternativa a kapt que prioriza a Kotlin. KSP analiza el código Kotlin directamente, lo que es hasta 2 veces más rápido. También comprende mejor las construcciones de lenguaje de Kotlin.

Puedes ejecutar kapt y KSP en conjunto en tu proyecto mientras realizas la migración, y la migración se puede realizar módulo por módulo y biblioteca por biblioteca.

Nota: Si a un módulo le quedan procesadores de kapt, los stubs se generan de todas formas en ese módulo. Esto significa que la mayoría de las mejoras de rendimiento ocurrirán solo cuando se quiten todos los usos de kapt del módulo.

A continuación, se incluye una descripción general de los pasos de migración:

1. Verifica las bibliotecas que usas para la compatibilidad con KSP.
2. Agrega el complemento KSP al proyecto.
3. Reemplaza procesadores de anotaciones con KSP.
4. Quita el complemento kapt.

Verifica las bibliotecas que usas para la compatibilidad con KSP

Para comenzar, verifica si las bibliotecas que usas con kapt ya tienen compatibilidad con KSP. Este es el caso de muchas bibliotecas populares (incluidas Dagger, Glide, Room y Moshi). Otras están agregando compatibilidad.

Puedes consultar la lista de bibliotecas compatibles en la documentación, o bien consultar la documentación y la herramienta de seguimiento de errores de las bibliotecas que usas.

Nota: Si bien no es una dependencia de biblioteca que se incluya normalmente, la vinculación de datos también usa un procesador de anotaciones para proporcionar su funcionalidad, y la compatibilidad con KSP para la vinculación de datos no está planificada. Puedes mitigar el impacto de kapt en tu compilación al aislar los usos de la vinculación de datos a módulos separados.

Agrega el complemento KSP al proyecto

Primero, declara el complemento KSP en el archivo build.gradle.kts de nivel superior. Asegúrate de elegir una versión de KSP que esté alineada con la versión de Kotlin de tu proyecto. Puedes encontrar una lista de las actualizaciones en la página de GitHub de KSP.

Nota: La primera parte de la versión de KSP debe coincidir con la versión de Kotlin que se usa en tu compilación. Por ejemplo, si usas Kotlin 2.0.21, la versión de KSP debe ser una de las versiones 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
}

Luego, habilita KSP en el archivo build.gradle.kts a nivel del módulo:

Kotlin

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

Groovy

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

Reemplaza los procesadores de anotaciones con KSP

Con KSP habilitado, puedes comenzar a reemplazar los usos de kapt por KSP. Para una gran mayoría de bibliotecas, esto solo requiere cambiar kapt a ksp en la declaración de dependencia, ya que envían el procesador de anotaciones y el procesador KSP en el mismo artefacto.

Nota: Es posible que algunas bibliotecas (como Glide) requieran que cambies la dependencia a un artefacto diferente. Asegúrate de consultar la documentación correspondiente.

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

Después de pasar a KSP, sincroniza y compila tu proyecto para ver si todavía funciona correctamente.

A continuación, presentamos algunos problemas comunes para tener en cuenta:

• Algunas bibliotecas no admiten exactamente el mismo conjunto de funciones con kapt y KSP. Si el código falla después de la migración, consulta la documentación de la biblioteca.
• KSP tiene información de tipo Kotlin más precisa que kapt (por ejemplo, sobre la nulabilidad), lo que significa que los procesadores KSP pueden ser más precisos sobre los requisitos de tipo. Esto también puede requerir algunas correcciones en el código fuente, además de la actualización de los archivos de compilación.
• Si antes pasabas argumentos al procesador de anotaciones, es probable que debas pasarlos a KSP ahora. Ten en cuenta que el formato de los argumentos puede diferir entre kapt y KSP. Consulta la documentación de KSP y la documentación de la biblioteca que usas para obtener más información.

Quita el complemento kapt

Cuando ya no tengas dependencias incluidas con kapt en tu módulo, quita el complemento kapt.

Nota:La vinculación de datos también requiere que se habilite kapt en el módulo. En los módulos en los que se usa la vinculación de datos, kapt no se puede quitar.

Si se declaró en un bloque de complementos:

Kotlin

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

Groovy

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

Si usaba la sintaxis de la aplicación de complementos con Groovy:

apply plugin: 'kotlin-kapt'

También debes quitar cualquier configuración restante relacionada con kapt, por ejemplo:

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

Recursos adicionales

• Documentación de KSP en Kotlinlang.org
• KSP en GitHub
• kapt en Kotlinlang.org -->