Kotlin Gradle プラグインのコンパイラオプション

Kotlinの各リリースには、サポートされているターゲット向けのコンパイラーが含まれています。 JVM、JavaScript、およびサポートされているプラットフォーム向けのネイティブバイナリです。

これらのコンパイラーは、以下で使用されます。

• Kotlinプロジェクトで__Compile__または__Run__ボタンをクリックしたときのIDE。
• コンソールまたはIDEでgradle buildを実行したときのGradle。
• コンソールまたはIDEでmvn compileまたはmvn test-compileを実行したときのMaven。

コマンドラインコンパイラーの操作のチュートリアルで説明されているように、コマンドラインから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 ="文字列を検索します。

ヒント

サードパーティのプラグインを作成している場合は、オーバーライドの問題を回避するために、プロジェクトレベルで構成を適用するのが最適です。このためには、新しいKotlin plugin DSL extension typesを使用できます。この構成については、ご自身の側で明示的にドキュメント化することをお勧めします。

拡張機能レベル

すべてのターゲットおよび共有ソースセットの共通コンパイラーオプションは、最上位レベルの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.compilerOptionsDSLによって適用される構成は、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コンパイラーのオプションの完全なリストを次に示します。

共通属性

Name	Description	Possible values	Default value
optIn	オプトインコンパイラー引数のリストを構成するためのプロパティ	listOf( /* opt-ins */ )	emptyList()
progressiveMode	プログレッシブコンパイラーモードを有効にします	true, false	false
extraWarnings	trueの場合、警告を発する追加の宣言、式、および型のコンパイラーチェックを有効にします	true, false	false

JVMに固有の属性

Name	Description	Possible values	Default value
javaParameters	メソッドパラメーターに関するJava 1.8リフレクションのメタデータを生成します		false
jvmTarget	生成されたJVMバイトコードのターゲットバージョン	"1.8", "9", "10", ..., "22", "23"。また、コンパイラーオプションの型を参照してください。	"1.8"
noJdk	Javaランタイムをクラスパスに自動的に含めません		false
jvmTargetValidationMode	KotlinとJava間のJVMターゲット互換性の検証 KotlinCompile型のタスクのプロパティ。	WARNING, ERROR, IGNORE	ERROR

JVMとJavaScriptに共通の属性

Name	Description	Possible values	Default value
allWarningsAsErrors	警告がある場合にエラーを報告します		false
suppressWarnings	警告を生成しません		false
verbose	詳細なロギング出力を有効にします。Gradleデバッグログレベルが有効になっている場合にのみ機能します		false
freeCompilerArgs	追加のコンパイラー引数のリスト。ここでは実験的な-X引数も使用できます。例を参照してください		[]
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)

ヒント

今後のリリースでは、属性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"])
    }
}

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に固有の属性

Name	Description	Possible values	Default value
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型の代わりに新しい型を使用します。

Option	Type	Example
jvmTarget	JvmTarget	compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
apiVersion and 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 reference。
• インクリメンタルコンパイル、キャッシュサポート、ビルドレポート、およびKotlinデーモン。
• Gradleの基本と詳細。
• Gradleプラグインバリアントのサポート。