Kotlin Multiplatform에서의 KSP
이 가이드에서는 Kotlin Multiplatform 프로젝트에서 KSP(Kotlin Symbol Processing)를 사용하는 방법을 설명합니다. 빠른 시작을 원하신다면 멀티플랫폼 예제 프로젝트를 참고하세요. 이 예제에서는 여러 타깃에 KSP를 적용하며, 프로세서가 프로젝트에서 사용할 Foo 클래스를 생성합니다.
멀티플랫폼 프로젝트에 KSP 추가하기
클라이언트 모듈(프로세서를 사용하는 모듈)에 KSP를 추가하려면 다음 단계를 따르세요.
모듈의
build.gradle(.kts)파일을 엽니다.plugins {}블록에 KSP 플러그인을 추가합니다.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부터는 멀티플랫폼 프로젝트에서 포괄적인(catch-all) ksp(...) 구성을 사용하면 빌드 에러가 발생합니다. 이전 버전에서는 deprecated로 표시되었습니다. 필요하지 않은 곳에서 프로세서가 실행되는 것을 방지하기 위해 각 타깃을 명시적으로 구성하세요.
단일 타깃에서 여러 프로세서 사용하기
하나의 타깃에 둘 이상의 프로세서를 추가할 수 있습니다.
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는 해당 소스 세트(source set) 이름으로부터 구성 이름을 도출합니다.
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와 같이 각 타깃별로 개별적인 컴파일(compilation)을 생성합니다. 하나 이상의 프로세서가 구성된 각 Kotlin 컴파일 태스크에 대해, KSP는 이에 대응하는 심볼 프로세싱 태스크를 생성합니다.
예제 프로젝트에서는 6개의 타깃을 정의합니다. 각 타깃에는 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 실행 시 각 플랫폼별 진입점(entry point) 목록
