L'assistant de mise à niveau du plug-in Android Gradle (AGP) est un outil dans Android Studio qui vous aide à mettre à niveau la version d'AGP utilisée par votre projet.
De nouvelles versions d'AGP sont publiées régulièrement pour inclure de nouvelles fonctionnalités permettant de configurer votre build, de développer de nouvelles API compatibles avec d'autres plug-ins Gradle et d'affiner l'intégration du projet avec Android Studio. La mise à niveau de la version d'AGP utilisée par votre projet vous permet de bénéficier des dernières fonctionnalités.
Pour en savoir plus sur la structure de projet recommandée pour l'assistant de mise à niveau, consultez la section Configuration de cette page.
Cas d'utilisation de l'assistant de mise à niveau AGP
L'assistant de mise à niveau AGP vous guide pour effectuer les modifications nécessaires à la mise à niveau des versions AGP. Voici ses cas d'utilisation les plus courants :
Modifications de syntaxe : l'assistant de mise à niveau tâche de convertir vos fichiers de compilation créés dans une ancienne version d'AGP en fichiers adaptés à une version plus récente du plug-in. Au fur et à mesure du développement d'AGP, les fichiers de compilation sont mis à jour pour prendre en charge les interfaces qui sont remplacées, obsolètes ou non compatibles avec le temps.
Exigences de compatibilité entre AGP et Gradle : l'assistant de mise à niveau connaît les exigences de compatibilité entre AGP et Gradle et s'assure que vous utilisez la version de Gradle requise pour votre version d'AGP.
Exigences de compatibilité entre AGP et les plug-ins Gradle tiers : l'assistant de mise à niveau connaît les exigences de compatibilité entre AGP et certains plug-ins Gradle tiers, et s'assure que vous utilisez des versions de plug-ins Gradle tiers compatibles avec votre version d'AGP.
En général, l'assistant de mise à niveau facilite la mise à jour des fichiers de compilation et la compréhension des messages d'erreur associés après une mise à niveau AGP. L'assistant de mise à niveau explique également pourquoi les modifications proposées sont nécessaires.
Utiliser l'assistant de mise à niveau AGP
Pour utiliser l'assistant de mise à niveau, assurez-vous que la structure de votre projet le permet, puis exécutez-le à partir d'Android Studio, comme décrit dans la section Exécuter l'assistant de mise à niveau.
Configurer votre projet
Avant d'exécuter l'assistant de mise à niveau, assurez-vous que votre projet est correctement formaté et sauvegardé. Pour vous assurer que l'assistant de mise à niveau AGP est bien configuré, lisez les sections qui suivent.
Structurer votre projet à l'aide des fichiers de compilation Gradle et du langage spécifique au domaine
Pour profiter au mieux de l'Assistant AGP :
- Configurez le build à l'aide des fichiers de compilation Gradle : l'assistant de mise à niveau repose sur une analyse statique des fichiers de compilation Gradle. Pour exploiter au mieux l'assistant de mise à niveau, configurez votre build à l'aide de ces fichiers de compilation.
- Utilisez le langage assertif de compilation propre au domaine : les fichiers de compilation Gradle sont exprimés dans Groovy ou Kotlin. Toutefois, plus l'expression de la configuration du projet est assertive, plus il y a de chances que l'assistant de mise à niveau trouve correctement tous les emplacements qui nécessitent à ajuster en vue d'une mise à niveau.
Même si un projet ne se heurte pas à ces restrictions, l'assistant de mise à niveau peut tout de même échouer à procéder correctement. Consultez la page Résoudre les erreurs pour savoir comment résoudre ou signaler des bugs.
Sauvegarder votre projet
Avant d'utiliser l'assistant de mise à niveau, nous vous recommandons de ne pas laisser de modifications non enregistrées dans votre projet (elles sont indiquées dans le système de contrôle des versions). Si vous n'utilisez pas le contrôle des versions, utilisez une sauvegarde d'une des dernières versions satisfaisants disponibles.
Une fois que l'assistant de mise à niveau a été exécuté et que le projet a été correctement créé et testé, vous pouvez valider la nouvelle version du projet dans votre système de contrôle des versions.
Exécuter l'assistant de mise à niveau
Pour exécuter l'assistant de mise à niveau, procédez comme suit :
Pour lancer l'assistant de mise à niveau, accédez à Tools > AGP Upgrade Assistant (Outils > Assistant de mise à niveau AGP) ou cliquez sur l'invite de notification, comme illustré à la figure 1.
La fenêtre d'outil qui s'affiche affiche les détails de la mise à niveau par défaut, y compris la version actuelle d'AGP du projet et la dernière version compatible avec cette version d'Android Studio.
Figure 1. Fenêtre de l'assistant de mise à niveau AGP lancée et invite de notification. Vérifiez les étapes obligatoires et recommandées.
Dans le panneau de gauche, l'arborescence comporte des cases à cocher permettant de détailler les étapes individuelles de la mise à niveau, classées selon qu'elles sont requises ou recommandées pour la mise à niveau et selon qu'elles sont nécessaires ou non pour d'autres étapes. Sélectionnez des éléments individuels dans l'arborescence pour afficher plus de détails concernant chaque étape dans le panneau principal.
Pour exécuter la mise à niveau, sélectionnez les étapes requises et souhaitées, puis cliquez sur Run selected steps (Exécuter les étapes sélectionnées).
L'assistant de mise à niveau modifie les fichiers de compilation du projet et tente de synchroniser la nouvelle compilation du projet avec Android Studio. Cette opération peut prendre un certain temps si vous disposez de nombreux modules, car vous devrez peut-être télécharger de nouvelles versions de plug-ins et de bibliothèques.
Examinez le rapport post-mise à niveau. Ce rapport décrit les étapes effectuées et indique si la mise à niveau a réussi ou échoué. Il inclut également une action d'annulation des modifications apportées par l'assistant de mise à niveau en cas de problèmes lors des étapes de compilation ou de test du projet après la mise à niveau.
Une fois le projet synchronisé avec Android Studio, créez le projet et exécutez des suites de tests pour vérifier que la mise à niveau n'a modifié aucune fonctionnalité.
Une fois que vous avez vérifié le bon état de votre projet, validez la nouvelle version de votre projet sur votre système de contrôle des versions.
Résoudre les erreurs
Si l'assistant de mise à niveau propose une mise à niveau, mais que celle-ci échoue, cela provient généralement des modifications des fichiers de compilation, ce qui entraîne un échec de synchronisation. Pour isoler l'erreur et la corriger, procédez comme suit :
Commencez par inspecter l'erreur qui a causé l'échec de la synchronisation. La cause de l'erreur peut parfois être claire et vous pouvez la corriger dans les fichiers de compilation du projet.
Si le message d'erreur n'est pas clair ou si vous ne parvenez pas à identifier la cause du problème, restaurez le projet à son état d'origine pour décomposer la mise à niveau en plus petites étapes. Restaurez l'état d'origine à partir du contrôle des versions ou à partir de sauvegardes et assurez-vous que le projet est dans son état d'origine et synchronisé avec Android Studio.
Examinez l'erreur en étudiant deux types de répartition de la mise à niveau :
Passez à une autre version d'AGP, antérieure à la dernière. Si la mise à niveau d'un grand nombre de versions ne fonctionne pas correctement, le meilleur moyen d'isoler le problème consiste à effectuer une série de mises à niveau plus petites, d'une version à la suivante, afin de trouver la première mise à niveau défectueuse.
Suivez les étapes une par une lors des mises à niveau. Une fois que vous avez trouvé la mise à niveau défectueuse, il peut être possible de désactiver individuellement les étapes de la mise à niveau. Si c'est le cas, essayez de réaliser chaque étape une par une pour identifier celle qui est responsable du problème. Si vous ne trouvez pas l'étape responsable, consultez les notes de version des autres plug-ins Gradle que vous utilisez pour résoudre les problèmes de compatibilité avec Gradle ou AGP. Parfois, une nouvelle version traite de l'utilisation d'API internes ou obsolètes.
Signalez un bug. Parfois, toutes les étapes préparatoires et la synchronisation réussissent, mais la dernière étape de la mise à niveau échoue. Dans ce cas, veuillez signaler un bug. Même si vous parvenez à corriger l'erreur vous-même, signalez l'erreur d'origine à l'outil de suivi des bugs pour que l'équipe de développement puisse le résoudre.