Skip to content

Kotlin Symbol Processing API ​

Kotlin Symbol Processing(KSP)은 Kotlin을 위한 소스 코드 생성 프레임워크입니다. KSP API를 사용하면 소스 코드에 대한 정적 정보를 검사하고 이를 바탕으로 새로운 코드를 생성하는 프로세서를 만들 수 있습니다. 가장 일반적인 사용 사례는 애노테이션을 기반으로 코드를 생성하는 것입니다.

KSP는 경량 컴파일러 플러그인의 생성을 간소화하는 것을 목표로 합니다. KSP로 빌드된 컴파일러 플러그인을 심볼 프로세서(symbol processor) 또는 줄여서 프로세서라고 부릅니다. KSP의 잘 정의된 API는 컴파일러 변경 사항을 숨겨주므로 프로세서 유지 관리에 많은 노력을 들일 필요가 없습니다. 하지만 이러한 접근 방식에는 트레이드오프가 따릅니다. 예를 들어, KSP 기반 프로세서는 표현식이나 문을 검사할 수 없으며 소스 코드를 수정할 수 없습니다.

KSP 기반 플러그인의 일반적인 사용 사례는 다음과 같습니다:

첫 번째 KSP 기반 프로세서를 만드는 방법을 알아보려면 KSP 시작하기를 참조하세요.

요구 사항 ​

최신 KSP 버전인 2.3.12은 다음 의존성 버전을 지원합니다:

의존성최소 및 최대 버전
Kotlin Gradle 플러그인 (KGP)2.3.20–2.4.x
Android Gradle 플러그인 (AGP)8.13.0 이상
Gradle8.13 이상. AGP 9.0 이상의 경우 Gradle 9.x를 사용하세요.
JDK17 이상

컴파일 중 KSP 동작 방식 ​

KSP는 Kotlin 문법을 기반으로 Kotlin 소스 코드를 심볼 계층 구조로 표현합니다. 프로세서는 이러한 심볼을 사용하여 클래스, 함수, 프로퍼티, 타입과 같은 선언을 검사합니다.

KSP는 선언과 타입 정보를 모델링하지만, 프로세서가 표현식이나 함수 본문에 접근할 수 있도록 하지는 않습니다.

KSP는 다음과 같이 컴파일 프로세스에 결합됩니다:

  1. KSP 프로세서가 소스 코드와 리소스를 분석합니다.

  2. 프로세서가 소스 파일이나 기타 출력을 생성합니다.

  3. Kotlin 컴파일러가 원본 소스 코드와 생성된 코드를 함께 컴파일합니다.

KSP에 대해 자세히 알아보려면 다음 동영상을 시청하세요:

KSP가 프로세서를 실행하는 방식 ​

KSP는 SymbolProcessor 인스턴스를 생성하기 위한 진입점으로 SymbolProcessorProvider 구현체를 사용합니다:

kotlin
interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

SymbolProcessor 인터페이스는 처리 로직을 포함합니다. KSP는 process() 함수를 호출하고 Resolver를 제공하며, 프로세서는 이를 사용하여 소스 코드의 심볼에 접근합니다:

kotlin
interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated>
    fun finish() {}
    fun onError() {}
}

프로세서를 구현하고 등록하는 방법에 대한 단계별 가이드는 KSP 시작하기를 참조하세요.

지원되는 라이브러리 ​

다음 표는 Android에서 널리 사용되는 라이브러리와 이들의 KSP 지원 단계를 나열합니다:

라이브러리지원 현황
Room공식 지원
Moshi공식 지원
RxHttp공식 지원
Kotshi공식 지원
Lyricist공식 지원
Lich SavedState공식 지원
gRPC Dekorator공식 지원
EasyAdapter공식 지원
Koin Annotations공식 지원
Glide공식 지원
Micronaut공식 지원
Epoxy공식 지원
Paris공식 지원
Auto Dagger공식 지원
SealedX공식 지원
Ktorfit공식 지원
Mockative공식 지원
Kotest공식 지원
DeeplinkDispatchairbnb/DeepLinkDispatch#323을 통해 지원
DaggerAlpha
MotifAlpha
Hilt진행 중
Auto Factory아직 지원되지 않음

기타 리소스 ​