Skonfiguruj warianty publikacji

Warianty publikacji umożliwiają dostosowanie treści do potrzeb użytkowników. Skonfigurowanie wariantów publikacji umożliwia publikowanie różnych wariantów kompilacji, z których każdy ma własne atrybuty.

Jeśli opublikujesz kilka wariantów kompilacji, użytkownicy będą mogli wybrać funkcje dopasowane do swoich potrzeb. Możesz na przykład publikować różne artefakty do kompilacji debugowania i wersji. Artefakt publikacji na potrzeby debugowania może mieć dodatkowy kod logowania i różne zależności, aby umożliwić to dodatkowe logowanie.

Zanim przejdziesz dalej, przygotuj bibliotekę do udostępnienia.

Użyj metadanych modułu Gradle

Aby publikować warianty biblioteki, musisz używać metadanych modułu Gradle (GMM). GMM opisuje Twoją publikację i utrzymuje zarządzanie zależnościami z uwzględnieniem wariantów. Aplikacja GMM jest domyślnie publikowana w Twojej bibliotece.

Zalety korzystania z GMM:

• Jeśli używasz GMM z Gradle w wersji 6.0 lub nowszej, możesz opublikować wiele wariantów publikacji lub artefaktów, z których każdy będzie miał własne atrybuty i zależności. Jeśli używasz pliku POM Maven zamiast GMM, możesz opublikować tylko jeden artefakt. Jeśli używasz pliku POM, możesz opublikować dodatkowe artefakty za pomocą klasyfikatorów, ale dodatkowe artefakty nie mogą mieć własnych zależności.
• Gradle automatycznie tworzy 1 wariant na potrzeby kompilacji i 1 dla środowiska wykonawczego, każdy z własnymi zależnościami. Możesz opublikować jeden wariant do kompilacji, a drugi do środowiska wykonawczego, aby klient mógł dokonać wyboru na podstawie tego, kiedy korzysta z Twojej biblioteki. Usługa GMM zapewnia klientom wgląd w różne zależności kompilacji i czasu działania w zależności od wykorzystania w opublikowanej bibliotece funkcji api, implementation lub compileOnly/runtimeOnly. Pełną listę zależności znajdziesz w sekcji Konfiguracje zależności. Jest to możliwe nawet wtedy, gdy publikujesz pojedynczy wariant publikacji.
• Jeśli używasz sprzętu testowego, możesz opublikować dodatkowy wariant ze specjalnymi metadanymi lub możliwościami, które pozwolą konsumentom wybrać ten wariant. Ta opcja jest dostępna nawet wtedy, gdy publikujesz tylko 1 wariant publikacji.

Omówienie wariantów publikacji

Aby zrozumieć, jak działają warianty publikacji, warto zapoznać się z podstawowymi krokami publikowania Gradle. Oto kilka najważniejszych kwestii dotyczących publikacji:

• Wariant kompilacji: konfiguracja, której używa Gradle, do utworzenia biblioteki, która jest usługą obejmującą różne typy kompilacji i smaki usługi. Więcej informacji znajdziesz w glosariuszu kompilacji Androida.
• Artefakt: plik lub katalog utworzony przez kompilację. W kontekście publikowania w bibliotece artefaktem jest zwykle plik JAR lub AAR.
• Wariant publikacji: artefakt z powiązanymi atrybutami, funkcjami i zależnościami. Pamiętaj, że Gradle wywołuje warianty publikacji warianty. W tych dokumentach są one jednak nazywane wariantami publikacji, aby odróżnić je od wariantów kompilacji.
• Atrybut: Gradle używa atrybutów do identyfikowania i wybierania wariantów publikacji, jeśli dostępnych jest wiele opcji. Na przykład org.gradle.usage=java-api i org.gradle.jvm.version=11 to atrybuty wersji.
• Komponent oprogramowania: obiekt Gradle, który może zawierać co najmniej 1 wariant publikacji i jest opublikowany w jednym zestawie współrzędnych Maven (groupdId:artifactId:version). Udostępnia go w strumieniu DSL Gradle za pomocą Project.getComponents().
• Publikacja – co jest publikowane w repozytorium i z których korzystają klienci. Publikacje składają się z jednego komponentu oprogramowania i jego metadanych – na przykład z tożsamości (groupId:artifactId:version).

Wtyczka Androida do obsługi Gradle (AGP) 7.1 wprowadza język specyficzny dla domeny (DSL), aby umożliwić kontrolowanie, które warianty kompilacji mają być używane podczas publikacji, a które mają być ignorowane. DSL pozwala tworzyć instancje SoftwareComponent, które zawierają:

• 1 wariant publikacji z 1 wariantu kompilacji
• Kilka wariantów publikacji z kilku wariantów kompilacji

Gdy tworzysz komponent oprogramowania z wieloma wersjami publikacji, AGP ustawia dla każdego z nich atrybuty, które umożliwiają konsumentowi wybranie odpowiedniej wersji. Te atrybuty pochodzą bezpośrednio z typu kompilacji i smaków używanych do tworzenia wariantu kompilacji. Tworzenie komponentu z jednym wariantem publikacji nie wymaga atrybutów, bo nie ma potrzeby rozróżniania.

Tworzenie komponentu oprogramowania z 1 wariantem publikacji

Ten fragment kodu konfiguruje komponent oprogramowania z pojedynczą wersją publikacji utworzoną na podstawie wariantu kompilacji release i dodaje źródłowy plik JAR jako artefakt dodatkowy:

Kotlin

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

Odlotowy

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

Możesz utworzyć kilka komponentów, z których każdy ma 1 wariant publikacji, i rozmieszczać je według różnych współrzędnych Maven. W tym przypadku atrybuty nie są ustawione dla wariantu publikacji. Po przeanalizowaniu metadanych publikacji nie można stwierdzić, że pochodzi ona z wariantu kompilacji release. Nie ma potrzeby ujednoznacznienia, ponieważ uwzględniamy tylko 1 wariant publikacji.

Tworzenie komponentu oprogramowania z kilkoma wersjami publikacji

Możesz wybrać wszystkie wersje kompilacji lub ich część, by umieścić je w jednym komponencie oprogramowania. AGP automatycznie używa nazw typów kompilacji, nazw smaków i wymiarów smaków produktu do tworzenia atrybutów, dzięki czemu użytkownik może je odróżnić.

Aby opublikować wszystkie warianty kompilacji w jednym komponencie, w bloku multipleVariants{} wpisz allVariants() w pliku build.gradle na poziomie modułu:

Kotlin

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

Odlotowy

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

Spowoduje to utworzenie jednego komponentu o nazwie default. Jeśli chcesz nadać komponentowi inną nazwę, użyj multipleVariants({name}). W takim przypadku jako atrybuty są używane wszystkie wymiary typu kompilacji i smaku produktu.

Za pomocą właściwości includeBuildTypeValues() i includeFlavorDimensionAndValues() możesz też wybrać opublikowane warianty:

Kotlin

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

Odlotowy

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

W tym przykładzie komponent niestandardowy zawiera wszystkie kombinacje (debug, release) dla typu kompilacji, (blue, pink) dla wymiaru color i (square) dla wymiaru shape .

Musisz podawać wszystkie wymiary ze względu na smak, nawet jeśli publikujesz tylko jedną wartość z danego wymiaru, dzięki czemu AGP będzie wiedzieć, której wartości użyć w przypadku każdego wymiaru.

W tabeli poniżej znajdziesz wygenerowane wersje publikacji wraz z powiązanymi atrybutami.

Uwaga: jak określono w pliku kompilacji, warianty kompilacji, które używają wartości shape innych niż square, nie są uwzględnione w publikacji. Z tego powodu atrybut wymiaru smaku produktu shape nie został uwzględniony. Klient nie musi wybierać wartości w przypadku tego wymiaru. Więcej informacji o tym, jak Gradle nadaje priorytet smakom i wymiarom produktów podczas nadawania nazw wersji kompilacji, przeczytaj artykuł Łączenie różnych smaków produktów z wymiarami smaków.

Wariant	Atrybuty
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"

W praktyce pojawia się więcej wariantów. Na przykład każdy z powyższych wariantów jest publikowany 2 razy: raz na potrzeby kompilacji i drugi w czasie działania z różnymi zależnościami (w zależności od tego, czy zadeklarowane zależności używają implementation czy api) i z inną wartością atrybutu org.gradle.Usage. Jednak artefakty (plik AAR) w przypadku tych 2 wariantów są takie same.

Więcej informacji znajdziesz w dokumentacji interfejsu API publishing.

Ważne: gdy publikujesz wiele wersji publikacji, nazwy smaków produktów i wymiarów smaków stają się częścią interfejsu API publikowania. Projekt, który ją pobiera, powinien mieć pasujące nazwy rodzaju i wymiarów lub użyć metod, aby dodać zależności kompilacji i ręcznie wybrać potrzebny artefakt. W przypadku typów kompilacji, ponieważ wymiar jest wbudowany, pasujące są tylko nazwy typów kompilacji lub projekt konsumenta musi też używać kreacji zastępczych.

Problem ze zgodnością przy publikowaniu bibliotek o wielu smakach

Projekt, w którym stosuje się standard AGP w wersji 7.0 lub starszej, nie może używać bibliotek o różnych rodzajach opublikowanych w interfejsie AGP w wersji 7.1 lub nowszej. Jest to znany problem spowodowany zmianą nazwy atrybutu wymiaru smaku produktu z dimensionName na com.android.build.api.attributes.ProductFlavor:dimensionName w AGP.1. W zależności od konfiguracji projektu możesz obejść ten problem, używając missingDimensionStrategy w starym interfejsie API.

Załóżmy np., że Twój projekt aplikacji ma tylko wymiar smaku wersji:

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

Odlotowy

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