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 la compilación y el entorno de ejecución, según el uso que haga la biblioteca publicada de api, implementation o compileOnly/runtimeOnly. Consulta Configuraciones de dependencias a fin de obtener una lista completa. Esto está disponible incluso si publicas una sola variante de publicación.
• Cuando usas dispositivos de prueba, puedes publicar una variante adicional con metadatos o capacidades especiales que permita al consumidor seleccionarla. 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 familiarizarte con los pasos de publicación básicos de Gradle. 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:

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

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:

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

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():

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

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.

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.

Problema de compatibilidad para publicar bibliotecas de varios tipos

Un proyecto que use 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 nombre del atributo para la dimensión de variantes 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 solucionar este problema.

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

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

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