Kotlin Gradleプラグインのコンパイラーオプション
Kotlinの各リリースには、サポートされているターゲット用のコンパイラーが含まれています。 JVM、JavaScript、そしてサポートされているプラットフォーム用のネイティブバイナリです。
これらのコンパイラーは、以下の場合に使用されます。
- IDEでKotlinプロジェクトのCompileまたはRunボタンをクリックした場合。
- コンソールまたは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プラグイン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リファレンスを参照してください。
コンパイル単位レベル
特定のコンパイル単位またはタスクのコンパイラーオプションは、タスク設定内の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および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 {}への移行
Kotlin 2.2.0より前は、kotlinOptions {}ブロックを使用してコンパイラーオプションを設定できました。kotlinOptions {}ブロックはKotlin 2.0.0から非推奨になっているため、このセクションではビルドスクリプトをcompilerOptions {}ブロックを使用するように移行するためのガイダンスと推奨事項を提供します。
コンパイラーオプションを一元化し、型を使用する
可能な限り、コンパイラーオプションは拡張レベルで設定し、特定のタスクについてはコンパイル単位レベルで上書きしてください。
compilerOptions {}ブロックでは生の文字列を使用できないため、それらを型付きの値に変換してください。たとえば、以下のようなコードがある場合：
plugins {
kotlin("jvm") version "2.2.10"
}
tasks.withType<KotlinCompile>().configureEach {
kotlinOptions {
jvmTarget = "17"
languageVersion = "2.1"
apiVersion = "2.1"
}
}plugins {
id 'org.jetbrains.kotlin.jvm' version '2.2.10'
}
tasks.withType(KotlinCompile).configureEach {
kotlinOptions {
jvmTarget = '17'
languageVersion = '2.1'
apiVersion = '2.1'
}
}移行後は次のようになります。
plugins {
kotlin("jvm") version "2.2.10"
}
kotlin {
// Extension level
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.1")
apiVersion = KotlinVersion.fromVersion("2.1")
}
}
// Example of overriding at compilation unit level
tasks.named<KotlinJvmCompile>("compileKotlin"){
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.1")
}
}plugins {
id 'org.jetbrains.kotlin.jvm' version '2.2.10'
}
kotlin {
// Extension level
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.1")
apiVersion = KotlinVersion.fromVersion("2.1")
}
}
// Example of overriding at compilation unit level
tasks.named("compileKotlin", KotlinJvmCompile).configure {
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.1")
}
}android.kotlinOptionsからの移行
ビルドスクリプトで以前android.kotlinOptionsを使用していた場合、代わりに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プロジェクトのコンパイラーオプションは、拡張、ターゲット、コンパイル単位（タスク）の各レベルで定義できます。
デフォルトのJVMコンパイルタスクは、プロダクションコード用がcompileKotlin、テストコード用がcompileTestKotlinです。 カスタムソースセット用のタスクは、そのcompile<Name>Kotlinパターンに従って命名されます。
gradlew tasks --allコマンドをターミナルで実行し、Other tasksグループでcompile*Kotlinというタスク名を検索することで、Androidコンパイルタスクのリストを確認できます。
注意すべきいくつかの重要な詳細：
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および共通ターゲットには、それぞれKotlin2JsCompileおよびKotlinCompileCommon型を使用します。
gradlew tasks --allコマンドをターミナルで実行し、Other tasksグループでcompile*KotlinJSというタスク名を検索することで、JavaScriptコンパイルタスクのリストを確認できます。
すべての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 { /*...*/ }
}すべてのコンパイラーオプション
Gradleコンパイラーのオプションの全リストを以下に示します。
共通の属性
| 名前 | 説明 | 設定可能な値 | デフォルト値 |
|---|---|---|---|
optIn | オプトインコンパイラー引数のリストを設定するためのプロパティです。 | 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", ..., "23", "24"。また、コンパイラーオプションの型も参照してください。 | "1.8" |
noJdk | Javaランタイムをクラスパスに自動的に含めません。 | false | |
jvmTargetValidationMode |
| WARNING, ERROR, IGNORE | ERROR |
jvmDefault | インターフェースで宣言された関数がJVM上のデフォルトメソッドにどのようにコンパイルされるかを制御します。 | ENABLE, NO_COMPATIBILITY, DISABLE | ENABLE |
JVMとJavaScriptに共通の属性
| 名前 | 説明 | 設定可能な値 | デフォルト値 |
|---|---|---|---|
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属性を使用して、追加の（実験的なものを含む）コンパイラー引数を指定します。 この属性には、単一の引数または引数のリストを追加できます。
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"
)
)
}
}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 {
compilerOptions {
languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1)
}
}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 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) |
次に何をしますか？
詳細はこちらをご覧ください。