Publier plusieurs bibliothèques Android en une seule avec la bibliothèque fusionnée

Dans les projets comportant de nombreux modules, il peut être difficile de distribuer des bibliothèques Android à vos utilisateurs tout en essayant de maintenir une structure de projet claire. Dans de nombreux cas, il est nécessaire de publier beaucoup plus de bibliothèques que prévu.

Le plug-in Fused Library fourni avec le plug-in Android Gradle permet d'empaqueter plusieurs modules de bibliothèque Android dans une seule bibliothèque Android publiable. Cela vous permet de modulariser le code source et les ressources de votre bibliothèque dans votre build comme bon vous semble, tout en évitant d'exposer la structure de votre projet une fois distribué.

Conseil : Consultez la recette Gradle du plug-in de bibliothèque fusionnée, qui indique comment configurer une bibliothèque fusionnée et fournit des conseils plus pratiques.

La distribution sous forme de bibliothèque unique peut présenter les avantages suivants :

• Dépendances simplifiées : remplace plusieurs dépendances de bibliothèque par un seul fichier AAR, ce qui simplifie la configuration du projet et la gestion des versions pour vos utilisateurs.
• Taille de bibliothèque réduite : peut améliorer la minification du code, ce qui réduit la taille des fichiers AAR.
• Sécurité améliorée : peut offrir un meilleur contrôle sur les détails d'implémentation interne des bibliothèques publiées.

Créer une bibliothèque fusionnée

Pour créer une bibliothèque fusionnée, vous devez créer un module Android, ajouter des dépendances, puis publier la bibliothèque fusionnée.

Prérequis

Pour utiliser le plug-in de bibliothèque fusionnée, utilisez AGP 9.0 ou une version ultérieure. Les versions précédentes du plug-in de bibliothèque fusionnée présentent des comportements et des problèmes différents, qui sont corrigés dans AGP 9.0.

Ajouter un module de bibliothèque fusionné

Pour utiliser le plug-in, vous devez ajouter un nouveau module Android à votre projet :

Dans cet exemple, le module de bibliothèque fusionné sera appelé myFusedLibrary.

1. Ajoutez include(":myFusedLibrary") au fichier settings.gradle.kts.
2. Ajoutez android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" } sous la section [plugins] dans le fichier gradle/libs.versions.toml.
3. Ajoutez alias(libs.plugins.android.fusedlibrary) apply false dans le bloc de plug-ins du fichier build.gradle.kts de premier niveau.
4. Pour créer le module myFusedLibrary, créez un répertoire nommé myFusedLibrary (effectuez un clic droit sur "My Application" > New > Directory).
5. Créez un fichier build.gradle.kts dans le module myFusedLibrary (effectuez un clic droit sur le module myFusedLibrary > Nouveau > Fichier).
6. Collez ce qui suit dans le fichier myFusedLibrary/build.gradle.kts :

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary {
    namespace = "com.example.myFusedLibrary"
    minSdk = 21
}

dependencies { }

Groovy

plugins {
    id 'com.android.fused-library'
}

androidFusedLibrary {
    namespace 'com.example.myFusedLibrary'
    minSdk 21
}

dependencies {

}

Ajouter des dépendances

La fonctionnalité de base de la bibliothèque fusionnée consiste à regrouper les dépendances. Le plug-in permet d'ajouter des dépendances de projet locales et des bibliothèques externes. Pour spécifier les dépendances à empaqueter, utilisez la configuration include. Les dépendances transitives ne sont pas empaquetées.

Exemple :

Kotlin

dependencies {
    include(project(":image-rendering"))
    include("mycoolfonts:font-wingdings:5.0")
}

Groovy

dependencies {
    include project(':image-rendering')
    include 'mycoolfonts:font-wingdings:5.0'
}

Remarque : Si une dépendance spécifiée à l'aide d'une instruction include dépend d'un projet de bibliothèque Android local, vous devez publier le projet de bibliothèque Android local dans un dépôt local configuré. Pour en savoir plus, consultez Publier votre bibliothèque.

Publier votre bibliothèque fusionnée

Avant de publier une bibliothèque fusionnée, vous devez vous familiariser avec la publication d'une bibliothèque Android. La publication d'une bibliothèque fusionnée est semblable à celle d'une bibliothèque Android. Toutefois, vous devez tenir compte de certaines différences clés pour publier correctement la bibliothèque fusionnée :

• Le plug-in Maven Publish doit également être appliqué à tout module auquel le plug-in de bibliothèque fusionnée est appliqué.
• La publication doit hériter de fusedLibraryComponent, car cela fournit les dépendances requises pour compiler l'artefact de bibliothèque fusionné.

Voici un exemple de configuration de publications :

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        register<MavenPublication>("release") {
             groupId = "my-company"
             artifactId = "my-fused-library"
             version = "1.0"
             from(components["fusedLibraryComponent"])
        }
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        release(MavenPublication) {
            groupId = "my-company"
            artifactId = "my-fused-library"
            version = "1.0"
            afterEvaluate {
            from components.fusedLibraryComponent
        }
    }
}

Publier votre bibliothèque fusionnée pour la tester

Vous devez tester la dépendance à une bibliothèque fusionnée publiée à partir d'une application Android ou d'une bibliothèque Android. La méthode recommandée consiste à publier la bibliothèque fusionnée et ses dépendances de projet dans un dépôt Maven local.

Pour publier les artefacts de la bibliothèque fusionnée dans un dépôt local, définissez une configuration semblable à celle-ci :

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

repositories {
    maven {
        name = "myLocalRepo"
        url = uri(layout.buildDirectory.dir("myLocalRepo"))
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

repositories {
    maven {
        name 'myLocalRepo'
        url layout.buildDirectory.dir('myLocalRepo')
    }
}

Importer votre bibliothèque fusionnée

Pour distribuer votre bibliothèque fusionnée, consultez Importer votre bibliothèque.

Comportement et mesures de protection

La combinaison de bibliothèques Android présente des subtilités qui peuvent compliquer la gestion des priorités par le plug-in. Par exemple, deux bibliothèques ayant le même chemin de classe entraîneront un échec de compilation lors de la fusion de la bibliothèque. La fusion des ressources prendra en compte l'ordre des dépendances spécifié lors de la sélection d'une ressource portant le même nom dans différentes bibliothèques.

• Les bibliothèques fusionnées ne peuvent être publiées qu'en tant qu'artefact de bibliothèque Android (AAR) pour être ajoutées en tant que dépendance.
• La fusion de bibliothèques qui utilisent la liaison de données n'est pas possible.
• Vous ne pouvez pas fusionner plusieurs types de compilation et types de produit dans une même bibliothèque fusionnée. Créez des bibliothèques fusionnées distinctes pour différentes variantes.

Pour équilibrer la quantité de configuration nécessaire et la facilité d'utilisation, le plug-in échouera lors de la compilation en cas de conflits ambigus ou utilisera des heuristiques lors de la fusion des artefacts. Le tableau suivant décrit comment les artefacts sont fusionnés :

Type	Comportement
Classes	Les bibliothèques ayant le même chemin de classe entraîneront un échec de compilation lors de la fusion de la bibliothèque.
Ressources pour Android	La fusion des ressources prendra en compte l'ordre des dépendances spécifié lors de la sélection d'une ressource portant le même nom dans différents fichiers.
Métadonnées AAR	Les versions des métadonnées AAR sont fusionnées en donnant la priorité à la valeur la plus élevée de chaque bibliothèque de dépendances. Un DSL est fourni pour remplacer ces valeurs. Kotlin androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } }
Ressources Java	Les fichiers de ressources Java dans plusieurs bibliothèques avec des chemins d'accès identiques ne sont pas autorisés et entraîneront l'échec de la compilation.

Problèmes connus

Fused Library est un nouveau plug-in. Des problèmes connus sont en cours de résolution pour répondre à tous les cas d'utilisation. Vous pouvez signaler des bugs pour tout problème que vous rencontrez.

• Problème 454305444 : les bibliothèques contenant des règles ProGuard client qui ne sont pas appelées "proguard.txt" entraînent un échec de compilation. Corrigé dans AGP 9.1 et versions ultérieures.
• Problème 374982739 : Ajout de dépendances de fichiers sur d'autres fichiers .aar
• Problème 231433225 : pas de compatibilité avec la fusion des artefacts RenderScript et Prefab

Expérimental : un module de bibliothèque fusionné ne peut être publié qu'en tant que bibliothèque externe. Un projet de bibliothèque fusionnée locale ne peut pas être ajouté en tant que dépendance de projet à un autre module, dans les modules d'application Android ou de bibliothèque Android. Le plug-in limite les modules de bibliothèque fusionnés à la publication uniquement. La consommation directe de projets n'est pas entièrement compatible avec Studio. La restriction de publication uniquement peut être désactivée en ajoutant android.experimental.fusedLibrarySupport.publicationOnly=false au fichier gradle.properties.

Comprendre les dépendances d'une bibliothèque fusionnée

La bibliothèque fusionnée n'a pas de sources et utilise efficacement les bibliothèques Android comme seule source. Il est important de comprendre d'où provient chaque élément. Pour lister les dépendances fusionnées dans l'artefact obtenu et les dépendances nécessaires pour créer l'artefact, exécutez la tâche gradle :report sur la bibliothèque fusionnée. La tâche génère un rapport JSON qui est enregistré dans le répertoire build/reports de la bibliothèque fusionnée.

Pour en savoir plus sur les dépendances internes des plug-ins, exécutez la tâche gradle :dependencies afin d'afficher l'état des configurations des plug-ins.