Cómo usar el Asistente de actualización del complemento de Android para Gradle

El Asistente de actualización del complemento de Android para Gradle (AGP) es una herramienta de Android Studio que te ayuda a actualizar la versión de AGP que usa tu proyecto.

Publicamos de manera regular los cambios del AGP relacionados con funciones nuevas para configurar compilaciones, nuevas API para usar con otros complementos para Gradle y perfeccionamiento de la integración de compilaciones con Android Studio. Actualizar la versión del AGP que usa tu proyecto te permite beneficiarte con las funciones más recientes.

¿Para qué se usa el Asistente de actualización del AGP?

El Asistente de actualización del AGP te ayuda a realizar los cambios necesarios para actualizar las versiones del AGP. Estos son sus casos de uso más comunes:

  • Cambios de sintaxis: El Asistente de actualización intenta traducir los archivos de tu compilación de una versión anterior del AGP a aquellos que requiere una versión posterior. A medida que desarrollamos el AGP, actualizamos los archivos de compilación para que admitan interfaces, ya que estos se reemplazan, se vuelven obsoletos o dejan de admitirse con el tiempo.

  • Requisitos de compatibilidad entre el AGP y Gradle: El Asistente de actualización conoce los requisitos de compatibilidad entre el AGP y Gradle, y ayuda a garantizar que uses la versión de Gradle que requiere tu versión del AGP.

  • Requisitos de compatibilidad entre el AGP y los complementos para Gradle de terceros: El Asistente de actualización conoce los requisitos de compatibilidad entre el AGP y algunos complementos para Gradle de terceros, y ayuda a garantizar que uses las versiones de complementos para Gradle de terceros que requiere tu versión del AGP.

En general, el Asistente de actualización tiene como objetivo reducir en parte la necesidad de realizar cambios de prueba y error en los archivos de compilación, o bien deducir el significado de los mensajes de error después de la actualización, y también explica por qué los cambios que propone son necesarios.

Cómo usar el Asistente de actualización del AGP

Para usar el Asistente de actualización, asegúrate de que la estructura del proyecto sea compatible y, luego, ejecútalo desde Android Studio como se describe a continuación.

Configuración

Antes de ejecutar el Asistente de actualización, asegúrate de que tu proyecto tenga el formato correcto y realiza una copia de seguridad.

Estructura tu proyecto con archivos de compilación de Gradle y lenguaje específico del dominio

El Asistente de actualización del AGP funcionará mejor si haces lo siguiente:

  • Configurar la compilación con los archivos de compilación de Gradle: El Asistente de actualización se basa en el análisis estático de los archivos de compilación de Gradle. Para aprovecharlo al máximo, debes configurar tu compilación usando esos archivos. Ten en cuenta que el Asistente de actualización no admite proyectos que usen buildSrc para definir las constantes y variables usadas en los archivos de compilación. En general, no recomendamos usar buildSrc para estructurar un proyecto, ya que puede ser ineficiente: cualquier cambio en las constantes y variables de buildSrc, sin importar qué tan pequeño sea, activa un recompilación del proyecto.
  • Usar el lenguaje de compilación declarativo específico del dominio: Los archivos de compilación de Gradle se expresan en lenguajes de programación completos, Groovy y/o Kotlin. Sin embargo, cuanto más declarativa sea la expresión de la configuración del proyecto, más probable es que el Asistente de actualización encuentre correctamente todos los puntos que requieran ajustes para una actualización.

Incluso si un proyecto no se ejecuta en función de estas limitaciones, es posible que el Asistente de actualización no realice una actualización limpia. En la sección Solución de problemas, puedes obtener ayuda para resolver o informar errores.

Crea una copia de seguridad de tu proyecto

Antes de comenzar a usar el Asistente de actualización, te recomendamos que tu proyecto no tenga cambios sin confirmar tal como los ve tu sistema de control de versión. Si no usas un control de versión, te sugerimos que realices una copia de seguridad de una última versión buena conocida en ese momento.

Una vez que ejecutes el Asistente de actualización y se compile y pruebe correctamente el proyecto, podrás confirmar la versión nueva del proyecto en tu sistema de control de versión.

Ejecuta el Asistente de actualización

Para ejecutar el Asistente de actualización, sigue estos pasos:

  1. Inicia el Asistente de actualización desde el mensaje de notificación o navega a Tools > AGP Upgrade Assistant… En la ventana de herramientas que aparece, se muestran los detalles de la actualización predeterminada de la versión actual del AGP del proyecto a la versión más reciente compatible con esta versión de Android Studio.
La ventana de herramientas del Asistente de actualización del AGP durante el inicio y el mensaje notificación.
Figura 1: Ventana de herramientas del Asistente de actualización del AGP durante el inicio y el mensaje notificación
  1. Verifica los pasos obligatorios y los recomendados. En el panel de la izquierda, hay un árbol con casillas de verificación que detalla los pasos individuales de la actualización, divididos por obligatorios y recomendados, y en función de si son requisitos previos para otros pasos. Selecciona elementos individuales en el árbol para ver más detalles sobre cada paso en el panel principal.

  2. Ejecuta la actualización. Para ello, selecciona los pasos necesarios o deseados y haz clic en Run selected steps. El Asistente de actualización realizará cambios en los archivos de compilación del proyecto y tratará de sincronizar la nueva compilación del proyecto con Android Studio. Esto puede demorar un tiempo si tienes muchos módulos, ya que es posible que debas descargar nuevas versiones de complementos y bibliotecas.

  3. Una vez que el proyecto se sincronice correctamente con Android Studio, compílalo y ejecuta conjuntos de pruebas para verificar que la operación de actualización no haya cambiado ninguna funcionalidad.

  4. Una vez que hayas verificado que tu proyecto se encuentra en buen estado, confirma la versión nueva del proyecto en tu sistema de control de versión.

Solución de problemas

Si el Asistente de actualización ofrece una actualización, pero esta falla (generalmente, porque se realizan cambios en los archivos de compilación que generan un error de sincronización), puedes seguir algunos pasos para aislar y corregir el error.

  • Primero, inspecciona el error que produjo la falla de sincronización. A veces, el error tiene una causa clara, que puedes resolver en los archivos de compilación del proyecto.

  • Si el mensaje de error no es claro o no es evidente cuál es la causa del problema, es hora de revertir el proyecto a su estado original para dividir la actualización en pasos más pequeños. Restablece el estado original del control de versión o de las copias de seguridad y asegúrate de que el proyecto (en su estado original) se vuelva a sincronizar con Android Studio. Luego, puedes investigar usando los dos siguientes tipos de desgloses de actualización:

    • Actualiza a una versión del AGP que no sea la más reciente. Si la actualización que salió mal fue la de una gran cantidad de versiones, la mejor manera de progresar y aislar el problema es realizar una serie de actualizaciones más pequeñas, de una versión a otra, para encontrar la primera actualización que genera el problema.
    • Dentro de una actualización, realiza los pasos individuales. Una vez que encuentres entre las sucesivas versiones del AGP una actualización que genere el problema, tal vez puedas desactivar sus pasos individuales. En ese caso, intenta seguirla paso por paso para ver cuál de todos es el responsable. Si no encuentras el paso responsable, te recomendamos que consultes las notas de la versión de otros complementos de Gradle que uses en busca de problemas de compatibilidad con Gradle o el AGP. En ocasiones, habrá una nueva versión para resolver el uso de API obsoletas o internas.
  • Informa un error. A veces, todos los pasos preparatorios y la sincronización se ejecutan de forma correcta, pero falla el paso de actualización final. En ese caso, informa un error.

Incluso si logras corregir el error por tu cuenta, informa el error original en la herramienta de seguimiento de errores para que el equipo de desarrollo pueda resolverlo.