Migra a Kotlin integrado

El complemento de Android para Gradle 9.0 introduce compatibilidad integrada con Kotlin y la habilita de forma predeterminada. Esto significa que ya no tienes que aplicar el complemento org.jetbrains.kotlin.android (o kotlin-android) en tus archivos de compilación para compilar archivos fuente de Kotlin. Con Kotlin integrado, tus archivos de compilación son más simples y puedes evitar problemas de compatibilidad entre el AGP y el plugin kotlin-android.

Nota: Kotlin integrado solo reemplaza el complemento kotlin-android. Si escribes un módulo de biblioteca de Kotlin Multiplatform (KMP), aún debes aplicar el complemento org.jetbrains.kotlin.multiplatform y el complemento com.android.kotlin.multiplatform.library. Además, ya no se permite usar el plugin org.jetbrains.kotlin.multiplatform junto con el plugin com.android.library o com.android.application cuando se habilita Kotlin integrado.

Habilita Kotlin integrado

Necesitas AGP 9.0 o una versión posterior para tener compatibilidad integrada con Kotlin. AGP 9.0 ya habilita Kotlin integrado para todos los módulos en los que aplicas AGP, por lo que no necesitas hacer nada para habilitarlo. Sin embargo, si anteriormente inhabilitaste Kotlin integrado configurando android.builtInKotlin=false en el archivo gradle.properties, debes quitar ese parámetro de configuración o establecerlo en true.

Nota: También puedes habilitar Kotlin integrado para un módulo a la vez.

Kotlin integrado requiere algunos cambios en tu proyecto, por lo que, después de habilitar Kotlin integrado, sigue los próximos pasos para migrar tu proyecto.

Pasos de la migración

Después de actualizar tu proyecto de una versión anterior del AGP a la versión 9.0 o después de habilitar manualmente Kotlin integrado, es posible que veas el siguiente mensaje de error:

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

…o

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

Este error se produce porque Kotlin integrado requiere algunos cambios en tu proyecto. Para resolver este error, sigue estos pasos:

Nota: Si aún no está todo listo para migrar tu proyecto, también puedes inhabilitar Kotlin integrado.

1. Cómo quitar el complemento de kotlin-android
2. Migra el complemento kotlin-kapt si es necesario
3. Migra el DSL de android.kotlinOptions{} si es necesario
4. Migra el DSL de kotlin.sourceSets{} si es necesario

1. Cómo quitar el complemento kotlin-android

Quita el complemento org.jetbrains.kotlin.android (o kotlin-android) de los archivos de compilación a nivel del módulo en los que lo aplicas. El código exacto que debes quitar depende de si usas catálogos de versiones para declarar complementos.

Con catálogos de versiones

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

No hay catálogos de versiones

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

Luego, quita el complemento de tu archivo de compilación de nivel superior:

Con catálogos de versiones

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

No hay catálogos de versiones

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

Si usas catálogos de versiones, también quita la definición del complemento del archivo TOML del catálogo de versiones (por lo general, gradle/libs.versions.toml):

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. Migra el complemento kotlin-kapt si es necesario

El complemento org.jetbrains.kotlin.kapt (o kotlin-kapt) no es compatible con Kotlin integrado. Si usas kapt, te recomendamos que migres tu proyecto a KSP.

Si aún no puedes migrar a KSP, reemplaza el complemento kotlin-kapt por el complemento com.android.legacy-kapt, usando la misma versión que tu complemento de Android Gradle.

Por ejemplo, con los catálogos de versiones, actualiza tu archivo TOML del catálogo de versiones de la siguiente manera:

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

Luego, actualiza tus archivos de compilación:

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Nota: Si declaras el complemento kotlin-kapt en el bloque plugins{} como kotlin("kapt") version "<KOTLIN_VERSION>", quita esa línea.

3. Migra el DSL de android.kotlinOptions{} si es necesario

Si usas el DSL de android.kotlinOptions{}, debes migrarlo al DSL de kotlin.compilerOptions{}.

Por ejemplo, actualiza este código:

Kotlin

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

Groovy

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

… al nuevo DSL:

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Nota: Con Kotlin integrado, no es necesario establecer kotlin.compilerOptions.jvmTarget porque su valor predeterminado es android.compileOptions.targetCompatibility.

4. Migra el DSL de kotlin.sourceSets{} si es necesario

Cuando usas el complemento kotlin-android, AGP te permite agregar directorios de fuentes de Kotlin adicionales con el DSL de android.sourceSets{} o el DSL de kotlin.sourceSets{}. Con el DSL de android.sourceSets{}, puedes agregar los directorios al conjunto AndroidSourceSet.kotlin o al conjunto AndroidSourceSet.java.

Con Kotlin integrado, la única opción admitida es agregar los directorios al conjunto AndroidSourceSet.kotlin con el DSL de android.sourceSets{}. Si usas opciones no admitidas, migra de la siguiente manera:

Kotlin

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

Si deseas agregar un directorio de origen de Kotlin a una variante específica o si un directorio se genera mediante una tarea, puedes usar los métodos addStaticSourceDirectory o addGeneratedSourceDirectory en la API de variantes:

Kotlin

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Groovy

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Informar problemas

Si tienes problemas después de completar los pasos anteriores, revisa los problemas conocidos en el problema núm. 438678642 y envíanos tus comentarios si es necesario.

Cómo inhabilitar Kotlin integrado

Si no puedes migrar tu proyecto para usar Kotlin integrado, configura android.builtInKotlin=false en el archivo gradle.properties para inhabilitarlo temporalmente. Cuando lo hagas, la compilación mostrará una advertencia que te recordará que migres a Kotlin integrado, ya que no podrás inhabilitar Kotlin integrado en una versión futura de AGP 9.x antes de AGP 10.0.

Nota: También debes establecer android.newDsl=false para inhabilitar la nueva DSL, ya que el complemento kotlin-android no es compatible con ella.

Cuando esté todo listo para migrar tu proyecto, habilita Kotlin integrado y sigue los pasos de migración.

Migración módulo por módulo

La propiedad android.builtInKotlin de Gradle te permite habilitar o inhabilitar Kotlin integrado para todos los módulos en los que apliques el AGP.

Si migrar todos tus módulos a la vez es un desafío, puedes migrar un módulo a la vez:

1. Configura android.builtInKotlin=false en el archivo gradle.properties para inhabilitar Kotlin integrado en todos los módulos.

2. Aplica el complemento com.android.built-in-kotlin al módulo en el que deseas habilitar Kotlin integrado, con la misma versión que tu complemento de Android para Gradle.

3. Sigue los pasos de migración anteriores para migrar este módulo a Kotlin integrado.

4. Una vez que hayas migrado todos tus módulos, quita el parámetro de configuración android.builtInKotlin=false en gradle.properties y el complemento com.android.built-in-kotlin en tus archivos de compilación.

Opción para inhabilitar de forma selectiva el código Kotlin integrado

El complemento de Android para Gradle 9.0 habilita Kotlin integrado para todos los módulos en los que se aplica. Recomendamos inhabilitar Kotlin integrado de forma selectiva para los módulos que no tienen fuentes de Kotlin en proyectos grandes. Esto quita la tarea de compilación de Kotlin, que tiene un pequeño costo de rendimiento de compilación, y la dependencia automática de la biblioteca estándar de Kotlin.

Para inhabilitar Kotlin integrado en un módulo, establece enableKotlin = false en el archivo de compilación de ese módulo:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}