kapt에서 KSP로 마이그레이션하기

이 가이드에서는 애너테이션 프로세서를 kapt에서 KSP로 옮기는 방법을 배워요. 마이그레이션하면 프로젝트가 Kotlin 기능을 충분히 활용하면서 빌드 성능도 개선할 수 있답니다.

출처: Migrate from kapt to KSP

본문

kapt(Kotlin Annotation Processing Tool)는 Kotlin에서 Java 애너테이션 프로세서를 사용할 수 있게 해 주는 유용한 도구예요. kapt는 Kotlin 소스 코드를 Java "스텁(stub)"으로 번역한 다음, 그 스텁에 대해 애너테이션 프로세서를 실행하는 방식으로 동작하죠. 그런데 이 과정은 비용이 크게 들고 빌드 시간을 크게 늘리며, 번역 과정에서 Kotlin 고유의 기능 일부가 유실된다는 단점이 있어요.

반면 KSP(Kotlin Symbol Processing)는 Kotlin 전용으로 설계된 kapt의 대안이에요. KSP는 모든 Kotlin 기능을 이해하고 소스 코드를 직접 분석하기 때문에 빌드 시간이 줄어들어요.

시작하기 전에, 프로젝트에 사용 중인 프로세서가 KSP를 지원하는지 확인하세요. 지원 라이브러리 목록을 확인하거나 각 프로세서의 문서를 참고하면 됩니다.

KSP와 kapt는 서로 나란히 실행될 수 있어요. 그래서 프로젝트를 라이브러리나 모듈 단위로 하나씩 단계적으로 마이그레이션할 수 있답니다.

프로젝트에 KSP 플러그인 추가하기

프로젝트 레벨의 build.gradle(.kts) 파일에 있는 plugins {} 블록에 KSP를 추가해요:

plugins {
    id("com.google.devtools.ksp") version "2.3.10" apply false 
}

plugins {
    id 'com.google.devtools.ksp' version '2.3.10' apply false 
}

KSP의 최신 버전은 GitHub Releases에서 찾아볼 수 있어요.

프로세서 업데이트하기

마이그레이션하려는 프로세서를 사용하는 모듈을 찾으세요. 해당 모듈의 build.gradle(.kts) 파일에서 다음을 진행합니다.

plugins {} 블록에 KSP를 추가해요:

plugins {
    id("com.google.devtools.ksp")
}

plugins {
    id 'com.google.devtools.ksp'
}

dependencies {} 블록에서 kapt를 ksp로 바꿔요:

dependencies {
    implementation("com.google.dagger:dagger:2.48")
    // kapt("com.google.dagger:dagger-compiler:2.48")

    // KSP processor dependency:
    ksp("com.google.dagger:dagger-compiler:2.48") 
}

dependencies {
    implementation 'com.google.dagger:dagger:2.48'
    // kapt 'com.google.dagger:dagger-compiler:2.48'

    // KSP processor dependency:
    ksp 'com.google.dagger:dagger-compiler:2.48'
}

대부분의 라이브러리에서는 이 교체만으로 충분해요. 추가 변경이 필요한지 각 라이브러리 문서를 확인해 보세요.

kapt 플러그인 제거하기

모든 프로세서를 KSP로 마이그레이션한 후에는 모든 빌드 파일에서 kapt 플러그인을 안전하게 제거할 수 있어요:

plugins {
   // Delete this line:
    id("org.jetbrains.kotlin.kapt")
}

plugins {
    // Delete this line:
    id 'org.jetbrains.kotlin.kapt'
}

혹시 남아 있는 kapt 설정이 있다면 그것도 함께 삭제하세요.

다음 단계는?

KSP 시작하기(Getting started with KSP)에서 나만의 KSP 기반 애너테이션 프로세서를 만드는 방법을 배워요.
KSP 저장소에서 KSP를 사용한 예제 프로젝트를 살펴보세요.
개요(Overview)에서 KSP에 대해 더 자세히 읽어보세요.

kapt에서 KSP로 마이그레이션하기