Kotlin Gradle プラグインのコンパイラオプション
Kotlin の各リリースには、サポートされているターゲット(JVM、JavaScript、およびサポートされているプラットフォーム向けのネイティブバイナリ)用のコンパイラが含まれています。
これらのコンパイラは、以下によって使用されます:
- IDE: Kotlin プロジェクトで Compile または Run ボタンをクリックしたとき。
- Gradle: コンソールまたは IDE で
gradle buildを実行したとき。 - Maven: コンソールまたは IDE で
mvn compileやmvn test-compileを実行したとき。
また、コマンドラインコンパイラでの作業のチュートリアルで説明されているように、コマンドラインから手動で Kotlin コンパイラを実行することもできます。
オプションの定義方法
Kotlin コンパイラには、コンパイルプロセスを細かく調整するためのオプションが多数用意されています。
Gradle DSL を使用すると、コンパイラオプションを包括的に設定できます。これは Kotlin Multiplatform および JVM/Android プロジェクトで利用可能です。
Gradle DSL では、ビルドスクリプト内でコンパイラオプションを次の 3 つのレベルで設定できます:
- Extension(拡張)レベル: すべてのターゲットおよび共有ソースセットを対象とする
kotlin {}ブロック内。 - Target(ターゲット)レベル: 特定のターゲットを対象とするブロック内。
- Compilation unit(コンパイル単位)レベル: 通常は特定のコンパイルタスク内。
上位レベルの設定は、下位レベルの規約(デフォルト)として使用されます:
- Extension レベルで設定されたコンパイラオプションは、
commonMain、nativeMain、commonTestなどの共有ソースセットを含む Target レベルのオプションのデフォルトになります。 - Target レベルで設定されたコンパイラオプションは、
compileKotlinJvmやcompileTestKotlinJvmタスクなどの Compilation unit(タスク)レベルのオプションのデフォルトになります。
逆に、下位レベルで行われた設定は、上位レベルの関連する設定をオーバーライドします:
- タスクレベルのコンパイラオプションは、Target レベルまたは Extension レベルの関連設定をオーバーライドします。
- Target レベルのコンパイラオプションは、Extension レベルの関連設定をオーバーライドします。
コンパイルにどのレベルのコンパイラ引数が適用されているかを確認するには、Gradle の DEBUG レベルのロギングを使用します。 JVM および JS/WASM タスクの場合は、ログ内で "Kotlin compiler args:" という文字列を検索してください。Native タスクの場合は "Arguments =" という文字列を検索してください。
サードパーティ製プラグインの作者である場合、オーバーライドの問題を避けるために、設定はプロジェクトレベルで適用することをお勧めします。これには、新しい Kotlin プラグイン DSL 拡張タイプを使用できます。この設定については、プラグイン側で明示的にドキュメント化しておくことが推奨されます。
Extension レベル
すべてのターゲットおよび共有ソースセットに対する共通のコンパイラオプションは、トップレベルの compilerOptions {} ブロックで設定できます:
kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}Target レベル
JVM/Android ターゲットのコンパイラオプションは、target {} ブロック内の compilerOptions {} ブロックで設定できます:
kotlin {
target {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}
}Kotlin Multiplatform プロジェクトでは、特定のターゲット内でコンパイラオプションを設定できます。例えば、jvm { compilerOptions {}} のように記述します。詳細については、Multiplatform Gradle DSL リファレンスを参照してください。
Compilation unit レベル
特定のコンパイル単位またはタスクのコンパイラオプションは、タスク設定内の 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 DSL と 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 {} ブロックに移行するためのガイダンスと推奨事項を提供します:
コンパイラオプションの集約と型の使用
可能な限り、コンパイラオプションは Extension レベルで設定し、特定のタスクについては Compilation unit レベルでオーバーライドしてください。
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 {
// Extension レベル
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// Compilation unit レベルでのオーバーライドの例
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 {
// Extension レベル
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// Compilation unit レベルでのオーバーライドの例
tasks.named("compileKotlin", KotlinJvmCompile).configure {
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.4")
}
}android.kotlinOptions からの移行
ビルドスクリプトで以前 android.kotlinOptions を使用していた場合は、代わりに Extension レベルまたは Target レベルの 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 が既に利用可能かどうかを確認し、代わりにそれを使用してください。-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 プロジェクトのコンパイラオプションは、Extension、Target、および Compilation unit レベル(タスク)で定義できます。
デフォルトの JVM コンパイルタスクは、本番コード向けが compileKotlin、テストコード向けが compileTestKotlin と呼ばれます。カスタムソースセットのタスクには、compile<Name>Kotlin パターンに従って名前が付けられます。
Android のコンパイルタスクの一覧を確認するには、ターミナルで gradlew tasks --all コマンドを実行し、Other tasks グループ内の compile*Kotlin タスク名を検索してください。
注意すべき重要な詳細:
kotlin.compilerOptionsは、プロジェクト内のすべての Kotlin コンパイルタスクを設定します。kotlin.compilerOptionsDSL によって適用された設定は、tasks.named<KotlinJvmCompile>("compileKotlin") { }(またはtasks.withType<KotlinJvmCompile>().configureEach { })のアプローチを使用してオーバーライドできます。
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 および common ターゲットには、それぞれ Kotlin2JsCompile および KotlinCompileCommon 型を使用します。
JavaScript のコンパイルタスクの一覧を確認するには、ターミナルで gradlew tasks --all コマンドを実行し、Other tasks グループ内の compile*KotlinJS タスク名を検索してください。
すべての 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, 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 | プログレッシブコンパイラモードを有効にする | true, false | false |
suppressWarnings | 警告を生成しない | false | |
verbose | 詳細なログ出力を有効にする。Gradle のデバッグログレベルが有効な場合にのみ機能します | false |
今後のリリースで freeCompilerArgs 属性を非推奨にする予定です。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 属性は、Extension、Target、および Compilation unit (タスク) レベルで利用可能です。
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 宣言のエクスポートを無効にする | 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 | ソースマップを生成する | 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) |
次のステップ
以下の詳細についてもご確認ください:
