Skip to content

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)으로 컴파일러 옵션을 구성할 수 있습니다:

Kotlin 컴파일러 옵션 수준

더 높은 수준의 설정은 하위 수준의 규칙(기본값)으로 사용됩니다:

  • 확장 수준에서 설정된 컴파일러 옵션은 commonMain, nativeMain, commonTest와 같은 공유 소스 세트를 포함하여 타깃 수준 옵션의 기본값이 됩니다.
  • 타깃 수준에서 설정된 컴파일러 옵션은 compileKotlinJvm 및 compileTestKotlinJvm 태스크와 같은 컴파일 단위(태스크) 수준 옵션의 기본값이 됩니다.

반대로, 하위 수준에서 지정된 설정은 상위 수준의 관련 설정을 재정의(override)합니다:

  • 태스크 수준의 컴파일러 옵션은 타깃 또는 확장 수준의 관련 구성을 재정의합니다.
  • 타깃 수준의 컴파일러 옵션은 확장 수준의 관련 구성을 재정의합니다.

컴파일에 어떤 수준의 컴파일러 인자가 적용되었는지 확인하려면 Gradle 로깅의 DEBUG 레벨을 사용하세요. JVM 및 JS/WASM 태스크의 경우 로그 내에서 "Kotlin compiler args:" 문자열을 검색하고, Native 태스크의 경우 "Arguments =" 문자열을 검색하세요.

서드파티 플러그인 작성자라면 재정의 문제를 방지하기 위해 프로젝트 수준에서 구성을 적용하는 것이 가장 좋습니다. 이를 위해 새로운 Kotlin 플러그인 DSL 확장 타입을 사용할 수 있습니다. 이 구성을 작성자 측 문서에 명시적으로 기록해 두는 것을 권장합니다.

확장 수준(Extension level) ​

최상위 수준의 compilerOptions {} 블록에서 모든 타깃 및 공유 소스 세트에 대한 공통 컴파일러 옵션을 구성할 수 있습니다:

kotlin
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}

타깃 수준(Target level) ​

target {} 블록 내부의 compilerOptions {} 블록에서 JVM/Android 타깃을 위한 컴파일러 옵션을 구성할 수 있습니다:

kotlin
kotlin {
    target {
        compilerOptions {
            optIn.add("kotlin.RequiresOptIn")
        }
    }
}

Kotlin Multiplatform 프로젝트에서는 특정 타깃 내부에서 컴파일러 옵션을 구성할 수 있습니다. 예를 들면 jvm { compilerOptions {}}와 같습니다. 자세한 내용은 Multiplatform Gradle DSL 레퍼런스를 참조하세요.

컴파일 단위 수준(Compilation unit level) ​

태스크 구성 내부의 compilerOptions {} 블록에서 특정 컴파일 단위 또는 태스크에 대한 컴파일러 옵션을 구성할 수 있습니다:

kotlin
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}

KotlinCompilation을 통해 컴파일 단위 수준에서 컴파일러 옵션에 접근하고 구성할 수도 있습니다:

kotlin
kotlin {
    target {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {
                    optIn.add("kotlin.RequiresOptIn")
                }
            }
        }
    }
}

JVM/Android 및 Kotlin Multiplatform과 다른 타깃의 플러그인을 구성하려면 해당 Kotlin 컴파일 태스크의 compilerOptions {} 프로퍼티를 사용하세요. 다음 예제는 Kotlin 및 Groovy DSL 모두에서 이 구성을 설정하는 방법을 보여줍니다:

kotlin
tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}
groovy
tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}

kotlinOptions {}에서 compilerOptions {}로 마이그레이션 ​

Kotlin 2.2.0 이전에는 kotlinOptions {} 블록을 사용하여 컴파일러 옵션을 구성할 수 있었습니다. kotlinOptions {} 블록은 Kotlin 2.0.0부터 deprecated되었으므로, 이 섹션에서는 빌드 스크립트를 대신 compilerOptions {} 블록을 사용하도록 마이그레이션하기 위한 가이드와 권장 사항을 제공합니다:

컴파일러 옵션 중앙화 및 타입 사용 ​

가능하면 항상 확장 수준에서 컴파일러 옵션을 구성하고, 컴파일 단위 수준에서 특정 태스크를 위해 이를 재정의하세요.

compilerOptions {} 블록에서는 일반 문자열을 사용할 수 없으므로 타입이 지정된 값으로 변환해야 합니다. 예를 들어 다음과 같은 코드가 있다면:

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions {
        jvmTarget = "17"
        languageVersion = "2.4"
        apiVersion = "2.4"
    }
}
kotlin
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}

tasks.withType(KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = '17'
        languageVersion = '2.4'
        apiVersion = '2.4'
    }
}

마이그레이션 후에는 다음과 같아야 합니다:

kotlin
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")
    }
}
kotlin
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 프로젝트가 있다면:

kotlin
plugins {
    id("com.android.application")
    kotlin("android")
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}
kotlin
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    kotlinOptions {
        jvmTarget = '17'
    }
}

다음과 같이 업데이트합니다:

kotlin
plugins {
    id("com.android.application")
    kotlin("android")
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}
kotlin
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}

또한, Android 타깃이 포함된 Kotlin Multiplatform 프로젝트의 경우:

kotlin
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions.jvmTarget = "17"
        }
    }
}
kotlin
plugins {
    id 'org.jetbrains.kotlin.multiplatform'
    id 'com.android.application'
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = '17'
            }
        }
    }
}

다음과 같이 업데이트합니다:

kotlin
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}
kotlin
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)

예를 들어 다음과 같은 코드가 있다면:

kotlin
kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all")
}
kotlin
kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"]
}

다음과 같이 마이그레이션합니다:

kotlin
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}
kotlin
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.compilerOptions DSL에 의해 적용된 구성을 재정의할 수 있습니다.

JavaScript 타깃 지정 ​

JavaScript 컴파일 태스크는 프로덕션 코드의 경우 compileKotlinJs, 테스트 코드의 경우 compileTestKotlinJs, 커스텀 소스 세트의 경우 compile<Name>KotlinJs라고 불립니다.

단일 태스크를 구성하려면 해당 태스크의 이름을 사용하세요:

kotlin
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

val compileKotlin: KotlinCompilationTask<*> by tasks

compileKotlin.compilerOptions.suppressWarnings.set(true)
groovy
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 컴파일 태스크를 구성하는 것도 가능합니다:

kotlin
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions { /*...*/ }
}
groovy
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)
extraWarningstrue인 경우 경고를 발생시키는 추가 선언, 표현식 및 타입 컴파일러 검사를 활성화합니다.true, falsefalse
freeCompilerArgs추가 컴파일러 인자 목록입니다. 여기에서 실험적 -X 인자도 사용할 수 있습니다. 예시를 참조하세요.[]
languageVersion컴파일 중에 사용할 수 있는 Kotlin 언어 기능 및 구문을 제어합니다. 자세한 내용은 -language-version을 참조하세요."2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL)
optInopt-in 컴파일러 인자 목록을 구성하기 위한 프로퍼티입니다.listOf( /* opt-ins */ )emptyList()
progressiveMode점진적 컴파일러 모드(progressive compiler mode)를 활성화합니다.true, falsefalse
suppressWarnings경고를 생성하지 않습니다.false
verbose상세 로깅 출력을 활성화합니다. Gradle 디버그 로그 레벨이 활성화된 경우에만 작동합니다.false

향후 릴리스에서 freeCompilerArgs 속성을 deprecate할 예정입니다. Kotlin Gradle DSL에서 누락된 옵션이 있다면 이슈를 등록해 주세요.

freeCompilerArgs를 통한 추가 인자 사용 예시 ​

추가 컴파일러 인자(실험적 인자 포함)를 전달하려면 freeCompilerArgs 속성을 사용하세요. 이 속성에 단일 인자 또는 인자 목록을 추가할 수 있습니다:

kotlin
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"
            )
        ) 
    }
}
groovy
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
kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
    }
}
groovy
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"
jvmTargetValidationModeWARNING, ERROR, IGNOREERROR
jvmDefault인터페이스에 선언된 함수가 JVM의 디폴트 메서드로 컴파일되는 방식을 제어합니다.ENABLE, NO_COMPATIBILITY, DISABLEENABLE
noJdkJava 런타임을 클래스패스에 자동으로 포함하지 않습니다.false
-Xadd-modules(실험적) 초기 모듈 외에 지정된 루트 모듈을 확인합니다. 모듈 경로의 모든 모듈을 확인하려면 ALL-MODULE-PATH 값을 설정하세요.쉼표로 구분된 모듈 이름 또는 freeCompilerArgs를 통해 전달되는 ALL-MODULE-PATH

JavaScript 전용 속성 ​

이름설명가능한 값기본값
friendModulesDisabled내부(internal) 선언 내보내기(export)를 비활성화합니다.false
main실행 시 main 함수를 호출해야 하는지 여부를 지정합니다.JsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALLJsMainFunctionExecutionMode.CALL
moduleKind컴파일러가 생성하는 JS 모듈의 종류입니다.JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMDnull
sourceMap소스 맵(Source map)을 생성합니다.false
sourceMapEmbedSources소스 맵에 소스 파일을 포함합니다.JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYSnull
sourceMapNamesPolicyKotlin 코드에 선언한 변수 및 함수 이름을 소스 맵에 추가합니다. 동작에 대한 자세한 내용은 컴파일러 레퍼런스를 참조하세요.JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NOnull
sourceMapPrefix소스 맵의 경로에 지정된 접두사를 추가합니다.null
target특정 ECMA 버전을 위한 JS 파일을 생성합니다."es5", "es2015", "es2020""es5"
useEsClasses생성된 JavaScript 코드가 ES2015 클래스를 사용하도록 합니다. ES2015 및 ES2020 타깃 사용 시 기본적으로 활성화됩니다.null

컴파일러 옵션용 타입 ​

일부 compilerOptions는 String 타입 대신 커스텀 타입을 사용합니다:

옵션타입예시
apiVersion 및 languageVersionKotlinVersioncompilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4)
jvmTargetJvmTargetcompilerOptions.jvmTarget.set(JvmTarget.JVM_11)
mainJsMainFunctionExecutionModecompilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)
moduleKindJsModuleKindcompilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)
sourceMapEmbedSourcesJsSourceMapEmbedModecompilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)
sourceMapNamesPolicyJsSourceMapNamesPolicycompilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)

다음 단계 ​

다음에 대해 자세히 알아보세요: