KSP와 Kotlin Multiplatform

이 글에서는 Kotlin Multiplatform 프로젝트에서 Kotlin Symbol Processing(KSP)을 사용하는 방법을 배워요. 빠르게 시작하려면 소스 저장소에 여러 타깃을 가진 멀티플랫폼 프로젝트의 예제가 있어요. 이 예제의 프로세서는 프로젝트가 사용하는 Foo 클래스를 생성합니다.

출처: KSP with Kotlin Multiplatform

본문

멀티플랫폼 프로젝트에 KSP 추가하기

프로세서를 사용하는 클라이언트 모듈의 build.gradle.kts 파일에서, 심볼 처리가 필요한 각 타깃에 알맞은 KSP 프로세서 의존성을 추가해요:

dependencies {
  add("ksp<Target>", <processor>)
}

<Target>은 멀티플랫폼 프로젝트에서 사용하는 타깃 중 하나예요.

전체 타깃 목록은 Multiplatform Gradle DSL 참조와 Kotlin/Native 지원 타깃에서 확인할 수 있어요.

<processor>는 Gradle 프로젝트 경로로, 다음 중 하나일 수 있어요.
심볼 프로세서의 로직을 담고 있는 프로젝트 내 특정 디렉터리:

add("kspJvm", project(":local-processor"))

Room과 같은 외부 프로세서:

add("kspJvm", "androidx.room:room-compiler:2.6.1")

KSP 2부터는 모든 것을 맡는 포괄(catch-all) ksp(...) 설정이 더 이상 사용되지 않아요(deprecated). 각 타깃을 명시적으로 구성해서 필요 없는 곳에서는 프로세서가 실행되지 않도록 하세요.

한 타깃에 여러 프로세서 사용하기

한 타깃에 프로세서를 둘 이상 추가할 수 있어요:

add("kspAndroid", project(":test-processor"))
add("kspAndroid", "androidx.room:room-compiler:2.6.1")

add('kspAndroid', project(':test-processor'))
add('kspAndroid', 'androidx.room:room-compiler:2.6.1')

같은 프로세서를 여러 타깃에 사용하기

같은 프로세서를 둘 이상의 타깃에 추가할 수도 있어요:

add("kspIosX64", project(":test-processor"))
add("kspIosArm64", project(":test-processor"))
add("kspIosSimulatorArm64", project(":test-processor"))

add('kspIosX64', project(':test-processor'))
add('kspIosArm64', project(':test-processor'))
add('kspIosSimulatorArm64', project(':test-processor'))

iOS 타깃이 많다면 반복문을 사용해 중복을 피할 수 있어요:

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

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

테스트 컴파일을 위한 KSP 구성하기

테스트 컴파일 중에 KSP를 실행하려면 해당 테스트 설정에 프로세서를 추가해요:

add("kspJvmTest", project(":test-processor"))
add("kspJsTest", project(":test-processor"))
add("kspIosX64Test", project(":test-processor"))

add('kspJvmTest', project(':test-processor'))
add('kspJsTest', project(':test-processor'))
add('kspIosX64Test', project(':test-processor'))

Android 호스트 및 디바이스 테스트의 경우, KSP는 해당 소스 세트 이름에서 설정 이름을 파생해요:

add("kspAndroidHostTest", project(":test-processor"))
add("kspAndroidDeviceTest", project(":test-processor"))

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)에 대해 별도의 컴파일을 만들어요. KSP 프로세서가 하나 이상 구성된 각 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 작업이 없어요.

KSP와 Kotlin Multiplatform