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つのレベルで設定できます。

• 拡張レベル: すべてのターゲットと共有ソースセットのkotlin {}ブロック内。
• ターゲットレベル: 特定のターゲットのブロック内。
• コンパイルユニットレベル: 通常、特定のコンパイルタスク内。

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

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

逆に、下位レベルで行われた設定は、上位レベルの関連する設定をオーバーライドします。

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

どのレベルのコンパイラ引数がコンパイルに適用されているかを確認するには、GradleのロギングのDEBUGレベルを使用します。 JVMおよびJS/WASMタスクの場合、ログ内で"Kotlin compiler args:"という文字列を検索します。Nativeタスクの場合、"Arguments ="という文字列を検索します。

TIP

サードパーティ製プラグインの作者の場合、オーバーライドの問題を避けるためにプロジェクトレベルで設定を適用するのが最善です。これには新しいKotlinプラグインDSL拡張タイプを使用できます。この設定については、ご自身で明示的に文書化することをお勧めします。

拡張レベル

すべてのターゲットと共有ソースセットの共通コンパイラオプションは、トップレベルのcompilerOptions {}ブロックで設定できます。

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

ターゲットレベル

JVM/Androidターゲットのコンパイラオプションは、target {}ブロック内のcompilerOptions {}ブロックで設定できます。

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

Kotlin Multiplatformプロジェクトでは、特定のターゲット内でコンパイラオプションを設定できます。例えば、jvm { compilerOptions {}}です。詳細については、Multiplatform Gradle DSL referenceを参照してください。

コンパイルユニットレベル

特定のコンパイルユニットまたはタスクのコンパイラオプションは、タスク設定内のcompilerOptions {}ブロックで設定できます。

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

KotlinCompilationを介して、コンパイルユニットレベルでコンパイラオプションにアクセスして設定することもできます。

kotlin {
    target {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {

                }
            }
        }
    }
}

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

JVMをターゲットにする

前述のとおり、JVM/Androidプロジェクトのコンパイラオプションは、拡張、ターゲット、コンパイルユニットレベル（タスク）で定義できます。

デフォルトのJVMコンパイルタスクは、プロダクションコードにはcompileKotlin、テストコードにはcompileTestKotlinと呼ばれます。カスタムソースセットのタスクは、compile<Name>Kotlinパターンに従って命名されます。

ターミナルでgradlew tasks --allコマンドを実行し、Other tasksグループでcompile*Kotlinタスク名を検索することで、Androidコンパイルタスクのリストを確認できます。

留意すべきいくつかの重要な詳細点があります。

• android.kotlinOptionsとkotlin.compilerOptionsの設定ブロックは互いにオーバーライドします。最後の（最も低い）ブロックが適用されます。
• kotlin.compilerOptionsは、プロジェクト内のすべてのKotlinコンパイルタスクを設定します。
• kotlin.compilerOptions DSLによって適用された設定は、tasks.named<KotlinJvmCompile>("compileKotlin") { }（またはtasks.withType<KotlinJvmCompile>().configureEach { }）のアプローチを使用してオーバーライドできます。

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

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

Gradleコンパイラのオプションの完全なリストを以下に示します。

共通属性

名前	説明	指定可能な値	デフォルト値
optIn	opt-inコンパイラ引数のリストを設定するためのプロパティ	listOf( /* opt-ins */ )	emptyList()
progressiveMode	プログレッシブコンパイラモードを有効にします	true, false	false
extraWarnings	trueの場合に警告を発する追加の宣言、式、型に関するコンパイラチェックを有効にします	true, false	false

JVM固有の属性

名前	説明	指定可能な値	デフォルト値
javaParameters	メソッドパラメータに対するJava 1.8リフレクション用のメタデータを生成します		false
jvmTarget	生成されるJVMバイトコードのターゲットバージョン	"1.8", "9", "10", ..., "22", "23"。また、コンパイラオプションの型も参照	"1.8"
noJdk	Javaランタイムをクラスパスに自動的に含めない		false
jvmTargetValidationMode		WARNING, ERROR, IGNORE	ERROR

JVMとJavaScriptに共通の属性

名前	説明	指定可能な値	デフォルト値
allWarningsAsErrors	警告がある場合にエラーとして報告します		false
suppressWarnings	警告を生成しません		false
verbose	詳細なロギング出力を有効にします。Gradleのデバッグログレベルが有効な場合にのみ機能します		false
freeCompilerArgs	追加のコンパイラ引数のリスト。実験的な-X引数もここで使用できます。追加引数のfreeCompilerArgs経由での使用例を参照		[]
apiVersion	宣言の使用をバンドルされたライブラリの指定されたバージョンからのものに制限します	"1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL)
languageVersion	指定されたKotlinバージョンとのソース互換性を提供します	"1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL)

DANGER

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

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

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

Kotlin

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

kotlin {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion.set(KotlinVersion.KOTLIN_2_1)
        jvmTarget.set(JvmTarget.JVM_1_8)
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")

        // Single additional argument
        freeCompilerArgs.add("-Xno-param-assertions")

        // List of arguments
        freeCompilerArgs.addAll(
            listOf(
                "-Xno-receiver-assertions",
                "-Xno-call-assertions"
            )
        ) 
    }
}

Groovy

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion = KotlinVersion.KOTLIN_2_1
        jvmTarget = JvmTarget.JVM_1_8
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")
        
        // Single additional argument, can be a key-value pair
        freeCompilerArgs.add("-Xno-param-assertions")
        
        // List of arguments
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

TIP

freeCompilerArgs属性は、拡張、ターゲット、およびコンパイルユニット（タスク）の各レベルで利用可能です。

languageVersionの設定例

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

Kotlin

kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1)
    }
}

Groovy

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

また、コンパイラオプションの型も参照してください。

JavaScript固有の属性

名前	説明	指定可能な値	デフォルト値
friendModulesDisabled	内部宣言のエクスポートを無効にします		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_1)
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)

次のステップ

詳細については、以下を参照してください。

• Kotlin Multiplatform DSLリファレンス。
• インクリメンタルコンパイル、キャッシュサポート、ビルドレポート、Kotlinデーモン。
• Gradleの基本と詳細。
• Gradleプラグインバリアントのサポート。