在 Kotlin Multiplatform 中使用 KSP
本文介绍如何在 Kotlin Multiplatform 项目中使用 Kotlin 符号处理 (Kotlin Symbol Processing, KSP). 如需快速上手, 请参见 源代码仓库 中的示例 Multiplatform 项目, 这个示例项目在多个编译目标中使用 KSP, 示例项目中的处理器会生成项目使用的 Foo 类.
在跨平台项目中添加 KSP
在客户端模块(使用处理器的模块)的 build.gradle.kts 文件中, 为需要符号处理的每个编译目标, 添加相应的 KSP 处理器依赖项:
<Target>是跨平台项目使用的编译目标之一.<processor>是 Gradle 项目路径. 它可以是:项目中包含符号处理器逻辑的特定目录:
add("kspJvm", project(":local-processor"))外部处理器, 例如 Room:
add("kspJvm", "androidx.room:room-compiler:2.6.1")
在单个编译目标中使用多个处理器
可以为一个编译目标添加多个处理器:
在多个编译目标中使用同一个处理器
可以为多个编译目标添加同一个处理器:
如果有多个 iOS 编译目标, 可以使用循环, 避免重复编写配置:
为测试编译配置 KSP
要在测试编译期间运行 KSP, 请将处理器添加到相应的测试配置中:
对于 Android 主机测试和设备测试, KSP 根据对应的源代码集名称生成配置名称:
查找 KSP 配置名称
KSP 根据 Kotlin Multiplatform 源代码集生成配置名称. 要查看某个模块的 KSP 配置的完整列表, 请运行以下命令:
在输出中查找与编译目标源代码集对应的配置名称.
编译与处理
在跨平台项目中, Kotlin 会为每个编译目标和源代码集分别创建 编译任务, 例如 main 和 test. 对于配置了一个或多个 KSP 处理器的每个 Kotlin 编译任务, KSP 都会创建相应的符号处理任务.
示例项目 定义了 6 个编译目标. 每个编译目标都有 main 和 test 编译任务, 因此会产生以下编译任务和符号处理任务:
JVM:
jvmMain和jvmTestJS:
jsMain和jsTestLinuxX64:
linuxX64Main和linuxX64TestAndroidNativeX64:
androidNativeX64Main和androidNativeX64TestAndroidNativeArm64:
androidNativeArm64Main和androidNativeArm64TestMingwX64:
mingwX64Main和mingwX64Test
在示例项目的 workload/build.gradle.kts 文件中, 为以下配置声明了 KSP 依赖项:
kspJvm和kspJvmTestkspJs和kspJsTestkspAndroidNativeX64和kspAndroidNativeX64TestkspAndroidNativeArm64和kspAndroidNativeArm64TestkspLinuxX64kspMingwX64
对于每个声明了 KSP 依赖项的配置, KSP 都会创建一个符号处理任务. 在这个示例中, 项目创建了至少 12 个 Kotlin 编译任务和 10 个符号处理任务. 其余的编译任务没有对应的 KSP 任务, 因为没有为它们配置 KSP.