Ajouter des dépendances de build

Le système de compilation Gradle d'Android Studio vous permet d'inclure des binaires externes ou d'autres modules de bibliothèque à votre build en tant que dépendances. Les dépendances peuvent se trouver sur votre machine ou dans un dépôt distant, et toutes les dépendances transitives qu'elles déclarent sont également incluses automatiquement. Cette page explique comment utiliser les dépendances avec votre projet Android et fournit des détails sur les comportements et les configurations spécifiques au plug-in Android Gradle (AGP). Pour une présentation plus approfondie des concepts liés aux dépendances Gradle, consultez le guide Gradle pour la gestion des dépendances. Gardez toutefois à l'esprit que votre projet Android doit exclusivement utiliser les configurations de dépendances définies sur cette page.

Attention : N'utilisez pas de numéros de version dynamiques, tels que 'com.android.tools.build:gradle:3.+', lorsque vous spécifiez des dépendances. L'utilisation de cette fonctionnalité peut entraîner des mises à jour inattendues, des difficultés à résoudre les différences de version et des performances médiocres.

Ajouter une dépendance de bibliothèque ou de plug-in

Le meilleur moyen d'ajouter et de gérer des dépendances de compilation consiste à utiliser les catalogues de versions, la méthode utilisée par les nouveaux projets par défaut. Cette section décrit les types de configurations les plus courants utilisés pour les projets Android. Pour plus d'options, consultez la documentation Gradle. Pour obtenir un exemple d'application utilisant des catalogues de versions, consultez Now in Android. Si vous avez déjà configuré des dépendances de compilation sans catalogues de versions et que vous disposez d'un projet multimodule, nous vous recommandons de migrer.

Pour obtenir des conseils sur l'ajout et la gestion des dépendances natives (non courantes), consultez la section Dépendances natives.

Dans l'exemple suivant, nous ajoutons une dépendance binaire distante (la bibliothèque Macrobenchmark Jetpack), une dépendance de module de bibliothèque locale (myLibrary) et une dépendance de plug-in (le plug-in Android Gradle) à notre projet. Voici les étapes générales à suivre pour ajouter ces dépendances à votre projet :

Remarque :Il est possible de déclarer des catalogues de versions dans le fichier de paramètres, mais nous vous recommandons d'utiliser un fichier toml distinct pour bénéficier d'une meilleure prise en charge des suggestions de code et de la mise en surbrillance d'Android Studio.

1. Ajoutez un alias pour la version de la dépendance souhaitée dans la section [versions] du fichier de catalogue de versions, appelée libs.versions.toml (sous le répertoire gradle dans la vue Project (Projet) ou Gradle Scripts (Scripts Gradle) dans la vue Android) :

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Les alias peuvent inclure des tirets ou des traits de soulignement. Ces alias génèrent des valeurs imbriquées que vous pouvez référencer dans les scripts de compilation. Les références commencent par le nom du catalogue, la partie libs de libs.versions.toml. Lorsque vous utilisez un catalogue de versions unique, nous vous recommandons de conserver la valeur par défaut "libs".

2. Ajoutez un alias pour la dépendance dans les sections [libraries] (pour les binaires distants ou les modules de bibliothèque locaux) ou [plugins] (pour les plug-ins) du fichier libs.versions.toml.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Certaines bibliothèques sont disponibles dans une nomenclature publiée qui regroupe des familles de bibliothèques et leurs versions. Vous pouvez inclure une nomenclature dans votre catalogue de versions et vos fichiers de compilation, et lui permettre de gérer ces versions à votre place. Pour en savoir plus, consultez la section Utiliser la nomenclature.

3. Ajoutez une référence à l'alias de dépendance au script de compilation du ou des modules qui nécessitent la dépendance. Convertissez les traits de soulignement et les tirets de l'alias en points lorsque vous y faites référence à partir d'un script de compilation. Notre script de compilation au niveau du module ressemblerait à ceci:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Les références de plug-in incluent plugins après le nom du catalogue, et les références de version incluent versions après le nom du catalogue (les références de version sont peu courantes. Pour en savoir plus, consultez la section Dépendances avec les mêmes numéros de version). Les références de bibliothèque n'incluent pas de qualificatif libraries. Vous ne pouvez donc pas utiliser versions ni plugins au début d'un alias de bibliothèque.

Configurer les dépendances

Dans le bloc dependencies, vous pouvez déclarer une dépendance à une bibliothèque à l'aide de différentes configurations de dépendance (comme implementation, présenté précédemment). Chaque configuration de dépendance fournit à Gradle des instructions différentes sur l'utilisation de cette dépendance. Le tableau suivant décrit chacune des configurations que vous pouvez utiliser pour les dépendances de votre projet Android.

Configuration	Comportement
implementation	Gradle ajoute la dépendance au classpath de compilation et la package dans la sortie de compilation. Lorsque votre module configure une dépendance implementation, cela indique à Gradle que vous ne souhaitez pas que le module divulgue la dépendance à d'autres modules au moment de la compilation. Autrement dit, la dépendance n'est pas mise à la disposition des autres modules qui dépendent du module actuel. L'utilisation de cette configuration de dépendance à la place de api peut améliorer considérablement le temps de compilation, car elle réduit le nombre de modules que le système de compilation doit recompiler. Par exemple, si une dépendance implementation modifie son API, Gradle ne recompile que cette dépendance et les modules qui en dépendent directement. La plupart des modules d'application et de test doivent utiliser cette configuration.
api	Gradle ajoute la dépendance au classpath et à la sortie de compilation. Lorsqu'un module inclut une dépendance api, cela indique à Gradle qu'il souhaite exporter de manière transitoire cette dépendance vers d'autres modules, afin qu'ils soient disponibles au moment de l'exécution et de la compilation. Utilisez cette configuration avec prudence et uniquement avec les dépendances que vous devez exporter de manière transitoire vers d'autres consommateurs en amont. Si une dépendance api modifie son API externe, Gradle recompile tous les modules qui y ont accès au moment de la compilation. La présence d'un grand nombre de dépendances api peut augmenter considérablement la durée de la compilation. À moins que vous ne souhaitiez exposer l'API d'une dépendance à un module distinct, les modules de la bibliothèque doivent utiliser des dépendances implementation.
compileOnly	Gradle ajoute la dépendance au classpath de compilation uniquement (c'est-à-dire qu'elle n'est pas ajoutée à la sortie de compilation). Cette approche est utile lorsque vous créez un module Android et que vous avez besoin de sa dépendance lors de la compilation, mais qu'elle n'est pas indispensable lors de l'exécution. Par exemple, si vous dépendez d'une bibliothèque qui n'inclut que des annotations au moment de la compilation (généralement utilisées pour générer du code, mais souvent non incluses dans la sortie de compilation), vous pouvez marquer cette bibliothèque compileOnly. Si vous utilisez cette configuration, le module de votre bibliothèque doit inclure une condition d'exécution pour vérifier si la dépendance est disponible, puis modifier correctement son comportement à la volée pour pouvoir fonctionner même si elle n'est pas fournie. Cela permet de réduire la taille de l'application finale en n'ajoutant pas de dépendances temporaires dont l'importance n'est pas critique. Remarque:Vous ne pouvez pas utiliser la configuration compileOnly avec les dépendances Android Archive (AAR).
runtimeOnly	Gradle ajoute la dépendance uniquement à la sortie de compilation, pour une utilisation en cours d'exécution. Autrement dit, il n'est pas ajouté au classpath de compilation. Cette méthode est rarement utilisée sur Android, mais couramment utilisée dans les applications de serveur pour fournir des implémentations de journalisation. Par exemple, une bibliothèque peut utiliser une API de journalisation qui n'inclut pas d'implémentation. Les consommateurs de cette bibliothèque peuvent l'ajouter en tant que dépendance implementation et inclure une dépendance runtimeOnly pour l'implémentation de journalisation à utiliser.
ksp kapt annotationProcessor	Ces configurations fournissent des bibliothèques qui traitent les annotations et d'autres symboles dans votre code avant sa compilation. Elles valident généralement votre code ou génèrent du code supplémentaire, ce qui réduit la quantité de code que vous devez écrire. Pour ajouter une telle dépendance, vous devez l'ajouter au classpath du processeur d'annotations à l'aide des configurations ksp, kapt ou annotationProcessor. L'utilisation de ces configurations améliore les performances de compilation en séparant le classpath de compilation et le classpath du processeur d'annotations. Si Gradle trouve des processeurs d'annotations sur le classpath de compilation, il désactive l' évitement de compilation, ce qui a un impact négatif sur la durée de compilation (Gradle 5.0 et versions ultérieures ignorent les processeurs d'annotations trouvés sur le classpath de compilation). Le plug-in Android Gradle suppose qu'une dépendance est un processeur d'annotations si son fichier JAR contient l'élément suivant : META-INF/services/javax.annotation.processing.Processor Si le plug-in détecte un processeur d'annotations sur le classpath de compilation, il signale une erreur de compilation. ksp est un processeur de symboles Kotlin et est exécuté par le compilateur Kotlin. kapt et apt sont des outils distincts qui traitent les annotations avant l'exécution des compilateurs Kotlin ou Java. Lorsque vous choisissez la configuration à utiliser, tenez compte des points suivants: Si un processeur est disponible en tant que processeur de symboles Kotlin, utilisez-le comme dépendance ksp. Pour en savoir plus sur l'utilisation des processeurs de symboles Kotlin, consultez Migrer de Kapt vers KSP. Si le processeur n'est pas disponible en tant que processeur de symboles Kotlin : Si votre projet inclut une source Kotlin (mais peut également inclure une source Java), utilisez kapt pour l'inclure. Si votre projet n'utilise qu'une source Java, utilisez annotationProcessor pour l'inclure. Pour en savoir plus sur l'utilisation des processeurs d'annotations, consultez la page Ajouter des processeurs d'annotations.
lintChecks	Utilisez cette configuration pour inclure une bibliothèque contenant les vérifications lint que vous souhaitez que Gradle exécute lors de la compilation de votre projet d'application Android. Notez que les AAR contenant un fichier lint.jar exécutent automatiquement les vérifications définies dans ce fichier lint.jar. Vous n'avez pas besoin d'ajouter une dépendance lintChecks explicite. Cela vous permet de définir des bibliothèques et les vérifications lint associées dans une seule dépendance, garantissant que vos vérifications sont exécutées lorsque les consommateurs utilisent votre bibliothèque.
lintPublish	Utilisez cette configuration dans les projets de bibliothèque Android pour inclure les vérifications lint que vous souhaitez voir Gradle compiler dans un fichier lint.jar et packager dans votre AAR. Avec cette approche, les projets qui consomment votre AAR appliquent également ces vérifications lint. Si vous utilisiez précédemment la configuration de dépendances lintChecks pour inclure les vérifications lint dans l'AAR publiée, vous devez migrer ces dépendances afin d'utiliser la configuration lintPublish à sa place. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Configurer les dépendances pour une variante de compilation spécifique

Toutes les configurations précédentes appliquent les dépendances à toutes les variantes de compilation. Si vous souhaitez déclarer une dépendance uniquement pour un ensemble de sources de variantes de compilation spécifique ou pour un ensemble de sources de test, vous devez mettre en majuscules le nom de la configuration et le faire précéder du nom de la variante de compilation ou de l'ensemble de sources de test.

Par exemple, pour ajouter une dépendance binaire distante uniquement à votre type de produit "sans frais" à l'aide de la configuration implementation, utilisez la commande suivante:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Toutefois, si vous souhaitez ajouter une dépendance pour une variante qui associe un type de produit et un type de compilation, vous devez initialiser le nom de la configuration :

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Pour ajouter des dépendances implementation à vos tests locaux et instrumentés, procédez comme suit :

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Cependant, certaines configurations n'ont aucun sens dans ce cas de figure. Par exemple, comme les autres modules ne peuvent pas dépendre de androidTest, l'avertissement suivant s'affiche si vous utilisez la configuration androidTestApi :

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Ordre des dépendances

La liste de vos dépendances définit leur ordre de priorité : la première bibliothèque répertoriée est prioritaire sur la deuxième, qui est prioritaire sur la troisième, etc. Cet ordre est important si des ressources sont fusionnées ou si des éléments du fichier manifeste sont fusionnés dans votre application à partir des bibliothèques.

Par exemple, si votre projet déclare :

• une dépendance à LIB_A et LIB_B (dans cet ordre) ;
• où LIB_A dépend de LIB_C et LIB_D (dans cet ordre) ; et
• LIB_B dépend également de LIB_C.

L'ordre de priorité des dépendances sera le suivant :

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Ainsi LIB_A et LIB_B peuvent ignorer LIB_C, et LIB_D a une priorité plus élevée que LIB_B, car LIB_A (qui en dépend) a une priorité plus élevée que LIB_B.

Pour en savoir plus sur la fusion des fichiers manifestes de différentes sources/dépendances de projet, consultez la section Fusionner plusieurs fichiers manifestes.

Informations sur les dépendances pour la Play Console

Lorsque vous créez votre application, AGP inclut des métadonnées qui décrivent les dépendances de bibliothèque compilées dans votre application. Lorsque vous importez votre application, la Play Console inspecte ces métadonnées pour vous envoyer des alertes sur les problèmes connus liés aux SDK et aux dépendances utilisés par votre application, et, dans certains cas, vous fournir des commentaires pratiques pour résoudre ces problèmes.

Les données sont compressées, chiffrées par une clé de signature Google Play et stockées dans le bloc de signature de votre application de publication. Nous vous recommandons de conserver ce fichier pour offrir une expérience utilisateur positive et sécurisée. Vous pouvez désactiver cette fonctionnalité en incluant le bloc dependenciesInfo suivant dans le fichier build.gradle.kts de votre module.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Pour en savoir plus sur nos règles et les problèmes potentiels liés aux dépendances, consultez notre page d'assistance sur l'utilisation de SDK tiers dans votre application.

Insights sur les SDK

Android Studio affiche des avertissements d'analyse lint dans le fichier de catalogue de versions et dans la boîte de dialogue Project Structure (Structure du projet) pour les SDK publics dans le Google Play SDK Index lorsque les problèmes suivants s'appliquent:

• Les SDK sont marqués comme obsolètes par leurs auteurs.
• Les SDK enfreignent les règles Play.

Ces avertissements vous indiquent que vous devez mettre à jour ces dépendances, car l'utilisation de versions obsolètes pourrait vous empêcher de publier dans la Google Play Console par la suite.

Ajouter des dépendances de compilation sans catalogues de versions

Nous vous recommandons d'utiliser des catalogues de versions pour ajouter et gérer des dépendances, mais les projets simples peuvent ne pas en avoir besoin. Voici un exemple de fichier de compilation qui n'utilise pas de catalogues de versions :

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Ce fichier de compilation déclare une dépendance à la version 12.3 de la bibliothèque "app-magic", dans le groupe d'espaces de noms "com.example.android". La déclaration de dépendance binaire distante est un raccourci pour ce qui suit :

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Le fichier de compilation déclare également une dépendance à un module de bibliothèque Android nommé "mylibrary". Ce nom doit correspondre à celui de la bibliothèque défini par include: dans votre fichier settings.gradle.kts. Lorsque vous compilez votre application, le système compile le module de bibliothèque et package le contenu compilé obtenu dans l'application.

Le fichier de compilation déclare également une dépendance sur le plug-in Android Gradle (com.application.android). Si plusieurs modules utilisent le même plug-in, vous ne pouvez avoir qu'une seule version du plug-in sur le chemin d'accès au build pour tous les modules. Au lieu de spécifier la version dans chacun des scripts de compilation du module, vous devez inclure la dépendance du plug-in dans le script de compilation racine avec la version et indiquer de ne pas l'appliquer. L'ajout de apply false indique à Gradle de noter la version du plug-in, mais de ne pas l'utiliser dans la compilation racine. En général, le script de compilation racine est vide, à l'exception de ce bloc plugins.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Si vous disposez d'un projet à module unique, vous pouvez spécifier explicitement la version dans le script de compilation au niveau du module et laisser le script de compilation au niveau du projet vide:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}