Le plug-in Android Gradle est le système de compilation pris en charge par les applications Android. Il permet de compiler de nombreux types de sources différents et de les associer dans une application que vous pouvez exécuter sur un appareil Android physique ou un émulateur.
La section suivante décrit l'évolution prévue du DSL et de l'API du plug-in Android Gradle. À mesure que de nouvelles API seront introduites dans des versions stables, les anciennes seront marquées comme obsolètes. Ces API obsolètes deviendront alors indisponibles dans la prochaine version stable. Les sections suivantes fournissent des informations sur les modifications à venir dans chaque version majeure du plug-in Android Gradle.
Pour obtenir un journal plus détaillé des abandons ou des suppressions d'API dans le plug-in Android Gradle, consultez les mises à jour de l'API du plug-in Android Gradle.
AGP 10.0 (fin 2026)
Modifications et modernisation de l'API du plug-in Android Gradle 10.0
L'AGP 10.0 finalise la transition vers un modèle de compilation entièrement différé et compatible avec le cache de configuration. Cette version est le résultat d'un effort pluriannuel visant à remplacer les API héritées et non différées par une architecture plus sûre et plus performante.
Pourquoi un modèle de compilation différé ?
Dans l'ancien modèle de compilation non différé, Gradle évalue les objets, interroge les données de variante et configure les tâches dans tous les modules du projet lors de chaque synchronisation ou appel de compilation. Cette évaluation anticipée gaspille du temps CPU et de la mémoire sur les variantes et les tâches qui ne sont pas en cours d'exécution, et provoque des conflits d'ordre d'évaluation dans les scripts de compilation complexes.
En passant à un modèle de compilation entièrement différé à l'aide de fournisseurs différés
(Provider<T>) et de l'API Variant moderne (androidComponents {}), les propriétés
et le câblage des tâches sont calculés de manière différée à la demande uniquement lorsque le
graphique d'exécution de la compilation active en a besoin.
Les API héritées supprimées dans cette version étaient fondamentalement incompatibles avec cette architecture moderne. Leur suppression permet à l'AGP de prendre entièrement en charge le cache de configuration Gradle et l'isolation des projets, ce qui améliore considérablement les vitesses de compilation et les temps de synchronisation dans Android Studio.
Principale différence architecturale
L'ancienne API BaseVariant (applicationVariants.all {}) était anticipée et axée sur les tâches. Elle permettait aux développeurs d'accéder directement aux tâches Gradle et aux configurations internes pendant la phase de configuration, ce qui nuit intrinsèquement aux fonctionnalités de performances modernes de Gradle.
La nouvelle API Variant (androidComponents {}) est différée et axée sur les artefacts. Elle
utilise largement l'API Property de Gradle et supprime complètement toutes les références à
Task et TaskProvider, ce qui vous oblige à interagir de manière propre avec les entrées et les
sorties (Variant.artifacts) plutôt qu'avec les tâches sous-jacentes elles-mêmes.
Éléments supprimés et remplacés
Toutes les interfaces et classes précédentes utilisées dans l'ancien DSL et l'ancienne API Variant sont supprimées. Pour préparer vos scripts de compilation et vos plug-ins personnalisés, migrez à partir des API et des indicateurs suivants en fin de vie :
| API ou fonctionnalité supprimée | Remplacement ou action nécessaire |
|---|---|
Accès direct aux tâches :
|
API Artifacts : au lieu d'extraire la tâche pour
modifier son comportement, utilisez variant.artifacts pour
ajouter, modifier ou remplacer les fichiers réels (artefacts) qui passent entre les
tâches.
|
Enregistrement anticipé des sources :
|
API Sources : câblez le répertoire de sortie de votre tâche personnalisée à l'aide de variant.sources.java.addGeneratedSourceDirectory(...).
|
Accès au classpath / à la configuration :
|
API Instrumentation : pour modifier ou inspecter le bytecode
(cas d'utilisation le plus courant pour l'accès au classpath), utilisez
variant.instrumentation.transformClassesWith(...) à l'aide de
AsmClassVisitorFactory.
|
Mutation anticipée des propriétés :
|
Instances `MapProperty` différées : utilisez
variant.buildConfigFields.put(...) et
variant.manifestPlaceholders.put(...).
|
Indicateurs de désactivation :
|
Aucun remplacement direct. Supprimez ces indicateurs de
gradle.properties ; le DSL moderne et Kotlin intégré sont
strictement appliqués.
|
Extensions de l'ancienne API Variant :
|
Remplacez par androidComponents.onVariants(). |
Filtrage des variantes (bloc variantFilter) |
Remplacez par androidComponents.beforeVariants() à l'aide de
sélecteurs de variantes.
|
Composants SDK et NDK :
|
Accédez aux composants du SDK à l'aide de
androidComponents.sdkComponents.
|
Environnements de test :
|
Migrez l'enregistrement personnalisé des appareils de test vers les appareils gérés par Gradle. |
API d'enregistrement obsolètes :
|
Supprimées sans remplacement direct. |
| API Transform |
Remplacez les transformations par l'API Artifacts et
AsmClassVisitorFactory.
|
Pour accéder à toutes les interfaces et classes de remplacement du DSL et de l'API Variant (androidComponents {})
, utilisez toujours l'artefact gradle-api
lorsque vous développez des plug-ins Gradle personnalisés ou une logique de compilation.
Procédure de migration
Pour que votre mise à niveau vers l'AGP 10.0 soit transparente et prévisible, suivez ces pratiques de migration :
- Exécutez l'assistant de mise à niveau de l'AGP : avant de passer directement à la version 10.0, exécutez
l'assistant de mise à niveau officiel de l'AGP dans
Android Studio (
Tools > AGP Upgrade Assistant). Il automatise plusieurs migrations courantes de DSL et de scripts de compilation, et permet de préserver les comportements de compilation existants. - Utilisez les compétences du mode Agent dans Android Studio : profitez des compétences de mise à niveau de l'IA (telles que les compétences de mise à niveau de l'AGP disponibles dans le dépôt de compétences Android) pour automatiser et simplifier la migration de la logique de compilation et des DSL complexes dans Android Studio.
- Corrigez d'abord les avertissements d'abandon dans l'AGP 9.x : mettez à niveau votre projet vers la dernière version de l'AGP 9.x et résolvez tous les avertissements d'abandon existants. Une fois que votre projet fonctionne avec la version 9.x sans avertissement et sans dépendre de
android.newDsl=falseouandroid.builtInKotlin=false, la transition vers la version 10.0 sera fluide. - Vérifiez les plug-ins Gradle tiers : assurez-vous que les plug-ins tiers sont mis à niveau vers des versions compatibles avec l'AGP 10.0. Les plug-ins qui dépendent encore des types d'extension hérités entraîneront des échecs de compilation tels que
ClassCastException: ... cannot be cast to class BaseExtension. - Utilisez des recettes de migration officielles : pour obtenir des exemples de migration complexes et concrets ainsi que des comparaisons côte à côte, consultez le dépôt GitHub officiel gradle-recipes.
Voici une comparaison avant/après montrant comment migrer d'une requête anticipée des anciennes variantes vers une configuration différée des variantes à l'aide de androidComponents {} :
Avant : ancienne API Variant (supprimée dans l'AGP 10.0)
// Eager evaluation using the legacy Variant API
android {
applicationVariants.all { variant ->
if (variant.buildType.name == "release") {
// Eagerly queries and modifies properties during evaluation
}
}
}
Après : API Variant moderne (androidComponents {})
// Lazy, Configuration Cache compatible Variant API
androidComponents {
onVariants(selector().withBuildType("release")) { variant ->
// Safely and lazily configures properties
}
}
Comment tester le comportement de l'AGP 10.0 dans l'AGP 9.x
Vous n'avez pas besoin d'attendre la sortie de l'AGP 10.0 pour commencer à tester ses comportements de compilation et à valider la compatibilité. Lorsque vous exécutez une version de l'AGP 9.x, vous pouvez appliquer explicitement le comportement de l'AGP 10.0 en vérifiant que votre gradle.properties désactive toutes les désactivations et définit les indicateurs de comportement strict suivants :
# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true
# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true
En appliquant android.newDsl=true et android.builtInKotlin=true, vous pouvez vérifier que votre logique de compilation personnalisée et vos plug-ins tiers sont entièrement compatibles avec les exigences strictes de l'API de l'AGP 10.0.
Désactivation sélective des sous-projets lors de la migration
Si vous souhaitez activer android.newDsl=true globalement dans votre projet pour tester les comportements modernes, mais que vous avez besoin de plus de temps pour migrer des sous-projets spécifiques, vous pouvez désactiver sélectivement des modules individuels à partir de l'AGP 9.4.0-alpha04.
Ajoutez android.newDsl.optOut à gradle.properties en spécifiant les chemins d'accès aux projets :
# Enable modern DSL globally across the build
android.newDsl=true
# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib
Désactivation sélective de Kotlin intégré par module
Si vous souhaitez activer Kotlin intégré globalement dans votre projet (android.builtInKotlin=true), mais que vous avez besoin de plus de temps pour migrer des sous-projets spécifiques à partir de kotlin-android (ou pour les modules sans code Kotlin), configurez ces modules au niveau du DSL plutôt qu'au niveau du projet. Définissez enableKotlin = false dans le fichier de compilation du module :
android {
enableKotlin = false
}
Workflow de commentaires et de signalement de bugs
Nous voulons nous assurer que la nouvelle API Variant est compatible avec les cas d'utilisation requis. Si vous rencontrez un obstacle lors de la migration à partir des anciennes API et que la nouvelle API Variant ne peut pas prendre en charge votre cas d'utilisation, procédez comme suit pour envoyer des commentaires :
- Vérifiez les éléments existants : commencez par consulter le bug de suivi global de l'API Variant de l'AGP 10.0 pour voir si votre blocage de migration est déjà connu, puis cliquez sur +1 pour le problème.
- Signalez les API manquantes : si votre cas d'utilisation est unique, envoyez une nouvelle demande de fonctionnalité à l'aide de notre modèle spécifique à l'AGP 10.0 afin que nous puissions examiner le problème et vous aider.
(Provisoire) L'accès aux classes internes privées du plug-in Android Gradle est supprimé
La dépendance à l'artefact gradle masque désormais toutes les classes internes
et n'accorde l'accès à la compilation qu'aux interfaces et aux classes
disponibles dans l'artefact gradle-api. Cela a un impact sur la compilation des plug-ins.
Il n'est pas possible d'ajouter manuellement une dépendance pour accéder aux classes internes.
AGP 9.0 (janvier 2026)
Les nouvelles API Variant sont stables, les anciennes API sont abandonnées
Les API Variant en phase d'incubation dans les versions 4.1 et 4.2 sont
stables et se trouvent dans l'gradle-api artefact. Les
interfaces et classes précédentes utilisées dans l'ancienne API Variant sont désormais
obsolètes et nécessitent une activation explicite pour être utilisées.
Les nouvelles interfaces DSL sont stables, les anciennes sont abandonnées
Les interfaces DSL en phase d'incubation dans les versions 4.1, 4.2 et
7.0 sont désormais stables et se trouvent dans l'artefact gradle-api. Les interfaces et classes précédentes utilisées dans le DSL sont désormais obsolètes et nécessitent une activation explicite pour être utilisées.
Les classes internes privées du plug-in Android Gradle restent accessibles
Les classes internes privées du plug-in Android Gradle, situées dans d'autres artefacts, sont toujours accessibles lors de la compilation des fichiers de version et des plug-ins, mais nous vous déconseillons de les utiliser, car elles peuvent changer de façon brutale à tout moment.