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
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 l'aboutissement d'un effort pluriannuel visant à remplacer les anciennes API non lazy par une architecture plus sûre et plus performante.
Pourquoi un modèle de compilation différée ?
Dans l'ancien modèle de compilation non différée, Gradle évalue les objets de manière anticipée, interroge les données de variantes et configure les tâches dans tous les modules du projet lors de chaque invocation de synchronisation ou de compilation. Cette évaluation anticipée gaspille du temps de processeur et de la mémoire sur des variantes et des 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 compilation actif en a besoin.
Les anciennes API supprimées dans cette version étaient fondamentalement incompatibles avec cette architecture moderne. Leur suppression permet à AGP de prendre entièrement en charge le cache de configuration Gradle et l'isolation des projets, ce qui améliore considérablement la vitesse de compilation et les temps de synchronisation dans Android Studio.
La principale différence architecturale
L'ancienne API BaseVariant (applicationVariants.all {}) était axée sur les tâches et les requêtes. Il permettait aux développeurs d'accéder directement aux tâches Gradle et aux configurations internes pendant la phase de configuration, ce qui enfreint intrinsèquement les fonctionnalités de performances Gradle modernes.
La nouvelle API Variant (androidComponents {}) est différée et axée sur les artefacts. Il utilise largement l'API Property de Gradle et supprime complètement toutes les références à Task et TaskProvider, ce qui vous oblige à interagir proprement 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 depuis les API et les indicateurs suivants qui ne sont plus disponibles :
| API ou fonctionnalité supprimée | Remplacement ou action requise |
|---|---|
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 d'une tâche à l'autre.
|
Enregistrement de la source eager :
|
API Sources : connectez le répertoire de sortie de votre tâche personnalisée à l'aide de variant.sources.java.addGeneratedSourceDirectory(...).
|
Accès au chemin de classe / à 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(...) avec AsmClassVisitorFactory.
|
Mutation de propriété eager :
|
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 langage DSL moderne et Kotlin intégré sont strictement appliqués.
|
Anciennes extensions de l'API Variant :
|
Remplacer par androidComponents.onVariants(). |
Filtrage des variantes (bloc variantFilter) |
Remplacez par androidComponents.beforeVariants() à l'aide de sélecteurs de variantes.
|
Composants du SDK et du NDK :
|
Accédez aux composants du SDK à l'aide de androidComponents.sdkComponents.
|
Environnements de test :
|
Migrez l'enregistrement des appareils de test personnalisés vers les appareils gérés par Gradle. |
API d'enregistrement obsolètes :
|
Supprimé 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 migration vers AGP 10.0 se déroule de manière fluide et prévisible, suivez ces pratiques de migration :
- Exécutez l'assistant de mise à niveau AGP : avant de passer directement à la version 10.0, exécutez l'assistant de mise à niveau AGP officiel 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. - Utiliser les compétences du mode Agent dans Android Studio : profitez des compétences de mise à niveau de l'IA (comme les compétences de mise à niveau 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 de dépréciation dans AGP 9.x : mettez à niveau votre projet vers la dernière version AGP 9.x et résolvez tous les avertissements de dépréciation existants. Une fois que votre projet fonctionne avec la version 9.x sans avertissement et sans s'appuyer sur
android.newDsl=falseniandroid.builtInKotlin=false, la transition vers la version 10.0 se fera en douceur. - Auditez les plug-ins Gradle tiers : assurez-vous que les plug-ins tiers sont mis à niveau vers des versions compatibles avec AGP 10.0. Les plug-ins qui s'appuient encore sur d'anciens types d'extensions entraîneront des échecs de compilation tels que
ClassCastException: ... cannot be cast to class BaseExtension. - Utilisez les recettes de migration officielles : pour des exemples de migration complexes et concrets, ainsi que des comparaisons côte à côte, consultez le dépôt GitHub gradle-recipes officiel.
Voici une comparaison avant/après montrant comment migrer des variantes héritées avec requête différée vers la configuration différée des variantes à l'aide de androidComponents {} :
Avant : ancienne API Variant (supprimée dans 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
}
}
Tester le comportement d'AGP 10.0 dans AGP 9.x
Vous n'avez pas besoin d'attendre la sortie d'AGP 10.0 pour commencer à tester ses comportements de compilation et valider la compatibilité. Lorsque vous exécutez une version AGP 9.x, vous pouvez appliquer explicitement le comportement 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 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 d'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 hors 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 variante d'API est compatible avec vos cas d'utilisation. Si vous rencontrez un problème lors de la migration depuis les anciennes API et que la nouvelle API Variant ne peut pas s'adapter à votre cas d'utilisation, suivez ces étapes pour nous faire part de vos commentaires :
- Vérifiez les éléments existants : commencez par consulter le bug de suivi global de l'API Variant AGP 10.0 pour voir si votre problème bloquant la migration est déjà connu, puis cliquez sur le bouton +1.
- Signaler des API manquantes : si votre cas d'utilisation est unique, déposez une demande de fonctionnalité à l'aide de notre modèle d'API Variant spécifique afin que nous puissions examiner votre demande 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 concerne 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'artefact gradle-api. 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 compilation et des plug-ins, mais nous vous déconseillons de les utiliser, car elles peuvent changer de façon brutale à tout moment.