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 マルチプラットフォームおよび JVM/Android プロジェクトで利用できます。

Gradle DSL を使用すると、ビルドスクリプト内の 3 つのレベルでコンパイラオプションを設定できます：

拡張レベル (Extension level)：kotlin {} ブロック内。すべてのターゲットと共有ソースセットに適用されます。
ターゲットレベル (Target level)：特定のターゲットのブロック内。
コンパイル単位レベル (Compilation unit level)：通常は特定のコンパイルタスク内。

Kotlin コンパイラオプションのレベル

上位レベルの設定は、下位レベルの慣習（デフォルト）として使用されます：

拡張レベルで設定されたコンパイラオプションは、ターゲットレベルのオプション（commonMain、nativeMain、commonTest などの共有ソースセットを含む）のデフォルトになります。
ターゲットレベルで設定されたコンパイラオプションは、コンパイル単位（タスク）レベル（compileKotlinJvm や compileTestKotlinJvm タスクなど）のオプションのデフォルトになります。

逆に、下位レベルで行われた設定は、関連する上位レベルの設定を上書き（override）します：

タスクレベルのコンパイラオプションは、ターゲットレベルまたは拡張レベルの関連する設定を上書きします。
ターゲットレベルのコンパイラオプションは、拡張レベルの関連する設定を上書きします。

コンパイルにどのレベルのコンパイラ引数が適用されているかを確認するには、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 の両方でこの設定を行う方法を示しています：

KotlinGroovy

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 {} ブロックを使用するように移行するためのガイドと推奨事項を提供します：

コンパイラオプションの中央集約と型の使用
android.kotlinOptions からの移行
freeCompilerArgs の移行

コンパイラオプションの中央集約と型の使用

可能な限り、拡張レベルでコンパイラオプションを設定し、コンパイル単位レベルで特定のタスクに対してそれらを上書きしてください。

compilerOptions {} ブロックでは生の文字列を使用できないため、型指定された値に変換してください。例えば、以下のような設定がある場合：

KotlinGroovy

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'
    }
}

移行後は以下のようになります：

KotlinGroovy

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 プロジェクトの場合：

KotlinGroovy

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'
    }
}

これを次のように更新します：

KotlinGroovy

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 マルチプラットフォームプロジェクトの場合：

KotlinGroovy

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'
            }
        }
    }
}

これを次のように更新します：

KotlinGroovy

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-compatibility`	`jvmDefault.set(JvmDefaultMode.ENABLE)`
`-Xjvm-default=all`	`jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)`
`-Xjvm-default=disable`	`jvmDefault.set(JvmDefaultMode.DISABLE)`

例えば、以下のような設定がある場合：

KotlinGroovy

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"]
}

次のように移行します：

KotlinGroovy

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 と呼ばれます。

単一のタスクを設定するには、その名前を使用します：

KotlinGroovy

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 コンパイルタスクを設定することも可能です：

KotlinGroovy

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`, `false`	`false`
`extraWarnings`	有効な場合、警告を出力する追加の宣言、式、および型のコンパイラチェックを有効にします	`true`, `false`	`false`

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`, `IGNORE`	`ERROR`
`jvmDefault`	インターフェースで宣言された関数を JVM 上のデフォルトメソッドにコンパイルする方法を制御します	`ENABLE`, `NO_COMPATIBILITY`, `DISABLE`	`ENABLE`

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" (実験的)
`languageVersion`	指定されたバージョンの Kotlin とのソース互換性を提供します	"1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (実験的)

将来のリリースで freeCompilerArgs 属性を非推奨にする予定です。Kotlin Gradle DSL に不足しているオプションがある場合は、問題を報告してください。

freeCompilerArgs を介した追加引数の使用例

追加の（実験的なものを含む）コンパイラ引数を提供するには、freeCompilerArgs 属性を使用します。この属性に単一の引数または引数のリストを追加できます：

KotlinGroovy

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 の設定例

言語バージョンを設定するには、次の構文を使用します：

KotlinGroovy

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`	内部（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"`	`"es5"`
`useEsClasses`	生成された JavaScript コードで ES2015 クラスを使用できるようにします。ES2015 ターゲットを使用する場合はデフォルトで有効になります		`null`

コンパイラオプションの型

一部の compilerOptions では、String 型の代わりに新しい型が使用されます：

オプション	型	例
`jvmTarget`	`JvmTarget`	`compilerOptions.jvmTarget.set(JvmTarget.JVM_11)`
`apiVersion` および `languageVersion`	`KotlinVersion`	`compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_3)`
`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)`

次のステップ

以下についてさらに詳しく学習してください：

Dokkaを実行する

出力形式

取得

操作と演算子

Kotlin Gradle プラグインにおけるコンパイラオプション ​

オプションの定義方法 ​

拡張レベル ​

ターゲットレベル ​

コンパイル単位レベル ​

kotlinOptions {} から compilerOptions {} への移行 ​

コンパイラオプションの中央集約と型の使用 ​

android.kotlinOptions からの移行 ​

freeCompilerArgs の移行 ​

JVM をターゲットにする ​

JavaScript をターゲットにする ​

すべての Kotlin コンパイルタスク ​

すべてのコンパイラオプション ​

共通属性 ​

JVM 固有の属性 ​

JVM と JavaScript に共通の属性 ​

freeCompilerArgs を介した追加引数の使用例 ​

languageVersion の設定例 ​

JavaScript 固有の属性 ​

コンパイラオプションの型 ​

次のステップ ​

Kotlin Gradle プラグインにおけるコンパイラオプション

オプションの定義方法

拡張レベル

ターゲットレベル

コンパイル単位レベル

`kotlinOptions {}` から `compilerOptions {}` への移行

コンパイラオプションの中央集約と型の使用

`android.kotlinOptions` からの移行

`freeCompilerArgs` の移行

JVM をターゲットにする

JavaScript をターゲットにする

すべての Kotlin コンパイルタスク

すべてのコンパイラオプション

共通属性

JVM 固有の属性

JVM と JavaScript に共通の属性

freeCompilerArgs を介した追加引数の使用例

languageVersion の設定例

JavaScript 固有の属性

コンパイラオプションの型

次のステップ