Compiler options in the Kotlin Gradle plugin

코틀린의 각 릴리스에는 지원되는 대상(JVM, 자바스크립트 및 지원되는 플랫폼용 기본 바이너리)용 컴파일러가 포함되어 있다.

이러한 컴파일러는 다음에서 사용된다:

IDE에서, 코틀린 프로젝트의 컴파일 또는 실행 버튼을 클릭할 때.
그레이들에서, 콘솔 또는 IDE에서 gradle build를 호출할 때.
메이븐(Maven), 콘솔 또는 IDE에서 mvn compile 또는 mvn test-compile을 호출할 때.

커맨드-라인 컴파일러 사용 튜토리얼에 설명된 대로 커맨드-라인에서 수동으로 코틀린 컴파일러를 실행할 수도 있다.

How to define options

코틀린 컴파일러에는 컴파일 프로세스를 조정할 수 있는 다양한 옵션이 있다.

빌드 스크립트를 사용하여, 추가 컴파일 옵션을 지정할 수 있다. 이를 위해 코틀린 컴파일 태스크의 compilerOptions 프로퍼티을 사용하자. 예를 들어:

코틀린

  tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
      freeCompilerArgs.add("-Xexport-kdoc")
    }
  }

그루비

tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

Target the JVM

JVM 컴파일 태스크는 프로덕션 코드의 경우 compileKotlin, 테스트 코드의 경우 compileTestKotlin이라고 한다. 커스텀 소스 세트(source sets)에 대한 태스크는 compile<Name>Kotlin 패턴에 따라 이름이 지정된다.

안드로이드 프로젝트의 태스크 이름에는 빌드 이름이 포함되며 compile<BuildVariant>Kotlin 패턴(예: compileDebugKotlin 또는 compileReleaseUnitTestKotlin)을 따른다.

JVM 및 안드로이드 프로젝트 모두에서, 프로젝트 코틀린 확장 DSL을 사용하여 옵션을 정의할 수 있다:

코틀린

  kotlin {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9)
    }
  }

그루비

  kotlin {
    compilerOptions {
        apiVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }
  }

알아야 둬야할 중요한 세부 사항:

android.kotlinOptions 및 kotlin.compilerOptions 구성 블록은 서로를 오버라이드(override)한다. 마지막(가장 낮은) 블록이 적용된다.
kotlin.compilerOptions는 프로젝트의 모든 코틀린 컴파일 태스크를 구성한다.
tasks.named<KotlinJvmCompile>("compileKotlin") { }(또는 tasks.withType<KotlinJvmCompile>().configureEach { }) 접근 방식을 사용하여 kotlin.compilerOptions DSL에서 적용한 구성을 오버라이드할 수 있다.

Target JavaScript

자바스크립트 컴파일 태스크는 프로덕션 코드의 경우 compileKotlinJs, 테스트 코드의 경우 compileTestKotlinJs, 커스텀 소스 세트(source sets)의 경우 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.set(true)
    }
  }

그레이들 코틀린 DSL을 사용하면, 먼저 프로젝트의 태스크에서 태스크을 가져와야 한다.

자바스크립트(JS) 및 일반 대상에, 각각 Kotlin2JsCompile 및 KotlinCompileCommon 타입을 사용한다.

For all Kotlin compilation tasks

프로젝트에서 모든 코틀린 컴파일 태스크를 구성하는 것도 가능하다:

코틀린

  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 { /*...*/ }
  }

All compiler options

다음은 그레이들 태스크에 대한 전체 옵션 목록이다:

Common attributes

이름	설명	가능한 값	기본(Default) 값
`optIn`	opt-in 컴파일러 아규먼트 목록을 구성하기 위한 프로퍼티	`listOf( /* opt-ins */ )`	`emptyList()`
`progressiveMode`	프로그레시브(progressive) 컴파일러 모드 활성화	`true, false`	`false`

Attributes specific to JVM

이름	설명	가능한 값	기본(Default) 값
`javaParameters`	메소드 파라미터에 대한 자바 1.8 리플렉션을 위한 메타데이터 생성		false
`jvmTarget`	생성된 JVM 바이트코드의 대상 버전	“1.8”, “9”, “10”, …, “19”. 또한, 컴파일러 옵션에 대한 타입을 참조하자	“1.8”
`noJdk`	자바 런타임을 클래스 경로에 자동으로 포함하지 말자		false
`jvmTargetValidationMode`	- 코틀린과 자바 사이의 JVM 대상 호환성 검증 - `KotlinCompile` 타입의 태스크 프로퍼티.	`WARNING`, `ERROR`, `INFO`	`ERROR`

Attributes common to JVM, JS, and JS DCE

이름	설명	기본(Default) 값
`allWarningsAsErrors`	경고가 있는 경우 오류 리포트	false
`suppressWarnings`	경고 생성 안 함	false
`verbose`	상세 로깅 출력을 활성화한다. 그레이들 디버그 로그 레벨이 활성화된 경우에만 작동한다.	false
`freeCompilerArgs`	추가 컴파일러 아규먼트 목록이다. 여기에서도 실험적인 `-X` 아규먼트를 사용할 수 있다. 예시 보기.	[]

향후 릴리스에서 freeCompilerArgs 특성을 더 이상 사용하지 않을 예정이다. 코틀린 그레이들 DSL에서 일부 옵션이 누락된 경우, 이슈를 생성해보자.

Example of additional arguments usage via freeCompilerArgs

freeCompilerArgs 애트리뷰트를 사용하여 추가(실험적 포함) 컴파일러 인수를 제공한다. 이 특성 또는 인수 목록에 단일 아규먼트를 추가할 수 있다:

코틀린

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

  val compileKotlin: KotlinCompilationTask<*> by tasks

  // 단일 실험 인수
  compileKotlin.compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")
  // 추가 단일 인수는, 키-값 쌍일 수 있다.
  compileKotlin.compilerOptions.freeCompilerArgs.add("-Xno-param-assertions")
  // 아규먼트 리스트
  compileKotlin.compilerOptions.freeCompilerArgs.addAll(listOf("-Xno-receiver-assertions", "-Xno-call-assertions"))

그루비

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

  tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // 단일 실험 인수
        freeCompilerArgs.add("-Xexport-kdoc")
        // 추가 단일 인수는, 키-값 쌍일 수 있다.
        freeCompilerArgs.add("-Xno-param-assertions")
        // 아규먼트 리스트
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
  }

Attributes common to JVM and JS

이름	설명	가능한 값	기본(Default) 값
`apiVersion`	지정된 번들 라이브러리 버전의 선언으로 선언 사용을 제한한다.	“1.3” (DEPRECATED), “1.4” (DEPRECATED), “1.5”, “1.6”, “1.7”, “1.8”, “1.9” (EXPERIMENTAL)
`languageVersion`	지정된 버전의 코틀린과 소스 호환성 제공	“1.3” (DEPRECATED), “1.4” (DEPRECATED), “1.5”, “1.6”, “1.7”, “1.8”, “1.9” (EXPERIMENTAL)

Example of setting a languageVersion

언어 버전을 설정하려면, 다음 문법을 사용하자:

코틀린

  tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9)
    }

그루비

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

또한 컴파일러 옵션에 타입을 참조하자.

Attributes specific to JS

이름	설명	가능한 값	기본(Default) 값
`friendModulesDisabled`	내부 선언 내보내기 비활성화		false
`main`	실행 시 `메인(main)` 함수를 호출해야 하는지 여부를 정의한다.	“call”, “noCall”. 또한, 컴파일러 옵션 타입을 참고하자.	“call”
`metaInfo`	메타데이터로 .meta.js 및 .kjsm 파일을 생성한다. 라이브러리 생성에 사용		true
`moduleKind`	컴파일러가 생성한 JS 모듈의 종류	“umd”, “commonjs”, “amd”, “plain”, “es”. 또한, 컴파일러 옵션 타입을 참고하자.	“umd”
`outputFile`	컴파일 결과의 *.js 파일		“/js/packages//kotlin/.js"
`sourceMap`	소스 맵 생성		true
`sourceMapEmbedSources`	소스 파일을 소스 파일에 임베드	“never”, “always”, “inlining”. 또한, 컴파일러 옵션 타입을 참고하자.
`sourceMapNamesPolicy`	코틀린 코드에서 선언한 변수 및 함수 이름을 소스 맵에 추가한다. 동작에 대한 자세한 내용은, 컴파일러 레퍼런스를 참고하자.	“simple-names”, “fully-qualified-names”, “no”. 또한, 컴파일러 옵션 타입을 참고하자.	“simple-names”
`sourceMapPrefix`	소스 맵 경로에 지정된 접두사 추가
`target`	특정 ECMA 버전에 대한 JS 파일 생성	“v5”	“v5”
`typedArrays`	기본(primitive) 배열을 JS 타입 배열로 변환		true

Types for compiler options

일부 compilerOptions는 스트링(String) 타입 대신 새 타입을 사용한다:

옵션	타입	예제
`jvmTarget`	JvmTarget	compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
`apiVersion and languageVersion`	KotlinVersion	compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_1_9)
`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)

다음은?

다음 내용을 학습해보자:

Incremental compilation, caches support, build reports, and the Kotlin daemon.
Gradle basics and specifics.
Support for Gradle plugin variants.