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

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 para Android 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.

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:

• Cómo configurar tu compilación
• Referencia del DSL del complemento de Android para Gradle
• Referencia del DSL de Gradle
• Guía del usuario sobre el rendimiento de Gradle

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.1.0 del archivo build.gradle.kts:

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

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

Precaución: No debes usar dependencias dinámicas en los números de versión, como 'com.android.tools.build:gradle:2.+'. El uso de esa función puede causar 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.

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.1 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.1

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.1 en el archivo gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.1-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.

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. Te recomendamos que uses la versión preliminar más reciente de Android Studio y AGP para trabajar en proyectos que se orienten 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:

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.

8.1.0 (julio de 2023)

El complemento de Android para Gradle 8.1.0 es una actualización importante que incluye una variedad de nuevas funciones y mejoras.

Compatibilidad

DSL de Kotlin es la opción predeterminada para la configuración de compilación

Los proyectos nuevos ahora usan la DSL de Kotlin (build.gradle.kts) de forma predeterminada para la configuración de compilación. Esto ofrece una mejor experiencia de edición que la DSL de Groovy (build.gradle) con resaltado de sintaxis, finalización de código y navegación a declaraciones. Ten en cuenta que, si usas AGP 8.1 y el DSL de Kotlin para configurar la compilación, debes usar Gradle 8.1 a fin de obtener la mejor experiencia. Para obtener más información, consulta la guía de migración de DSL de Kotlin.

Compatibilidad automática con idiomas de las apps

A partir de Android Studio Giraffe Canary 7 y AGP 8.1.0-alpha07, puedes configurar tu app para que admita automáticamente las preferencias de idioma de las apps. En función de los recursos de tu proyecto, el complemento de Android para Gradle genera el archivo LocaleConfig y agrega una referencia a él en el archivo de manifiesto final, de modo que ya no tengas que hacerlo de forma manual. AGP usa los recursos en las carpetas res de los módulos de tu app y las dependencias de módulos de biblioteca para determinar las configuraciones regionales que se incluirán en el archivo LocaleConfig.

Ten en cuenta que la función automática de idioma de las apps admite apps que ejecutan Android 13 (nivel de API 33) o versiones posteriores. Para usar la función, debes establecer compileSdkVersion en 33 o un valor superior. Para configurar las preferencias de idioma de las apps en versiones anteriores de Android, debes usar las APIs y los selectores de idioma integrados en la app.

Para habilitar la compatibilidad automática de idiomas de las apps, especifica una configuración regional predeterminada:

1. En la carpeta res del módulo de la app, crea un archivo nuevo llamado resources.properties.

2. En el archivo resources.properties, establece la configuración regional predeterminada con la etiqueta unqualifiedResLocale. Para formar los nombres de configuración regional, combina el código de idioma con la secuencia de comandos opcional y los códigos regionales, y separa cada uno con un guion:

   • Idioma: Usa el código ISO 639-1 de dos o tres letras.
   • Secuencia de comandos (opcional): Usa el código ISO 15924.
   • Región (opcional): Usa el código ISO 3166-1-alpha-2 de dos letras o el código UN_M.49 de tres dígitos.

   Por ejemplo, si tu configuración regional predeterminada es Inglés (Estados Unidos):

       unqualifiedResLocale=en-US
       

AGP agrega esta configuración regional predeterminada y todas las configuraciones regionales alternativas que especificaste, con directorios values-* en la carpeta res, al archivo LocaleConfig generado automáticamente.

La compatibilidad automática de idiomas de las apps está desactivada de forma predeterminada. Para activar la función, usa la configuración generateLocaleConfig en el bloque androidResources {} del archivo build.gradle.kts a nivel del módulo (archivo build.gradle si usas Groovy):

android {
  androidResources {
    generateLocaleConfig = true
  }
}

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android Lint contiene código de bytes orientado a JVM 17

A partir de AGP 8.1.0-alpha04, Android Lint incluye código de bytes orientado a JVM 17. Si escribes comprobaciones de lint personalizadas, debes compilar con JDK 17 o versiones posteriores y especificar jvmTarget = '17' en las opciones del compilador de Kotlin.

Para obtener más información sobre la herramienta lint, consulta Cómo mejorar tu código con controles de lint.

Se movió la configuración de compresión de la biblioteca nativa a DSL

A partir de AGP 8.1.0-alpha10, recibirás una advertencia si no configuras la compresión de bibliotecas nativas usando el DSL en lugar del manifiesto. En la siguiente guía, se explica cómo actualizar tu configuración para usar el DSL. Para obtener ayuda para realizar estas actualizaciones, usa el Asistente de actualización del AGP (Herramientas > Asistente de actualización del AGP).

Para usar bibliotecas nativas sin comprimir, quita el atributo android::extractNativeLibs del manifiesto y agrega el siguiente código al archivo build.gradle.kts a nivel del módulo (archivo build.gradle si usas Groovy):

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

Marcas de compilación experimentales

Estas son marcas experimentales para configurar tu compilación disponibles en AGP 8.1.