Skip to content

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 コンパイラオプションのレベル

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

  • 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
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}

Target レベル ​

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

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

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

Compilation unit レベル ​

特定のコンパイル単位またはタスクのコンパイラオプションは、タスク設定内の 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 Multiplatform とは異なるターゲットのプラグインを設定したい場合は、対応する Kotlin コンパイルタスクの compilerOptions {} プロパティを使用します。以下の例は、Kotlin DSL と 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)
    }
}

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

Kotlin 2.2.0 より前は、kotlinOptions {} ブロックを使用してコンパイラオプションを設定できました。kotlinOptions {} ブロックは Kotlin 2.0.0 から非推奨(deprecated)となっているため、このセクションではビルドスクリプトを compilerOptions {} ブロックに移行するためのガイダンスと推奨事項を提供します:

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

可能な限り、コンパイラオプションは Extension レベルで設定し、特定のタスクについては Compilation unit レベルでオーバーライドしてください。

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

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions {
        jvmTarget = "17"
        languageVersion = "2.4"
        apiVersion = "2.4"
    }
}
kotlin
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}

tasks.withType(KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = '17'
        languageVersion = '2.4'
        apiVersion = '2.4'
    }
}

移行後は次のようになります:

kotlin
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")
    }
}
kotlin
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 プロジェクトの場合:

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

次のように更新します:

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

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

次のように更新します:

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-compatibilityjvmDefault.set(JvmDefaultMode.ENABLE)
    -Xjvm-default=alljvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    -Xjvm-default=disablejvmDefault.set(JvmDefaultMode.DISABLE)

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

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

次のように移行します:

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 プロジェクトのコンパイラオプションは、Extension、Target、および Compilation unit レベル(タスク)で定義できます。

デフォルトの JVM コンパイルタスクは、本番コード向けが compileKotlin、テストコード向けが compileTestKotlin と呼ばれます。カスタムソースセットのタスクには、compile<Name>Kotlin パターンに従って名前が付けられます。

Android のコンパイルタスクの一覧を確認するには、ターミナルで gradlew tasks --all コマンドを実行し、Other tasks グループ内の compile*Kotlin タスク名を検索してください。

注意すべき重要な詳細:

  • 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 および common ターゲットには、それぞれ Kotlin2JsCompile および KotlinCompileCommon 型を使用します。

JavaScript のコンパイルタスクの一覧を確認するには、ターミナルで gradlew tasks --all コマンドを実行し、Other tasks グループ内の compile*KotlinJS タスク名を検索してください。

すべての 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 { /*...*/ }
}

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

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, falsefalse
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, falsefalse
suppressWarnings警告を生成しないfalse
verbose詳細なログ出力を有効にする。Gradle のデバッグログレベルが有効な場合にのみ機能しますfalse

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

freeCompilerArgs による追加引数の使用例 ​

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

kotlin
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"
            )
        ) 
    }
}
groovy
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
kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
    }
}
groovy
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"
jvmTargetValidationModeWARNING, ERROR, IGNOREERROR
jvmDefaultインターフェースで宣言された関数を JVM 上のデフォルトメソッドにコンパイルする方法を制御するENABLE, NO_COMPATIBILITY, DISABLEENABLE
noJdkクラスパスに Java ランタイムを自動的に含めないfalse
-Xadd-modules(実験的) 初期モジュールに加えて、指定されたルートモジュールを解決する。モジュールパス上のすべてのモジュールを解決するには、ALL-MODULE-PATH の値を設定します。カンマ区切りのモジュール名、または freeCompilerArgs 経由で渡される ALL-MODULE-PATH

JavaScript に固有の属性 ​

名前説明取り得る値デフォルト値
friendModulesDisabledinternal 宣言のエクスポートを無効にするfalse
main実行時に main 関数を呼び出すかどうかを指定するJsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALLJsMainFunctionExecutionMode.CALL
moduleKindコンパイラによって生成される JS モジュールの種類JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMDnull
sourceMapソースマップを生成するfalse
sourceMapEmbedSourcesソースファイルをソースマップ内に埋め込むJsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYSnull
sourceMapNamesPolicyKotlin コードで宣言した変数名と関数名をソースマップに追加する。動作の詳細については、コンパイラリファレンスを参照JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NOnull
sourceMapPrefixソースマップ内のパスに指定されたプレフィックスを追加するnull
target特定の ECMA バージョン向けの JS ファイルを生成する"es5", "es2015", "es2020""es5"
useEsClasses生成された JavaScript コードに ES2015 クラスを使用させる。ES2015 および ES2020 ターゲットを使用する場合はデフォルトで有効null

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

一部の compilerOptions では、String 型の代わりにカスタム型が使用されます:

オプション型例
apiVersion および languageVersionKotlinVersioncompilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4)
jvmTargetJvmTargetcompilerOptions.jvmTarget.set(JvmTarget.JVM_11)
mainJsMainFunctionExecutionModecompilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)
moduleKindJsModuleKindcompilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)
sourceMapEmbedSourcesJsSourceMapEmbedModecompilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)
sourceMapNamesPolicyJsSourceMapNamesPolicycompilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)

次のステップ ​

以下の詳細についてもご確認ください: