發布項目變數可讓您為使用者打造更貼近個人需求的體驗。您可以透過設定發布項目變數發布不同的建構變數,每個變數有其專屬的屬性。
透過發布多個程式庫的建構變數,使用者就能根據自身需求選擇合適的功能。舉例來說,您可以為偵錯與發布建構類型發布不同的成品。偵錯用的發布項目成果可能會具有多餘的記錄程式碼,以及用來啟用這些額外紀錄的不同依附元件。
在進行後續操作前,請務必備妥您要發布的程式庫。
使用 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 做為次要成果:
Kotlin
android { publishing { singleVariant("release") { withSourcesJar() } } }
Groovy
android { publishing { singleVariant('release') { withSourcesJar() } } }
您可以建立多個元件,每個元件設定單一發布項目變數,並發布至不同的 Maven 座標。在這種情況下,發布項目變數並不會設定屬性。因此您無法透過發布項目的中繼資料判斷該發布變數是否出自 release
的建構變數。由於只有一個發布項目變數,因此不需要區分變數。
建立具有多個發布項目變數的軟體元件
您可以選擇將全部或部分的建構變數放入一個軟體元件。AGP 會自動使用建構類型名稱、變種版本名稱,以及變種版本維度名稱建立屬性,以利取用的專案可區分變數。
如要發布單一元件中的所有建構變數,請在模組層級的 build.gradle
檔案中的 multipleVariants{}
區塊指定 allVariants()
:
Kotlin
android { publishing { multipleVariants { allVariants() withJavadocJar() } } }
Groovy
android { publishing { multipleVariants { allVariants() withJavadocJar() } } }
這會建立一個名為「default
」的單一元件。如要重新命名元件,請使用 multipleVariants({name})
。在這種情況下,所有的建構類型和變種版本維度都會作為屬性使用。
您也可以利用 includeBuildTypeValues()
和 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' ) } } }
在以上的範例中,自訂元件包含下列程式碼的所有組合:建構類型的 (debug
、release
)、color
維度的 (blue
、pink
) 和 shape
維度的 (square
)。
您必須列出所有版本維度,即使您只發布維度中的一個值也是如此,如此 AGP 即可知道每個維度要使用的值。
下表列出了發布項目變數的結果和相關屬性。
變數 | 屬性 |
---|---|
blueSquareDebug | com.android.build.api.attributes.BuildTypeAttr ="debug"
com.android.build.api.attributes.ProductFlavorAttr:color ="blue" |
blueSquareRelease |
com.android.build.api.attributes.BuildTypeAttr="release"
|
pinkSquareDebug |
com.android.build.api.attributes.BuildTypeAttr="debug"
|
pinkSquareRelease |
com.android.build.api.attributes.BuildTypeAttr="release"
|
在實務上會發布更多的變化版本。舉例來說,以上每個變數都發布兩次,一次用於編譯,另一次用於執行階段。兩次發布的變數具有不同的依附元件 (取決於宣告的依附元件採用的是 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
來解決這個問題。
舉例來說,假設應用程式專案只有一個版本變種版本維度:
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)
}
}