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-alpha05, utilisez l'assistant de mise à niveau du plug-in Android Gradle dans Android Studio Narwhal 4 Feature Drop | 2025.1.4.

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-alpha05 est le niveau d'API 36.

Le plug-in Android Gradle 9.0.0-alpha05 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. Cette modification 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 :

• Passez à 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.

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 récupérer les 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 disponibles depuis de nombreuses versions d'AGP. Vous pouvez donc utiliser 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 inclut une compatibilité intégrée pour la compilation de Kotlin, ce qui remplace le plug-in Kotlin appliqué séparément. Cela simplifie l'intégration à AGP, en évitant l'utilisation des API obsolètes et en améliorant les performances dans certains cas.

Le plug-in Android Gradle 9.0 a une dépendance d'exécution sur le plug-in Kotlin Gradle 2.2.10, qui est la version minimale requise pour la compatibilité Kotlin intégrée.

Vous pouvez désactiver Kotlin intégré en définissant android.builtInKotlin=false.

Si vous avez désactivé Kotlin intégré et que vous devez également utiliser une ancienne version du plug-in Kotlin Gradle, vous pouvez forcer la rétrogradation :

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

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 pouvez ainsi choisir de conserver le comportement de l'AGP 8.13 lors de la mise à niveau :

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 d'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

DSL modifiée

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 ne s'agit que 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, LibraryExension, 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 :

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

• AndroidSourceSet.jni, car il ne fonctionnait pas.

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

• BuildType.isRenderscriptDebuggable, car il ne fonctionnait pas.

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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.

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

• VariantBuilder.enableUnitTest, car il n'était pas applicable 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.

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
  }
}

API supprimées

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

• 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.

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

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.