Mengonfigurasi varian publikasi

Varian publikasi memungkinkan Anda membuat pengalaman yang lebih disesuaikan bagi pengguna Anda. Mengonfigurasi varian publikasi memungkinkan Anda memublikasikan berbagai varian build dengan atributnya masing-masing.

Dengan memublikasikan beberapa varian build library, pengguna dapat memilih fitur yang sesuai dengan kebutuhan mereka. Misalnya, Anda dapat memublikasikan artefak yang berbeda untuk jenis build debug atau rilis. Artefak publikasi debug mungkin memiliki kode logging tambahan, dan dependensi yang berbeda untuk mengaktifkan logging tambahan ini.

Sebelum melanjutkan, pastikan Anda menyiapkan library untuk rilis.

Menggunakan Metadata Modul Gradle

Untuk memublikasikan varian library, Anda harus menggunakan Metadata Modul Gradle (GMM). GMM mendeskripsikan publikasi Anda dan mempertahankan pengelolaan dependensi berdasarkan varian. GMM dipublikasikan dengan library Anda secara default.

Manfaat menggunakan GMM meliputi:

• Jika menggunakan GMM dengan Gradle 6.0 atau yang lebih baru, Anda dapat memublikasikan beberapa varian publikasi atau beberapa artefak—masing-masing dengan atribut dan dependensinya sendiri. Jika menggunakan file POM Maven, bukan GMM, Anda hanya dapat memublikasikan satu artefak. Jika menggunakan file POM, Anda dapat memublikasikan artefak tambahan menggunakan pengklasifikasi, tetapi artefak tambahan tersebut tidak boleh memiliki dependensinya sendiri.
• Gradle akan otomatis membuat satu varian untuk kompilasi dan satu varian untuk runtime, dengan dependensinya masing-masing. Anda dapat memublikasikan satu varian untuk kompilasi dan satu varian untuk runtime agar konsumen dapat memilih berdasarkan kapan mereka menggunakan library Anda. GMM memungkinkan konsumen melihat dependensi yang berbeda untuk kompilasi dan runtime, berdasarkan penggunaan library yang dipublikasikan dari api, implementation, atau compileOnly/runtimeOnly. Baca Konfigurasi dependensi untuk mengetahui daftar lengkap dependensi. Fitur ini tersedia meskipun Anda memublikasikan satu varian publikasi.
• Saat menggunakan perlengkapan pengujian, Anda dapat memublikasikan varian tambahan dengan metadata khusus atau kemampuan yang memungkinkan konsumen memilihnya. Fitur ini tersedia meskipun Anda memublikasikan satu varian publikasi.

Memahami varian publikasi

Untuk memahami cara kerja varian publikasi, sebaiknya pahami langkah-langkah publikasi dasar Gradle. Berikut adalah beberapa konsep utama publikasi:

• Varian build: Konfigurasi yang digunakan Gradle untuk mem-build library Anda, yang merupakan cross product dari jenis build dan ragam produk. Untuk mempelajari lebih lanjut, lihat glosarium build Android.
• Artefak: File atau direktori yang dihasilkan build. Dalam konteks publikasi library, artefak biasanya berupa file JAR atau AAR.
• Varian publikasi: Artefak dengan atribut, fitur, dan dependensi terkait. Perlu diperhatikan bahwa Gradle memanggil varian publikasi sebagai varian. Namun, varian tersebut disebut varian publikasi dalam dokumen ini untuk membedakannya dari varian build.
• Atribut: Gradle menggunakan atribut untuk mengidentifikasi dan memilih varian publikasi jika ada beberapa opsi. Misalnya, org.gradle.usage=java-api dan org.gradle.jvm.version=11 adalah atribut varian.
• Komponen software: Objek Gradle yang dapat menyimpan satu atau beberapa varian publikasi, dan dipublikasikan ke satu kumpulan koordinat Maven (groupdId:artifactId:version). Objek tersebut ditampilkan dalam DSL Gradle melalui Project.getComponents().
• Publikasi: Apa yang dipublikasikan ke repositori dan digunakan oleh konsumen. Publikasi terdiri dari satu komponen software dan metadatanya, misalnya, identitasnya (groupId:artifactId:version).

Plugin Android Gradle (AGP) 7.1 memperkenalkan bahasa khusus domain (DSL) untuk mengontrol varian build mana yang digunakan selama publikasi dan mana yang diabaikan. DSL memungkinkan Anda membuat instance SoftwareComponent yang berisi salah satu dari hal berikut:

• Satu varian publikasi dari satu varian build
• Beberapa varian publikasi dari beberapa varian build

Saat membuat komponen software dengan beberapa varian publikasi, AGP menyiapkan atribut pada setiap varian yang memungkinkan konsumen memilih varian yang sesuai dengan kebutuhan mereka. Atribut ini berasal langsung dari jenis dan ragam build yang digunakan untuk membuat varian build. Pembuatan komponen dengan satu varian publikasi tidak memerlukan atribut karena tidak perlu membedakannya.

Membuat komponen software dengan satu varian publikasi

Cuplikan berikut mengonfigurasi komponen software dengan satu varian publikasi yang dibuat dari varian build release dan menambahkan JAR sumber sebagai artefak sekunder:

Kotlin

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

Groovy

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

Anda dapat membuat beberapa komponen, masing-masing dengan satu varian publikasi, dan mendistribusikannya dalam koordinat Maven yang berbeda. Dalam hal ini, atribut tidak ditetapkan pada varian publikasi. Anda tidak dapat mengetahui bahwa varian publikasi ini berasal dari varian build release dengan melihat metadata publikasi. Karena hanya ada satu varian publikasi yang terlibat, disambiguasi tidak diperlukan.

Membuat komponen software dengan beberapa varian publikasi

Anda dapat memilih semua atau subset varian build yang akan dimasukkan ke dalam satu komponen software. AGP akan otomatis menggunakan nama jenis build, nama ragam produk, dan nama dimensi ragam produk untuk membuat atribut, sehingga project yang menggunakannya dapat membedakannya.

Untuk memublikasikan semua varian build dalam satu komponen, tentukan allVariants() dalam blok multipleVariants{} pada file build.gradle level modul:

Kotlin

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

Groovy

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

Tindakan ini akan membuat satu komponen yang disebut default. Untuk menamai komponen Anda dengan nama lain, gunakan multipleVariants({name}). Dalam hal ini, semua jenis build dan dimensi ragam produk digunakan sebagai atribut.

Anda juga dapat memilih varian mana yang dipublikasikan menggunakan includeBuildTypeValues() dan 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'
      )
    }
  }
}

Pada contoh ini, komponen kustom berisi semua kombinasi debug, release) untuk jenis build, (blue, pink) untuk dimensi color, dan (square) untuk dimensi shape.

Semua dimensi ragam harus dicantumkan, meskipun Anda hanya memublikasikan satu nilai dari dimensi, sehingga AGP mengetahui nilai mana yang akan digunakan untuk setiap dimensi.

Tabel berikut mencantumkan varian publikasi yang dihasilkan beserta atribut terkaitnya.

Catatan: Seperti yang disebutkan dalam file build, varian build yang menggunakan nilai shape selain square tidak disertakan dalam publikasi. Oleh karena itu, atribut untuk dimensi ragam produk shape tidak disertakan. Konsumen tidak perlu memilih nilai untuk dimensi ini. Untuk informasi selengkapnya tentang cara Gradle memprioritaskan ragam dan dimensi produk saat menamai varian build, lihat Menggabungkan beberapa ragam produk dengan dimensi ragam.

Varian	Atribut
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"

Dalam praktiknya, lebih banyak varian dipublikasikan. Misalnya, setiap varian di atas dipublikasikan dua kali, sekali untuk kompilasi dan sekali untuk runtime, dengan dependensi berbeda (berdasarkan apakah dependensi yang dideklarasikan menggunakan implementation atau api) dan dengan nilai yang berbeda untuk atribut org.gradle.Usage. Namun, artefak (file AAR) untuk kedua varian ini sama.

Untuk informasi selengkapnya, lihat dokumentasi API publishing.

Penting: Saat memublikasikan beberapa varian publikasi, nama ragam produk dan dimensi ragam menjadi bagian dari API publikasi. Jadi, project yang menggunakannya harus memiliki nama ragam dan dimensi yang cocok atau menggunakan metode untuk menambahkan dependensi build dan memilih artefak yang diperlukan secara manual. Untuk jenis build, karena dimensi bawaan, hanya nama jenis build yang harus cocok atau project konsumen juga harus menggunakan penggantian.

Masalah kompatibilitas untuk memublikasikan library multi ragam

Project yang menggunakan AGP 7.0 atau yang lebih lama tidak dapat menggunakan library multi ragam yang dipublikasikan dengan AGP 7.1 atau yang lebih baru. Ini adalah masalah umum yang disebabkan oleh perubahan pada nama atribut untuk dimensi ragam produk dari dimensionName menjadi com.android.build.api.attributes.ProductFlavor:dimensionName di AGP 7.1. Bergantung pada penyiapan project, Anda dapat menggunakan missingDimensionStrategy di API varian lama untuk mengatasi masalah ini.

Misalnya, project aplikasi Anda hanya memiliki dimensi ragam produk versi:

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