Cómo configurar variantes de publicación

Las variantes de las publicaciones te permiten crear una experiencia más personalizada para los usuarios. La configuración de variantes de publicación te permite publicar diferentes variantes de compilación, cada una con sus propios atributos.

La publicación de múltiples variantes de compilación de tu biblioteca permite al usuario elegir las funciones adecuadas para sus necesidades. Por ejemplo, puedes publicar diferentes artefactos para los tipos de compilación de depuración frente a lanzamiento. El artefacto de la publicación de depuración puede tener código de registro adicional y diferentes dependencias para habilitar este registro adicional.

Antes de continuar, asegúrate de preparar la biblioteca para el lanzamiento.

Cómo usar metadatos del módulo Gradle

Para publicar variantes de tu biblioteca, debes usar los metadatos del módulo Gradle (GMM). GMM describe tu publicación y mantiene la administración de dependencias con reconocimiento de variantes. Se publica con tu biblioteca de forma predeterminada.

Estos son algunos de los beneficios:

• Si usas GMM con Gradle 6.0 o una versión posterior, puedes publicar múltiples variantes de publicación, o varios artefactos, cada uno con sus propios atributos y dependencias. Si usas el archivo POM de Maven en lugar de GMM, solo puedes publicar un artefacto. Si usas un archivo POM, puedes publicar artefactos adicionales mediante clasificadores, pero esos artefactos no pueden tener sus propias dependencias.
• Gradle crea automáticamente una variante para la compilación y otra para el tiempo de ejecución, cada una con sus propias dependencias. Puedes publicar una variante para la compilación y otra para el tiempo de ejecución, de modo que el consumidor pueda elegir en función del momento en que use tu biblioteca. GMM permite que los consumidores vean diferentes dependencias para compilar y del entorno de ejecución, según el uso de la biblioteca api, implementation o compileOnly/runtimeOnly. Consulta Configuraciones de dependencias para obtener una lista completa de las dependencias. Esto está disponible incluso si publicas una sola variante de publicación.
• Cuando se usan dispositivos de prueba, se puede publicar una variante adicional con dispositivos metadatos o capacidades que permiten que el consumidor lo seleccione. Esto está disponible incluso si publicas una sola variante de publicación.

Información sobre las variantes de las publicaciones

Para comprender cómo funcionan las variantes de publicación, es útil conocer de Gradle pasos básicos de publicación. Estos son algunos conceptos clave para la publicación:

• Variante de compilación: Es la configuración que Gradle usa para compilar tu biblioteca, el producto cruzado del tipo de compilación y la variante de producto. Si deseas obtener más información, consulta el glosario de compilación de Android.
• Artefacto: Es un archivo o directorio que produce una compilación. En el contexto de la publicación de bibliotecas, un artefacto suele ser un archivo JAR o AAR.
• Variante de publicación: Es un artefacto con sus atributos, funciones y dependencias asociados. Ten en cuenta que Gradle llama a las variantes de la publicación variantes. Sin embargo, se denominan variantes de publicación en estos documentos para distinguirlas de las variantes de compilación.
• Atributo: Gradle usa atributos para identificar y seleccionar variantes de publicación cuando hay varias opciones. Por ejemplo, org.gradle.usage=java-api y org.gradle.jvm.version=11 son atributos de variantes.
• Componente de software: Es un objeto de Gradle que puede contener una o más variantes de publicación y se publica en un solo conjunto de coordenadas de Maven (groupdId:artifactId:version). Se expone en el DSL de Gradle mediante Project.getComponents().
• Publicación: Es lo que se publica en el repositorio y usan los consumidores. Las publicaciones consisten en un componente de software y sus metadatos, por ejemplo, su identidad (groupId:artifactId:version).

El complemento de Android para Gradle (AGP) 7.1 presenta un lenguaje específico del dominio (DSL) a fin de controlar las variantes de compilación que se usan durante la publicación y las que se ignoran. El DSL te permite crear instancias de SoftwareComponent que contengan cualquiera de las siguientes opciones:

• Una variante de publicación a partir de una variante de compilación
• Múltiples variantes de publicación a partir de diferentes variantes de compilación

Cuando se crea un componente de software con múltiples variantes de publicación, AGP configura atributos en cada variante que le permiten al consumidor seleccionar la variante correcta que necesita. Estos atributos provienen directamente del tipo y las variantes de compilación que se usaron para crear la variante de compilación. La creación de un componente con una sola variante de publicación no requiere atributos porque no es necesario distinguirlos.

Cómo crear un componente de software con una única variante de publicación

En el siguiente fragmento, se configura un componente de software con una sola variante de publicación creada a partir de la variante de compilación release, y se agrega el JAR de origen como artefacto secundario:

Kotlin

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

Groovy

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

Puedes crear varios componentes, cada uno con una sola variante de publicación, y distribuirlos en diferentes coordenadas de Maven. En este caso, no se establecen atributos en la variante de publicación. Por lo tanto, no puedes determinar que esta variante de publicación pertenece a la variante de compilación release si observas los metadatos de la publicación. Como solo hay una variante de publicación involucrada, no es necesario desambiguar.

Cómo crear un componente de software con múltiples variantes de publicación

Puedes seleccionar todas las variantes de compilación, o un subconjunto de ellas, y colocarlas en un solo componente de software. AGP usa automáticamente los nombres de tipo de compilación, los de variante de producto y los de dimensión de variantes de producto para crear atributos de modo que el proyecto consumidor pueda diferenciarlos.

A fin de publicar todas las variantes de compilación en un solo componente, especifica allVariants() en el bloque multipleVariants{} del archivo build.gradle al nivel del módulo:

Kotlin

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

Groovy

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

Esto crea un único componente llamado default. Para cambiar el nombre del componente, usa multipleVariants({name}). En este caso, todas las dimensiones de variantes de producto y de tipo de compilación se usan como atributos.

También puedes seleccionar qué variantes se publican con includeBuildTypeValues() y 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'
      )
    }
  }
}

En este ejemplo, el componente personalizado contiene todas las combinaciones de (debug, release) para el tipo de compilación, (blue, pink) para el color de la dimensión y (square) para la shape de la dimensión.

Se deben enumerar todas las dimensiones de variantes, incluso si solo publicas un valor de una dimensión, de modo que AGP sepa qué valor usar para cada dimensión.

En la siguiente tabla, se muestran las variantes de las publicaciones resultantes y los atributos asociados.

Nota: Como se especifica en el archivo de compilación, las variantes de compilación que usan valores de shape distintas a square no se incluyen en la publicación. Por este motivo, no se incluye el atributo de la dimensión de variantes de producto shape. El consumidor no necesita seleccionar un valor para esta dimensión. Si deseas obtener más información sobre la forma en que Gradle prioriza las variantes y dimensiones de los productos cuando le asigna nombres a variantes de compilación, consulta Cómo combinar múltiples variantes de productos con dimensiones de variantes.

Variante	Atributos
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 la práctica, se publican más variantes. Por ejemplo, cada una de las variantes anteriores se publica dos veces, una para la compilación y otra para el entorno de ejecución, con diferentes dependencias (en función de si las dependencias declaradas usan implementation o api) y con un valor diferente para el atributo org.gradle.Usage. Sin embargo, los artefactos (archivos AAR) para estas dos variantes son los mismos.

Si deseas obtener más información, consulta la documentación de la API de publishing.

Importante: Cuando se publican múltiples variantes de publicación, los nombres de las variantes de productos y de las dimensiones de variantes se incluyen en la API de publicación. Por lo tanto, el proyecto consumidor debe tener nombres de variantes y dimensiones coincidentes, o usar métodos para agregar dependencias de compilación y seleccionar de forma manual el artefacto necesario. Para los tipos de compilación, debido a que la dimensión está integrada, solo los nombres de tipo de compilación deben coincidir (o el proyecto consumidor también debe usar resguardos).

Problema de compatibilidad para publicar bibliotecas de varios tipos

Un proyecto que usa AGP 7.0 o versiones anteriores no puede consumir bibliotecas de varios tipos publicadas. con AGP 7.1 o versiones posteriores. Este es un problema conocido causado por un cambio en el atributo nombre de la dimensión de variante de producto de dimensionName a com.android.build.api.attributes.ProductFlavor:dimensionName en AGP 7.1. Según la configuración de tu proyecto, puedes usar missingDimensionStrategy en la API de la variante anterior para que funcione en torno a este tema.

Por ejemplo, supongamos que tu proyecto de aplicación solo tiene una versión de producto dimensión de variantes:

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