kapt 컴파일러 플러그인

• 다음과 같은 경우 kapt를 사용하세요:
  • Maven 프로젝트를 사용하는 경우.
  • Gradle 프로젝트를 사용하지만, 필요한 Java 어노테이션 프로세서가 아직 KSP를 지원하지 않는 경우. 지원되는 라이브러리 목록 보기.
• 다음과 같은 경우 KSP를 사용하세요:
  • Gradle 프로젝트를 사용하고, 필요한 Java 어노테이션 프로세서가 KSP를 지원하는 경우.
  • 직접 어노테이션 프로세서를 만들려는 경우.

kapt 컴파일러 플러그인을 사용하면 Kotlin에서 기존 Java 어노테이션 프로세서를 사용할 수 있으며, Maven과 Gradle 모두에서 작동합니다. kapt는 Kotlin 소스 코드에서 스텁(stub) 파일을 생성한 다음, 해당 스텁에 대해 Java 어노테이션 프로세서를 실행합니다.

이를 통해 Kotlin 프로젝트에서 MapStruct나 Data Binding과 같은 라이브러리를 위한 Java 기반 어노테이션 처리가 가능해집니다.

kapt는 IntelliJ 빌드 시스템에서 지원되지 않습니다. IntelliJ IDEA에서 어노테이션 처리를 다시 실행하려면 Maven 도구 창에서 빌드를 시작하세요.

플러그인 설정하기

Gradle, Maven을 위해 kapt 플러그인을 구성하거나 커맨드 라인에서 사용할 수 있습니다.

Gradle

Gradle에서 kapt를 사용하려면 다음 단계를 따르세요:

1. 빌드 스크립트 파일 build.gradle(.kts)에 kapt Gradle 플러그인을 적용합니다:

   KotlinGroovy

   plugins {
       kotlin("kapt") version "2.4.10"
   }

   plugins {
       id "org.jetbrains.kotlin.kapt" version "2.4.10"
   }

2. dependencies {} 블록에서 kapt 구성을 사용하여 해당하는 의존성을 추가합니다:

   KotlinGroovy

   dependencies {
       kapt("groupId:artifactId:version")
   }

   dependencies {
       kapt 'groupId:artifactId:version'
   }

3. 이전에 어노테이션 프로세서를 위해 Android 지원 기능을 사용했다면, annotationProcessor 구성의 사용처를 kapt로 변경하세요. 프로젝트에 Java 클래스가 포함되어 있는 경우에도 kapt 플러그인이 이를 함께 처리합니다.

   androidTest 또는 test 소스에 어노테이션 프로세서를 사용하는 경우, 각각 kaptAndroidTest와 kaptTest라는 이름의 kapt 구성을 사용합니다. kaptAndroidTest와 kaptTest는 kapt를 상속받으므로, kapt 의존성을 제공하면 프로덕션 소스와 테스트 모두에서 사용할 수 있습니다.

Maven

설정을 간소화하기 위해 <extensions> 옵션을 사용하거나, kapt 실행을 완전히 제어하기 위해 수동으로 설정할 수 있습니다.

자동 구성

Kotlin Maven 플러그인의 <extensions> 옵션을 활성화하여 kapt 구성을 간소화할 수 있습니다. 이 경우 kapt의 <execution> 섹션을 목표(goal)나 소스 디렉토리와 함께 수동으로 설정할 필요가 없습니다.

kapt를 자동으로 구성하려면, pom.xml 빌드 파일에서 kotlin-maven-plugin의 <extensions> 옵션을 true로 설정하세요:

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <extensions>true</extensions>
    <configuration>
        <annotationProcessorPaths>
            <!-- 여기에 어노테이션 프로세서를 지정하세요 -->
            <annotationProcessorPath>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</plugin>

<extensions> 옵션에 대한 자세한 내용은 자동 구성을 참고하세요.

수동 구성

Kotlin Maven 프로젝트에서 kapt를 수동으로 설정하려면, compile 실행 이전에 kotlin-maven-plugin의 kapt 목표 실행을 추가하세요:

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </goals>
    <configuration>
        <sourceDirs>
            <sourceDir>src/main/kotlin</sourceDir>
            <sourceDir>src/main/java</sourceDir>
        </sourceDirs>
        <annotationProcessorPaths>
            <!-- 여기에 어노테이션 프로세서를 지정하세요 -->
            <annotationProcessorPath>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

어노테이션 처리 모드를 구성하려면 <configuration> 블록에서 aptMode 옵션을 설정하세요. 예시:

<configuration>
   ...
   <aptMode>stubs</aptMode>
</configuration>

CLI

kapt는 Kotlin 컴파일러의 바이너리 배포판에 독립적인 CLI 도구로 포함되어 있습니다.

커맨드 라인에서 kapt를 실행하려면 다음을 사용하세요:

kapt <options> <source files>

예시:

kapt -Kapt-mode=stubsAndApt \
  -Kapt-sources=build/kapt/sources \
  -Kapt-classes=build/kapt/classes \
  -Kapt-stubs=build/kapt/stubs \
  -Kapt-classpath=lib/ap.jar \
  -Kapt-classpath=lib/anotherAp.jar \
  src/main/kotlin

• kapt 전용 컴파일러 옵션 전체 목록을 확인하세요.
• 모든 유효한 Kotlin 컴파일러 옵션도 전달할 수 있습니다. kotlinc -help를 실행하여 확인할 수 있습니다.

어노테이션 프로세서 구성

kapt는 프로세서 클래스패스 관리, 공유 구성으로부터 프로세서 상속, javac 전용 프로세서 활성 상태 유지 등 어노테이션 프로세서가 검색, 조직 및 실행되는 방식을 제어하는 옵션을 제공합니다.

어노테이션 프로세서 및 javac에 옵션을 전달하는 것과 같은 추가 구성 옵션은 어노테이션 프로세서 구성을 참고하세요.

프로세서 클래스패스 및 검색 구성

kapt의 프로세서 경로(processor path)에 포함되지 않은 어노테이션 프로세서의 검색을 비활성화할 수 있습니다. 이를 통해 컴파일 클래스패스에서 불필요한 어노테이션 프로세서를 제외할 수 있습니다.

Gradle

Gradle은 프로젝트 재빌드 시 컴파일 회피(compile avoidance)를 사용하여 어노테이션 처리를 건너뛰고, kapt를 사용한 증분 빌드 시간을 개선합니다. 특히 다음과 같은 경우에 어노테이션 처리를 건너뜁니다:

• 프로젝트의 소스 파일이 변경되지 않았을 때.
• 의존성의 변경 사항이 ABI 호환될 때 (예: 함수 본문만 변경된 경우).

그러나 컴파일 클래스패스에서 발견된 어노테이션 프로세서의 경우에는 컴파일 회피를 사용할 수 없습니다. 해당 프로세서의 내부 구현이 변경되면 프로세서의 ABI가 변경되지 않더라도 어노테이션 처리 작업을 다시 실행해야 하기 때문입니다.

따라서 컴파일 클래스패스에 있는 어노테이션 프로세서를 사용하는 것은 권장되지 않습니다. 이러한 프로세서를 kapt 처리에서 제외하려면 gradle.properties 파일에 kapt.include.compile.classpath 속성을 추가하세요:

# gradle.properties
kapt.include.compile.classpath=false

이 옵션을 false로 설정하면, 프로세서 경로(kapt* 구성)에 포함되지 않은 어노테이션 프로세서 의존성은 kapt 처리에서 제외됩니다.

Maven

kapt의 프로세서 경로에 포함되지 않은 어노테이션 프로세서를 제외하려면, kapt 플러그인의 <execution> 섹션에서 includeCompileClasspath 옵션을 false로 설정하세요:

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </goals>
    <configuration>
        <includeCompileClasspath>false</includeCompileClasspath>
        <sourceDirs>...</sourceDirs>
        <annotationProcessorPaths>...</annotationProcessorPaths>
    </configuration>
</execution>

또는 pom.xml의 <properties> 섹션에서 kapt.include.compile.classpath 속성을 사용할 수 있습니다:

<properties>
    <kapt.include.compile.classpath>false</kapt.include.compile.classpath>
</properties>

이 옵션을 false로 설정하면, <annotationProcessorPaths> 섹션에 포함되지 않은 어노테이션 프로세서는 kapt 처리에서 제외됩니다.

includeCompileClasspath 옵션이 설정되지 않았고 kapt가 프로세서 경로에 명시적으로 정의되지 않은 어노테이션 프로세서를 컴파일 클래스패스에서 감지하면, 다음과 같은 지원 중단(deprecation) 경고가 표시됩니다:

[WARNING] Annotation processors discovery from compile classpath is deprecated.
Set 'kapt.include.compile.classpath=false' to disable discovery.

kapt 클래스패스에 포함되지 않은 어노테이션 프로세서 목록을 보려면, 빌드를 --info 로그 레벨 옵션과 함께 실행하세요.

상위 구성(superconfigurations)으로부터 어노테이션 프로세서 상속

별도의 Gradle 구성을 상위 구성으로 정의하여 공통 어노테이션 프로세서 세트를 구성하고, 이를 하위 프로젝트의 kapt 전용 구성에서 확장하여 사용할 수 있습니다.

예를 들어, MapStruct를 사용하는 하위 프로젝트의 경우 build.gradle(.kts) 파일에서 다음과 같이 구성합니다:

val commonAnnotationProcessors by configurations.creating
configurations.named("kapt") { extendsFrom(commonAnnotationProcessors) }

dependencies {
    implementation("org.mapstruct:mapstruct:1.6.3")
    commonAnnotationProcessors("org.mapstruct:mapstruct-processor:1.6.3")
}

이 예제에서 commonAnnotationProcessors Gradle 구성은 모든 프로젝트에서 사용하고자 하는 공통 어노테이션 처리 상위 구성입니다. extendsFrom() 메서드를 사용하여 commonAnnotationProcessors를 상위 구성으로 추가합니다. kapt는 commonAnnotationProcessors Gradle 구성이 MapStruct 어노테이션 프로세서에 의존하고 있음을 인식하고, 이를 자신의 어노테이션 처리 구성에 포함시킵니다.

Java 컴파일러의 어노테이션 프로세서 유지

기본적으로 kapt는 모든 어노테이션 프로세서를 실행하고 javac에 의한 어노테이션 처리는 비활성화합니다. 하지만 Lombok과 같은 일부 어노테이션 프로세서를 실행하기 위해 javac가 필요할 수 있습니다.

Gradle 빌드 파일에서 keepJavacAnnotationProcessors 옵션을 사용하세요:

kapt {
    keepJavacAnnotationProcessors = true
}

Maven을 사용하는 경우 플러그인 설정을 명시적으로 구성해야 합니다. 이 Lombok 컴파일러 플러그인 설정 예시를 참고하세요.

kapt 빌드 최적화

kapt는 작업을 병렬로 실행하거나, 빌드 캐시 활용, 프로세서 클래스 로더 캐싱, 증분 어노테이션 처리 사용 등 어노테이션 처리 시간을 줄이기 위한 몇 가지 Gradle 전용 전략을 제공합니다.

오류 타입 보정, 스텁 메타데이터 제거, 컴파일 클래스패스 스캐닝 등 빌드 동작에 영향을 주는 추가 옵션은 동작 옵션을 참고하세요.

kapt 작업을 병렬로 실행하기

kapt는 Gradle Worker API를 사용하여 어노테이션 처리 작업을 실행합니다. Worker API를 사용하면 Gradle이 단일 프로젝트 내의 독립적인 어노테이션 처리 작업을 병렬로 실행할 수 있으며, 이는 일부 경우에 실행 시간을 크게 단축시킵니다.

Kotlin Gradle 플러그인에서 커스텀 JDK 버전을 설정하는 경우, kapt 작업 워커(worker)는 processIsolation() 모드만 사용합니다.

kapt 워커 프로세스에 추가 JVM 인수를 제공하려면 KaptWithoutKotlincTask의 입력값인 kaptProcessJvmArgs를 사용하세요:

KotlinGroovy

tasks.withType<org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask>()
    .configureEach {
        kaptProcessJvmArgs.add("-Xmx512m")
    }

tasks.withType(org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask.class)
    .configureEach {
        kaptProcessJvmArgs.add('-Xmx512m')
    }

Gradle 빌드 캐시 안전하게 사용하기

kapt 어노테이션 처리 작업은 기본적으로 Gradle에서 캐시됩니다. 하지만 어노테이션 프로세서는 임의의 코드를 실행할 수 있습니다. 이는 작업 입력을 출력으로 불필요하게 변환하거나 Gradle이 추적하지 않는 파일에 접근하고 수정하는 결과를 초래할 수 있습니다.

빌드에 사용된 어노테이션 프로세서가 제대로 캐시될 수 없는 경우, kapt 작업에 대한 잘못된 캐시 히트(false-positive hits)를 방지하기 위해 캐싱을 비활성화할 수 있습니다. 이를 위해 빌드 스크립트에서 useBuildCache 속성을 사용하세요:

kapt {
    useBuildCache = false
}

Experimental

어노테이션 프로세서 클래스 로더 캐싱

어노테이션 프로세서의 클래스 로더 캐싱은 여러 Gradle 작업을 연속해서 실행할 때 kapt의 성능을 높이는 데 도움이 됩니다.

이 기능을 활성화하려면 gradle.properties 파일에서 다음 속성들을 사용하세요:

# gradle.properties
#
# 양수 값은 캐싱을 활성화합니다.
# kapt를 사용하는 모듈 수와 동일한 값을 사용하세요.
kapt.classloaders.cache.size=5

# 캐싱이 작동하려면 false로 설정해야 합니다.
kapt.include.compile.classpath=false

어노테이션 프로세서 캐싱과 관련하여 문제가 발생하는 경우, 해당 프로세서에 대한 캐싱을 비활성화하세요:

# 캐싱을 비활성화할 어노테이션 프로세서의 전체 이름을 지정합니다.
kapt.classloaders.cache.disableForProcessors=[어노테이션 프로세서 전체 이름]

이 기능과 관련하여 문제가 발생하면 YouTrack에 피드백을 남겨 주시면 감사하겠습니다.

증분 어노테이션 처리 사용하기

Gradle에서 kapt는 기본적으로 증분 어노테이션 처리를 지원하므로 변경된 파일만 다시 처리됩니다.

현재 증분 어노테이션 처리는 다음과 같은 경우에만 작동합니다:

• 증분 컴파일이 활성화되어 있어야 합니다.
• 빌드에 사용된 모든 어노테이션 프로세서가 증분형(incremental)이어야 합니다.

증분 어노테이션 처리를 비활성화하려면 gradle.properties 파일에 다음 라인을 추가하세요:

kapt.incremental.apt=false

현재 kapt의 증분 어노테이션 처리는 Maven이나 CLI에서는 지원되지 않습니다.

성능 분석

kapt는 어노테이션 처리 성능을 파악하는 데 도움이 되는 내장 진단 기능을 제공합니다. 여기에는 프로세서별 실행 시간 보고서와 사용되지 않는 프로세서를 식별하기 위한 생성된 파일 수 통계가 포함됩니다.

증분 처리 디버깅을 위한 파일 읽기 기록 및 메모리 누수 감지와 같은 더 많은 진단 옵션은 진단 및 통계 옵션을 참고하세요.

어노테이션 프로세서 성능 측정

어노테이션 프로세서 실행에 대한 성능 통계를 얻으려면 showProcessorStats 옵션을 사용하세요. 출력 예시는 다음과 같습니다:

Kapt Annotation Processing performance report:
com.example.processor.TestingProcessor: total: 133 ms, init: 36 ms, 2 round(s): 97 ms, 0 ms
com.example.processor.AnotherProcessor: total: 100 ms, init: 6 ms, 1 round(s): 93 ms

dumpProcessorStats 옵션을 사용하여 이 보고서를 파일로 저장할 수 있습니다. 예를 들어, 다음 CLI 명령은 kapt를 실행하고 통계를 ap-perf-report.file 파일에 저장합니다:

kapt -Kapt-mode=stubsAndApt \
  -Kapt-classpath=processor/build/libs/processor.jar \
  -Kapt-dump-processor-stats=ap-perf-report.file \
  sample/src/main/

생성된 파일 수 추적

kapt 플러그인은 각 어노테이션 프로세서에 대해 생성된 파일 수에 대한 통계를 보고할 수 있습니다.

이를 통해 사용되지 않는 어노테이션 프로세서가 빌드에 포함되어 있는지 추적할 수 있습니다. 생성된 보고서를 사용하여 불필요한 어노테이션 프로세서를 실행하는 모듈을 찾아내고, 이를 방지하도록 모듈을 업데이트할 수 있습니다.

통계 보고를 활성화하려면:

1. Gradle 빌드 파일에서 showProcessorStats 옵션 값을 true로 설정합니다:

   // build.gradle(.kts)
   kapt {
       showProcessorStats = true
   }

2. gradle.properties 파일에서 verbose 컴파일러 옵션을 true로 설정합니다:

   # gradle.properties
   kapt.verbose=true

통계는 info 레벨의 로그에 나타납니다. Annotation processor stats: 라인 다음에 각 어노테이션 프로세서의 실행 시간에 대한 통계가 표시됩니다. 그 후 Generated files report: 라인 다음에 각 어노테이션 프로세서가 생성한 파일 수에 대한 통계가 표시됩니다. 예시:

[INFO] Annotation processor stats:
[INFO] org.mapstruct.ap.MappingProcessor: total: 290 ms, init: 1 ms, 3 round(s): 289 ms, 0 ms, 0 ms
[INFO] Generated files report:
[INFO] org.mapstruct.ap.MappingProcessor: total sources: 2, sources per round: 2, 0, 0

현재 showProcessorStats 및 verbose 컴파일러 옵션을 사용한 생성 파일 수 추적은 Maven이나 CLI에서 지원되지 않습니다.

Kotlin 소스 생성

kapt는 Kotlin 소스를 생성할 수 있습니다. 생성된 Kotlin 소스 파일을 processingEnv.options["kapt.kotlin.generated"]에 지정된 디렉토리에 작성하면, 이 파일들은 메인 소스와 함께 컴파일됩니다.

kapt는 생성된 Kotlin 파일에 대해 다중 라운드(multiple rounds) 처리를 지원하지 않습니다.

컴파일러 옵션

어노테이션 프로세서 구성

옵션	설명	설정 방법
aptMode	kapt 워크플로 단계의 실행을 제어합니다: stubsAndApt: 스텁을 생성하고 어노테이션 처리를 실행합니다 (기본값) stubs: Kotlin에서 Java 스텁만 생성합니다 apt: 어노테이션 프로세서만 실행합니다 (스텁이 이미 존재한다고 가정함)	Gradle: 직접 사용할 수 없음; Gradle은 스텁 생성과 apt를 별도의 작업으로 실행합니다 Maven: CLI: -Kapt-mode=stubsAndApt
classpath	어노테이션 프로세서가 검색되는 클래스패스 항목입니다.	Gradle: Maven: CLI: -Kapt-classpath=lib/my-processor.jar
processors	검색 과정을 건너뛰고 실행할 프로세서의 정규화된 클래스 이름(쉼표로 구분)입니다.	Gradle: Maven: CLI: -Kapt-processors=com.example.MyProcessor
apOption	어노테이션 프로세서에 전달되는 키-값 옵션입니다.	Gradle: Maven: CLI: -Kapt-options:room.schemaLocation=/schemas
javacOption	Java 컴파일러에 전달되는 키-값 옵션입니다.	Gradle: Maven: CLI: -Kapt-javac-option:-source=11
processIncrementally	증분 어노테이션 처리를 활성화합니다. 변경 사항의 영향을 받는 파일만 다시 처리합니다.	Gradle: Maven: 현재 지원되지 않음 CLI: 현재 지원되지 않음

출력 디렉토리 옵션

옵션	설명	설정 방법
sources	어노테이션 프로세서가 .java 소스 파일을 생성하는 디렉토리입니다.	Gradle: 자동으로 build/generated/source/kapt/main으로 설정됨 Maven: 자동으로 target/generated-sources/kapt/로 설정됨 CLI: -Kapt-sources=build/kapt/sources
classes	생성된 소스에서 컴파일된 .class 파일의 디렉토리입니다.	Gradle: 자동으로 관리됨 Maven: 자동으로 관리됨 CLI: -Kapt-classes=build/kapt/classes
stubs	Kotlin 소스에서 생성된 Java 스텁 파일의 디렉토리로, 어노테이션 프로세서의 입력으로 사용됩니다.	Gradle: 자동으로 관리됨 Maven: 자동으로 관리됨 CLI: -Kapt-stubs=build/kapt/stubs
incrementalData	증분 빌드를 위한 상태를 저장합니다.	Gradle: 자동으로 관리됨 Maven: 현재 지원되지 않음 CLI: 현재 지원되지 않음

동작 옵션

옵션	설명	설정 방법
correctErrorTypes	기본적으로 kapt는 생성된 클래스의 타입을 포함하여 모든 알 수 없는 타입을 NonExistentClass로 대체합니다. 스텁에서 오류 타입 추론을 활성화하여 해결되지 않은 오류 타입을 생성된 소스의 타입으로 대체할 수 있습니다. 기본값: false	Gradle: Maven: CLI: -Kapt-correct-error-types=true
dumpDefaultParameterValues	생성된 스텁에 필드 값으로 기본 파라미터 초기화 식을 포함합니다. 기본값: false	Gradle: Maven: 사용 불가 CLI: -Kapt-dump-default-parameter-values=true
mapDiagnosticLocations	스텁 파일의 오류 메시지를 원래의 Kotlin 소스 위치로 매핑합니다. 기본값: false	Gradle: Maven: CLI: -Kapt-map-diagnostic-locations=true
strict	스텁 생성 시 발생하는 비호환성 문제를 경고 대신 오류로 처리합니다. 기본값: false	Gradle: Maven: 사용 불가 CLI: -Kapt-strict=true
stripMetadata	생성된 스텁에서 @kotlin.Metadata 어노테이션을 제거하여 스텁 크기를 줄이고 프로세서로부터 Kotlin 전용 정보를 숨깁니다. 기본값: false	Gradle: Maven: 사용 불가 CLI: -Kapt-strip-metadata=true
verbose	상세한 kapt 로깅을 활성화합니다. 기본값: false	Gradle: Maven: 현재 지원되지 않음 CLI: 현재 지원되지 않음
infoAsWarnings	kapt의 정보(info) 레벨 메시지를 경고(warning)로 격상합니다. 기본값: false	Gradle: 직접 사용할 수 없음 Maven: 현재 지원되지 않음 CLI: 현재 지원되지 않음
includeCompileClasspath	어노테이션 프로세서를 찾기 위해 컴파일 클래스패스를 스캔합니다. 재현성을 위해 false로 설정하는 것이 좋습니다. 기본값: true	Gradle: Maven: CLI: 현재 지원되지 않음

진단 및 통계 옵션

옵션	설명	설정 방법
showProcessorStats	프로세서별 실행 시간을 표준 출력(stdout)에 출력합니다.	Gradle: Maven: 사용 불가 CLI: -Kapt-show-processor-stats=true
dumpProcessorStats	프로세서 타이밍 통계를 파일에 기록합니다.	Gradle: 사용 불가 Maven: 사용 불가 CLI: -Kapt-dump-processor-stats=build/kapt-stats.txt
dumpFileReadHistory	프로세서가 읽은 파일 목록을 파일에 기록합니다. 증분 어노테이션 프로세서 디버깅에 유용합니다.	Gradle: 사용 불가 Maven: 사용 불가 CLI: -Kapt-dump-file-read-history=build/kapt-reads.txt
detectMemoryLeaks	메모리 누수 감지 모드: none, default, 또는 paranoid.	Gradle: Maven: 현재 지원되지 않음 CLI: 현재 지원되지 않음

다음 단계

• MapStruct 어노테이션 프로세서와 함께 kapt 사용하기
• kapt에서 KSP로 마이그레이션하는 방법 보기