Publikationsvarianten konfigurieren

Mit Publikationsvarianten kannst du Nutzern ein personalisiertes Erlebnis bieten. Wenn Sie Publikationsvarianten konfigurieren, können Sie verschiedene Build-Varianten mit jeweils eigenen Attributen veröffentlichen.

Wenn Sie mehrere Build-Varianten Ihrer Bibliothek veröffentlichen, können Nutzer die für ihre Anforderungen geeigneten Funktionen auswählen. So haben Sie beispielsweise die Möglichkeit, verschiedene Artefakte für die Build-Typen Debug- und Release-Typ zu veröffentlichen. Das Artefakt der Debug-Publikation kann zusätzlichen Logging-Code und andere Abhängigkeiten haben, um dieses zusätzliche Logging zu aktivieren.

Bevor Sie fortfahren, müssen Sie Ihre Bibliothek auf die Veröffentlichung vorbereiten.

Gradle-Modulmetadaten verwenden

Wenn Sie Varianten Ihrer Bibliothek veröffentlichen möchten, müssen Sie die Gradle Module Metadata (GMM) verwenden. GMM beschreibt Ihre Publikation und verwaltet die variantenbasierte Abhängigkeitsverwaltung. GMM wird standardmäßig mit Ihrer Bibliothek veröffentlicht.

Zu den Vorteilen von GMM gehören:

• Wenn Sie GMM mit Gradle 6.0 oder höher verwenden, können Sie mehrere Publikationsvarianten oder mehrere Artefakte mit jeweils eigenen Attributen und Abhängigkeiten veröffentlichen. Wenn Sie die POM-Datei von Maven anstelle von GMM verwenden, können Sie nur ein Artefakt veröffentlichen. Bei Verwendung einer POM-Datei können Sie zusätzliche Artefakte mithilfe von Klassifikatoren veröffentlichen, diese dürfen jedoch keine eigenen Abhängigkeiten haben.
• Gradle erstellt automatisch eine Variante für die Kompilierung und eine für die Laufzeit mit jeweils eigenen Abhängigkeiten. Sie können eine Variante für die Kompilierung und eine für die Laufzeit veröffentlichen, sodass Nutzer je nachdem, wann sie Ihre Bibliothek verwenden, auswählen können. Mit GMM können Nutzer je nach Nutzung von api, implementation oder compileOnly/runtimeOnly durch die veröffentlichte Bibliothek unterschiedliche Abhängigkeiten für Kompilierung und Laufzeit sehen. Eine vollständige Liste der Abhängigkeiten finden Sie unter Abhängigkeitskonfigurationen. Das ist auch dann möglich, wenn du eine einzelne Publikationsvariante veröffentlichst.
• Wenn Sie Test-Displays verwenden, können Sie eine zusätzliche Variante mit speziellen Metadaten oder Funktionen veröffentlichen, über die der Nutzer sie auswählen kann. Das ist auch dann möglich, wenn du nur eine Variante einer Publikation veröffentlichst.

Publikationsvarianten verstehen

Damit Sie die Funktionsweise von Publikationsvarianten verstehen können, sollten Sie sich mit den grundlegenden Veröffentlichungsschritten von Gradle vertraut machen. Hier einige wichtige Konzepte der Publikation:

• Build-Variante: Die Konfiguration, die Gradle verwendet, um Ihre Bibliothek zu erstellen. Diese ist das Produkt aus Build-Typ und Produkt-Flavor. Weitere Informationen finden Sie im Android-Build-Glossar.
• Artefakt: Eine Datei oder ein Verzeichnis, die bzw. das von einem Build erstellt wird. Bei der Veröffentlichung einer Bibliothek ist ein Artefakt normalerweise eine JAR- oder AAR-Datei.
• Publikationsvariante: Ein Artefakt mit den zugehörigen Attributen, Funktionen und Abhängigkeiten. Gradle ruft die Publikationsvarianten variants auf. Sie werden in diesen Dokumenten jedoch als Publikationsvarianten bezeichnet, um sie von Build-Varianten zu unterscheiden.
• Attribut: Gradle verwendet Attribute, um Publikationsvarianten zu identifizieren und auszuwählen, wenn es mehrere Optionen gibt. org.gradle.usage=java-api und org.gradle.jvm.version=11 sind beispielsweise Variantenattribute.
• Softwarekomponente: Ein Gradle-Objekt, das eine oder mehrere Publikationsvarianten enthalten kann und in einem einzelnen Satz von Maven-Koordinaten (groupdId:artifactId:version) veröffentlicht wird. Es wird über Project.getComponents() in der DSL von Gradle verfügbar gemacht.
• Publikation: Was im Repository veröffentlicht wird und von Nutzern verwendet wird. Publikationen bestehen aus einer Softwarekomponente und ihren Metadaten, z. B. ihrer Identität (groupId:artifactId:version).

Das Android Gradle-Plug-in (AGP) 7.1 führt eine domainspezifische Sprache (DSL) ein, um zu steuern, welche Build-Varianten bei der Veröffentlichung verwendet und welche ignoriert werden. Mit der DSL können Sie Instanzen von SoftwareComponent erstellen, die eines der folgenden Elemente enthalten:

• Eine Publikationsvariante aus einer Build-Variante
• Mehrere Publikationsvarianten aus mehreren Build-Varianten

Beim Erstellen einer Softwarekomponente mit mehreren Publikationsvarianten legt AGP für jede Variante Attribute fest, damit der Nutzer die gewünschte Variante auswählen kann. Diese Attribute stammen direkt aus dem Build-Typ und den Geschmacksrichtungen, die zum Erstellen der Build-Variante verwendet wurden. Zum Erstellen einer Komponente mit einer einzelnen Publikationsvariante sind keine Attribute erforderlich, da diese nicht unterschieden werden müssen.

Softwarekomponente mit einer einzelnen Publikationsvariante erstellen

Mit dem folgenden Snippet wird eine Softwarekomponente mit einer einzelnen Publikationsvariante konfiguriert, die aus der Build-Variante release erstellt wurde, und die Quell-JAR-Datei als sekundäres Artefakt hinzugefügt:

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

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

Du kannst mehrere Komponenten mit jeweils einer einzelnen Publikationsvariante erstellen und sie unter verschiedenen Maven-Koordinaten verteilen. In diesem Fall werden keine Attribute für die Publikationsvariante festgelegt. In den Publikationsmetadaten lässt sich nicht erkennen, ob diese Publikationsvariante zur Build-Variante release gehört. Da nur eine Publikationsvariante beteiligt ist, ist keine Unterscheidung erforderlich.

Softwarekomponente mit mehreren Publikationsvarianten erstellen

Sie können alle Build-Varianten oder einen Teil davon auswählen, um sie in eine einzelne Softwarekomponente einzufügen. AGP verwendet automatisch die Namen der Build-Typen, Produktvarianten und Produktvarianten, um Attribute zu erstellen, damit das nutzende Projekt zwischen ihnen unterscheiden kann.

Wenn Sie alle Build-Varianten in einer einzelnen Komponente veröffentlichen möchten, geben Sie allVariants() im multipleVariants{}-Block in der Datei build.gradle auf Modulebene an:

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

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

Dadurch wird eine einzelne Komponente mit dem Namen default erstellt. Wenn Sie der Komponente einen anderen Namen geben möchten, verwenden Sie multipleVariants({name}). In diesem Fall werden alle Dimensionen vom Typ „Build-Typ“ und „Produktgeschmack“ als Attribute verwendet.

Mit includeBuildTypeValues() und includeFlavorDimensionAndValues() können Sie auch auswählen, welche Varianten veröffentlicht werden sollen:

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

In diesem Beispiel enthält die benutzerdefinierte Komponente alle Kombinationen von (debug, release) für den Build-Typ, (blue, pink) für die Dimension color und (square) für die Dimension shape .

Alle Flavor-Dimensionen müssen aufgelistet werden, auch wenn Sie nur einen Wert aus einer Dimension veröffentlichen, damit AGP weiß, welcher Wert für jede Dimension verwendet werden soll.

In der folgenden Tabelle sind die resultierenden Publikationsvarianten und die zugehörigen Attribute aufgeführt.

In der Praxis werden mehr Varianten veröffentlicht. Beispielsweise wird jede der oben genannten Varianten zweimal veröffentlicht, einmal zur Kompilierung und einmal für die Laufzeit, mit unterschiedlichen Abhängigkeiten (je nachdem, ob die deklarierten Abhängigkeiten implementation oder api verwenden) und mit einem anderen Wert für das Attribut org.gradle.Usage. Die Artefakte (AAR-Datei) für diese beiden Varianten sind jedoch identisch.

Weitere Informationen finden Sie in der Dokumentation zur publishing API.

Kompatibilitätsproblem beim Veröffentlichen von Bibliotheken mit mehreren Geschmacksrichtungen

Ein Projekt, das AGP 7.0 oder niedriger verwendet, kann keine Multi-Flavor-Bibliotheken nutzen, die mit AGP 7.1 oder höher veröffentlicht wurden. Dies ist ein bekanntes Problem, das durch eine Änderung des Attributnamens für die Dimension „Produktgeschmack“ von dimensionName zu com.android.build.api.attributes.ProductFlavor:dimensionName in AGP 7.1 verursacht wird. Je nach Einrichtung Ihres Projekts können Sie missingDimensionStrategy in der alten API-Variante verwenden, um dieses Problem zu umgehen.

Angenommen, Ihr Anwendungsprojekt hat nur eine Dimension für die Produktvarianten:

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