Mises à jour de l'API du plug-in Android Gradle

Cette page suit l'abandon et les suppressions de l'API du plug-in Android Gradle (AGP), et fournit des informations sur la façon de mettre à jour votre code en conséquence.

Outil de suivi des abandons et des suppressions d'API

Le tableau suivant récapitule les moments où les API AGP sont abandonnés ou supprimés en fonction de la version d'AGP.

AGP 8.8

Voici les mises à jour importantes de l'API pour AGP 8.8.

Les configurations de ressources sont obsolètes

Les configurations de ressources sont obsolètes depuis AGP 8.8. En effet, l'AGP n'accepte plus différentes densités de ressources et la Google Play Console exige désormais que les applications soient publiées en tant qu'app bundles. Pour la configuration linguistique, vous pouvez spécifier les paramètres régionaux compatibles avec votre application à l'aide du DSL localeFilters pour mapper les configurations de paramètres régionaux aux ressources correspondantes.

AGP 8.0

Voici les principales mises à jour de l'API pour AGP 8.0.

L'API Transform a été supprimée

À partir de la version 8.0 d'AGP, l'API Transform est supprimée. Cela signifie que toutes les classes du package com.android.build.api.transform sont supprimées.

L'API Transform va être supprimée pour améliorer les performances de compilation. Les projets qui utilisent l'API Transform obligent AGP à utiliser un flux moins optimisé pour la compilation, ce qui peut entraîner des régressions importantes des durées de compilation. Il est également difficile d'utiliser l'API Transform et de la combiner avec d'autres fonctionnalités Gradle. Les API de remplacement ont pour objectif de faciliter l'extension de la fonctionnalité AGP sans introduire de problèmes de performances ou d'exactitude.

API de remplacement

Il n'existe pas de solution de remplacement unique pour l'API Transform, car il existe de nouvelles API ciblées pour chaque cas d'utilisation. Toutes les API de remplacement se trouvent dans le bloc androidComponents {}. Ces API sont toutes disponibles via AGP 7.2.

Assistance pour la transformation de bytecode

Pour transformer le bytecode, utilisez l'API Instrumentation. Pour les bibliothèques, vous ne pouvez enregistrer une instrumentation que pour les classes de projets en local. Pour les applications et les tests, vous pouvez choisir d'enregistrer une instrumentation uniquement pour les classes locales ou pour toutes les classes, y compris les dépendances locales et distantes. Pour utiliser cette API, l'instrumentation s'exécute indépendamment sur chaque classe, avec un accès limité aux autres classes du chemin de la classe (consultez createClassVisitor() pour plus d'informations). Cette restriction améliore les performances des builds complets et incrémentiels. Elle assure la simplicité de la surface de l'API. Chaque bibliothèque est instrumentée en parallèle dès qu'elle est prête, plutôt qu'au terme de la compilation. En outre, une modification dans une seule classe signifie que seules les classes concernées doivent être réinstrumentées dans une compilation incrémentielle. Pour obtenir un exemple d'utilisation de l'API Instrumentation, consultez la recette AGP Transformer des classes avec ASM.

Assistance pour l'ajout de classes générées à votre application

Pour ajouter d'autres classes générées à l'application, utilisez l'API Artifacts avec MultipleArtifact.ALL_CLASSES_DIRS. Plus précisément, utilisez

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

avec MultipleArtifact.ALL_CLASSES_DIRS pour ajouter d'autres répertoires générés aux classes de projet. L'API Artifacts sélectionne automatiquement un emplacement unique de sortie de la tâche personnalisée. Consultez la recette addToAllClasses pour découvrir un exemple d'utilisation de cette API.

Assistance pour les transformations basées sur l'analyse complète du programme

Pour implémenter des transformations basées sur l'analyse de programmes entiers, toutes les classes peuvent être transformées ensemble en une seule tâche. Cette approche doit être utilisée avec prudence, car son coût en termes de performance de compilation est beaucoup plus élevé que si vous utilisez l'API Instrumentation. Si votre plug-in utilise cette API, il est recommandé d'activer la transformation par type de compilation, afin que le développeur de l'application puisse la désactiver pour les compilations de développement.

Pour enregistrer une tâche qui transforme toutes les classes ensemble, le plug-in Android Gradle 7.4 introduit l'API Artifacts.forScope. Pour transformer toutes les classes du projet actuel, utilisez Artifacts.forScope.PROJECT. Pour transformer toutes les classes du projet actuel, les projets importés et toutes les dépendances externes, utilisez Artifacts.forScope.ALL. Le code suivant montre comment utiliser Artifacts.forScope.ALL pour enregistrer une tâche qui transforme toutes les classes ensemble :

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

Reportez-vous à la recette modifyProjectClasses pour voir un exemple d'utilisation de cette API et à la recette customizeAgpDsl pour découvrir un exemple d'enregistrement des extensions personnalisées dans les types de compilation Android.

Si votre cas d'utilisation n'est couvert par aucune des API AndroidComponents, veuillez signaler un bug.

Plusieurs plug-ins couramment utilisés ont déjà migré pour utiliser ces nouvelles API, notamment le plug-in de surveillance des performances Firebase (la version 1.4.1 prend en charge AGP 8.0) et le plugin Hilt Gradle (la version 2.40.1 prend en charge AGP 8.0). L'assistant de mise à niveau AGP permet également aux développeurs de projets de mettre à niveau les plug-ins couramment utilisés, selon les besoins.

Si vous utilisez l'API Transform via un plug-in tiers, veuillez informer l'auteur que son plug-in devra être mis à jour pour fonctionner avec les nouvelles API pour AGP 8.0.

AGP 7.2

Voici les principales mises à jour de l'API pour AGP 7.2.

RenderScript est obsolète

À partir de la version 7.2 d'AGP, les API RenderScript sont obsolètes. Elles continueront de fonctionner, mais déclencheront des avertissements et seront complètement supprimées dans les futures versions d'AGP. Pour découvrir comment effectuer la transition depuis RenderScript, consultez la page Migrer à partir de RenderScript.

Component.transformClassesWith et Component.setAsmFramesComputationMode sont obsolètes

À partir de la version 7.2 d'AGP, les API d'instrumentation du bytecode Component.transformClassesWith et Component.setAsmFramesComputationMode sont obsolètes. Elles ont été déplacées vers un nouveau bloc, Component.instrumentation, qui contient toutes les API associées à la configuration du processus d'instrumentation. Pour continuer à utiliser ces fonctionnalités d'instrumentation, utilisez plutôt les API correspondantes dans le nouveau bloc, comme illustré par l'extrait de code suivant :

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }