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 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 des dépendances de compilation consiste à utiliser les catalogues de versions, la méthode utilisée par défaut par les nouveaux projets. Cette section couvre les types de configurations les plus courants utilisés pour les projets Android. Consultez la documentation Gradle pour plus d'options. 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 catalogue de versions et que vous disposez d'un projet multimodule, nous vous recommandons d'effectuer la migration.

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 Jetpack Macrobenchmark), une dépendance du 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 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 des versions, appelée libs.versions.toml (sous le répertoire gradle dans la 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 auxquelles vous pouvez faire référence 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 de "libs".

  2. Ajoutez un alias pour la dépendance dans les sections [libraries] (pour les binaires distants ou les modules de bibliothèque locale) 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 (BOM) 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 le laisser gérer ces versions pour vous. 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 le référencez à 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 rares. Consultez la section Dépendances avec les mêmes numéros de version pour obtenir des exemples de références 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 de bibliothèque à l'aide de l'une des 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 transmette 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 au lieu 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 recompile uniquement 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 que le module souhaite exporter de manière transitoire cette dépendance vers d'autres modules, afin qu'elle soit disponible 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 ayant accès à cette dépendance au moment de la compilation. 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 (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 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 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 elle est couramment utilisée dans les applications serveur pour fournir des implémentations de journalisation. Par exemple, une bibliothèque peut utiliser une API de journalisation sans implémentation. Les utilisateurs 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 réelle à 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é. Elles valident généralement votre code ou en génèrent 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. L'utilisation de ces configurations améliore les performances de compilation en séparant le classpath de compilation du classpath du processeur d'annotations. Si Gradle détecte des processeurs d'annotations sur le classpath de compilation, il désactive l' évitement de compilation, qui a un impact négatif sur le temps de compilation (Gradle 5.0 et versions ultérieures ignorent les processeurs d'annotations détecté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. Il 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 KP.
  • 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 que le code source Java, utilisez annotationProcessor pour l'inclure.

Pour en savoir plus sur l'utilisation des processeurs d'annotations, consultez 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 des vérifications lint associées dans une seule dépendance, ce qui garantit que vos vérifications sont exécutées lorsque les utilisateurs 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 des 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 combine 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.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) ;
  • 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 compilez votre application, l'AGP inclut des métadonnées qui décrivent les dépendances de bibliothèque compilées dans votre application. Lors de l'importation de votre application, la Play Console inspecte ces métadonnées pour fournir des alertes concernant les problèmes connus liés aux SDK et aux dépendances utilisés par votre application. Dans certains cas, elle fournit des commentaires exploitables 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 version d'application. Nous vous recommandons de conserver ce fichier de dépendances pour 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 des 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 ne respectent pas les règles de 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 à l'avenir.

Ajouter des dépendances de compilation sans catalogues de versions

Nous vous recommandons d'utiliser des catalogues de versions pour ajouter et gérer les 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 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é "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 empaquette 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 classpath de compilation 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 règle générale, 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 ce champ vide:

Kotlin

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

Groovy

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