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 dans 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, et donne des détails sur les comportements et les configurations propres 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.

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

Le meilleur moyen d'ajouter et de gérer les dépendances de compilation consiste à utiliser des catalogues de versions, la méthode utilisée par défaut par les nouveaux projets. Cette section présente les types de configurations les plus courants utilisés pour les projets Android. Pour en savoir plus, consultez la documentation Gradle. Pour obtenir un exemple d'application qui utilise 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:

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 seul catalogue de versions, 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 les familles de bibliothèques et leurs versions. Vous pouvez inclure une nomenclature dans votre catalogue de versions et vos fichiers de compilation, et la laisser 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 se présente comme suit:

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

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

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 préférez déclarer une dépendance uniquement pour l'ensemble de sources d'une variante 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 l'ensemble de sources de la variante de compilation ou de test.

Par exemple, pour ajouter une dépendance binaire distante uniquement à votre type de produit "sans frais" à l'aide de la configuration implementation, procédez comme suit:

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

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:

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

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

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 :

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

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.

Les avertissements 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:

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

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 sur 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:

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

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 le build racine. En général, le script de compilation racine est vide, à l'exception de ce bloc plugins.

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

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

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

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

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