코틀린 심볼 처리 API

코틀린 심볼 처리(KSP)는 경량 컴파일러 플러그인을 개발하는 데 사용할 수 있는 API입니다. KSP는 학습 곡선을 최소화하면서 코틀린의 강점을 활용하는 간소화된 컴파일러 플러그인 API를 제공합니다. kapt와 비교하여 KSP를 사용하는 어노테이션 프로세서는 최대 두 배 빠르게 실행될 수 있습니다.

• KSP가 kapt와 어떻게 비교되는지 자세히 알아보려면 KSP를 사용해야 하는 이유를 확인하세요.
• KSP 프로세서 작성을 시작하려면 KSP 빠른 시작을 참조하세요.

개요

KSP API는 코틀린 프로그램을 코틀린답게(idiomatically) 처리합니다. KSP는 확장 함수, 선언-사이트 가변성, 지역 함수와 같은 코틀린 고유 기능을 이해합니다. 또한 타입을 명시적으로 모델링하고 동등성 및 할당 호환성과 같은 기본적인 타입 검사를 제공합니다.

이 API는 코틀린 문법에 따라 코틀린 프로그램 구조를 심볼(symbol) 수준에서 모델링합니다. KSP 기반 플러그인이 소스 프로그램을 처리할 때, 클래스, 클래스 멤버, 함수 및 관련 매개변수와 같은 구성 요소는 프로세서에서 접근할 수 있지만, if 블록 및 for 루프와 같은 요소는 접근할 수 없습니다.

개념적으로 KSP는 코틀린 리플렉션의 KType와 유사합니다. 이 API를 통해 프로세서는 클래스 선언에서 특정 타입 인수를 가진 해당 타입으로, 그리고 그 반대로도 탐색할 수 있습니다. 또한 타입 인수를 대체하고, 가변성을 지정하며, 스타 프로젝션을 적용하고, 타입의 널 허용 여부를 표시할 수 있습니다.

KSP를 코틀린 프로그램의 전처리기(preprocessor) 프레임워크로 생각할 수도 있습니다. KSP 기반 플러그인을 심볼 프로세서 또는 간단히 _프로세서_로 간주하면 컴파일의 데이터 흐름은 다음 단계로 설명할 수 있습니다.

1. 프로세서는 소스 프로그램과 리소스를 읽고 분석합니다.
2. 프로세서는 코드 또는 다른 형태의 출력을 생성합니다.
3. 코틀린 컴파일러는 생성된 코드와 함께 소스 프로그램을 컴파일합니다.

완전한 컴파일러 플러그인과 달리 프로세서는 코드를 수정할 수 없습니다. 언어 의미론을 변경하는 컴파일러 플러그인은 때때로 매우 혼란스러울 수 있습니다. KSP는 소스 프로그램을 읽기 전용으로 처리하여 이러한 문제를 피합니다.

이 영상에서 KSP의 개요를 확인할 수도 있습니다.

KSP가 소스 파일을 보는 방식

대부분의 프로세서는 입력 소스 코드의 다양한 프로그램 구조를 탐색합니다. API 사용법을 자세히 알아보기 전에, KSP의 관점에서 파일이 어떻게 보이는지 살펴보겠습니다.

KSFile
  packageName: KSName
  fileName: String
  annotations: List<KSAnnotation>  (File annotations)
  declarations: List<KSDeclaration>
    KSClassDeclaration // class, interface, object
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      classKind: ClassKind
      primaryConstructor: KSFunctionDeclaration
      superTypes: List<KSTypeReference>
      // contains inner classes, member functions, properties, etc.
      declarations: List<KSDeclaration>
    KSFunctionDeclaration // top level function
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      functionKind: FunctionKind
      extensionReceiver: KSTypeReference?
      returnType: KSTypeReference
      parameters: List<KSValueParameter>
      // contains local classes, local functions, local variables, etc.
      declarations: List<KSDeclaration>
    KSPropertyDeclaration // global variable
      simpleName: KSName
      qualifiedName: KSName
      containingFile: String
      typeParameters: KSTypeParameter
      parentDeclaration: KSDeclaration
      extensionReceiver: KSTypeReference?
      type: KSTypeReference
      getter: KSPropertyGetter
        returnType: KSTypeReference
      setter: KSPropertySetter
        parameter: KSValueParameter

이 보기에는 파일에 선언된 일반적인 요소들인 클래스, 함수, 프로퍼티 등이 나열됩니다.

SymbolProcessorProvider: 진입점

KSP는 SymbolProcessor를 인스턴스화하기 위해 SymbolProcessorProvider 인터페이스의 구현을 기대합니다.

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

SymbolProcessor는 다음과 같이 정의됩니다.

interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated> // Let's focus on this
    fun finish() {}
    fun onError() {}
}

Resolver는 SymbolProcessor에 심볼과 같은 컴파일러 세부 정보에 대한 접근을 제공합니다. 최상위 함수와 최상위 클래스 내의 비지역(non-local) 함수를 모두 찾는 프로세서는 다음과 같습니다.

class HelloFunctionFinderProcessor : SymbolProcessor() {
    // ...
    val functions = mutableListOf<KSClassDeclaration>()
    val visitor = FindFunctionsVisitor()

    override fun process(resolver: Resolver) {
        resolver.getAllFiles().forEach { it.accept(visitor, Unit) }
    }

    inner class FindFunctionsVisitor : KSVisitorVoid() {
        override fun visitClassDeclaration(classDeclaration: KSClassDeclaration, data: Unit) {
            classDeclaration.getDeclaredFunctions().forEach { it.accept(this, Unit) }
        }

        override fun visitFunctionDeclaration(function: KSFunctionDeclaration, data: Unit) {
            functions.add(function)
        }

        override fun visitFile(file: KSFile, data: Unit) {
            file.declarations.forEach { it.accept(this, Unit) }
        }
    }
    // ...
    
    class Provider : SymbolProcessorProvider {
        override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor = TODO()
    }
}

리소스

• 빠른 시작
• KSP를 사용해야 하는 이유?
• 예시
• KSP가 코틀린 코드를 모델링하는 방식
• 자바 어노테이션 프로세서 작성자를 위한 참조
• 점진적 처리 노트
• 다중 라운드 처리 노트
• 멀티플랫폼 프로젝트의 KSP
• 명령줄에서 KSP 실행
• 자주 묻는 질문

지원 라이브러리

다음 표에는 안드로이드의 인기 라이브러리 목록과 KSP 지원 단계가 포함되어 있습니다.

라이브러리	상태
Room	공식 지원
Moshi	공식 지원
RxHttp	공식 지원
Kotshi	공식 지원
Lyricist	공식 지원
Lich SavedState	공식 지원
gRPC Dekorator	공식 지원
EasyAdapter	공식 지원
Koin Annotations	공식 지원
Glide	공식 지원
Micronaut	공식 지원
Epoxy	공식 지원
Paris	공식 지원
Auto Dagger	공식 지원
SealedX	공식 지원
Ktorfit	공식 지원
Mockative	공식 지원
DeeplinkDispatch	airbnb/DeepLinkDispatch#323를 통해 지원
Dagger	알파
Motif	알파
Hilt	진행 중
Auto Factory	아직 지원되지 않음