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 complemento kotlin-android.

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, deberás quitar ese parámetro de configuración o establecer android.builtInKotlin=true para habilitarlo.

Kotlin integrado requiere que realices 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 posterior, 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.

Esto se debe a que Kotlin integrado requiere que realices algunos cambios en tu proyecto. Para resolver este error, realiza los siguientes pasos.

1. Cómo quitar el complemento kotlin-android
2. Migra el complemento kotlin-kapt si es necesario
3. Migra el bloque kotlinOptions{} 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.

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

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

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

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

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

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

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

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

// 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 (generalmente 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

Si usas org.jetbrains.kotlin.kapt (o kotlin-kapt) en tus archivos de compilación, este complemento no será compatible con Kotlin integrado. Debes reemplazar este complemento por el complemento com.android.legacy-kapt, con la misma versión que tu complemento de Android para Gradle actual.

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:

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

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

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

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

3. Migra el bloque kotlinOptions{} si es necesario

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

Por ejemplo, actualiza este código:

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

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

… al nuevo DSL:

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

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

Informar problemas

Después de completar los pasos anteriores, si tienes problemas, consulta los problemas conocidos en la descripción del problema #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 inhabilitar temporalmente Kotlin integrado. 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.

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 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.experimental.built-in-kotlin al módulo en el que deseas habilitar Kotlin integrado, con la misma versión que tu complemento de Android Gradle actual.

3. Realiza 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.experimental.built-in-kotlin en tus archivos de compilación.