Migración a Kotlin incorporado para desarrolladores de aplicaciones

Esta guía describe los pasos de migración específicamente para desarrolladores de aplicaciones.

Estas instrucciones asumen que estás actualizando desde una versión de AGP creada antes de la 9.0.0 a una versión de AGP 9.0.0+. También deberías usar las versiones mínimas de dependencia compatibles enumeradas en la documentación del Android Gradle Plugin.

Flutter establece el comportamiento predeterminado para usar el Kotlin Gradle Plugin (KGP) heredado y los tipos antiguos de DSL de AGP para soportar proyectos que aún no se han migrado. La herramienta de migración de Flutter añade automáticamente android.builtInKotlin=false y android.newDsl=false a tu archivo gradle.properties.

Si estas banderas faltan en tu archivo gradle.properties, la herramienta de Flutter las añade automáticamente la próxima vez que compiles o ejecutes tu aplicación usando flutter run o flutter build apk.

Alternativamente, compilar el proyecto utilizando las herramientas de Android Studio también añade estas banderas automáticamente. Una vez completado el proceso, verifica que las banderas se hayan añadido. Para más detalles, consulta el issue #183910 de Flutter.

Todos los proyectos add-to-app deben añadir manualmente android.builtInKotlin=false y android.newDsl=false al archivo gradle.properties de la aplicación host de Android. La herramienta de migración de Flutter no puede ejecutarse durante las compilaciones de la aplicación host de Android add-to-app porque la aplicación host es un proyecto de Android nativo puro.

...
android.newDsl=false
android.builtInKotlin=false

Primero, busca el complemento kotlin-android (o el complemento org.jetbrains.kotlin.android). Es probable que se encuentre en el bloque plugins del archivo <app-src>/android/app/build.gradle o el archivo <app-src>/android/app/build.gradle.kts. Si utilizas la sintaxis apply heredada, se ubicará en el archivo <app-src>/android/app/build.gradle basado en Groovy, ya que esta sintaxis no es compatible con el DSL de Kotlin.

Los siguientes ejemplos demuestran cómo migrar una aplicación de Flutter para Android y una aplicación host de Android add-to-app:

plugins {
    id("com.android.application")
    id("kotlin-android")
    // ...
}
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}
​
// ...

plugins {
    id("com.android.application")
    id("kotlin-android")
    // ...
}
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}

plugins {
    id("com.android.application")
    // ...
}
​
android {
    // ...
}
​
kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}
​
// ...

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
// ...
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}
​
// ...

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
 ...
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}

apply plugin: 'com.android.application'
// ...
​
android {
    // ...
}
​
kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}
​
// ...

Las aplicaciones nativas de Android utilizan la palabra clave alias para aplicar complementos, lo cual es incompatible con la sintaxis apply() heredada. Por lo tanto, solo se incluyen las instrucciones del bloque plugins {}.

Before:

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    // ...
}
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}
​
// ...

A continuación, elimina el complemento kotlin-android y el bloque kotlinOptions:

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    // ...
}
​
android {
    // ...
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
    // ...
}

Añade el bloque DSL kotlin.compilerOptions{} con lo siguiente:

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}

Así es como probablemente quedará el archivo:

After:

plugins {
    alias(libs.plugins.android.application)
    // ...
}
​
android {
    // ...
}
​
kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}
​
// ...

Ejecuta flutter run o flutter build apk para confirmar que tu aplicación se compila y se inicia en un dispositivo Android o emulador conectado.

Si tu aplicación falla al compilarse debido a que estás usando un complemento de Flutter que no se ha migrado, sigue las instrucciones a continuación:

Sigue estas instrucciones solo si tu aplicación utiliza un complemento de Flutter que aún no se ha migrado a Kotlin incorporado.

1. Busca el repositorio del complemento de Flutter no migrado buscando el nombre del complemento en pub.dev o en línea.
2. Revisa el historial de cambios (changelog) del complemento para confirmar que ninguna versión existente se haya migrado a Kotlin incorporado.
3. Informa sobre el problema a los autores del complemento, comunicándoles que el Kotlin Gradle Plugin es incompatible y no será soportado en una versión futura de Flutter.

Puedes utilizar la siguiente plantilla para el issue:

Título del issue: Migrate plugin to built-in Kotlin

Issue Body:

I am using `<plugin-name>` in my Flutter app.
​
Starting with Android Gradle Plugin (AGP) 9.0,
support for applying the Kotlin Gradle Plugin (KGP) has been removed.
Because this plugin applies KGP,
it causes a compilation error that prevents my app from building.
Flutter [issue #181383](https://github.com/flutter/flutter/issues/181383)
includes an example of the error.
​
Flutter has temporarily added support to allow KGP
while apps and plugins migrate to AGP 9.0 or later,
but this support will be removed in a future version of Flutter.
​
Please migrate this plugin to use built-in Kotlin to
ensure your plugin users can successfully
build their apps in future versions of Flutter.
​
Here is the Flutter
[migration guide for plugin authors](https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors).

Por favor, sé respetuoso y ten en cuenta las reglas y el código de conducta del repositorio del complemento al informar sobre problemas e interactuar con los autores del mismo.

Como referencia, consulta el Código de Conducta de Flutter.

Para los siguientes pasos, consulta la descripción general de la migración a Kotlin incorporado.

Issues relevantes:

• Issue #183910: Añadir migración para desactivar Kotlin incorporado y nuevo DSL
• Issue #181383: Los complementos de Flutter deben ser compatibles con AGP 9.0.0

Los archivos de compilación de Gradle en tu aplicación varían según la versión de Flutter utilizada al crear tu aplicación. Considera mantenerte al día con la última versión de los archivos de compilación ejecutando periódicamente flutter upgrade en el directorio raíz de tu aplicación.