Notes de version de l'aperçu du plug-in Android Gradle

Cette page contient les notes de version des versions Preview du plug-in Android Gradle (AGP).

Plug-in Android Gradle 9.0

Le plug-in Android Gradle 9.0 est une nouvelle version majeure d'AGP qui apporte des modifications à l'API et au comportement.

Pour passer au plug-in Android Gradle 9.0.0-beta04, utilisez l'assistant de mise à niveau du plug-in Android Gradle dans Android Studio Otter 3 Feature Drop | 2025.2.3.

L'assistant de mise à niveau AGP vous aide à préserver les comportements existants lors de la mise à niveau de votre projet, le cas échéant. Vous pouvez ainsi mettre à niveau votre projet pour utiliser AGP 9.0, même si vous n'êtes pas prêt à adopter toutes les nouvelles valeurs par défaut d'AGP 9.0.

Compatibilité

Le niveau d'API Android maximal compatible avec le plug-in Android Gradle 9.0.0-beta04 est le niveau d'API 36.

Le plug-in Android Gradle 9.0.0-beta04 nécessite Gradle 9.0.0.

Les classes DSL android n'implémentent désormais que les nouvelles interfaces publiques.

Au cours des dernières années, nous avons introduit de nouvelles interfaces pour notre DSL et notre API afin de mieux contrôler les API publiques. Les versions 7.x et 8.x d'AGP utilisaient encore les anciens types DSL (par exemple, BaseExtension), qui implémentaient également les nouvelles interfaces publiques, afin de maintenir la compatibilité à mesure que les interfaces étaient développées.

AGP 9.0 utilise exclusivement nos nouvelles interfaces DSL, et les implémentations ont été remplacées par de nouveaux types entièrement masqués. Cela supprime également l'accès à l'ancienne API Variant obsolète.

Pour passer à AGP 9.0, vous devrez peut-être effectuer les opérations suivantes :

• Assurez-vous que votre projet est compatible avec Kotlin intégré : le plug-in org.jetbrains.kotlin.android n'est pas compatible avec le nouveau DSL.

• Migrez les projets KMP vers le plug-in Android Gradle Library pour KMP : l'utilisation du plug-in org.jetbrains.kotlin.multiplatform dans le même sous-projet Gradle que les plug-ins com.android.library et com.android.application n'est pas compatible avec le nouveau DSL.

• Mettez à jour vos fichiers de compilation : bien que le changement d'interfaces soit destiné à maintenir le DSL aussi similaire que possible, il peut y avoir quelques petites modifications.

• Mettez à jour votre logique de compilation personnalisée pour référencer le nouveau DSL et la nouvelle API : remplacez toutes les références au DSL interne par les interfaces DSL publiques. Dans la plupart des cas, il s'agit d'un remplacement à l'identique. Remplacez toute utilisation de l'API applicationVariants et des API similaires par la nouvelle API androidComponents. Cela peut être plus complexe, car l'API androidComponents est conçue pour être plus stable afin de maintenir la compatibilité des plug-ins plus longtemps. Pour obtenir des exemples, consultez nos recettes Gradle.

• Mettez à jour les plug-ins tiers : certains plug-ins tiers peuvent encore dépendre d'interfaces ou d'API qui ne sont plus exposées. Migrez vers des versions de ces plug-ins compatibles avec AGP 9.0.

Le passage aux nouvelles interfaces DSL empêche les plug-ins et les scripts de compilation Gradle d'utiliser diverses API obsolètes, y compris :

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

Si vous passez à AGP 9.0 et que le message d'erreur suivant s'affiche, cela signifie que votre projet fait toujours référence à certains des anciens types :

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Si vous êtes bloqué par des plug-ins tiers incompatibles, vous pouvez désactiver les nouvelles implémentations et revenir aux anciennes pour le DSL et l'ancienne API de variante. Pendant ce temps, les nouvelles interfaces sont également disponibles et vous pouvez toujours mettre à jour votre propre logique de compilation vers la nouvelle API. Pour désactiver le cookie, ajoutez la ligne suivante à votre fichier gradle.properties :

android.newDsl=false

Vous pouvez également commencer à migrer vers les nouvelles API avant de passer à AGP 9.0. Les nouvelles interfaces sont présentes depuis de nombreuses versions d'AGP. Vous pouvez donc avoir un mélange d'anciennes et de nouvelles interfaces. La documentation de référence de l'API AGP présente la surface de l'API pour chaque version d'AGP, ainsi que la date d'ajout de chaque classe, méthode et champ.

Au cours de la phase alpha 9.0, nous contacterons les auteurs de plug-ins pour les aider à adapter et à publier des plug-ins entièrement compatibles avec les nouveaux modes. Nous améliorerons également l'assistant de mise à niveau AGP dans Android Studio pour vous guider tout au long de la migration.

Si vous constatez que le nouveau DSL ou l'API Variant manquent de fonctionnalités, veuillez signaler un problème dès que possible.

Kotlin intégré

Le plug-in Android Gradle 9.0 introduit la prise en charge intégrée de Kotlin et l'active par défaut. Cela signifie que vous n'avez plus besoin d'appliquer le plug-in org.jetbrains.kotlin.android (ou kotlin-android) dans vos fichiers de compilation pour compiler les fichiers sources Kotlin. Cela simplifie l'intégration de Kotlin avec AGP, évite l'utilisation d'API obsolètes et améliore les performances dans certains cas.

Par conséquent, lorsque vous mettez à niveau votre projet vers AGP 9.0, vous devez également migrer vers Kotlin intégré ou désactiver cette fonctionnalité.

Vous pouvez également désactiver sélectivement la prise en charge intégrée de Kotlin pour les sous-projets Gradle qui ne comportent pas de sources Kotlin.

Dépendance d'exécution sur le plug-in Gradle de Kotlin

Pour fournir une prise en charge intégrée de Kotlin, le plug-in Android Gradle 9.0 dispose désormais d'une dépendance d'exécution sur le plug-in Kotlin Gradle (KGP) 2.2.10. Cela signifie que vous n'avez plus besoin de déclarer une version KGP. Si vous utilisez une version KGP antérieure à 2.2.10, Gradle mettra automatiquement à niveau votre version KGP vers la version 2.2.10. De même, si vous utilisez une version KSP antérieure à 2.2.10-2.0.2, AGP la mettra à niveau vers la version 2.2.10-2.0.2 pour qu'elle corresponde à la version KGP.

Passer à une version KGP supérieure

Pour utiliser une version supérieure de KGP ou KSP, ajoutez ce qui suit à votre fichier de compilation de premier niveau :

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

Revenir à une version KGP antérieure

Vous ne pouvez rétrograder la version de KGP que si vous avez désactivé Kotlin intégré. En effet, AGP 9.0 active Kotlin intégré par défaut, et Kotlin intégré nécessite KGP 2.2.10 ou version ultérieure.

Pour utiliser une version antérieure de KGP ou KSP, déclarez cette version dans votre fichier de compilation de premier niveau à l'aide d'une déclaration de version stricte :

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

Notez que la version minimale de KGP à laquelle vous pouvez revenir est la version 2.0.0.

Compatibilité des IDE avec les outils de test

AGP 9.0 est entièrement compatible avec l'IDE Android Studio pour les fixtures de test.

Plug-in de la bibliothèque fusionnée

Le plug-in Fused Library (Preview) vous permet de publier plusieurs bibliothèques sous forme d'un seul fichier AAR de bibliothèque Android. Cela peut permettre à vos utilisateurs de s'appuyer plus facilement sur vos artefacts publiés.

Pour savoir comment vous lancer, consultez Publier plusieurs bibliothèques Android en une seule avec la bibliothèque fusionnée.

Changements de comportement

Le plug-in Android Gradle 9.0 présente les nouveaux comportements suivants :

AGP 9.0 inclut des mises à jour des valeurs par défaut des propriétés Gradle suivantes. Vous avez ainsi le choix de conserver le comportement de l'AGP 8.13 lors de la mise à niveau :

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Fonctionnalités supprimées

Le plug-in Android Gradle 9.0 supprime les fonctionnalités suivantes :

• Compatibilité avec les applications Wear OS intégrées
  AGP 9.0 supprime la compatibilité avec l'intégration des applications Wear OS, qui n'est plus prise en charge dans Play. Cela inclut la suppression des configurations wearApp et du DSL AndroidSourceSet.wearAppConfigurationName. Pour savoir comment publier votre application sur Wear OS, consultez Distribuer votre application sur Wear OS.
• Tâche de création de rapports androidDependencies et sourceSets
• Prise en charge des APK divisés en fonction de la densité
  AGP 9.0 ne permet plus de créer des APK divisés en fonction de la densité de l'écran. La fonctionnalité et les API associées ont été supprimées. Pour fractionner les APK en fonction de la densité d'écran à l'aide d'AGP 9.0 ou version ultérieure, utilisez les app bundles.

DSL modifié

Le plug-in Android Gradle 9.0 présente les modifications importantes suivantes dans le DSL :

• La paramétrisation de CommonExtension a été supprimée.

  En soi, il s'agit uniquement d'un changement cassant au niveau de la source pour éviter de futurs changements cassants au niveau de la source, mais cela signifie également que les méthodes de blocage doivent passer de CommonExtension à ApplicationExtension, LibraryExtension, DynamicFeatureExtension et TestExtension.

  Lorsque vous mettez à niveau votre projet vers AGP 9.0, refactorisez le code du plug-in Gradle qui utilise ces paramètres ou les méthodes de bloc. Par exemple, le plug-in suivant est mis à jour pour supprimer le paramètre de type et ne pas s'appuyer sur les méthodes de bloc supprimées :

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  Pour les plug-ins qui ciblent une plage de versions AGP, l'utilisation directe du getter est compatible au niveau binaire avec les versions AGP antérieures à 9.0.

DSL supprimée

Le plug-in Android Gradle 9.0 supprime les éléments suivants :

• AndroidSourceSet.jni, car il ne fonctionnait pas.

• AndroidSourceSet.wearAppConfigurationName, en lien avec la suppression de la compatibilité avec l'application Wear OS intégrée.

• BuildType.isRenderscriptDebuggable, car il ne fonctionnait pas.

• DependencyVariantSelection a été remplacé par DependencySelection, qui est exposé en tant que kotlin.android.localDependencySelection.

• Installation.installOptions(String). Il est remplacé par la propriété mutable de Installation.installOptions.

• Bloc PostProcessing expérimental, mais jamais stabilisé.

• ProductFlavor.setDimension, qui est remplacé par la propriété dimension

• LanguageSplitOptions, qui n'était utile que pour Google Play Instant, qui est obsolète.

• DensitySplit, car la fonctionnalité n'est plus disponible. La solution consiste à utiliser des app bundles.

API supprimées

Le plug-in Android Gradle 9.0 supprime les éléments suivants :

• AndroidComponentsExtension.finalizeDSl a été remplacé par finalizeDsl.

• Component.transformClassesWith a été remplacé par Instrumentation.transformClassesWith.

• Component.setAsmFramesComputationMode a été remplacé par Instrumentation.setAsmFramesComputationMode.

• ComponentBuilder.enabled a été remplacé par ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk a été remplacé par includeInApk.

• DependenciesInfoBuilder.includedInBundle a été remplacé par includeInBundle.

• GeneratesApk.targetSdkVersion a été remplacé par targetSdk.

• Variant.minSdkVersion a été remplacé par minSdk.

• Variant.maxSdkVersion a été remplacé par maxSdk.

• Variant.targetSdkVersion a été remplacé par targetSdk.

• Variant.unitTest, car il ne s'appliquait pas au plug-in com.android.test. unitTest est disponible sur les sous-types VariantBuilder étendant HasUnitTest.

• VariantBuilder.targetSdk et targetSdkPreview, car ils n'avaient pas de sens dans les bibliothèques. Utilisez plutôt GeneratesApkBuilder.targetSdk ou GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, car il ne s'appliquait pas au plug-in com.android.test. enableUnitTest est disponible sur les sous-types VariantBuilder étendant HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled est supprimé au profit de enableUnitTest, dont le nom est plus cohérent, sur les sous-types VariantBuilder étendant HasUnitTestBuilder.

• VariantOutput.enable a été remplacé par enabled.

• FeaturePlugin et FeatureExtension, qui sont obsolètes et désactivés.

• Les API BaseExtension.registerTransform obsolètes et désactivées, qui n'étaient conservées que pour permettre la compilation avec la dernière version d'AGP tout en ciblant l'exécution sur AGP 4.2 ou version antérieure.

Propriétés Gradle supprimées

Les propriétés Gradle suivantes ont été ajoutées à l'origine pour désactiver globalement les fonctionnalités activées par défaut.

Ces fonctionnalités sont désactivées par défaut depuis AGP 8.0 ou version antérieure. Activez ces fonctionnalités uniquement dans les sous-projets qui les utilisent pour une compilation plus efficace.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Propriétés Gradle appliquées

AGP 9.0 génère une erreur si vous définissez les propriétés Gradle suivantes.

L'assistant de mise à niveau du plug-in Android Gradle ne mettra pas à niveau les projets vers AGP 9.0 qui utilisent ces propriétés.

Problèmes résolus

Plug-in Android Gradle 9.0.0-beta04

Plug-in Android Gradle 9.0.0-beta03

Plug-in Android Gradle 9.0.0-beta02

Plug-in Android Gradle 9.0.0-beta01

Plug-in Android Gradle 9.0.0-alpha14

Plug-in Android Gradle 9.0.0-alpha13

Plug-in Android Gradle 9.0.0-alpha12

Plug-in Android Gradle 9.0.0-alpha11

Plug-in Android Gradle 9.0.0-alpha10

Plug-in Android Gradle 9.0.0-alpha09

Plug-in Android Gradle 9.0.0-alpha08

Plug-in Android Gradle 9.0.0-alpha07

Plug-in Android Gradle 9.0.0-alpha06

Plug-in Android Gradle 9.0.0-alpha05

Plug-in Android Gradle 9.0.0-alpha04

Plug-in Android Gradle 9.0.0-alpha03

Plug-in Android Gradle 9.0.0-alpha02

Plug-in Android Gradle 9.0.0-alpha01