KSP 與 Kotlin Multiplatform
本指南說明如何在 Kotlin Multiplatform 專案中使用 Kotlin Symbol Processing (KSP)。 若要快速入門,請參閱多平台範例專案。 該專案在數個目標中使用了 KSP,且其處理器會產生專案所使用的 Foo 類別。
將 KSP 新增至多平台專案
若要將 KSP 新增至用戶端模組(使用處理器的模組):
開啟該模組的
build.gradle(.kts)檔案。將 KSP 外掛程式新增至
plugins {}區塊:kotlin// build.gradle.kts plugins { kotlin("multiplatform") version "2.4.21" id("com.google.devtools.ksp") version "2.3.12" }groovy// build.gradle plugins { id 'org.jetbrains.kotlin.multiplatform' version '2.4.21' id 'com.google.devtools.ksp' version '2.3.12' }為每個需要符號處理的目標新增處理器相依性:
kotlindependencies { add("ksp<Target>", <processor>) }<Target>是多平台專案中所使用的目標之一的名稱,首字母大寫。例如,對於iosArm64目標,請使用kspIosArm64組態。若需目標的完整清單,請參閱 Multiplatform Gradle DSL 參考 與 Kotlin/Native 支援的目標與主機。
<processor>為處理器相依性。它可以是:包含符號處理器邏輯的專案模組:
kotlinadd("kspJvm", project(":local-processor"))外部處理器,例如 Room:
kotlinadd("kspJvm", "androidx.room3:room3-compiler:3.0.3")
自 KSP 2.3.12 起,通配的 ksp(...) 組態會在多平台專案中導致組建錯誤。較早版本會將其回報為已棄用。請明確設定每個目標,以避免在不需要的地方執行處理器。
在單一目標中使用多個處理器
您可以將多個處理器新增至同一個目標:
dependencies {
add("kspAndroid", project(":test-processor"))
add("kspAndroid", "androidx.room3:room3-compiler:3.0.3")
}dependencies {
add('kspAndroid', project(':test-processor'))
add('kspAndroid', 'androidx.room3:room3-compiler:3.0.3')
}在多個目標中使用相同的處理器
您可以將相同的處理器新增至多個目標:
dependencies {
add("kspIosX64", project(":test-processor"))
add("kspIosArm64", project(":test-processor"))
add("kspIosSimulatorArm64", project(":test-processor"))
}dependencies {
add('kspIosX64', project(':test-processor'))
add('kspIosArm64', project(':test-processor'))
add('kspIosSimulatorArm64', project(':test-processor'))
}如果您有多個 iOS 目標,可以使用迴圈來避免重複程式碼:
dependencies {
kotlin.targets.filter { it.name.startsWith("ios") }.forEach { target ->
add(
"ksp${target.name.replaceFirstChar { it.uppercaseChar() }}",
project(":test-processor")
)
}
}dependencies {
kotlin.targets.findAll { it.name.startsWith('ios') }.each { target ->
add("ksp${target.name.capitalize()}", project(':test-processor'))
}
}為測試編譯設定 KSP
若要在測試編譯期間執行 KSP,請將處理器新增至對應的測試組態中:
dependencies {
add("kspJvmTest", project(":test-processor"))
add("kspJsTest", project(":test-processor"))
add("kspIosX64Test", project(":test-processor"))
}dependencies {
add('kspJvmTest', project(':test-processor'))
add('kspJsTest', project(':test-processor'))
add('kspIosX64Test', project(':test-processor'))
}對於 Android 主機與裝置測試,KSP 會根據對應的原始碼集名稱來推導組態名稱:
dependencies {
add("kspAndroidHostTest", project(":test-processor"))
add("kspAndroidDeviceTest", project(":test-processor"))
}dependencies {
add('kspAndroidHostTest', project(':test-processor'))
add('kspAndroidDeviceTest', project(':test-processor'))
}尋找 KSP 組態名稱
KSP 會從 Kotlin Multiplatform 原始碼集推導出組態名稱。若要檢視模組完整的 KSP 組態清單,請執行:
./gradlew :<your-module-name>:dependencies | grep ksp尋找與您的目標原始碼集相對應的組態名稱。
編譯與處理
在多平台專案中,Kotlin 會為每個目標建立獨立的編譯(例如 main 和 test)。對於每個設定了一或多個處理器的 Kotlin 編譯任務,KSP 都會建立對應的符號處理任務。
該範例專案定義了六個目標。每個目標都有 main 和 test 編譯,進而產生以下編譯與符號處理任務:
- JVM:
jvmMain和jvmTest - JS:
jsMain和jsTest - LinuxX64:
linuxX64Main和linuxX64Test - AndroidNativeX64:
androidNativeX64Main和androidNativeX64Test - AndroidNativeArm64:
androidNativeArm64Main和androidNativeArm64Test - MingwX64:
mingwX64Main和mingwX64Test
在範例的 workload/build.gradle.kts 檔案中,為以下組態宣告了 KSP 相依性:
kspJvm和kspJvmTestkspJs和kspJsTestkspAndroidNativeX64和kspAndroidNativeX64TestkspAndroidNativeArm64和kspAndroidNativeArm64TestkspLinuxX64kspMingwX64
KSP 會為每個宣告了 KSP 相依性的組態建立一個符號處理任務。在此範例中,該專案至少有 12 個 Kotlin 編譯任務與 10 個符號處理任務。其餘編譯沒有對應的 KSP 任務,因為未對它們設定 KSP。
相關參考
- KSP 存儲庫中的多平台範例專案。
- 從命令列執行 KSP 時各平台的入口點清單。
