Skip to content

Kotlin 多平台中的 KSP ​

本指南介绍了如何在 Kotlin 多平台(Kotlin Multiplatform)项目中使用 Kotlin 符号处理(Kotlin Symbol Processing,KSP)。 要快速上手,请参阅多平台示例项目。 该项目在多个目标中使用了 KSP,其处理器会生成一个供该项目使用的 Foo 类。

为多平台项目添加 KSP ​

要将 KSP 添加到客户端模块(使用处理器的模块):

  1. 打开该模块的 build.gradle(.kts) 文件。

  2. 将 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'
    }
  3. 为每个需要符号处理的目标添加处理器依赖项:

    kotlin
    dependencies {
        add("ksp<Target>", <processor>)
    }
    • <Target> 是多平台项目中使用的某个目标的名称,首字母大写。例如,对于 iosArm64 目标,使用 kspIosArm64 配置。

    • <processor> 是处理器依赖项。它可以是:

      • 项目中包含符号处理器逻辑的模块:

        kotlin
        add("kspJvm", project(":local-processor"))
      • 外部处理器,例如 Room:

        kotlin
        add("kspJvm", "androidx.room3:room3-compiler:3.0.3")

自 KSP 2.3.12 起,通配型 ksp(...) 配置在多平台项目中会导致构建错误。早期版本会将其报告为已弃用。请显式配置每个目标,以避免在不需要的地方运行处理器。

在单个目标中使用多个处理器 ​

你可以向同一个目标添加多个处理器:

kotlin
dependencies {
    add("kspAndroid", project(":test-processor"))
    add("kspAndroid", "androidx.room3:room3-compiler:3.0.3")
}
groovy
dependencies {
    add('kspAndroid', project(':test-processor'))
    add('kspAndroid', 'androidx.room3:room3-compiler:3.0.3')
}

在多个目标中使用同一个处理器 ​

你可以将同一个处理器添加到多个目标:

kotlin
dependencies {
    add("kspIosX64", project(":test-processor"))
    add("kspIosArm64", project(":test-processor"))
    add("kspIosSimulatorArm64", project(":test-processor"))
}
groovy
dependencies {
    add('kspIosX64', project(':test-processor'))
    add('kspIosArm64', project(':test-processor'))
    add('kspIosSimulatorArm64', project(':test-processor'))
}

如果拥有多个 iOS 目标,你可以使用循环来避免重复:

kotlin
dependencies {
    kotlin.targets.filter { it.name.startsWith("ios") }.forEach { target ->
        add(
            "ksp${target.name.replaceFirstChar { it.uppercaseChar() }}",
            project(":test-processor")
        )
    }
}
groovy
dependencies {
    kotlin.targets.findAll { it.name.startsWith('ios') }.each { target ->
        add("ksp${target.name.capitalize()}", project(':test-processor'))
    }
}

为测试编译配置 KSP ​

要在测试编译期间运行 KSP,请将处理器添加到对应的测试配置中:

kotlin
dependencies {
    add("kspJvmTest", project(":test-processor"))
    add("kspJsTest", project(":test-processor"))
    add("kspIosX64Test", project(":test-processor"))
}
groovy
dependencies {
    add('kspJvmTest', project(':test-processor'))
    add('kspJsTest', project(':test-processor'))
    add('kspIosX64Test', project(':test-processor'))
}

对于 Android 主机和设备测试,KSP 会从对应的源集名称派生出配置名称:

kotlin
dependencies {
    add("kspAndroidHostTest", project(":test-processor"))
    add("kspAndroidDeviceTest", project(":test-processor"))
}
groovy
dependencies {
    add('kspAndroidHostTest', project(':test-processor'))
    add('kspAndroidDeviceTest', project(':test-processor'))
}

查找 KSP 配置名称 ​

KSP 会从 Kotlin 多平台源集中派生配置名称。要查看模块的完整 KSP 配置列表,请运行:

bash
./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 和 kspJvmTest
  • kspJs 和 kspJsTest
  • kspAndroidNativeX64 和 kspAndroidNativeX64Test
  • kspAndroidNativeArm64 和 kspAndroidNativeArm64Test
  • kspLinuxX64
  • kspMingwX64

KSP 会为每个声明了 KSP 依赖项的配置创建一个符号处理任务。在此示例中,项目至少包含 12 个 Kotlin 编译任务和 10 个符号处理任务。其余编译由于未配置 KSP,因此没有对应的 KSP 任务。

另请参阅 ​