Configurer les variantes de publication

Les variantes de publication vous permettent de proposer une expérience plus personnalisée à vos utilisateurs. Configurer des variantes de publication permet de publier différentes variantes de compilation, chacune avec ses propres attributs.

Ces différentes variantes de compilation de votre bibliothèque permettent à vos utilisateurs de choisir les fonctionnalités qui répondent à leurs besoins. Par exemple, vous pouvez publier des artefacts différents pour les types de compilation débogage ou release. Votre artefact de publication de débogage pourrait comporter un code de journalisation supplémentaire et différentes dépendances nécessaires à son exécution.

Avant de continuer, assurez-vous de préparer votre bibliothèque n vue de sa publication.

Utiliser les métadonnées du module Gradle

Pour publier des variantes de votre bibliothèque, vous devez utiliser les métadonnées du module Gradle (GMM). Les GMM décrivent votre publication et assurent la gestion des dépendances basée sur les variantes. Par défaut, les GMM sont publiées dans votre bibliothèque.

Voici quelques avantages des GMM :

• Si vous utilisez les GMM avec Gradle 6.0 ou une version ultérieure, vous pouvez publier plusieurs variantes de publication ou plusieurs artefacts, chacun avec ses propres attributs et dépendances. Si vous utilisez le fichier POM de Maven au lieu de GMM, vous ne pouvez publier qu'un seul artefact. Si vous utilisez un fichier POM, vous pouvez publier d'autres artefacts à l'aide de classificateurs, mais ces artefacts ne peuvent pas avoir leurs propres dépendances.
• Gradle crée automatiquement une variante pour la compilation et une pour l'environnement d'exécution, chacune avec ses propres dépendances. Vous pouvez publier une variante pour la compilation et une autre pour l'environnement d'exécution, afin que le consommateur puisse choisir en fonction du moment où il utilise votre bibliothèque. Les GMM permettent aux consommateurs de voir différentes dépendances pour la compilation et l'exécution, en fonction de l'utilisation de api, implementation ou compileOnly/runtimeOnly dans la bibliothèque publiée. Consultez la section Configurations de dépendances pour obtenir la liste complète des dépendances. Cette option est disponible même si vous ne publiez qu'une seule variante de publication.
• Lorsque vous utilisez des outils de test, vous pouvez publier une variante supplémentaire avec des métadonnées ou des fonctionnalités spéciales permettant au consommateur de la sélectionner. Cette option est disponible même si vous ne publiez qu'une seule variante de publication.

Comprendre les variantes de publication

Pour comprendre le fonctionnement des variantes de publication, il est utile de vous familiariser avec les étapes de publication de base de Gradle. Voici quelques concepts clés de publication :

• Variante de compilation : la configuration que Gradle utilise pour compiler votre bibliothèque. Il s'agit du produit croisé de votre type de compilation et de votre type de produit. Pour en savoir plus, consultez le glossaire de la compilation Android.
• Artefact : un fichier ou un répertoire produit par une compilation. Dans un contexte de publication de bibliothèque, un artefact est généralement un fichier JAR ou AAR.
• Variante de publication : un artefact avec les attributs, fonctionnalités et dépendances associées. Notez que Gradle appelle les variantes de publication variants. Toutefois, on les appelle variantes de publication dans ces documents pour les distinguer des variantes de compilation.
• Attribut : un élément qui permet à Gradle d'identifier et de sélectionner des variantes de publication lorsqu'il existe plusieurs options. Par exemple, org.gradle.usage=java-api et org.gradle.jvm.version=11 sont des attributs de variante.
• Composant logiciel : un objet Gradle pouvant contenir une ou plusieurs variantes de publication. Publié dans un même ensemble de coordonnées Maven (groupdId:artifactId:version) et exposé dans le DSL de Gradle via Project.getComponents().
• Publication : éléments publiés dans le dépôt et utilisés par les consommateurs. Les publications consistent en un composant logiciel et des métadonnées, telles que son identité (groupId:artifactId:version).

Le plug-in Android Gradle (AGP) 7.1 introduit un langage spécifique au domaine (DSL) pour déterminer quelles variantes de compilation sont utilisées ou ignorées lors de la publication. Le DSL vous permet de créer des instances de SoftwareComponent contenant l'un des éléments suivants :

• Une variante de publication provenant d'une variante de compilation
• Plusieurs variantes de publication provenant de plusieurs variantes de compilation

Lors de la création d'un composant logiciel avec plusieurs variantes de publication, AGP définit des attributs pour chaque variante afin de permettre au consommateur de sélectionner la variante dont il a besoin. Ces attributs proviennent directement du type de compilation et des types de produit utilisés pour créer la variante de compilation. La création d'un composant avec une seule variante de publication ne nécessite pas d'attributs, car il n'y a pas d'ambiguïté.

Créer un composant logiciel avec une seule variante de publication

L'extrait de code suivant configure un composant logiciel avec une seule variante de publication, créée à partir de la variante de compilation release, et ajoute le fichier JAR source en tant qu'artefact secondaire :

Kotlin

android {
  publishing {
    singleVariant("release") {
        withSourcesJar()
    }
  }
}

Groovy

android {
  publishing {
    singleVariant('release') {
        withSourcesJar()
    }
  }
}

Vous pouvez créer plusieurs composants, chacun avec une seule variante de publication, et les distribuer sous différentes coordonnées Maven. Dans ce cas, les attributs ne sont pas définis pour la variante de publication. Examiner les métadonnées de la publication ne permet pas de savoir si cette variante de publication provient de la variante de compilation release. Étant donné qu'il n'y a qu'une seule variante de publication, il n'y a aucune ambiguïté.

Créer un composant logiciel avec plusieurs variantes de publication

Vous pouvez sélectionner toutes vos variantes de compilation, ou seulement un sous-ensemble, et les intégrer dans un composant logiciel unique. AGP utilise automatiquement les noms des types de compilation, types de produit et groupes de types de produit pour créer des attributs permettant au projet de les distinguer.

Pour publier toutes les variantes de compilation dans un seul composant, spécifiez allVariants() dans le bloc multipleVariants{} du fichier build.gradle au niveau du module :

Kotlin

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

Groovy

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

Cette opération crée un unique composant nommé default. Pour attribuer un autre nom à votre composant, utilisez multipleVariants({name}). Dans ce cas, tous les types de compilation et groupes de types de produit sont utilisés en tant qu'attributs.

Vous pouvez également sélectionner les variantes publiées à l'aide de includeBuildTypeValues() et includeFlavorDimensionAndValues() :

Kotlin

android {
  publishing {
    multipleVariants("custom") {
      includeBuildTypeValues("debug", "release")
      includeFlavorDimensionAndValues(
        dimension = "color",
        values = arrayOf("blue", "pink")
      )
        includeFlavorDimensionAndValues(
          dimension = "shape",
          values = arrayOf("square")
      )
    }
  }
}

Groovy

android {
  publishing {
    multipleVariants('custom') {
      includeBuildTypeValues('debug', 'release')
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'color',
        /*values =*/ 'blue', 'pink'
      )
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'shape',
        /*values =*/ 'square'
      )
    }
  }
}

Dans cet exemple, le composant personnalisé contient toutes les combinaisons (debug, release) pour le type de compilation, (blue, pink) pour le groupe de types color, et (square) pour le groupe de types shape.

Tous les groupes de types de produit doivent être répertoriés, même si vous ne publiez qu'une seule valeur d'un groupe donné, pour qu'AGP sache quelle valeur utiliser pour chaque groupe.

Le tableau suivant répertorie les variantes de publication obtenues et leurs attributs associés.

Note : comme indiqué dans le fichier de compilation, les variantes de compilation qui utilisent des valeurs shape autres que square ne sont pas incluses dans la publication. Pour cette raison, l'attribut du groupe de types de produit shape n'est pas inclus. Le consommateur n'a pas besoin de sélectionner de valeur pour ce groupe. Pour en savoir plus sur la façon dont Gradle donne la priorité aux types et groupes de types de produit lors de l'attribution d'un nom aux variantes de compilation, consultez la section Combiner plusieurs types de produit avec plusieurs groupes de types.

Variante	Attributs
blueSquareDebug	com.android.build.api.attributes.BuildTypeAttr="debug" com.android.build.api.attributes.ProductFlavorAttr:color="blue"
blueSquareRelease	com.android.build.api.attributes.BuildTypeAttr="release" com.android.build.api.attributes.ProductFlavorAttr:color="blue"
pinkSquareDebug	com.android.build.api.attributes.BuildTypeAttr="debug" com.android.build.api.attributes.ProductFlavorAttr:color="pink"
pinkSquareRelease	com.android.build.api.attributes.BuildTypeAttr="release" com.android.build.api.attributes.ProductFlavorAttr:color="pink"

En pratique, davantage de variantes sont publiées. Par exemple, chacune des variantes ci-dessus est publiée deux fois, une pour la compilation et une pour l'exécution, avec des dépendances différentes (selon que les dépendances déclarées utilisent implementation ou api), et avec une valeur différente pour l'attribut org.gradle.Usage. Toutefois, les artefacts (fichier AAR) de ces deux variantes sont identiques.

Pour plus d'informations, consultez la section Documentation sur l'API publishing.

Important : Lorsque vous publiez plusieurs variantes de publication, les noms des types de produit et des groupes de types de produit sont intégrés à l'API de publication. Par conséquent, soit les noms de type de produit et de groupe de types doivent correspondre dans le projet consommateur, soit vous devez utiliser des méthodes pour ajouter des dépendances de compilation et sélectionner manuellement l'artefact nécessaire. Pour les types de compilation, puisque le groupe de types est intégré, seuls les noms des types de compilation doivent correspondre, sans quoi le projet consommateur doit également utiliser des alternatives de remplacement.

Problème de compatibilité pour la publication de bibliothèques à plusieurs types

Un projet utilisant AGP 7.0 ou une version antérieure ne peut pas utiliser les bibliothèques à plusieurs types publiées avec AGP 7.1 ou une version ultérieure. Il s'agit d'un problème connu causé par la modification du nom de l'attribut du groupe de types de produit de dimensionName à com.android.build.api.attributes.ProductFlavor:dimensionName dans AGP 7.1. En fonction de la configuration de votre projet, vous pouvez utiliser missingDimensionStrategy dans l'ancienne API des variantes pour contourner ce problème.

Par exemple, supposons que votre projet d'application ne comporte qu'un groupe de types de produit de version:

Kotlin

android {
    applicationVariants.forEach { variant ->
        val flavor = variant.productFlavors[0].name
        val attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        val dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}

Groovy

android {
    applicationVariants.forEach { variant ->
        def flavor = variant.getProductFlavors()[0].name
        def attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        def dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}