명령줄에서 KSP 실행하기

명령줄에서 KSP 실행하기 (Running KSP from the command line)

대부분의 프로젝트는 Gradle 플러그인으로 KSP를 사용해요. Gradle 플러그인은 컴파일 중에 KSP를 자동으로 돌려주죠. KSP를 명령줄에서도 쓸 수는 있지만, 보통은 다른 빌드 시스템과 통합하거나 프로세서를 개발·테스트·디버깅할 때만 사용해요.

KSP는 JVM 애플리케이션이라 명령줄에서 실행할 때는 java 명령으로 띄워요. 클래스패스와 필요한 인자를 함께 넘겨주면 되죠.

java -cp <classpath> <mainclass> <options> <processor>
Argument Description
<classpath> KSP 런타임 JAR과 그 의존성들이 있는 경로.
<mainclass> 플랫폼별 KSP 진입점 중 하나.
<options> KSP를 위한 명령줄 옵션.
<processor> 프로세서 JAR 경로.

출처: Kotlin 공식 문서

본문

클래스패스 (Classpath)

Gradle 플러그인과 달리 java 명령은 의존성을 자동으로 해결하지 않아요. 클래스패스에 KSP 런타임 JAR과 그 의존성들을 직접 넣어줘야 해요.

KSP 릴리스 페이지에서 artifacts.zip을 내려받아요. 압축 파일 안에 필요한 KSP JAR 파일들이 들어 있어요.

  • symbol-processing-aa-2.3.10.jar
  • symbol-processing-common-deps-2.3.10.jar
  • symbol-processing-api-2.3.10.jar

Maven 저장소에서 다음 런타임 의존성들도 함께 포함해야 해요.

메인 클래스 (Main class)

KSP는 JVM 애플리케이션이라 실행할 메인 클래스를 지정해야 해요. KSP는 지원하는 플랫폼마다 다른 진입점을 제공해요.

Entry point Platforms
KSPJvmMain Kotlin/JVM과 Android
KSPJsMain Kotlin/JS
KSPNativeMain Kotlin/Native 타깃. 예: iOS, macOS, Linux, Windows
KSPCommonMain Kotlin Multiplatform 프로젝트의 공통(common) 컴파일

java로 KSP를 실행할 때는 완전한 클래스 이름(fully qualified class name)을 지정해요. 예를 들면 이렇게요.

java -cp <classpath> com.google.devtools.ksp.cmdline.KSPJvmMain <options> <processor>

다음 예제는 KSPJvmMain을 사용해 JVM 타깃에서 KSP를 실행하는 모습이에요.

java -cp \
symbol-processing-aa-2.3.10.jar:symbol-processing-common-deps-2.3.10.jar:symbol-processing-api-2.3.10.jar:kotlin-stdlib-2.3.20.jar:kotlinx-coroutines-core-jvm-1.10.2.jar \
com.google.devtools.ksp.cmdline.KSPJvmMain \
-language-version=2.0 \
-api-version=2.0 \
-jvm-target=11 \
-module-name=main \
-source-roots=project_dir/src/kotlin/main \
-project-base-dir=project_dir/ \
-output-base-dir=project_dir/build/ \
-caches-dir=project_dir/build/caches/ \
-class-output-dir=project_dir/build/out/main/classes \
-kotlin-output-dir=project_dir/build/out/main/kotlin/ \
-java-output-dir=project_dir/build/out/main/java/ \
-resource-output-dir=project_dir/build/out/main/res/ \
path/to/processor.jar

옵션 (Options)

명령줄로 실행할 때 KSP가 요구하는 옵션들은 이래요.

Option Description
-language-version=<version> 프로젝트에서 사용하는 Kotlin 언어 버전.
-api-version=<version> Kotlin API 버전.
-jvm-target=<version> 대상 JVM 버전.
-module-name=<name> 모듈 이름.
-source-roots=<paths> 소스 루트 디렉터리. 여러 디렉터리는 콜론으로 구분해요.
-project-base-dir=<path> 프로젝트 루트 디렉터리.
-output-base-dir=<path> KSP 출력의 기본 디렉터리.
-caches-dir=<path> KSP 캐시 디렉터리.
-java-output-dir=<path> 생성된 Java 파일 디렉터리.
-class-output-dir=<path> 생성된 클래스 파일 디렉터리.
-kotlin-output-dir=<path> 생성된 Kotlin 파일 디렉터리.
-resource-output-dir=<path> 생성된 리소스 디렉터리.
<processor> 프로세서 클래스패스.

그 외 유용한 옵션

  • -libraries=<path>: 소스 파일이 참조하는 의존성을 해결하는 데 쓰는 클래스패스. 보통 모듈의 컴파일 클래스패스예요.
  • -jdk-home=<path>: JDK 홈 디렉터리. 프로세서가 Java 심볼을 해석하고 Java 표준 라이브러리에 접근해야 할 때 사용해요.
  • -friends=<path>: 현재 모듈의 프렌드(friend) 모듈 클래스패스. 보통 모듈의 프렌드 클래스패스예요. 자세한 내용은 Friend modules을 참고해요.

KSP는 로깅 레벨을 설정하는 -Dksp.logging JVM 시스템 속성도 지원해요. 유효한 값은 error, warn(또는 warning), info, debug예요. 기본값은 warn이에요. 지원하지 않는 값을 주면 KSP는 warn으로 처리해요.

전체 옵션 목록을 보려면 다음 명령을 실행하면 돼요.