Notas de la versión preliminar del complemento de Android para Gradle

En esta página, se incluyen las notas de la versión de las versiones preliminares del complemento de Android para Gradle (AGP).

Complemento de Android para Gradle 9.0

El complemento de Android para Gradle 9.0 es una nueva versión principal del AGP que incluye cambios en el comportamiento y la API.

Para actualizar al complemento de Android para Gradle 9.0.0-beta01, usa el Asistente de actualización del complemento de Android para Gradle en Android Studio Otter 3 Feature Drop | 2025.2.3.

El asistente de actualización del AGP ayuda a conservar los comportamientos existentes cuando actualizas tu proyecto, si es apropiado, lo que te permite actualizar tu proyecto para usar AGP 9.0, incluso si no estás listo para implementar todos los nuevos valores predeterminados en AGP 9.0.

Compatibilidad

El nivel de API de Android máximo que admite el complemento de Android para Gradle 9.0.0-beta01 es el nivel de API 36.

El complemento de Android para Gradle 9.0.0-beta01 requiere Gradle 9.0.0.

Las clases de DSL de android ahora solo implementan las nuevas interfaces públicas

En los últimos años, presentamos nuevas interfaces para nuestra DSL y API con el objetivo de controlar mejor qué APIs son públicas. Las versiones 7.x y 8.x del AGP seguían usando los tipos de DSL antiguos (por ejemplo, BaseExtension), que también implementaban las nuevas interfaces públicas, para mantener la compatibilidad a medida que avanzaba el trabajo en las interfaces.

AGP 9.0 usa nuestras nuevas interfaces de DSL de forma exclusiva, y las implementaciones cambiaron a nuevos tipos que están completamente ocultos. Esto también quita el acceso a la API de variantes antigua y obsoleta.

Para actualizar a AGP 9.0, es posible que debas hacer lo siguiente:

• Asegúrate de que tu proyecto sea compatible con Kotlin integrado: El complemento org.jetbrains.kotlin.android no es compatible con el nuevo DSL.

• Cambia los proyectos de KMP al complemento de biblioteca de Android Gradle para KMP: El uso del complemento org.jetbrains.kotlin.multiplatform en el mismo subproyecto de Gradle que los complementos com.android.library y com.android.application no es compatible con el nuevo DSL.

• Actualiza tus archivos de compilación: Si bien el cambio de interfaces tiene como objetivo mantener la DSL lo más similar posible, es posible que haya algunos cambios pequeños.

• Actualiza la lógica de compilación personalizada para hacer referencia a la nueva DSL y API: Reemplaza cualquier referencia a la DSL interna por las interfaces de la DSL pública. En la mayoría de los casos, será un reemplazo uno a uno. Reemplaza cualquier uso de la API de applicationVariants y APIs similares por la nueva API de androidComponents. Esto puede ser más complejo, ya que la API de androidComponents está diseñada para ser más estable y mantener la compatibilidad de los complementos por más tiempo. Consulta nuestras Recetas de Gradle para ver ejemplos.

• Actualiza los complementos de terceros: Es posible que algunos complementos de terceros aún dependan de interfaces o APIs que ya no se exponen. Migra a versiones de esos complementos que sean compatibles con AGP 9.0.

El cambio a las nuevas interfaces de DSL evita que los complementos y los secuencias de comandos de compilación de Gradle usen varias APIs que dejaron de estar disponibles, incluidas las siguientes:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

Si actualizas a AGP 9.0 y ves el siguiente mensaje de error, significa que tu proyecto aún hace referencia a algunos de los tipos anteriores:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Si los complementos de terceros incompatibles te impiden avanzar, puedes inhabilitar la opción y recuperar las implementaciones anteriores del DSL, así como la API de Variant anterior. Mientras lo haces, las nuevas interfaces también están disponibles, y aún puedes actualizar tu propia lógica de compilación a la nueva API. Para inhabilitar la opción, incluye esta línea en tu archivo gradle.properties:

android.newDsl=false

También puedes comenzar a actualizar a las nuevas APIs antes de actualizar a AGP 9.0. Las nuevas interfaces están presentes en muchas versiones de AGP, por lo que puedes tener una combinación de interfaces nuevas y antiguas. En la documentación de referencia de la API de AGP, se muestra la plataforma de la API para cada versión de AGP y cuándo se agregó cada clase, método y campo.

Durante la fase alfa de la versión 9.0, nos comunicaremos con los autores de complementos para ayudarlos a adaptar y lanzar complementos que sean totalmente compatibles con los nuevos modos, y mejoraremos el Asistente de actualización del AGP en Android Studio para guiarte durante la migración.

Si detectas que faltan capacidades o funciones en el nuevo DSL o en la API de Variant, informa el problema lo antes posible.

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. Esto simplifica la integración de Kotlin con AGP, evita el uso de las APIs obsoletas y mejora el rendimiento en algunos casos.

Por lo tanto, cuando actualices tu proyecto a AGP 9.0, también deberás migrar a Kotlin integrado o inhabilitar la opción.

Puedes inhabilitar de forma selectiva la compatibilidad integrada con Kotlin para los subproyectos de Gradle que no tengan fuentes de Kotlin.

Dependencia de tiempo de ejecución en el complemento de Kotlin Gradle 2.2.10

El complemento de Android para Gradle 9.0 tiene una dependencia de tiempo de ejecución en el complemento de Kotlin para Gradle (KGP) 2.2.10, que es la versión mínima requerida para la compatibilidad integrada con Kotlin.

Esto significa que, si habilitas Kotlin integrado y usas una versión de KGP anterior a la 2.2.10, Gradle actualizará automáticamente la versión de KGP a la 2.2.10.

Del mismo modo, si usas una versión de KSP anterior a la 2.2.10-2.0.2, AGP actualizará la versión de KSP a la 2.2.10-2.0.2 para que coincida con la versión de KGP.

Por lo tanto, si inhabilitas Kotlin integrado y deseas usar una versión anterior de KGP o KSP, debes agregar lo siguiente a tu archivo de compilación de nivel superior:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

Compatibilidad del IDE con dispositivos de prueba

AGP 9.0 ofrece compatibilidad total con el IDE de Android Studio para fixtures de prueba. Para tener esta compatibilidad, usa AGP 9.0.0-alpha07 o una versión posterior.

Cambios en el comportamiento

El complemento de Android para Gradle 9.0 tiene los siguientes comportamientos nuevos:

AGP 9.0 incluye actualizaciones en los valores predeterminados de las siguientes propiedades de Gradle. Esto te permite conservar el comportamiento de AGP 8.13 cuando realices la actualización:

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Funciones quitadas

El complemento de Android para Gradle 9.0 quita las siguientes funciones:

• Compatibilidad con apps para Wear OS incorporadas
  AGP 9.0 quita la compatibilidad con la incorporación de apps para Wear OS, que ya no se admite en Play. Esto incluye quitar las configuraciones de wearApp y el DSL de AndroidSourceSet.wearAppConfigurationName. Consulta Distribuye a Wear OS para obtener información sobre cómo publicar tu app en Wear OS.
• Tarea de informe de androidDependencies y sourceSets
• Compatibilidad con APK divididos según la densidad
  AGP 9.0 ya no admite la creación de APK divididos según la densidad de la pantalla. Se quitaron la funcionalidad y las APIs relacionadas. Para dividir los APKs según la densidad de pantalla con AGP 9.0 o versiones posteriores, usa paquetes de aplicaciones.

DSL cambiada

El complemento de Android para Gradle 9.0 incluye los siguientes cambios rotundos en el DSL:

• Se quitó la parametrización de CommonExtension.

  En sí mismo, este es solo un cambio que genera interrupciones a nivel de la fuente para ayudar a evitar futuros cambios que generen interrupciones a nivel de la fuente, pero también significa que los métodos de bloqueo deben pasar de CommonExtension a ApplicationExtension, LibraryExension, DynamicFeatureExtension y TestExtension.

  Cuando actualices tu proyecto a AGP 9.0, refactoriza el código del complemento de Gradle que usa esos parámetros o los métodos de bloque. Por ejemplo, el siguiente complemento se actualiza para quitar el parámetro de tipo y no depender de los métodos de bloque quitados:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  En el caso de los complementos que se orientan a un rango de versiones del AGP, usar el getter directamente es compatible a nivel binario con las versiones del AGP anteriores a la 9.0.

Se quitó la DSL

El complemento de Android para Gradle 9.0 quita lo siguiente:

• AndroidSourceSet.jni, porque no funcionaba.

• AndroidSourceSet.wearAppConfigurationName, ya que se relaciona con la compatibilidad con apps integradas para Wear OS que se quitó.

• BuildType.isRenderscriptDebuggable, porque no funcionaba.

• DependencyVariantSelection. Se reemplaza por DependencySelection, que se expone como kotlin.android.localDependencySelection.

• Installation.installOptions(String), que se reemplaza por la propiedad mutable de Installation.installOptions.

• El bloque PostProcessing experimental, pero nunca estabilizado.

• ProductFlavor.setDimension, que se reemplaza por la propiedad dimension

• LanguageSplitOptions, que solo era útil para Google Play Instant, que está en desuso.

• DensitySplit, porque la función ya no es compatible El reemplazo es usar App Bundles.

APIs que se quitaron

El complemento de Android para Gradle 9.0 quita lo siguiente:

• AndroidComponentsExtension.finalizeDSl, que se reemplazó por finalizeDsl

• Component.transformClassesWith, que se reemplazó por Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode, que se reemplazó por Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled, que se reemplazó por ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. Se reemplaza por includeInApk

• DependenciesInfoBuilder.includedInBundle. Se reemplaza por includeInBundle

• GeneratesApk.targetSdkVersion. Se reemplaza por targetSdk

• Variant.minSdkVersion. Se reemplaza por minSdk

• Variant.maxSdkVersion. Se reemplaza por maxSdk

• Variant.targetSdkVersion. Se reemplaza por targetSdk

• Variant.unitTest, ya que no se aplicaba al complemento com.android.test unitTest está disponible en los subtipos VariantBuilder que extienden HasUnitTest.

• VariantBuilder.targetSdk y targetSdkPreview, ya que no eran significativos en las bibliotecas. En su lugar, usa GeneratesApkBuilder.targetSdk o GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, ya que no se aplicaba al complemento com.android.test enableUnitTest está disponible en los subtipos VariantBuilder que extienden HasUnitTestBuilder.

• Se quitó VariantBuilder.unitTestEnabled y se reemplazó por enableUnitTest, que tiene un nombre más coherente, en los subtipos VariantBuilder que extienden HasUnitTestBuilder.

• VariantOutput.enable. Se reemplaza por enabled

• FeaturePlugin y FeatureExtension, que dejaron de estar disponibles y se inhabilitaron.

• Las APIs de BaseExtension.registerTransform que quedaron obsoletas y se inhabilitaron, y que solo permanecieron para permitir la compilación con la versión más reciente de AGP mientras se segmentaba para ejecutarse en AGP 4.2 o versiones anteriores.

Se quitaron propiedades de Gradle

Inicialmente, las siguientes propiedades de Gradle se agregaron como formas de inhabilitar de manera global las funciones que estaban habilitadas de forma predeterminada.

Estas funciones están inhabilitadas de forma predeterminada desde AGP 8.0 o versiones anteriores. Habilita estas funciones solo en los subproyectos que las usen para lograr una compilación más eficiente.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Propiedades de Gradle aplicadas

AGP 9.0 arroja un error si estableces las siguientes propiedades de Gradle.

El Asistente de actualización del complemento de Android para Gradle no actualizará los proyectos a AGP 9.0 que usen estas propiedades.

Errores corregidos

Complemento de Android para Gradle 9.0.0-alpha10

Complemento de Android para Gradle 9.0.0-alpha09

Complemento de Android para Gradle 9.0.0-alpha08

Complemento de Android para Gradle 9.0.0-alpha07

Complemento de Android para Gradle 9.0.0-alpha06

Complemento de Android para Gradle 9.0.0-alpha05

Complemento de Android para Gradle 9.0.0-alpha04

Complemento de Android para Gradle 9.0.0-alpha03

Complemento de Android para Gradle 9.0.0-alpha02

Complemento de Android para Gradle 9.0.0-alpha01