Skip to content

Kotlin Gradle 플러그인의 컴파일러 옵션

Kotlin의 각 릴리스에는 지원되는 타겟(JVM, JavaScript 및 지원되는 플랫폼용 네이티브 바이너리)을 위한 컴파일러가 포함되어 있습니다.

이 컴파일러들은 다음 환경에서 사용됩니다:

  • IDE에서 Kotlin 프로젝트의 Compile 또는 Run 버튼을 클릭할 때.
  • 콘솔이나 IDE에서 gradle build를 호출할 때의 Gradle.
  • 콘솔이나 IDE에서 mvn compile 또는 mvn test-compile을 호출할 때의 Maven.

커맨드 라인 컴파일러 사용하기 튜토리얼의 설명에 따라 커맨드 라인에서 Kotlin 컴파일러를 수동으로 실행할 수도 있습니다.

옵션을 정의하는 방법

Kotlin 컴파일러에는 컴파일 프로세스를 맞춤화하기 위한 여러 옵션이 있습니다.

Gradle DSL을 사용하면 컴파일러 옵션을 포괄적으로 구성할 수 있습니다. 이는 Kotlin MultiplatformJVM/Android 프로젝트에서 사용할 수 있습니다.

Gradle DSL을 사용하면 빌드 스크립트 내에서 다음 세 가지 레벨로 컴파일러 옵션을 구성할 수 있습니다:

Kotlin 컴파일러 옵션 레벨

상위 레벨의 설정은 하위 레벨의 관례(기본값)로 사용됩니다:

  • 익스텐션 레벨에서 설정된 컴파일러 옵션은 commonMain, nativeMain, commonTest와 같은 공유 소스 세트를 포함한 타겟 레벨 옵션의 기본값이 됩니다.
  • 타겟 레벨에서 설정된 컴파일러 옵션은 compileKotlinJvmcompileTestKotlinJvm 태스크와 같은 컴파일 단위(태스크) 레벨 옵션의 기본값이 됩니다.

반대로, 하위 레벨에서 이루어진 구성은 상위 레벨의 관련 설정을 오버라이드합니다:

  • 태스크 레벨 컴파일러 옵션은 타겟 또는 익스텐션 레벨의 관련 구성을 오버라이드합니다.
  • 타겟 레벨 컴파일러 옵션은 익스텐션 레벨의 관련 구성을 오버라이드합니다.

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

서드파티 플러그인 작성자라면 오버라이드 문제를 피하기 위해 프로젝트 레벨에서 구성을 적용하는 것이 가장 좋습니다. 이를 위해 새로운 Kotlin 플러그인 DSL 익스텐션 타입을 사용할 수 있습니다. 이 구성을 문서에 명시적으로 기록하는 것을 권장합니다.

익스텐션 레벨

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

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

타겟 레벨

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

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

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

컴파일 단위 레벨

태스크 구성 내부의 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 멀티플랫폼 이외의 타겟 플러그인을 구성하려면 해당 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 {} 블록에서는 가공되지 않은 문자열(raw string)을 사용할 수 없으므로, 타입이 지정된 값(typed values)으로 변환해야 합니다. 예를 들어, 다음과 같은 코드가 있다면:

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

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

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

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

kotlin
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

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

kotlin {
    // 익스텐션 레벨
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.3")
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}

// 컴파일 단위 레벨에서의 오버라이드 예시
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}
kotlin
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.3.0'
}

kotlin {
  // 익스텐션 레벨
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.3")
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}

// 컴파일 단위 레벨에서의 오버라이드 예시
tasks.named("compileKotlin", KotlinJvmCompile).configure {
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.3")
    }
}

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 멀티플랫폼 프로젝트의 예시는 다음과 같습니다:

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을 사용할 수 있는지 확인하고 이를 대신 사용하세요.

  • -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 타입을, 공통(common) 타겟의 경우 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 { /*...*/ }
}

모든 컴파일러 옵션

다음은 Gradle 컴파일러 옵션의 전체 목록입니다:

공통 속성

이름설명가능한 값기본값
optIn옵트인 컴파일러 인자 목록을 구성하기 위한 속성listOf( /* opt-ins */ )emptyList()
progressiveMode프로그레시브 컴파일러 모드를 활성화합니다.true, falsefalse
extraWarningstrue인 경우 경고를 생성하는 추가 선언, 표현식 및 타입 컴파일러 체크를 활성화합니다.true, falsefalse

JVM 전용 속성

이름설명가능한 값기본값
javaParameters메서드 파라미터에 대한 Java 1.8 리플렉션용 메타데이터를 생성합니다.false
jvmTarget생성된 JVM 바이트코드의 타겟 버전입니다."1.8", "9", "10", ..., "24", 25". 또한 컴파일러 옵션용 타입을 참고하세요."1.8"
noJdk클래스패스에 Java 런타임을 자동으로 포함하지 않습니다.false
jvmTargetValidationMode
  • Kotlin과 Java 간의 JVM 타겟 호환성 유효성 검사
  • KotlinCompile 타입 태스크를 위한 속성입니다.
WARNING, ERROR, IGNOREERROR
jvmDefault인터페이스에 선언된 함수가 JVM에서 디폴트 메서드로 컴파일되는 방식을 제어합니다.ENABLE, NO_COMPATIBILITY, DISABLEENABLE

JVM 및 JavaScript 공통 속성

이름설명가능한 값기본값
allWarningsAsErrors경고가 있는 경우 이를 에러로 보고합니다.false
suppressWarnings경고를 생성하지 않습니다.false
verbose상세 로깅 출력을 활성화합니다. Gradle 디버그 로그 레벨이 활성화된 경우에만 작동합니다.false
freeCompilerArgs추가 컴파일러 인자 목록입니다. 실험적인 -X 인자도 여기서 사용할 수 있습니다. freeCompilerArgs를 통한 추가 인자 사용 예시를 참고하세요.[]
apiVersion번들 라이브러리의 지정된 버전 선언으로만 사용을 제한합니다."1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL)
languageVersion지정된 버전의 Kotlin과 소스 호환성을 제공합니다."1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL)

향후 릴리스에서 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_3)
        jvmTarget.set(JvmTarget.JVM_1_8)
        
        // 단일 실험적 인자
        freeCompilerArgs.add("-Xexport-kdoc")

        // 단일 추가 인자
        freeCompilerArgs.add("-Xno-param-assertions")

        // 인자 목록
        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_3
        jvmTarget = JvmTarget.JVM_1_8
        
        // 단일 실험적 인자
        freeCompilerArgs.add("-Xexport-kdoc")
        
        // 단일 추가 인자, 키-값 쌍이 될 수 있습니다.
        freeCompilerArgs.add("-Xno-param-assertions")
        
        // 인자 목록
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

freeCompilerArgs 속성은 익스텐션, 타겟컴파일 단위(태스크) 레벨에서 사용할 수 있습니다.

languageVersion 설정 예시

언어 버전을 설정하려면 다음 구문을 사용하세요:

kotlin
kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_3)
    }
}
groovy
tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_3
    }

또한 컴파일러 옵션용 타입을 참고하세요.

JavaScript 전용 속성

이름설명가능한 값기본값
friendModulesDisabled내부 선언 내보내기(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소스 맵을 생성합니다.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""es5"
useEsClasses생성된 JavaScript 코드가 ES2015 클래스를 사용하도록 합니다. ES2015 타겟 사용 시 기본적으로 활성화됩니다.null

컴파일러 옵션용 타입

일부 compilerOptionsString 타입 대신 새로운 타입을 사용합니다:

옵션타입예시
jvmTargetJvmTargetcompilerOptions.jvmTarget.set(JvmTarget.JVM_11)
apiVersionlanguageVersionKotlinVersioncompilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_3)
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)

다음 단계는?

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