多平台專案結構的進階概念
本文將說明 Kotlin Multiplatform 專案結構的進階概念,以及它們如何對應到 Gradle 的實作。如果你需要處理 Gradle 組建的低階抽象概念(組態、任務、發佈等),或正在為 Kotlin Multiplatform 組建建立 Gradle 外掛程式,這些資訊將非常有用。
本頁面在以下情況對你有所幫助:
- 需要在一組 Kotlin 未為其建立原始碼集的目標之間共享程式碼。
- 想要為 Kotlin Multiplatform 組建建立 Gradle 外掛程式,或需要處理 Gradle 組建的低階抽象概念,例如組態、任務、發佈等。
在深入研究進階概念之前,建議先了解多平台專案結構的基礎知識。
在多平台專案中,了解相依性管理最關鍵的事情之一,就是 Gradle 風格的專案或程式庫相依性,與 Kotlin 特有的原始碼集之間 dependsOn 關聯之間的差異:
dependsOn是通用原始碼集與特定平台原始碼集之間的關聯,它支援原始碼集階層結構,並在多平台專案中實現通用的程式碼共享。對於預設的原始碼集,其階層結構是自動管理的,但你可能需要在特定情況下對其進行修改。- 程式庫和專案相依性通常照常運作,但若要在多平台專案中妥善管理它們,你應該了解 Gradle 相依性如何解析為用於編譯的細部 原始碼集 → 原始碼集 相依性。
dependsOn 與原始碼集階層結構
通常,你會處理的是 相依性,而不是 dependsOn 關聯。然而,檢視 dependsOn 對於深入理解 Kotlin Multiplatform 專案的運作原理至關重要。
dependsOn 是兩個 Kotlin 原始碼集之間特有的 Kotlin 關聯。這可以是通用與特定平台原始碼集之間的連結,例如當 jvmMain 原始碼集相依於 commonMain、iosArm64Main 相依於 iosMain 等等。
以 Kotlin 原始碼集 A 和 B 的一般範例為例。運算式 A.dependsOn(B) 指示 Kotlin:
A可以觀察到來自B的 API,包含內部宣告。A可以為來自B的預期宣告(expect)提供實際實作(actual)。這是充分必要條件,因為若且唯若A.dependsOn(B)直接或間接成立時,A才能為B提供actuals。- 除了自己的目標外,
B還應該編譯至A所編譯到的所有目標。 A繼承B的所有常規相依性。
dependsOn 關聯會建立一種樹狀結構,稱為原始碼集階層結構。以下是適用於行動開發的典型專案範例,包含 android、iosArm64(iPhone 裝置)和 iosSimulatorArm64(適用於 Apple 晶片 Mac 的 iPhone 模擬器):
箭頭代表 dependsOn 關聯。 這些關聯會在編譯平台二進位檔期間保留。這就是 Kotlin 如何理解 iosMain 應該看到來自 commonMain 的 API,而不是來自 iosArm64Main 的 API:
dependsOn 關聯是透過 KotlinSourceSet.dependsOn(KotlinSourceSet) 呼叫來設定的,例如:
kotlin {
// 目標宣告
sourceSets {
// 設定 dependsOn 關聯的範例
iosArm64Main.dependsOn(commonMain)
}
}- 此範例展示了如何在建置指令碼中定義
dependsOn關聯。然而,Kotlin Gradle 外掛程式預設會建立原始碼集並設定這些關聯,因此你不需要手動進行。 dependsOn關聯在建置指令碼中與dependencies {}區塊分開宣告。這是因為dependsOn不是一般的相依性;相反地,它是 Kotlin 原始碼集之間的一種特定關聯,用於跨不同目標共享程式碼。
你不能使用 dependsOn 來宣告對已發佈程式庫或其他 Gradle 專案的常規相依性。例如,你不能將 commonMain 設定為相依於 kotlinx-coroutines-core 程式庫的 commonMain,也不能呼叫 commonTest.dependsOn(commonMain)。
宣告自訂原始碼集
在某些情況下,你可能需要在專案中建立自訂的中介原始碼集。 考慮一個編譯至 JVM、JS 和 Linux 的專案,且你只想在 JVM 和 JS 之間共享部分原始碼。 在這種情況下,你應該為這對目標找到一個特定的原始碼集,如多平台專案結構的基礎知識中所述。
Kotlin 不會自動建立這樣的原始碼集。這表示你應該使用 by creating 結構手動建立它:
kotlin {
jvm()
js()
linuxX64()
sourceSets {
// 建立名為 "jvmAndJs" 的原始碼集
val jvmAndJsMain by creating {
// …
}
}
}然而,Kotlin 仍然不知道如何處理或編譯此原始碼集。如果你畫出一張圖表,這個原始碼集將會是孤立的,並且沒有任何目標標籤:
若要解決此問題,請透過新增數個 dependsOn 關聯將 jvmAndJsMain 納入階層結構中:
kotlin {
jvm()
js()
linuxX64()
sourceSets {
val jvmAndJsMain by creating {
// 別忘了為 commonMain 新增 dependsOn
dependsOn(commonMain.get())
}
jvmMain {
dependsOn(jvmAndJsMain)
}
jsMain {
dependsOn(jvmAndJsMain)
}
}
}在此,jvmMain.dependsOn(jvmAndJsMain) 將 JVM 目標新增到 jvmAndJsMain,而 jsMain.dependsOn(jvmAndJsMain) 將 JS 目標新增到 jvmAndJsMain。
最終的專案結構將如下所示:
手動設定 dependsOn 關聯會停用預設階層範本的自動套用。 請參閱其他組態以深入了解此類情況及其處理方式。
對其他程式庫或專案的相依性
在多平台專案中,你可以設定對已發佈程式庫或其他 Gradle 專案的常規相依性。
Kotlin Multiplatform 通常以典型的 Gradle 方式宣告相依性。類似於 Gradle,你可以:
- 在建置指令碼中使用
dependencies {}區塊。 - 為相依性選擇適當的作用域,例如
implementation或api。 - 若相依項已發佈在儲存庫中,則透過指定其座標來參照相依項,例如
"com.google.guava:guava:32.1.2-jre";若為同一個組建中的 Gradle 專案,則指定其路徑,例如project(":utils:concurrency")。
多平台專案中的相依性設定具有一些特殊功能。每個 Kotlin 原始碼集都有自己的 dependencies {} 區塊。這允許你在特定平台原始碼集中宣告特定平台的相依性:
kotlin {
// 目標宣告
sourceSets {
jvmMain.dependencies {
// 這是 jvmMain 的相依性,因此可以新增特定於 JVM 的相依性
implementation("com.google.guava:guava:32.1.2-jre")
}
}
}通用相依性則較為複雜。考慮一個宣告對多平台程式庫(例如 kotlinx.coroutines)相依性的多平台專案:
kotlin {
android() // Android
iosArm64() // iPhone 裝置
iosSimulatorArm64() // 適用於 Apple 晶片 Mac 的 iPhone 模擬器
sourceSets {
commonMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}
}
}相依性解析中有三個重要概念:
多平台相依性會沿著
dependsOn結構向下傳播。當你將相依性新增至commonMain時,它會自動新增至直接或間接宣告與commonMain具有dependsOn關聯的所有原始碼集。在這種情況下,該相依性確實會自動新增至所有
*Main原始碼集:iosMain、jvmMain、iosSimulatorArm64Main和iosArm64Main。所有這些原始碼集都從commonMain原始碼集繼承了kotlin-coroutines-core相依性,因此你不需要手動將其複製並貼上到所有原始碼集中:傳播機制允許你透過選取特定的原始碼集,來選擇接收所宣告相依性的作用域。 例如,如果你想在 iOS 上使用
kotlinx.coroutines但不在 Android 上使用,你可以僅將此相依性新增至iosMain。原始碼集 → 多平台程式庫 的相依性(例如上述
commonMain到org.jetbrians.kotlinx:kotlinx-coroutines-core:1.7.3)代表相依性解析的中介狀態。解析的最終狀態始終由 原始碼集 → 原始碼集 的相依性表示。最終的 原始碼集 → 原始碼集 相依性並非
dependsOn關聯。為了推斷出細部的 原始碼集 → 原始碼集 相依性,Kotlin 會讀取與每個多平台程式庫一起發佈的原始碼集結構。在此步驟之後,每個程式庫在內部將不再以一個整體表示,而是以其原始碼集的集合來表示。請參閱
kotlinx-coroutines-core的這個範例:Kotlin 會獲取每個相依性關聯,並將其解析為來自相依項的原始碼集集合。該集合中的每個相依原始碼集都必須具有 相容的目標。如果相依原始碼集編譯至 至少與取用者原始碼集相同 的目標,則它具有相容的目標。
以範例專案中的
commonMain為例,它編譯至android、iosArm64和iosSimulatorArm64:- 首先,它會解析對
kotlinx-coroutines-core.commonMain的相依性。這是因為kotlinx-coroutines-core編譯至所有可能的 Kotlin 目標。因此,其commonMain會編譯至所有可能的目標,包含所需的android、iosArm64和iosSimulatorArm64。 - 其次,
commonMain相依於kotlinx-coroutines-core.concurrentMain。由於kotlinx-coroutines-core中的concurrentMain編譯至除 JS 之外的所有目標,因此它符合取用者專案之commonMain的目標。
然而,協同程式中如
iosArm64Main等原始碼集與取用者的commonMain不相容。儘管iosArm64Main編譯至commonMain的其中一個目標(即iosArm64),但它既無法編譯至android,也無法編譯至iosSimulatorArm64。相依性解析的結果會直接影響
kotlinx-coroutines-core中的哪些程式碼是可見的:
- 首先,它會解析對
跨原始碼集對齊通用相依性的版本
在 Kotlin Multiplatform 專案中,通用原始碼集會編譯多次以產出 klib,並作為每個已設定的編譯的一部分。為了產出一致的二進位檔,通用程式碼每次都應根據相同版本之多平台相依性進行編譯。Kotlin Gradle 外掛程式有助於對齊這些相依性,確保每個原始碼集的有效相依性版本皆相同。
在上述範例中,假設你想將 androidx.navigation:navigation-compose:2.7.7 相依性新增至你的 androidMain 原始碼集。你的專案明確為 commonMain 原始碼集宣告了 kotlinx-coroutines-core:1.7.3 相依性,但版本為 2.7.7 的 Compose Navigation 程式庫需要 Kotlin 協同程式 1.8.0 或更高版本。
由於 commonMain 與 androidMain 是一起編譯的,Kotlin Gradle 外掛程式會在兩個版本的協同程式庫之間進行選擇,並將 kotlinx-coroutines-core:1.8.0 套用至 commonMain 原始碼集。但為了使通用程式碼在所有設定的目標上一致地編譯,iOS 原始碼集也需要被約束在相同的相依性版本上。因此 Gradle 也會將 kotlinx.coroutines-*:1.8.0 相依性傳播至 iosMain 原始碼集。
相依性在 *Main 原始碼集與 *Test 原始碼集之間是分開對齊的。適用於 *Test 原始碼集的 Gradle 組態包含 *Main 原始碼集的所有相依性,但反之則不然。因此你可以使用較新的程式庫版本測試專案,而不會影響你的主要程式碼。
例如,你在 *Main 原始碼集中擁有 Kotlin 協同程式 1.7.3 相依性,並傳播到專案中的每個原始碼集。然而,在 iosTest 原始碼集中,你決定將版本升級至 1.8.0 以測試新的程式庫版本。根據相同的演算法,該相依性將會傳播到整個 *Test 原始碼集樹狀結構中,因此每個 *Test 原始碼集都將使用 kotlinx.coroutines-*:1.8.0 相依性進行編譯。
編譯
與單一平台專案不同,Kotlin Multiplatform 專案需要多次啟動編譯器才能建置所有的產物。每次啟動編譯器都是一次 Kotlin 編譯。
例如,以下是前面提到的 Kotlin 編譯期間如何產生 iPhone 裝置的二進位檔:
Kotlin 編譯按目標分組。預設情況下,Kotlin 會為每個目標建立兩次編譯:用於正式環境原始碼的 main 編譯,以及用於測試原始碼的 test 編譯。
建置指令碼中的編譯也以類似的方式存取。你先選取一個 Kotlin 目標,接著存取內部的 compilations 容器,最後依名稱選擇所需的編譯:
kotlin {
// 宣告並設定 JVM 目標
jvm {
val mainCompilation: KotlinJvmCompilation = compilations.getByName("main")
}
}