設定發布項目變數

發布項目變數可讓您為使用者打造更貼近個人需求的體驗。您可以透過設定發布項目變數發布不同的建構變數，每個變數有其專屬的屬性。

透過發布多個程式庫的建構變數，使用者就能根據自身需求選擇合適的功能。舉例來說，您可以為偵錯與發布建構類型發布不同的成品。偵錯用的發布項目成果可能會具有多餘的記錄程式碼，以及用來啟用這些額外紀錄的不同依附元件。

在進行後續操作前，請務必備妥您要發布的程式庫。

使用 Gradle Module Metadata

如要發布程式庫的變數，請務必使用 Gradle Module Metadata (GMM)。GMM 會描述您的發布內容，並維護可辨識變化版本的依附元件管理。根據預設，GMM 會和程式庫一起發布。

使用 GMM 的好處包括：

• 如果您透過 Gradle 6.0 以上版本使用 GMM，就能發布多個發布項目變數 (或多個成果)，而且每個變數都有專屬的屬性和依附元件。如果您使用的不是 GMM，而是 Maven 的 POM 檔案，就只能發布一個成果。如果使用的是 POM 檔，您可以使用分類器發布其他成果，但其他成果不會有專屬的依附元件。
• Gradle 會自動建立編譯用和執行階段用的變數，這兩個變數都有專屬的依附元件。您可以發布一個編譯用的變數和一個執行階段用的變數，讓取用者根據使用程式庫的時機選擇合適的變數。GMM 可以根據已發布的程式庫使用的 api、implementation 或 compileOnly/runtimeOnly，讓取用者看到編譯和執行階段不同的依附元件。如需依附元件的完整清單，請參閱依附元件設定。即使您只是發布一個發布項目變數也能利用這項功能。
• 使用測試固件時，您可以發布含有特殊中繼資料的其他變數或功能供取用者選取。即使您只是發布一個發布項目變數也能利用這項功能。

瞭解發布項目變數

如要瞭解發布項目變數的運作方式，建議您熟悉 Gradle 的基本發布步驟。以下列舉幾項有關發布的重要概念：

• 建構變數：為 Gradle 用於建構程式庫的設定，為建構類型和變種版本的交叉乘積。如要進一步瞭解，請參閱Android 建構詞彙一文。
• 成果：某個建構所產生的檔案或目錄。在程式庫的發布程序中，成果通常是 JAR 或 AAR 檔案。
• 發布項目變數：包含其關聯屬性、功能和依附元件的成果。請注意，Gradle 將發布項目的變數稱為「變數」。不過，我們在這些文件中將這類變數稱為「發布項目變數」，方便您區分這類變數與「建構變數」。
• 屬性：有多個選項時，Gradle 會使用屬性來識別及選取發布項目變數。舉例來說，org.gradle.usage=java-api 和 org.gradle.jvm.version=11 都是變數屬性。
• 軟體元件：為一個可保存一或多個發布項目變數且已發布至一組 Maven 座標的 Gradle 物件 (groupdId:artifactId:version)。這類物件會透過 Project.getComponents() 以 Gradle DSL 語言公開發布。
• 發布項目：發布至存放區供取用者使用的內容。發布內容包含一個軟體元件及其中繼資料 (例如其身分 (groupId:artifactId:version))。

Android Gradle 外掛程式 (AGP) 7.1 推出了一特定領域語言 (DSL)，可控管發布時要使用及忽略的建構變數。DSL 可讓您建立包含以下任一項目的 SoftwareComponent 執行個體：

• 單一建構變數中的一個發布項目變數。
• 多個建構變數中的多個發布項目變數。

如果您建立包含多個發布項目變數的軟體元件，AGP 就會為每個變數設定屬性，讓取用者視需要選取適當的變數。這些屬性皆直接取自建立建構變數時所使用的建構類型和變種版本。建立單一發布項目變數的元件不需要屬性，因為不需要將其區分。

建立只含一個發布項目變數的軟體元件

下列程式碼片段為軟體元件設定了單一發布項目變數 (透過 release 建構變數建立而成)，並新增來源 JAR 做為次要成果：

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

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

您可以建立多個元件，每個元件設定單一發布項目變數，並發布至不同的 Maven 座標。在這種情況下，發布項目變數並不會設定屬性。因此您無法透過發布項目的中繼資料判斷該發布變數是否出自 release 的建構變數。由於只有一個發布項目變數，因此不需要區分變數。

建立具有多個發布項目變數的軟體元件

您可以選擇將全部或部分的建構變數放入一個軟體元件。AGP 會自動使用建構類型名稱、變種版本名稱，以及變種版本維度名稱建立屬性，以利取用的專案可區分變數。

如要發布單一元件中的所有建構變數，請在模組層級的 build.gradle 檔案中的 multipleVariants{} 區塊指定 allVariants()：

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

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

這會建立一個名為「default」的單一元件。如要重新命名元件，請使用 multipleVariants({name})。在這種情況下，所有的建構類型和變種版本維度都會作為屬性使用。

您也可以利用 includeBuildTypeValues() 和 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'
      )
    }
  }
}

在以上的範例中，自訂元件包含下列程式碼的所有組合：建構類型的 (debug、release)、color 維度的 (blue、pink) 和 shape 維度的 (square)。

您必須列出所有版本維度，即使您只發布維度中的一個值也是如此，如此 AGP 即可知道每個維度要使用的值。

下表列出了發布項目變數的結果和相關屬性。

在實務上會發布更多的變化版本。舉例來說，以上每個變數都發布兩次，一次用於編譯，另一次用於執行階段。兩次發布的變數具有不同的依附元件 (取決於宣告的依附元件採用的是 implementation 還是 api) 且為 org.gradle.Usage 屬性提供不同的值。不過，這兩個變數的成果 (AAR 檔案) 是相同的。

詳情請參閱 publishing API 說明文件。

發布多變種程式庫的相容性問題

使用 AGP 7.0 以下版本的專案無法使用 AGP 7.1 以上版本發布的多變種版本程式庫。這是已知的問題，在 AGP 7.1 中，變種版本維度的屬性名稱從 dimensionName 變更為 com.android.build.api.attributes.ProductFlavor:dimensionName。視專案設定而定，您可以在舊版變數 API 中使用 missingDimensionStrategy 來解決這個問題。

舉例來說，假設應用程式專案只有一個版本變種版本維度：

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