Ajouter des dépendances de build

Le système de compilation Gradle d'Android Studio vous permet d'inclure des binaires 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 des dépendances avec votre projet Android, y compris des détails sur les comportements et les configurations spécifiques le 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 provoquer des mises à jour de version inattendues, des difficultés à résoudre les différences de version et de mauvaises performances.

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 est d'utiliser des catalogues de versions, la méthode que les nouveaux projets utilisent par défaut. Cette section aborde les problèmes Types de configuration utilisés pour les projets Android reportez-vous au Documentation Gradle pour plus d'options. Pour obtenir un exemple d'application qui utilise des catalogues de versions, consultez Maintenant disponible sur Android. Si vous avez déjà configuré des dépendances de compilation sans catalogue de versions et disposant d'un projet multimodule, nous vous recommandons en cours de migration.

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

Dans l'exemple suivant, nous ajoutons un binaire distant la dépendance (le jetpack Macrobenchmark bibliothèque), module de bibliothèque locale la dépendance (myLibrary) et un plug-in (le plug-in Android Gradle) à notre projet. Voici les options étapes pour ajouter ces dépendances à votre projet:

Remarque :Vous pouvez déclarer des catalogues de versions dans les paramètres fichier, mais nous vous recommandons d'utiliser un fichier toml distinct pour une meilleure prise en charge du code suggestions et mise en surbrillance d'Android Studio.

1. Ajoutez un alias pour la version de la dépendance que vous souhaitez dans le Section [versions] du fichier de catalogue de versions, appelée libs.versions.toml (sous le répertoire gradle dans vue Projet ou 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 catalogue, la partie libs de libs.versions.toml. Quand ? à l'aide d'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 [libraries] (pour binaires distants ou modules de bibliothèque locale) ou [plugins] (pour 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 les familles de bibliothèques et leurs versions. Vous pouvez inclure une nomenclature dans votre le catalogue de versions et les fichiers de compilation, et laissez-le gérer ces versions à votre place. Voir Utiliser la nomenclature pour en savoir plus.

3. Ajoutez une référence à l'alias de dépendance au script de compilation du module(s) nécessitant la dépendance. Convertir l'alias traits de soulignement et tirets à des points lorsque vous le référencez à partir d'un script de compilation. 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 aux plug-ins incluent plugins après le nom du catalogue. les références de version incluent versions après le nom du catalogue (la version les références ne sont pas courantes ; Voir la section Dépendances ayant les mêmes numéros de version pour obtenir des exemples de références de version.) Bibliothèque les références n'incluent pas de qualificatif libraries. Vous ne pouvez donc pas utiliser versions ou plugins au début d'une bibliothèque un alias.

Configurer les dépendances

Dans le bloc dependencies, vous pouvez déclarer une dépendance de bibliothèque à l'aide de l'une de plusieurs configurations de dépendances (comme implementation indiqué 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 configure une dépendance implementation, il est pour indiquer à 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 mis à la disposition des autres modules qui dépendent de ce module. Utiliser cette configuration de dépendance au lieu api peut améliorer considérablement le temps de compilation car cela réduit le nombre de modules dont le système de compilation a besoin pour recompiler. Par exemple, si un implementation modifie son API, Gradle recompile uniquement cette dépendance et les modules qui en dépendent directement. La plupart des applications et des tests modules 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, il est indiquant à Gradle que le module souhaite exporter de manière transitoire cette dépendance aux autres modules, pour qu'ils puissent y accéder à la fois au moment de l'exécution et de la compilation. Utilisez cette configuration avec prudence et uniquement avec les dépendances vous devez exporter de manière transitoire vers d'autres consommateurs en amont. Si un La dépendance api modifie son API externe, Gradle recompile tous les modules ayant accès à cette dépendance lors de la compilation en temps réel. Avoir un grand nombre de dépendances api peut augmente considérablement la durée de compilation. À moins que vous ne vouliez exposer l'API de la dépendance vers un module distinct, les modules de la bibliothèque doivent utiliser les dépendances implementation.
compileOnly	Gradle ajoute la dépendance uniquement au classpath de compilation (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. Pour 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 la marquer comme 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 compileOnly avec des 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 sur les serveurs pour fournir des implémentations de journalisation. Par exemple, un peut utiliser une API de journalisation qui n'inclut pas la mise en œuvre. Les utilisateurs de cette bibliothèque peuvent l'ajouter en tant que la dépendance implementation et incluez une Dépendance runtimeOnly pour la journalisation à utiliser.
ksp kapt annotationProcessor	Ces configurations fournissent des bibliothèques qui traitent les annotations et d'autres symboles dans votre code avant qu'il ne soit compilé. En général, valider votre code ou générer du code supplémentaire, ce qui réduit la quantité de code à é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. Utilisation de ces améliore les performances de compilation en séparant la compilation classpath à partir du classpath du processeur d'annotations. Si Gradle détecte d'annotations sur le classpath de compilation, il désactive <ph type="x-smartling-placeholder"></ph> l'évitement de compilation, ce qui a un impact négatif sur la durée de compilation (Gradle Les versions 5.0 et ultérieures ignorent les processeurs d'annotations trouvés dans la compilation classpath). 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. Il est exécuté par le Compilateur Kotlin. kapt et apt sont des outils distincts qui des annotations de processus avant l'exécution des compilateurs Kotlin ou Java. Pour choisir la configuration à utiliser, tenez compte de la suivantes: Si un processeur est disponible en tant que processeur de symboles Kotlin, utilisez en tant que dépendance ksp. Voir Migrer de Kapt vers Kps. pour en savoir plus sur l'utilisation des processeurs de symboles Kotlin. Si le processeur n'est pas disponible en tant que processeur de symboles Kotlin: <ph type="x-smartling-placeholder"> </ph> Si votre projet inclut une source Kotlin (mais peut aussi inclure une source Java), utiliser kapt pour l'inclure. Si votre projet n'utilise qu'un code source Java, utilisez annotationProcessor pour l'inclure. Pour en savoir plus sur l'utilisation des processeurs d'annotations, consultez Ajoutez des processeurs d'annotations.
lintChecks	Utilisez cette configuration pour inclure une bibliothèque contenant lint vérifications que Gradle doit exécuter lors de la compilation de votre application Android projet. Notez que les AAR contenant un fichier lint.jar exécuter 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 en veillant à ce que les vérifications soient exécutées lorsque les clients 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 des dépendances à toutes les variantes de compilation. Si Déclarez plutôt une dépendance pour un build spécifique un ensemble de sources de variantes ou pour une source de test , vous devez mettre en majuscules la configuration puis ajoutez le nom de la variante de compilation ou de l'ensemble de sources de test en préfixe.

Par exemple, pour ajouter une dépendance binaire distante uniquement à votre produit à l'aide de la configuration implementation, utilisez le code suivant:

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 produit type 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.5.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.5.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

Lors de la création de votre application, l'AGP inclut des métadonnées qui décrivent la bibliothèque dépendances compilées dans votre application. Lorsque vous importez votre application, l'application Play Store La console inspecte ces métadonnées pour fournir des alertes pour les problèmes connus liés aux SDK et les dépendances utilisées par votre application et, dans certains cas, fournissent des commentaires exploitables à résoudre ces problèmes.

Les données sont compressées, chiffrées à l'aide d'une clé de signature Google Play et stockées le bloc de signature de votre version d'application. Nous vous recommandons de conserver cette dépendance pour garantir une expérience utilisateur positive et sécurisée. Vous pouvez désactiver cette fonctionnalité en incluant le suivi dependenciesInfo 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 des versions et dans la section Projet "Structure" pour les SDK publics dans la Google Play SDK Index lorsque les problèmes suivants se produisent:

• Les SDK sont marqués comme obsolètes par leurs auteurs.
• Les SDK ne respectent pas les règles de Google Play.

Les avertissements indiquent que vous devez mettre à jour ces dépendances, car l'utilisation de versions obsolètes peut vous empêcher de publier sur Google Play console à l'avenir.

Ajouter des dépendances de compilation sans catalogue de versions

Nous vous recommandons d'utiliser des catalogues de versions pour ajouter et gérer les dépendances. projets n'en ont peut-être pas besoin. Voici un exemple de fichier de compilation qui n'utilise pas 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 par rapport à la version 12.3 de "app-magic" bibliothèque, dans le répertoire "com.example.android" dans ce groupe d'espaces de noms. Le binaire distant "déclaration de dépendance" est un raccourci pour désigner les éléments suivants:

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 sur un module de bibliothèque Android nommé "mabibliothèque"; ce nom doit correspondre à celui de la bibliothèque définie par l'élément include: dans votre fichier settings.gradle.kts. Lorsque vous compilez votre application, le système de compilation compile le module de bibliothèque et crée un package du contenu compilé obtenu dans le l'application.

Le fichier de compilation déclare également une dépendance au plug-in Android Gradle (com.application.android). Si plusieurs modules utilisent le même vous ne pouvez avoir qu'une seule version du plug-in sur le chemin de classe de compilation dans tous les modules. Au lieu de spécifier la version dans chacun des modules vous devez inclure la dépendance du plug-in dans le script de compilation racine avec la version, et indiquez de ne pas l'appliquer. Ajouter apply false indique Gradle pour noter la version du plug-in, mais pas pour l'utiliser dans le build 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 avez un projet à module unique, vous pouvez spécifier explicitement la version dans le script de compilation au niveau du module et laissez 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'
}