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

El repositorio de JCenter se convirtió en solo lectura el 31 de marzo de 2021. Para obtener más información, consulta la Actualización del servicio de JCenter.

El sistema de compilación de Android Studio se basa en Gradle, y el complemento de Android para Gradle incorpora varias funciones específicas para compilar apps para Android. Si bien el complemento de Android para Gradle (AGP) suele actualizarse en el paso de bloqueo con Android Studio, el complemento (y el resto del sistema Gradle) se pueden ejecutar independientemente de Android Studio y se pueden actualizar por separado.

En esta página, se explica cómo mantener tus herramientas de Gradle actualizadas y cuál es el contenido de las actualizaciones recientes. Para conocer las notas de las versiones anteriores del complemento de Android para Gradle, consulta las notas de las versiones anteriores.

Para ver qué se solucionó en esta versión del complemento de Android para Gradle, consulta los errores cerrados.

Si quieres obtener un resumen general sobre los próximos cambios rotundos, consulta el plan del complemento de Android para Gradle.

A fin de obtener detalles para configurar tus compilaciones de Android con Gradle, consulta las siguientes páginas:

Si quieres obtener más información sobre el sistema de compilación de Gradle, consulta la Guía del usuario de Gradle.

Cómo actualizar el complemento de Android para Gradle

Si actualizas Android Studio, es posible que recibas una solicitud para actualizar automáticamente el complemento de Android para Gradle a la versión más reciente disponible. Puedes aceptar la actualización o especificar manualmente una versión, según los requisitos de compilación del proyecto.

Puedes especificar la versión del complemento en el menú File > Project Structure > Project en Android Studio o en el archivo build.gradle.kts de nivel superior. La versión del complemento se aplica a todos los módulos integrados en ese proyecto de Android Studio. En el siguiente ejemplo, se configura el complemento en la versión 8.3.0 del archivo build.gradle.kts:

Kotlin

plugins {
    id("com.android.application") version "8.3.0" apply false
    id("com.android.library") version "8.3.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.20" apply false
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}

Precaución: No debes usar dependencias dinámicas en los números de versión, como 'com.android.tools.build:gradle:8.3.+'. El uso de esta función puede generar actualizaciones de versión inesperadas y dificultades para resolver diferencias entre versiones.

Si no se descargó la versión especificada del complemento, Gradle la descargará la próxima vez que compiles el proyecto o hagas clic en File > Sync Project with Gradle Files en la barra de menú de Android Studio.

Cómo actualizar Gradle

Si actualizas Android Studio, es posible que recibas una solicitud para actualizar también Gradle a la versión más reciente disponible. Puedes aceptar la actualización o especificar manualmente una versión, según los requisitos de compilación del proyecto.

En la siguiente tabla, se muestra qué versión de Gradle se requiere para cada versión del complemento de Android para Gradle. Si quieres obtener el mejor rendimiento, deberías usar la versión más reciente de Gradle y del complemento.

Versión del complementoVersión mínima de Gradle requerida
8.4 (alfa)8.6-rc-1
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5

Versiones anteriores

Versión del complementoVersión requerida de Gradle
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1
4.1.0+6.5+
4.0.0+6.1.1+
3.6.0 - 3.6.45.6.4+
3.5.0 - 3.5.45.4.1+
3.4.0 - 3.4.35.1.1+
3.3.0 - 3.3.34.10.1+
3.2.0 - 3.2.14.6+
3.1.0+4.4+
3.0.0+4.1+
2.3.0+3.3+
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

Puedes especificar la versión de Gradle en el menú File > Project Structure > Project en Android Studio o actualizar tu versión de Gradle con la línea de comandos. La forma recomendada es usar la herramienta de línea de comandos Gradle Wrapper, que actualiza las secuencias de comandos gradlew. En el siguiente ejemplo, se configura la versión de Gradle en 8.3 con Gradle Wrapper. Ten en cuenta que debes ejecutar este comando dos veces para actualizar tanto Gradle como el wrapper de Gradle (si quieres obtener más información, consulta el artículo para actualizar el wrapper de Gradle).

gradle wrapper --gradle-version 8.3

Sin embargo, en algunos casos, esto puede fallar; por ejemplo, si acabas de actualizar AGP y ya no es compatible con la versión actual de Gradle. En este caso, debes editar la referencia a la distribución de Gradle en el archivo gradle/wrapper/gradle-wrapper.properties. En el siguiente ejemplo, se configura la versión de Gradle en 8.3 en el archivo gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-bin.zip
...

Compatibilidad del complemento de Android para Gradle y Android Studio

El sistema de compilación de Android Studio se basa en Gradle, y el complemento de Android para Gradle (AGP) incorpora varias funciones específicas para compilar apps para Android. En la siguiente tabla, se muestra qué versión de AGP se requiere para cada versión de Android Studio.

Versión Android Studio Versión requerida del AGP
Jellyfish | 2023.3.1 3.2 a 8.4
Iguana | 2023.2.1 3.2-8.3
Hedgehog | 2023.1.1 3.2-8.2
Giraffe | 2022.3.1 3.2-8.1
Flamingo | 2022.2.1 3.2-8.0
Electric Eel | 2022.1.1 3.2-7.4

Versiones anteriores

Versión Android Studio Versión requerida del AGP
Dolphin | 2021.3.1 3.2-7.3
Chipmunk | 2021.2.1 3.2-7.2
Bumblebee | 2021.1.1 3.2-7.1
Arctic Fox | 2020.3.1 3.1-7.0

A fin de conocer las novedades del complemento de Android para Gradle, consulta las notas de la versión del complemento de Android para Gradle.

Versiones mínimas de herramientas para el nivel de API de Android

Hay versiones mínimas de Android Studio y AGP que admiten un nivel de API específico. El uso de versiones anteriores de Android Studio o AGP que las requeridas por targetSdk o compileSdk de tu proyecto podría generar problemas inesperados. Recomendamos usar la versión preliminar más reciente de Android Studio y AGP para trabajar en proyectos orientados a versiones preliminares del SO Android. Puedes instalar versiones preliminares de Android Studio junto con una versión estable.

Estas son las versiones mínimas de Android Studio y AGP:

Nivel de API Versión mínima de Android Studio Versión mínima del AGP
Vista previa de VanillaIceCream Jellyfish | 2023.3.1 8.4
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

Cambios en el control de versiones (noviembre de 2020)

Actualizaremos la numeración de versiones del complemento de Android para Gradle (AGP) a fin de que coincida mejor con la herramienta de compilación subyacente de Gradle.

Estos son algunos de los cambios más importantes:

  • AGP ahora usará el control de versiones semántico y los cambios rotundos se incluirán en las versiones principales.

  • Se lanzará una versión principal de AGP por año, que estará alineada con la actualización más importante de Gradle.

  • La versión posterior a AGP 4.2 será 7.0 y requerirá una actualización a Gradle 7.x. Cada lanzamiento importante de AGP requerirá una actualización importante de versión de la herramienta subyacente de Gradle.

  • Las API quedarán obsoletas aproximadamente con un año de anticipación y, al mismo tiempo, se pondrá a disposición una función de reemplazo. Las APIs obsoletas se quitarán aproximadamente un año después, en la próxima actualización importante.

Compatibilidad

El nivel de API máximo que admite el complemento de Android para Gradle 8.3 es el nivel de API 34. Esta es otra información sobre la compatibilidad:

Versión mínima Versión predeterminada Notas
Gradle 8.4 8.4 Para obtener más información, consulta cómo actualizar Gradle.
Herramientas de desarrollo del SDK 34.0.0 34.0.0 Instala o configura las herramientas de compilación del SDK.
NDK N/A 25.1.8937393 Instala o configura una versión diferente del NDK.
JDK 17 17 Para obtener más información, consulta cómo configurar la versión de JDK.

Las siguientes son funciones nuevas del complemento de Android para Gradle 8.3.

Compatibilidad con catálogos de versiones de Gradle

Android Studio admite catálogos de versiones de Gradle basados en TOML, una función que te permite administrar dependencias en una ubicación central y compartir dependencias entre módulos o proyectos. Android Studio ahora facilita la configuración de catálogos de versiones a través de sugerencias del editor y la integración con el diálogo Project Structure. Obtén información para configurar los catálogos de versiones de Gradle o migrar tu compilación a catálogos de versiones.

Cómo completar el código y navegar

Android Studio ofrece la función de completar el código cuando editas un catálogo de versiones en el formato de archivo TOML o agregas una dependencia de un catálogo de versiones a un archivo de compilación. Para completar el código, presiona Ctrl + Espacio (Comando + Espacio en macOS). Además, puedes navegar rápidamente desde una referencia de dependencia en el archivo build.gradle de tu app hasta donde está declarada en el catálogo de versiones presionando Ctrl + b (Comando + b en macOS).

Finalización del código cuando se agrega una dependencia

Integración con el diálogo Project Structure

Si tu proyecto usa un catálogo de versiones definido en el formato de archivo TOML, puedes editar las variables que definiste allí a través de la vista Variables del diálogo Project Structure (File > Project Structure > Variables) en Android Studio. Para cada catálogo de versiones, hay un menú desplegable que enumera las variables de ese catálogo. Para editar una variable, haz clic en su valor y reemplázala. Cuando guardas estos cambios, el archivo TOML se actualiza en consecuencia.

Variables de un catálogo de versiones en el diálogo Project Structure

También puedes actualizar las dependencias en la vista Dependencies del diálogo Project Structure (File > Project Structure > Dependencies). Para actualizar versiones con el diálogo Project Structure, navega hasta el módulo y la dependencia que quieras editar. Luego, actualiza el campo Requested Version. Cuando guardas estos cambios, el archivo TOML se actualiza en consecuencia. Ten en cuenta que, si la versión de la dependencia se definió con una variable, actualizar la versión directamente de esta manera reemplaza la variable por un valor codificado. Además, ten en cuenta que quitar una dependencia de un archivo de compilación, sin importar si usas el diálogo Project Structure o no, no se quita del catálogo de versiones.

Dependencias de un catálogo de versiones en el diálogo Project Structure

Problemas conocidos y limitaciones

A continuación, se muestran algunos problemas o limitaciones conocidos de la compatibilidad de los catálogos de versiones de Gradle en Android Studio.

  • Se produjo un error al destacar las declaraciones de alias del complemento en los archivos de secuencia de comandos de Kotlin: cuando agregas una declaración de complemento con el formato alias(libs.plugins.example), el editor agrega un subrayado rojo debajo de la parte libs. Este es un problema conocido en Gradle 8.0 y versiones anteriores, y se resolverá en una versión futura de Gradle.

  • Android Studio solo es compatible con catálogos de versiones en formato TOML: actualmente, la compatibilidad con la finalización del código, la navegación y el diálogo de estructura del proyecto de Android Studio solo está disponible para los catálogos de versiones definidos en el formato de archivo TOML. Sin embargo, aún puedes agregar un catálogo de versiones directamente en el archivo settings.gradle y usar sus dependencias en tu proyecto.

  • No se admite la navegación en los archivos de compilación KTS: la navegación a una definición de dependencia en un catálogo de versiones con Control + clic (Comando + clic en macOS) aún no es compatible con los archivos de compilación escritos con la secuencia de comandos de Kotlin.

  • Firebase Assistant agrega dependencias directamente en las secuencias de comandos de compilación: Firebase Assistant las agrega directamente a las secuencias de comandos de compilación, en lugar de hacerlo a través de catálogos de versiones.

  • No se admite la funcionalidad "Find usages": todavía no se admite la búsqueda de usos de una variable de catálogo de versiones en otros archivos de compilación, ya sea que el archivo de compilación esté en KTS o Groovy. Es decir, si usas Control + clic (Comando + clic en macOS) en una definición de variable de un catálogo de versiones, no se generarán los archivos de compilación en los que se usa la variable.

  • En el diálogo Project Structure de Android Studio, se muestran varios archivos de catálogo que se encuentran en la carpeta raíz gradle, pero no los catálogos de una compilación compuesta. Por ejemplo, si tienes dos archivos de catálogo, uno para tu app y otro para una compilación compuesta, el diálogo Project Structure solo muestra el archivo del catálogo de la app. Puedes usar una compilación compuesta, pero debes editar su archivo TOML directamente.

Estadísticas adicionales de SDK: Problemas relacionados con las políticas

Android Studio muestra advertencias de lint en los archivos build.gradle.kts y build.gradle, y en el diálogo Project Structure para los SDKs públicos que tienen incumplimientos de la política de Play en el Índice SDK de Google Play. Debes actualizar todas las dependencias que incumplan las políticas de Play, ya que estos podrían impedir que publiques contenido en Google Play Console en el futuro. Las advertencias de incumplimiento de política complementan las advertencias de versiones desactualizadas que muestra Android Studio.

Compatibilidad con la versión de compileSdk de Android Studio

Android Studio muestra una advertencia si tu proyecto usa un compileSdk que no es compatible con la versión actual de Android Studio. Si está disponible, también sugiere cambiar a una versión de Android Studio que admita el compileSdk que usa tu proyecto. Ten en cuenta que es posible que, para actualizar Android Studio, también debas actualizar el AGP. AGP también muestra una advertencia en la ventana de herramientas Build si el compileSdk que usa tu proyecto no es compatible con la versión actual de AGP.

Cambios en el comportamiento de lint

A partir del complemento de Android para Gradle 8.3.0-alpha02, cuando se ejecuta lint en un módulo, se ejecutan tareas de análisis de lint independientes para los componentes principales y de prueba del módulo. El motivo de este cambio es mejorar el rendimiento. Para volver al comportamiento anterior, configura android.experimental.lint.analysisPerComponent=false en tu archivo gradle.properties.