Configurare le varianti di pubblicazione

Le varianti della pubblicazione ti consentono di creare un'esperienza più personalizzata per i tuoi utenti. La configurazione delle varianti di pubblicazione ti consente di pubblicare diverse varianti di build, ciascuna con i propri attributi.

La pubblicazione di più varianti di build della tua libreria consente all'utente di scegliere le funzionalità appropriate per le sue esigenze. Ad esempio, puoi pubblicare elementi diversi per i tipi di build debug e release. L'artefatto della pubblicazione di debug potrebbe avere codice di logging aggiuntivo e dipendenze diverse per abilitare questo logging aggiuntivo.

Prima di procedere, assicurati di preparare la raccolta per l'uscita.

Utilizza i metadati del modulo Gradle

Per pubblicare varianti della tua libreria, devi utilizzare Gradle Module Metadata (GMM). GMM descrive la tua pubblicazione e gestisce la gestione delle dipendenze sensibile alle varianti. Per impostazione predefinita, Google Maps per cellulari viene pubblicato con la libreria.

I vantaggi dell'utilizzo di Google Maps per cellulari includono:

• Se utilizzi GMM con Gradle 6.0 o versioni successive, puoi pubblicare più varianti di pubblicazione o più artefatti, ciascuno con i propri attributi e dipendenze. Se utilizzi il file POM di Maven anziché GMM, puoi pubblicare un solo artefatto. Se utilizzi un file POM, puoi pubblicare artefatti aggiuntivi utilizzando i classificatori, ma gli artefatti aggiuntivi non possono avere dipendenze.
• Gradle crea automaticamente una variante per la compilazione e una per il runtime, ciascuna con le proprie dipendenze. Potresti pubblicare una variante per la compilazione e una per il runtime, in modo che il consumatore possa scegliere in base a quando utilizza la tua libreria. GMM consente ai consumatori di visualizzare diverse dipendenze per la compilazione e il runtime, in base all'utilizzo di api, implementation o compileOnly/runtimeOnly da parte della libreria pubblicata. Consulta Configurazioni delle dipendenze per un elenco completo delle dipendenze. Questa opzione è disponibile anche se pubblichi una variante della pubblicazione singola.
• Quando utilizzi gli impianti di test, puoi pubblicare una variante aggiuntiva con metadati o funzionalità speciali che consentano al consumatore di selezionarla. Questa opzione è disponibile anche se pubblichi una singola variante della pubblicazione.

Informazioni sulle varianti della pubblicazione

Per capire come funzionano le varianti di pubblicazione, è utile avere familiarità con la procedura di pubblicazione di base di Gradle. Di seguito sono riportati alcuni concetti chiave della pubblicazione:

• Variante build: la configurazione utilizzata da Gradle per creare la tua libreria, ovvero il cross-product tra tipo di build e versione del prodotto. Per scoprire di più, consulta il glossario della build di Android.
• Artefatto: un file o una directory prodotto da una build. Nell'ambito della pubblicazione delle librerie, un artefatto è solitamente un file JAR o AAR.
• Variante della pubblicazione: un artefatto con gli attributi, le funzionalità e le dipendenze associati. Tieni presente che Gradle chiama le varianti di pubblicazione varianti. Tuttavia, in questi documenti sono chiamate varianti della pubblicazione per distinguerle dalle varianti della build.
• Attributo: Gradle utilizza gli attributi per identificare e selezionare le varianti della pubblicazione quando sono disponibili più opzioni. Ad esempio, org.gradle.usage=java-api e org.gradle.jvm.version=11 sono attributi delle varianti.
• Componente software: un oggetto Gradle che può contenere una o più varianti di pubblicazione ed è pubblicato in un singolo set di coordinate Maven (groupdId:artifactId:version). Viene esposto nella DSL di Gradle fino al giorno Project.getComponents().
• Pubblicazione: cosa viene pubblicato nel repository e utilizzato dai consumatori. Le pubblicazioni sono composte da un componente software e dai relativi metadati, ad esempio la sua identità (groupId:artifactId:version).

Il plug-in Android per Gradle (AGP) 7.1 introduce un linguaggio specifico del dominio (DSL) per controllare quali varianti di build vengono utilizzate durante la pubblicazione e quali vengono ignorate. Il DSL ti consente di creare istanze di SoftwareComponent che contengono uno dei seguenti elementi:

• Una variante della pubblicazione da una variante di build
• Diverse varianti della pubblicazione da diverse varianti di build

Quando crea un componente software con più varianti di pubblicazione, il programma AGP imposta degli attributi per ogni variante, consentendo al consumatore di selezionare la variante appropriata di cui ha bisogno. Questi attributi provengono direttamente dal tipo di build e dalle versioni utilizzate per creare la variante. La creazione di un componente con una variante di pubblicazione singola non richiede attributi perché non è necessario fare una distinzione.

Creare un componente software con una singola variante di pubblicazione

Lo snippet seguente configura un componente software con una singola variante di pubblicazione creata dalla variante di build release e aggiunge il JAR di origine come artefatto secondario:

Kotlin

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

Trendy

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

Puoi creare diversi componenti, ciascuno con una singola variante di pubblicazione, e distribuirli sotto diverse coordinate Maven. In questo caso, gli attributi non sono impostati sulla variante della pubblicazione. Non puoi capire se questa variante della pubblicazione proviene dalla variante build release esaminando i metadati della pubblicazione. Poiché è coinvolta una sola variante di pubblicazione, non è necessaria alcuna disambiguazione.

Creare un componente software con più varianti di pubblicazione

Puoi selezionare tutte o un sottoinsieme di varianti di build da inserire in un singolo componente software. AGP utilizza automaticamente i nomi dei tipi di build, i nomi delle versioni del prodotto e delle dimensioni del prodotto per creare attributi in modo che il progetto utilizzato possa distinguerli.

Per pubblicare tutte le varianti build in un singolo componente, specifica allVariants() nel blocco multipleVariants{} nel file build.gradle a livello di modulo:

Kotlin

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

Trendy

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

In questo modo viene creato un singolo componente denominato default. Per assegnare un altro nome al componente, utilizza multipleVariants({name}). In questo caso, tutte le dimensioni relative al tipo di build e alla versione del prodotto vengono utilizzate come attributi.

Puoi anche selezionare quali varianti vengono pubblicate utilizzando includeBuildTypeValues() e includeFlavorDimensionAndValues():

Kotlin

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

Trendy

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

In questo esempio, il componente personalizzato contiene tutte le combinazioni di (debug, release) per il tipo di build, (blue, pink) per la dimensione color e (square) per la dimensione shape .

Anche se pubblichi un solo valore per dimensione, devono essere elencate tutte le dimensioni versione, in modo che AGP sappia quale valore utilizzare per ogni dimensione.

La seguente tabella elenca le varianti di pubblicazione risultanti e i relativi attributi associati.

Nota: come specificato nel file di build, le varianti di build che utilizzano valori shape diversi da square non sono incluse nella pubblicazione. Per questo motivo, l'attributo per la dimensione gusto prodotto shape non è incluso. Il consumatore non deve selezionare un valore per questa dimensione. Per saperne di più su come Gradle assegna la priorità ai gusti e alle dimensioni dei prodotti nella denominazione delle varianti di build, consulta l'articolo Combinare più gusti di prodotto con le dimensioni delle varianti.

Variante	Attributi
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"

In pratica, vengono pubblicate più varianti. Ad esempio, ciascuna delle varianti precedenti viene pubblicata due volte, una per la compilazione e l'altra per il runtime, con dipendenze diverse (in base all'uso di implementation o api da parte delle dipendenze dichiarate) e con un valore diverso per l'attributo org.gradle.Usage. Tuttavia, gli artefatti (file AAR) per queste due varianti sono gli stessi.

Per ulteriori informazioni, consulta la documentazione dell'API publishing.

Importante: quando pubblichi più varianti di pubblicazione, i nomi dei gusti e delle dimensioni dei prodotti diventano parte dell'API di pubblicazione. Di conseguenza, il progetto in uso dovrebbe avere nomi di versione e dimensione corrispondenti oppure utilizzare metodi per aggiungere dipendenze di build e selezionare manualmente l'artefatto necessario. Per i tipi di build, poiché la dimensione è integrata, devono corrispondere solo i nomi del tipo di build oppure il progetto consumer deve utilizzare anche i fallback.

Problema di compatibilità per la pubblicazione di librerie multicolore

Un progetto che utilizza AGP 7.0 o versioni precedenti non può utilizzare librerie multi versione pubblicate con AGP 7.1 o versioni successive. Si tratta di un problema noto causato da una modifica al nome dell'attributo per la dimensione flavor del prodotto da dimensionName a com.android.build.api.attributes.ProductFlavor:dimensionName in AGP 7.1. A seconda della configurazione del progetto, puoi utilizzare missingDimensionStrategy nell'API della variante precedente per risolvere questo problema.

Ad esempio, supponiamo che il progetto dell'applicazione abbia solo una dimensione versione del prodotto:

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

Trendy

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