Créer une bibliothèque Android

Une bibliothèque Android est structurellement identique à un module d'application Android. Elle contient tous les éléments nécessaires pour créer une application, y compris le code source, les fichiers de ressources et un fichier manifeste Android.

Cependant, au lieu de se compiler dans un APK qui s'exécute sur un appareil, une bibliothèque Android se compile dans un fichier d'archive Android (AAR) que vous pouvez utiliser comme dépendance pour un module d'application Android. Contrairement aux fichiers JAR, les fichiers AAR offrent les fonctionnalités suivantes pour les applications Android :

  • Les fichiers AAR peuvent contenir des ressources Android et un fichier manifeste, ce qui vous permet de regrouper des ressources partagées telles que des mises en page et des drawables, en plus des classes et des méthodes Kotlin ou Java.
  • Les fichiers AAR peuvent contenir des bibliothèques C/C++ à utiliser par le code C/C++ du module de l'application.

Un module de bibliothèque est utile dans les cas suivants :

  • Lorsque vous compilez plusieurs applications qui utilisent certains des mêmes composants, comme des activités, des services ou des mises en page d'UI
  • Lorsque vous compilez une application qui existe dans plusieurs versions d'APK (par exemple, une version sans frais et une version payante), qui partagent des composants essentiels

Dans les deux cas, déplacez les fichiers que vous souhaitez réutiliser dans un module de bibliothèque, puis ajoutez la bibliothèque en tant que dépendance pour chaque module d'application.

Cette page explique comment créer et utiliser un module de bibliothèque Android. Pour découvrir comment publier une bibliothèque, consultez la section Publier votre bibliothèque.

Créer un module de bibliothèque

Pour créer un module de bibliothèque dans votre projet, procédez comme suit :

  1. Cliquez sur File > New > New Module (Fichier > Nouveau > Nouveau module).
  2. Dans la fenêtre Create New Module (Créer un module) qui s'affiche, cliquez sur Android Library (Bibliothèque Android), puis sur Next (Suivant).

    Une option permet également de créer une bibliothèque Kotlin ou Java, puis de générer un fichier JAR traditionnel. Bien qu'un fichier JAR soit utile pour de nombreux projets, en particulier lorsque vous souhaitez partager du code avec d'autres plates-formes, il ne vous permet pas d'inclure des ressources Android ni des fichiers manifestes, ce qui est très pratique pour réutiliser du code dans les projets Android. Ce guide est consacré à la création de bibliothèques Android.

  3. Attribuez un nom à votre bibliothèque et sélectionnez une version minimale du SDK pour le code qu'elle contient, puis cliquez sur Finish (Terminer).

Une fois la synchronisation du projet Gradle terminée, le module de la bibliothèque apparaît dans le volet Project (Projet). Si vous ne voyez pas le nouveau dossier du module, assurez-vous que le volet affiche la vue Android.

Convertir un module d'application en module de bibliothèque

Si vous avez un module d'application existant avec le code que vous souhaitez réutiliser, vous pouvez le convertir en module de bibliothèque comme suit :

  1. Ouvrez le fichier build.gradle au niveau du module (si vous utilisez Groovy) ou le fichier build.gradle.kts (si vous utilisez un script Kotlin).
  2. Supprimez la ligne correspondant à applicationId. Seul un module d'application Android peut définir cette option.
  3. En haut du fichier, recherchez le bloc "plugins" qui se présente comme suit :

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

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

    Remplacez-le par ce qui suit :

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. Enregistrez le fichier, puis cliquez sur File > Sync Project with Gradle Files (Fichier > Synchroniser le projet avec les fichiers Gradle).

La structure du module reste la même, mais fonctionne désormais comme une bibliothèque Android. La compilation créera un fichier AAR au lieu d'un APK.

Lorsque vous souhaitez compiler le fichier AAR, sélectionnez le module de bibliothèque dans la fenêtre Project (Projet), puis cliquez sur Build > Build APK (Compiler > Compiler un APK).

Ajouter des dépendances à l'aide de la boîte de dialogue "Project Structure" (Structure du projet)

Vous pouvez utiliser la boîte de dialogue Project Structure (Structure du projet) pour ajouter des dépendances à votre projet. Les sections suivantes décrivent comment vous servir de cette boîte de dialogue pour ajouter des dépendances.

Utiliser votre bibliothèque depuis le même projet

Pour utiliser le code de votre nouvelle bibliothèque Android dans un autre module d'application ou de bibliothèque au sein du même projet, ajoutez une dépendance au niveau du projet :

  1. Accédez à File > Project Structure > Dependencies (Fichier > Structure du projet > Dépendances).
  2. Sélectionnez le module dans lequel vous souhaitez ajouter la bibliothèque.
  3. Dans l'onglet Declared Dependencies (Dépendances déclarées), cliquez sur et sélectionnez Module Dependency (Dépendance du module) dans le menu.

  4. Dans la boîte de dialogue Add Module Dependency (Ajouter une dépendance de module), sélectionnez le module de bibliothèque.

    Ajouter une dépendance de module dans la boîte de dialogue "Project Structure" (Structure du projet)

  5. Sélectionnez la configuration qui nécessite cette dépendance ou sélectionnez l'implémentation si elle s'applique à toutes les configurations, puis cliquez sur OK.

Android Studio modifie le fichier build.gradle ou build.gradle.kts de votre module pour ajouter la dépendance au format suivant :

Groovy

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

Utiliser votre bibliothèque dans d'autres projets

Nous vous recommandons de partager les dépendances (JAR et AAR) avec un dépôt Maven, soit hébergé sur un service tel que Maven Central, soit avec une structure de répertoires sur votre disque local. Pour en savoir plus sur l'utilisation des dépôts Maven, consultez Dépôts distants.

Lorsqu'une bibliothèque Android est publiée dans un dépôt Maven, les métadonnées sont intégrées afin que les dépendances de la bibliothèque soient incluses dans la compilation en cours d'utilisation. Ainsi, la bibliothèque est automatiquement dédupliquée si elle est utilisée à plusieurs endroits.

Pour utiliser le code de votre bibliothèque Android dans un autre module d'application au sein d'un autre projet, procédez comme suit :

  1. Accédez à File > Project Structure > Dependencies (Fichier > Structure du projet > Dépendances).
  2. Dans l'onglet Declared Dependencies (Dépendances déclarées), cliquez sur et sélectionnez Library Dependency (Dépendance de la bibliothèque) dans le menu.

  3. Dans la boîte de dialogue Add Library Dependency (Ajouter une dépendance de bibliothèque), recherchez la bibliothèque à ajouter à l'aide du champ de recherche. Ce formulaire recherche les dépôts spécifiés dans le bloc dependencyResolutionManagement { repositories {...}} du fichier settings.gradle ou settings.gradle.kts.

    Ajouter une dépendance de bibliothèque dans la boîte de dialogue "Project Structure" (Structure du projet)

  4. Sélectionnez la configuration qui nécessite cette dépendance ou sélectionnez l'implémentation si elle s'applique à toutes les configurations, puis cliquez sur OK.

Vérifiez le fichier build.gradle ou build.gradle.kts de votre application pour vous assurer qu'une déclaration semblable à la suivante s'affiche (selon la configuration de compilation que vous avez sélectionnée) :

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

Ajouter votre AAR ou votre JAR en tant que dépendance

Pour utiliser le code de votre bibliothèque Android dans un autre module d'application, procédez comme suit :

  1. Accédez à File > Project Structure > Dependencies (Fichier > Structure du projet > Dépendances).
  2. Dans l'onglet Declared Dependencies (Dépendances déclarées), cliquez sur et sélectionnez Jar Dependency (Dépendance Jar) dans le menu.

  3. Dans la boîte de dialogue Add Jar/Aar Dependency (Ajouter une dépendance Jar/AAR), saisissez d'abord le chemin d'accès à votre fichier AAR ou JAR, puis sélectionnez la configuration à laquelle la dépendance s'applique. Si la bibliothèque doit être disponible pour toutes les configurations, sélectionnez la configuration d'implémentation.

    Ajouter une dépendance AAR dans la boîte de dialogue "Project Structure" (Structure du projet)

    Vérifiez le fichier build.gradle ou build.gradle.kts de votre application pour vous assurer qu'une déclaration semblable à la suivante s'affiche (selon la configuration de compilation que vous avez sélectionnée) :

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

Pour importer une dépendance sur la version Gradle exécutée en dehors d'Android Studio, ajoutez un chemin d'accès à la dépendance dans le fichier build.gradle ou build.gradle.kts de votre application. Exemple :

Groovy

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

Pour en savoir plus sur l'ajout de dépendances Gradle, consultez Ajouter des dépendances de compilation.

Déclarer une ressource publique

Les ressources incluent tous les fichiers du répertoire res/ de votre projet, tels que les images. Par défaut, toutes les ressources d'une bibliothèque sont publiques. Pour rendre toutes les ressources implicitement privées, vous devez définir au moins un attribut spécifique comme public.

Pour déclarer une ressource publique, ajoutez une déclaration <public> au fichier public.xml de votre bibliothèque. Si vous n'avez pas encore ajouté de ressources publiques, vous devez créer le fichier public.xml dans le répertoire res/values/ de votre bibliothèque.

L'exemple de code suivant crée deux ressources de chaîne publiques nommées mylib_app_name et mylib_public_string :

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

Pour empêcher les utilisateurs de votre bibliothèque d'accéder aux ressources réservées à un usage interne, utilisez ce mécanisme automatique de désignation privée en déclarant une ou plusieurs ressources publiques. Vous pouvez également rendre toutes les ressources privées en ajoutant une balise <public /> vide, qui n'indique rien de public et rend donc toutes les ressources privées.

Vous devez rendre publiques toutes les ressources auxquelles les développeurs utilisant votre bibliothèque doivent avoir accès.

Rendre implicitement des attributs privés empêche les utilisateurs de votre bibliothèque de recevoir des suggestions de saisie automatique de code basées sur les ressources internes de la bibliothèque, tout en leur permettant de renommer ou de supprimer des ressources privées sans entraver le fonctionnement des clients de votre bibliothèque. Les ressources privées sont exclues de la saisie automatique de code, et lint vous avertit lorsque vous essayez de référencer une ressource privée.

Lorsque vous créez une bibliothèque, le plug-in Android Gradle récupère les définitions de ressources publiques et les extrait dans le fichier public.txt, qui est ensuite empaqueté dans le fichier AAR.

Remarques concernant le développement des modules de bibliothèque

Lorsque vous développez vos modules de bibliothèque et vos applications dépendantes, tenez compte des comportements et limites suivants.

  • Les bibliothèques sont fusionnées par ordre de priorité.

    Une fois que vous avez ajouté des références aux modules de bibliothèque à votre module d'application Android, vous pouvez définir leur priorité relative. Au moment de la compilation, les bibliothèques sont fusionnées une par une avec l'application, de la priorité la plus basse à la plus élevée.

  • Évitez les conflits de fusion des ressources.

    Les outils de compilation fusionnent les ressources d'un module de bibliothèque avec celles d'un module d'application dépendant. Si un ID de ressource donné est défini dans les deux modules, la ressource de l'application est utilisée.

    En cas de conflit entre plusieurs bibliothèques AAR, la ressource de la bibliothèque apparaissant en premier dans la liste des dépendances (en haut du bloc dependencies) est utilisée.

    Pour éviter les conflits de ressources, utilisez des classes R non transitives. Si cela n'est pas possible, envisagez d'utiliser un préfixe ou un autre schéma de dénomination cohérent propre au module (ou unique dans tous les modules du projet).

  • Dans les compilations multimodules, les dépendances JAR sont traitées comme des dépendances transitives.

    Lorsque vous ajoutez une dépendance JAR à un projet de bibliothèque générant une AAR, le fichier JAR est traité par le module de bibliothèque et empaqueté avec son AAR.

    Toutefois, si votre projet comprend un module de bibliothèque utilisé par un module d'application, le module d'application traite la dépendance JAR locale de la bibliothèque comme une dépendance transitive. Dans ce cas, le fichier JAR local est traité par le module d'application qui l'utilise, et non par le module de bibliothèque. Cela permet d'accélérer les compilations incrémentielles causées par des modifications du code d'une bibliothèque.

    Tout conflit de ressources Java causé par des dépendances JAR locales doit être résolu dans le module d'application qui utilise la bibliothèque.

  • Un module de bibliothèque peut dépendre d'une bibliothèque JAR externe.

    Vous pouvez développer un module de bibliothèque qui dépend d'une bibliothèque externe. Dans ce cas, le module dépendant doit s'exécuter sur une cible qui inclut la bibliothèque externe.

    Notez que le module de bibliothèque et l'application dépendante doivent déclarer la bibliothèque externe dans leurs fichiers manifestes, dans un élément <uses-library>.

  • La valeur minSdkVersion du module d'application doit être supérieure ou égale à la version définie par la bibliothèque.

    Une bibliothèque est compilée dans le module d'application dépendant. Par conséquent, les API utilisées dans le module de bibliothèque doivent être compatibles avec la version de la plate-forme prise en charge par le module d'application.

  • Chaque module de bibliothèque crée sa propre classe R.

    Lorsque vous compilez les modules d'application dépendants, les modules de bibliothèque sont compilés dans un fichier AAR, puis ajoutés au module d'application. Chaque bibliothèque possède donc sa propre classe R, nommée en fonction du nom de package de la bibliothèque.

    La classe R générée à partir du module principal et du module de bibliothèque est créée dans tous les packages nécessaires, y compris le package du module principal et les packages des bibliothèques.

  • Un module de bibliothèque peut inclure son propre fichier de configuration ProGuard.

    Si vous utilisez un projet de bibliothèque pour compiler et publier un fichier AAR, vous pouvez ajouter un fichier de configuration ProGuard à la configuration de compilation de votre bibliothèque. Dans ce cas, le plug-in Android Gradle applique les règles ProGuard que vous avez spécifiées. Les outils de compilation intègrent ce fichier dans le fichier AAR généré pour le module de bibliothèque. Lorsque vous ajoutez la bibliothèque à un module d'application, son fichier ProGuard est ajouté au fichier de configuration ProGuard (proguard.txt) du module d'application.

    En intégrant un fichier ProGuard dans votre module de bibliothèque, vous vous assurez que les modules d'application qui dépendent de votre bibliothèque n'ont pas besoin de mettre à jour manuellement leurs fichiers ProGuard pour l'utiliser. Lorsque le système de compilation Android Studio compile votre application, il utilise les directives du module d'application et de la bibliothèque. Il n'est donc pas nécessaire d'exécuter un réducteur de code sur la bibliothèque lors d'une étape distincte.

    Pour ajouter les règles ProGuard à votre projet de bibliothèque, spécifiez le nom du fichier avec la propriété consumerProguardFiles dans le bloc defaultConfig du fichier build.gradle ou build.gradle.kts de votre bibliothèque.

    Par exemple, l'extrait suivant définit lib-proguard-rules.txt comme fichier de configuration ProGuard de la bibliothèque :

    Groovy

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    Toutefois, si votre module de bibliothèque fait partie d'une compilation multimodule qui se compile dans un APK et qui ne génère pas de fichier AAR, n'exécutez la minification de code que sur le module d'application qui utilise la bibliothèque. Pour en savoir plus sur les règles ProGuard et leur utilisation, consultez Réduire, obscurcir et optimiser votre application.

  • Tester un module de bibliothèque revient à tester une application.

    La principale différence est que la bibliothèque et ses dépendances sont automatiquement incluses en tant que dépendances de l'APK test. Cela signifie que l'APK test inclut non seulement son propre code, mais aussi l'AAR de la bibliothèque et toutes ses dépendances. Étant donné qu'il n'y a pas d'application distincte en cours de test, la tâche androidTest installe (et désinstalle) uniquement l'APK test.

    Lorsque vous fusionnez plusieurs fichiers manifestes, Gradle suit l'ordre de priorité par défaut et fusionne le fichier manifeste de la bibliothèque avec le fichier manifeste principal de l'APK test.

Anatomie d'un fichier AAR

L'extension d'un fichier AAR est .aar et le type d'artefact Maven est également aar. Le fichier lui-même est un fichier ZIP. La seule entrée obligatoire est /AndroidManifest.xml.

Un fichier AAR peut également inclure une ou plusieurs des entrées facultatives suivantes :