Kotlin Gradle 플러그인의 컴파일러 옵션
Kotlin의 각 릴리스에는 지원되는 타깃을 위한 컴파일러가 포함되어 있습니다. 여기에는 JVM, JavaScript, 그리고 지원되는 플랫폼을 위한 네이티브 바이너리가 포함됩니다.
이 컴파일러들은 다음과 같은 상황에서 사용됩니다:
- IDE에서 Kotlin 프로젝트의 Compile 또는 Run 버튼을 클릭할 때.
- 콘솔이나 IDE에서
gradle build를 호출할 때. - 콘솔이나 IDE에서
mvn compile또는mvn test-compile을 호출할 때.
커맨드라인 컴파일러 사용법 튜토리얼에 설명된 대로 커맨드라인에서 Kotlin 컴파일러를 수동으로 실행할 수도 있습니다.
옵션 정의 방법
Kotlin 컴파일러에는 컴파일 프로세스를 조정할 수 있는 다양한 옵션이 있습니다.
Gradle DSL을 사용하면 컴파일러 옵션을 종합적으로 구성할 수 있습니다. 이는 Kotlin Multiplatform 및 JVM/Android 프로젝트에서 사용할 수 있습니다.
Gradle DSL을 사용하면 빌드 스크립트 내에서 다음 세 가지 수준(Level)으로 컴파일러 옵션을 구성할 수 있습니다:
- 확장 수준(Extension level): 모든 타깃 및 공유 소스 세트를 위한
kotlin {}블록 내부. - 타깃 수준(Target level): 특정 타깃을 위한 블록 내부.
- 컴파일 단위 수준(Compilation unit level): 일반적으로 특정 컴파일 태스크 내부.
더 높은 수준의 설정은 하위 수준의 규칙(기본값)으로 사용됩니다:
- 확장 수준에서 설정된 컴파일러 옵션은
commonMain,nativeMain,commonTest와 같은 공유 소스 세트를 포함하여 타깃 수준 옵션의 기본값이 됩니다. - 타깃 수준에서 설정된 컴파일러 옵션은
compileKotlinJvm및compileTestKotlinJvm태스크와 같은 컴파일 단위(태스크) 수준 옵션의 기본값이 됩니다.
반대로, 하위 수준에서 지정된 설정은 상위 수준의 관련 설정을 재정의(override)합니다:
- 태스크 수준의 컴파일러 옵션은 타깃 또는 확장 수준의 관련 구성을 재정의합니다.
- 타깃 수준의 컴파일러 옵션은 확장 수준의 관련 구성을 재정의합니다.
컴파일에 어떤 수준의 컴파일러 인자가 적용되었는지 확인하려면 Gradle 로깅의 DEBUG 레벨을 사용하세요. JVM 및 JS/WASM 태스크의 경우 로그 내에서 "Kotlin compiler args:" 문자열을 검색하고, Native 태스크의 경우 "Arguments =" 문자열을 검색하세요.
서드파티 플러그인 작성자라면 재정의 문제를 방지하기 위해 프로젝트 수준에서 구성을 적용하는 것이 가장 좋습니다. 이를 위해 새로운 Kotlin 플러그인 DSL 확장 타입을 사용할 수 있습니다. 이 구성을 작성자 측 문서에 명시적으로 기록해 두는 것을 권장합니다.
확장 수준(Extension level)
최상위 수준의 compilerOptions {} 블록에서 모든 타깃 및 공유 소스 세트에 대한 공통 컴파일러 옵션을 구성할 수 있습니다:
kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}타깃 수준(Target level)
target {} 블록 내부의 compilerOptions {} 블록에서 JVM/Android 타깃을 위한 컴파일러 옵션을 구성할 수 있습니다:
kotlin {
target {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}
}Kotlin Multiplatform 프로젝트에서는 특정 타깃 내부에서 컴파일러 옵션을 구성할 수 있습니다. 예를 들면 jvm { compilerOptions {}}와 같습니다. 자세한 내용은 Multiplatform Gradle DSL 레퍼런스를 참조하세요.
컴파일 단위 수준(Compilation unit level)
태스크 구성 내부의 compilerOptions {} 블록에서 특정 컴파일 단위 또는 태스크에 대한 컴파일러 옵션을 구성할 수 있습니다:
tasks.named<KotlinJvmCompile>("compileKotlin"){
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}KotlinCompilation을 통해 컴파일 단위 수준에서 컴파일러 옵션에 접근하고 구성할 수도 있습니다:
kotlin {
target {
val main by compilations.getting {
compileTaskProvider.configure {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}
}
}
}JVM/Android 및 Kotlin Multiplatform과 다른 타깃의 플러그인을 구성하려면 해당 Kotlin 컴파일 태스크의 compilerOptions {} 프로퍼티를 사용하세요. 다음 예제는 Kotlin 및 Groovy DSL 모두에서 이 구성을 설정하는 방법을 보여줍니다:
tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
compilerOptions {
apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
}
}tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
compilerOptions {
apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
}
}kotlinOptions {}에서 compilerOptions {}로 마이그레이션
kotlinOptions {}에서 compilerOptions {}로 마이그레이션 Kotlin 2.2.0 이전에는 kotlinOptions {} 블록을 사용하여 컴파일러 옵션을 구성할 수 있었습니다. kotlinOptions {} 블록은 Kotlin 2.0.0부터 deprecated되었으므로, 이 섹션에서는 빌드 스크립트를 대신 compilerOptions {} 블록을 사용하도록 마이그레이션하기 위한 가이드와 권장 사항을 제공합니다:
컴파일러 옵션 중앙화 및 타입 사용
가능하면 항상 확장 수준에서 컴파일러 옵션을 구성하고, 컴파일 단위 수준에서 특정 태스크를 위해 이를 재정의하세요.
compilerOptions {} 블록에서는 일반 문자열을 사용할 수 없으므로 타입이 지정된 값으로 변환해야 합니다. 예를 들어 다음과 같은 코드가 있다면:
plugins {
kotlin("jvm") version "2.4.21"
}
tasks.withType<KotlinCompile>().configureEach {
kotlinOptions {
jvmTarget = "17"
languageVersion = "2.4"
apiVersion = "2.4"
}
}plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}
tasks.withType(KotlinCompile).configureEach {
kotlinOptions {
jvmTarget = '17'
languageVersion = '2.4'
apiVersion = '2.4'
}
}마이그레이션 후에는 다음과 같아야 합니다:
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
kotlin("jvm") version "2.4.21"
}
kotlin {
// 확장 수준
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// 컴파일 단위 수준에서의 재정의 예시
tasks.named<KotlinJvmCompile>("compileKotlin"){
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.4")
}
}import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}
kotlin {
// 확장 수준
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// 컴파일 단위 수준에서의 재정의 예시
tasks.named("compileKotlin", KotlinJvmCompile).configure {
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.4")
}
}android.kotlinOptions에서 마이그레이션
빌드 스크립트에서 이전에 android.kotlinOptions를 사용했다면 확장 수준 또는 타깃 수준 중 하나에서 kotlin.compilerOptions를 사용하도록 마이그레이션하세요.
예를 들어 다음과 같은 Android 프로젝트가 있다면:
plugins {
id("com.android.application")
kotlin("android")
}
android {
kotlinOptions {
jvmTarget = "17"
}
}plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
}
android {
kotlinOptions {
jvmTarget = '17'
}
}다음과 같이 업데이트합니다:
plugins {
id("com.android.application")
kotlin("android")
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}또한, Android 타깃이 포함된 Kotlin Multiplatform 프로젝트의 경우:
plugins {
kotlin("multiplatform")
id("com.android.application")
}
kotlin {
androidTarget {
compilations.all {
kotlinOptions.jvmTarget = "17"
}
}
}plugins {
id 'org.jetbrains.kotlin.multiplatform'
id 'com.android.application'
}
kotlin {
androidTarget {
compilations.all {
kotlinOptions {
jvmTarget = '17'
}
}
}
}다음과 같이 업데이트합니다:
plugins {
kotlin("multiplatform")
id("com.android.application")
}
kotlin {
androidTarget {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}
}plugins {
id 'org.jetbrains.kotlin.multiplatform'
id 'com.android.application'
}
kotlin {
androidTarget {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}
}freeCompilerArgs 마이그레이션
모든
+=연산을add()또는addAll()함수로 대체하세요.-opt-in컴파일러 옵션을 사용하는 경우, KGP API 레퍼런스에서 전용 DSL이 이미 제공되는지 확인하고 대신 해당 DSL을 사용하세요.-progressive컴파일러 옵션의 모든 사용을 전용 DSL인progressiveMode.set(true)로 마이그레이션하세요.-Xjvm-default컴파일러 옵션의 모든 사용을 전용 DSL 사용으로 마이그레이션하세요:jvmDefault.set(). 옵션에 대해 다음 매핑을 사용합니다:이전 이후 -Xjvm-default=all-compatibilityjvmDefault.set(JvmDefaultMode.ENABLE)-Xjvm-default=alljvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)-Xjvm-default=disablejvmDefault.set(JvmDefaultMode.DISABLE)
예를 들어 다음과 같은 코드가 있다면:
kotlinOptions {
freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all")
}kotlinOptions {
freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"]
}다음과 같이 마이그레이션합니다:
kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
progressiveMode.set(true)
jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
}
}kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
freeCompilerArgs.addAll(["-Xcontext-receivers", "-Xinline-classes"])
progressiveMode.set(true)
jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
}
}JVM 타깃 지정
앞서 설명한 바와 같이, JVM/Android 프로젝트의 컴파일러 옵션은 확장, 타깃, 컴파일 단위 수준(태스크)에서 정의할 수 있습니다.
기본 JVM 컴파일 태스크는 프로덕션 코드의 경우 compileKotlin, 테스트 코드의 경우 compileTestKotlin이라고 불립니다. 커스텀 소스 세트의 태스크 이름은 compile<Name>Kotlin 패턴에 따라 지정됩니다.
터미널에서 gradlew tasks --all 명령을 실행하고 Other tasks 그룹에서 compile*Kotlin 태스크 이름을 검색하면 Android 컴파일 태스크 목록을 볼 수 있습니다.
알아두어야 할 몇 가지 중요한 세부 사항:
kotlin.compilerOptions는 프로젝트의 모든 Kotlin 컴파일 태스크를 구성합니다.tasks.named<KotlinJvmCompile>("compileKotlin") { }(또는tasks.withType<KotlinJvmCompile>().configureEach { }) 방식을 사용하여kotlin.compilerOptionsDSL에 의해 적용된 구성을 재정의할 수 있습니다.
JavaScript 타깃 지정
JavaScript 컴파일 태스크는 프로덕션 코드의 경우 compileKotlinJs, 테스트 코드의 경우 compileTestKotlinJs, 커스텀 소스 세트의 경우 compile<Name>KotlinJs라고 불립니다.
단일 태스크를 구성하려면 해당 태스크의 이름을 사용하세요:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
val compileKotlin: KotlinCompilationTask<*> by tasks
compileKotlin.compilerOptions.suppressWarnings.set(true)import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions {
suppressWarnings = true
}
}Gradle Kotlin DSL을 사용할 때는 먼저 프로젝트의 tasks에서 해당 태스크를 가져와야 합니다.
JS 타깃에는 Kotlin2JsCompile을, 공통 타깃에는 KotlinCompileCommon 타입을 각각 사용하세요.
터미널에서 gradlew tasks --all 명령을 실행하고 Other tasks 그룹에서 compile*KotlinJS 태스크 이름을 검색하면 JavaScript 컴파일 태스크 목록을 확인할 수 있습니다.
모든 Kotlin 컴파일 태스크 구성
프로젝트의 모든 Kotlin 컴파일 태스크를 구성하는 것도 가능합니다:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
compilerOptions { /*...*/ }
}import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions { /*...*/ }
}모든 컴파일러 옵션
Kotlin Gradle 플러그인을 통해 사용할 수 있는 Kotlin 컴파일러 옵션의 전체 목록은 다음과 같습니다:
공통 속성
| 이름 | 설명 | 가능한 값 | 기본값 |
|---|---|---|---|
allWarningsAsErrors | 경고가 하나라도 있으면 오류로 보고합니다. | false | |
apiVersion | 코드에서 사용할 수 있는 Kotlin API를 제어합니다. 자세한 내용은 -api-version을 참조하세요. | "2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL) | |
extraWarnings | true인 경우 경고를 발생시키는 추가 선언, 표현식 및 타입 컴파일러 검사를 활성화합니다. | true, false | false |
freeCompilerArgs | 추가 컴파일러 인자 목록입니다. 여기에서 실험적 -X 인자도 사용할 수 있습니다. 예시를 참조하세요. | [] | |
languageVersion | 컴파일 중에 사용할 수 있는 Kotlin 언어 기능 및 구문을 제어합니다. 자세한 내용은 -language-version을 참조하세요. | "2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL) | |
optIn | opt-in 컴파일러 인자 목록을 구성하기 위한 프로퍼티입니다. | listOf( /* opt-ins */ ) | emptyList() |
progressiveMode | 점진적 컴파일러 모드(progressive compiler mode)를 활성화합니다. | true, false | false |
suppressWarnings | 경고를 생성하지 않습니다. | false | |
verbose | 상세 로깅 출력을 활성화합니다. Gradle 디버그 로그 레벨이 활성화된 경우에만 작동합니다. | false |
향후 릴리스에서 freeCompilerArgs 속성을 deprecate할 예정입니다. Kotlin Gradle DSL에서 누락된 옵션이 있다면 이슈를 등록해 주세요.
freeCompilerArgs를 통한 추가 인자 사용 예시
추가 컴파일러 인자(실험적 인자 포함)를 전달하려면 freeCompilerArgs 속성을 사용하세요. 이 속성에 단일 인자 또는 인자 목록을 추가할 수 있습니다:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
kotlin {
compilerOptions {
// Kotlin API 버전 및 JVM 타깃 지정
apiVersion.set(KotlinVersion.KOTLIN_2_4)
jvmTarget.set(JvmTarget.JVM_1_8)
// 단일 실험적 인자
freeCompilerArgs.add("-Xexport-kdoc")
// 단일 추가 인자
freeCompilerArgs.add("-Xno-param-assertions")
// 모듈 경로에서 추가 루트 모듈 확인
freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")
// 인자 목록
freeCompilerArgs.addAll(
listOf(
"-Xno-receiver-assertions",
"-Xno-call-assertions"
)
)
}
}import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions {
// Kotlin API 버전 및 JVM 타깃 지정
apiVersion = KotlinVersion.KOTLIN_2_4
jvmTarget = JvmTarget.JVM_1_8
// 단일 실험적 인자
freeCompilerArgs.add("-Xexport-kdoc")
// 단일 추가 인자 (키-값 쌍 가능)
freeCompilerArgs.add("-Xno-param-assertions")
// 모듈 경로에서 추가 루트 모듈 확인
freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")
// 인자 목록
freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
}
}freeCompilerArgs 속성은 확장, 타깃, 컴파일 단위 (태스크) 수준에서 사용할 수 있습니다.
languageVersion 설정 예시
언어 버전을 설정하려면 다음 구문을 사용하세요:
kotlin {
compilerOptions {
languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
}
}tasks
.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
.configureEach {
compilerOptions.languageVersion =
org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4
}일부 속성은 커스텀 타입을 사용합니다. 자세한 내용은 컴파일러 옵션용 타입을 참조하세요.
JVM 전용 속성
| 이름 | 설명 | 가능한 값 | 기본값 |
|---|---|---|---|
javaParameters | 메서드 파라미터에 대한 Java 1.8 리플렉션용 메타데이터를 생성합니다. | false | |
jvmTarget | 생성되는 JVM 바이트코드의 타깃 버전입니다. | "1.8", "9", "10", ..., "25", "26". 컴파일러 옵션용 타입도 참조하세요. | "1.8" |
jvmTargetValidationMode |
| WARNING, ERROR, IGNORE | ERROR |
jvmDefault | 인터페이스에 선언된 함수가 JVM의 디폴트 메서드로 컴파일되는 방식을 제어합니다. | ENABLE, NO_COMPATIBILITY, DISABLE | ENABLE |
noJdk | Java 런타임을 클래스패스에 자동으로 포함하지 않습니다. | false | |
-Xadd-modules | (실험적) 초기 모듈 외에 지정된 루트 모듈을 확인합니다. 모듈 경로의 모든 모듈을 확인하려면 ALL-MODULE-PATH 값을 설정하세요. | 쉼표로 구분된 모듈 이름 또는 freeCompilerArgs를 통해 전달되는 ALL-MODULE-PATH |
JavaScript 전용 속성
| 이름 | 설명 | 가능한 값 | 기본값 |
|---|---|---|---|
friendModulesDisabled | 내부(internal) 선언 내보내기(export)를 비활성화합니다. | false | |
main | 실행 시 main 함수를 호출해야 하는지 여부를 지정합니다. | JsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALL | JsMainFunctionExecutionMode.CALL |
moduleKind | 컴파일러가 생성하는 JS 모듈의 종류입니다. | JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMD | null |
sourceMap | 소스 맵(Source map)을 생성합니다. | false | |
sourceMapEmbedSources | 소스 맵에 소스 파일을 포함합니다. | JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYS | null |
sourceMapNamesPolicy | Kotlin 코드에 선언한 변수 및 함수 이름을 소스 맵에 추가합니다. 동작에 대한 자세한 내용은 컴파일러 레퍼런스를 참조하세요. | JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NO | null |
sourceMapPrefix | 소스 맵의 경로에 지정된 접두사를 추가합니다. | null | |
target | 특정 ECMA 버전을 위한 JS 파일을 생성합니다. | "es5", "es2015", "es2020" | "es5" |
useEsClasses | 생성된 JavaScript 코드가 ES2015 클래스를 사용하도록 합니다. ES2015 및 ES2020 타깃 사용 시 기본적으로 활성화됩니다. | null |
컴파일러 옵션용 타입
일부 compilerOptions는 String 타입 대신 커스텀 타입을 사용합니다:
| 옵션 | 타입 | 예시 |
|---|---|---|
apiVersion 및 languageVersion | KotlinVersion | compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4) |
jvmTarget | JvmTarget | compilerOptions.jvmTarget.set(JvmTarget.JVM_11) |
main | JsMainFunctionExecutionMode | compilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL) |
moduleKind | JsModuleKind | compilerOptions.moduleKind.set(JsModuleKind.MODULE_ES) |
sourceMapEmbedSources | JsSourceMapEmbedMode | compilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING) |
sourceMapNamesPolicy | JsSourceMapNamesPolicy | compilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES) |
다음 단계
다음에 대해 자세히 알아보세요:
