Skip to content

Kotlinコンパイラオプション ​

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

これらのコンパイラは、以下によって使用されます:

  • Kotlinプロジェクトで Compile または Run ボタンをクリックしたときのIDE。
  • コンソールまたはIDEで gradle build を呼び出したときのGradle。
  • コンソールまたはIDEで mvn compile や mvn test-compile を呼び出したときのMaven。

また、コマンドラインコンパイラの使用チュートリアルで説明されているように、 コマンドラインからKotlinコンパイラを手動で実行することもできます。

コンパイラオプション ​

Kotlinコンパイラには、コンパイルプロセスをカスタマイズするための多数のオプションが用意されています。 さまざまなターゲットに対応するコンパイラオプションとそれぞれの説明がこのページにまとめられています。

コンパイラオプションとその値(コンパイラ引数)を設定するには、いくつかの方法があります:

  • IntelliJ IDEAでは、Settings/Preferences | Build, Execution, Deployment | Compiler | Kotlin Compiler の Additional command line parameters テキストボックスにコンパイラ引数を入力します。

  • Gradleを使用している場合は、Kotlinコンパイルタスクの compilerOptions プロパティでコンパイラ引数を指定します。 詳細はGradleコンパイラオプションを参照してください。

  • Mavenを使用している場合は、Mavenプラグインノードの <configuration> 要素内でコンパイラ引数を指定します。 詳細はMavenを参照してください。

  • コマンドラインコンパイラを実行する場合は、ユーティリティ呼び出しに直接コンパイラ引数を追加するか、argfileに記述します。

    例:

    bash
    $ kotlinc hello.kt -include-runtime -d hello.jar

    Windowsでは、区切り文字(空白、=、;、,)を含むコンパイラ引数を渡す場合、 それらの引数をダブルクォーテーション(")で囲んでください。

    $ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"

コンパイラオプションのスキーマ ​

すべてのコンパイラオプションに共通するスキーマは、JARアーティファクトとしてorg.jetbrains.kotlin:kotlin-compiler-arguments-descriptionで公開されています。このアーティファクトには、(Kotlin以外の利用者のための)すべてのコンパイラオプション説明のコード表現とJSON相当表現の両方が含まれています。また、各オプションが導入または安定化されたバージョンなどのメタデータも含まれています。

共通オプション ​

以下のオプションは、すべてのKotlinコンパイラに共通です。

-api-version version ​

コードが実行時に使用できるKotlin APIを制御するためのAPIバージョンを設定します。たとえば、Kotlinコンパイラバージョン2.4.0で -api-version=2.1 を使用すると、コードはKotlin標準ライブラリ2.1.0との互換性を維持します。

-api-version の値を -language-version の値より高く設定することはできません。

ほとんどの場合、APIバージョンと言語バージョンは同じにする必要があります。例外の1つは、古いバージョンのKotlin標準ライブラリを実行しなければならない利用者のためにライブラリを開発する場合です。その場合は、それらの利用者が利用できないAPIを誤って使用しないよう、古いAPIバージョンを設定してください。

APIバージョンが互換性に与える影響の詳細については、ライブラリ作成者のための後方互換性ガイドラインを参照してください。

-help (-h) ​

使用方法の情報を表示して終了します。標準オプションのみが表示されます。 高度なオプションを表示するには、-X を使用してください。

-kotlin-home path ​

ランタイムライブラリの検出に使用されるKotlinコンパイラへのカスタムパスを指定します。

-language-version version ​

コンパイル中に利用可能なKotlin言語機能を制御するための言語バージョンを設定します。

たとえば、コンパイラの動作を変更せずに新しいコンパイルパフォーマンスの向上の恩恵を受けたい場合、 新しいコンパイラバージョンで古い言語バージョンを使用できます。古い言語バージョンを使用すると、 新しい言語機能は使用できなくなりますが、そのバージョン以降に導入された新しいエラーや非推奨(deprecation)も発生しません。 このアプローチは、古いKotlinバージョンとの互換性を維持する必要があるライブラリ作成者に特に役立ちます。 詳細については、ライブラリ作成者のための後方互換性ガイドラインを参照してください。

言語バージョンとしては、最新の3つの安定版Kotlinバージョンのいずれかを設定できます。たとえば、Kotlin 2.5.0は2.2までの古い言語バージョンをサポートしています。

古い言語バージョンを使用する場合は、古いAPIバージョンも使用する必要があります。 詳細については、-api-version versionを参照してください。

技術的には、安定化される前に今後の言語機能を試すために、より新しい言語バージョンを設定することも可能です。 ただし、個々の機能については、専用の手順に従って有効にすることをお勧めします。

-opt-in annotation ​

指定された完全修飾名を持つ要求アノテーションによって、オプトインを必要とするAPIの使用を有効にします。

-P plugin:pluginId:optionName=value ​

Kotlinコンパイラプラグインにオプションを渡します。 コアプラグインとそのオプションは、ドキュメントのコアコンパイラプラグインセクションに記載されています。

-progressive ​

コンパイラのプログレッシブモードを有効にします。

プログレッシブモードでは、不安定なコードに対する非推奨化やバグ修正が、段階的な移行サイクルを経ることなく即座に適用されます。 プログレッシブモードで記述されたコードには後方互換性がありますが、 非プログレッシブモードで記述されたコードは、プログレッシブモードでコンパイルエラーを引き起こす可能性があります。

-script ​

Kotlinスクリプトファイルを評価します。このオプションを指定して呼び出されると、コンパイラは渡された引数の中で最初のKotlinスクリプト(*.kts)ファイルを実行します。

-verbose ​

コンパイルプロセスの詳細を含む詳細ログ出力を有効にします。

-version ​

コンパイラのバージョンを表示します。

Experimental

-X

高度なオプションに関する情報を表示して終了します。これらのオプションは現在不安定です。 それらの名前や動作は予告なしに変更される可能性があります。

Experimental

Kotlinコントラクトオプション

以下のオプションは、実験的なKotlinコントラクト(Kotlin contracts)機能を有効にします。

-Xallow-contracts-on-more-functions ​

プロパティアクセサ、特定の演算子関数、ジェネリック型に対する型アサーションなど、追加の宣言でコントラクトを有効にします。

-Xallow-condition-implies-returns-contracts ​

コントラクト内で returnsNotNull() 関数を使用して、指定された条件に対して戻り値が非nullであるとみなすことを許可します。

-Xallow-holdsin-contract ​

コントラクト内で holdsIn キーワードを使用して、ラムダの内部でブール条件が true であるとみなすことを許可します。

-Xallow-returns-result-of ​

returnsResultOf() コントラクトの使用を許可し、未使用の戻り値チェッカー(unused return value checker)が、無視できる結果と高階関数からの意味のある結果を区別できるようにします。

Experimental

-Xallow-reified-type-in-catch

inline 関数の catch 節で、具現化された(reified)Throwable 型パラメータのサポートを有効にします。

Experimental

-Xcollection-literals

ブラケット構文 [] によるコレクションリテラルのサポートを有効にします。

Experimental

-Xcompiler-plugin-order={plugin.before>plugin.after}

コンパイラプラグインの実行順序を設定します。コンパイラは plugin.before を先に実行し、その後に plugin.after を実行します。

3つ以上のプラグインに対して複数の順序ルールを定義できます。例:

bash
kotlinc -Xcompiler-plugin-order=plugin.first>plugin.middle
kotlinc -Xcompiler-plugin-order=plugin.middle>plugin.last

これにより、以下の実行順序になります:

  1. plugin.first
  2. plugin.middle
  3. plugin.last

コンパイラプラグインが存在しない場合、対応するルールは無視されます。

以下のプラグインをそのIDで設定できます:

コンパイラプラグインプラグインID
all-open, kotlin-springorg.jetbrains.kotlin.allopen
AtomicFUorg.jetbrains.kotlinx.atomicfu
Composeandroidx.compose.compiler.plugins.kotlin
js-plain-objectsorg.jetbrains.kotlinx.jspo
jvm-abi-genorg.jetbrains.kotlin.jvm.abi
kaptorg.jetbrains.kotlin.kapt3
Lombokorg.jetbrains.kotlin.lombok
no-arg, kotlin-jpaorg.jetbrains.kotlin.noarg
Parcelizeorg.jetbrains.kotlin.parcelize
Power-assertorg.jetbrains.kotlin.powerassert
SAM with receiverorg.jetbrains.kotlin.samWithReceiver
Serializationorg.jetbrains.kotlinx.serialization

この実行順序はコンパイラプラグインのバックエンドのみを制御し、フロントエンドは制御しません。

Experimental

-Xdata-flow-based-exhaustiveness

when 式に対するデータフローベースの網羅性チェックを有効にします。

Experimental

-Xexplicit-context-arguments

コンテキストパラメータに対する明示的なコンテキスト引数を有効にします。

これにより、呼び出し側でコンテキスト引数を渡すことでオーバーロードの曖昧さを解決できます。

Experimental

-Xklib-ir-inliner

Kotlin/Native、Kotlin/JS、およびKotlin/Wasmでモジュール内インライン化(intra-module inlining)を有効にするかどうかを設定します。デフォルトでは有効です。

このオプションは以下のモードをサポートしています:

  • disabled: Kotlin/Native、Kotlin/JS、およびKotlin/Wasmのモジュール内インライン化を無効にします。
  • full: モジュール間インライン化を有効にします。
Experimental

-Xintrinsic-const-evaluation

改良されたコンパイル時定数を有効にします。

Experimental

-Xname-based-destructuring

コンパイラがプロパティ名に基づいて分解宣言をどのように解釈するかを設定します。

このオプションは以下のモードをサポートしています:

  • only-syntax: 既存の分解宣言の動作を変更することなく、名前ベースの分解宣言の明示的な形式を有効にします。
  • name-mismatch: データクラスにおける位置ベースの分解宣言がプロパティ名と一致しない変数名を使用している場合に警告を報告します。
  • complete: 括弧を使用した短縮形式の名前ベースの分解宣言を有効にし、角括弧構文による位置ベースの分解宣言も引き続きサポートします。
Experimental

-Xphases-to-dump-before

IRローワリング(lowering)のコンパイルステージ後にダンプファイルを作成するには、ExternalPackageParentPatcherLowering に設定します。Kotlin/JVMの出力ディレクトリは、-Xdump-directory コンパイラオプションで設定します。

Experimental

-Xrepl

Kotlin REPLを起動します。

bash
kotlinc -Xrepl
Experimental

-Xreturn-value-checker

コンパイラが無視された結果をどのように報告するかを設定します:

  • disable: 未使用の戻り値チェッカーを無効にします(デフォルト)。
  • check: チェッカーを有効にし、マークされた関数からの無視された結果に対して警告を報告します。
  • full: チェッカーを有効にし、プロジェクト内のすべての関数をマークされたものとして扱い、無視された結果に対して警告を報告します。

警告の管理 ​

-nowarn ​

コンパイル中のすべての警告を抑制します。

-Werror ​

すべての警告をコンパイルエラーとして扱います。

-Wextra ​

該当する場合に警告を発する追加の宣言、式、および型のコンパイラチェックを有効にします。

Experimental

-Xrender-internal-diagnostic-names

警告とともに関係する内部診断名を出力します。これは、-Xwarning-level オプション用に設定する DIAGNOSTIC_NAME を特定するのに役立ちます。

Experimental

-Xwarning-level

特定のコンパイラ警告の重大度レベルを設定します:

bash
kotlinc -Xwarning-level=DIAGNOSTIC_NAME:(error|warning|disabled)
  • error: 指定された警告のみをエラーに引き上げます。
  • warning: 指定された診断に対して警告を発します(デフォルトで有効)。
  • disabled: 指定された警告のみをモジュール全体で抑制します。

モジュール全体のルールと特定のルールを組み合わせることで、プロジェクト内の警告レポートを調整できます:

コマンド説明
-nowarn -Xwarning-level=DIAGNOSTIC_NAME:warning指定されたものを除き、すべての警告を抑制します。
-Werror -Xwarning-level=DIAGNOSTIC_NAME:warning指定されたものを除き、すべての警告をエラーに引き上げます。
-Wextra -Xwarning-level=DIAGNOSTIC_NAME:disabled指定されたものを除き、すべての追加チェックを有効にします。

一般的なルールから除外したい警告が多数ある場合は、@argfile を使用して別のファイルにリストすることができます。

DIAGNOSTIC_NAME を調べるには、-Xrender-internal-diagnostic-names を使用できます。

@argfile ​

指定されたファイルからコンパイラオプションを読み込みます。このようなファイルには、値付きのコンパイラオプションやソースファイルへのパスを含めることができます。オプションとパスは空白で区切る必要があります。例:

-include-runtime -d hello.jar hello.kt

空白を含む値を渡すには、シングルクォーテーション(')またはダブルクォーテーション(")で囲みます。値の中に引用符が含まれている場合は、バックスラッシュ(\)でエスケープします。

-include-runtime -d 'My folder'

たとえば、コンパイラオプションとソースファイルを分けるために、複数の引数ファイルを渡すこともできます。

bash
$ kotlinc @compiler.options @classes

ファイルが現在のディレクトリと異なる場所にある場合は、相対パスを使用してください。

bash
$ kotlinc @options/compiler.options hello.kt

Kotlin/JVMコンパイラオプション ​

Kotlin/JVMコンパイラは、KotlinソースファイルをJavaクラスファイルにコンパイルします。 KotlinからJVMへのコンパイルを行うコマンドラインツールは kotlinc および kotlinc-jvm です。 これらを使用してKotlinスクリプトファイルを実行することもできます。

共通オプションに加えて、Kotlin/JVMコンパイラには以下に挙げるオプションがあります。

-classpath path (-cp path) ​

指定されたパスでクラスファイルを検索します。クラスパスの要素は、システムのパス区切り文字(Windowsでは ;、macOS/Linuxでは :)で区切ります。 クラスパスには、ファイルやディレクトリのパス、ZIPファイル、またはJARファイルを含めることができます。

-d path ​

生成されたクラスファイルを指定された場所に配置します。場所にはディレクトリ、ZIP、またはJARファイルを指定できます。

-include-runtime ​

結果のJARファイルにKotlinランタイムを含めます。これにより、生成されたアーカイブをJavaが有効な任意の環境で実行できるようになります。

-jdk-home path ​

デフォルトの JAVA_HOME と異なる場合に、クラスパスに含めるカスタムJDKホームディレクトリを使用します。

Experimental

-Xjdk-release=version

生成されるJVMバイトコードのターゲットバージョンを指定します。クラスパス内のJDKのAPIを指定されたJavaバージョンに制限します。 自動的に -jvm-target version も設定されます。 指定可能な値は 1.8、9、10、...、26 です。

このオプションは、すべてのJDKディストリビューションで有効であることが保証されているわけではありません。

-jvm-default mode ​

インターフェース内で宣言された関数をJVM上のデフォルトメソッドにコンパイルする方法を制御します。

モード説明
enableインターフェース内にデフォルト実装を生成し、サブクラスおよび DefaultImpls クラスにブリッジ関数を含めます。(デフォルト)
no-compatibility互換性ブリッジおよび DefaultImpls クラスを省略し、インターフェース内にデフォルト実装のみを生成します。
disableデフォルトメソッドを省略し、互換性ブリッジおよび DefaultImpls クラスのみを生成します。

-jvm-target version ​

生成されるJVMバイトコードのターゲットバージョンを指定します。指定可能な値は 1.8、9、10、...、26 です。 デフォルト値は 1.8 です。

-java-parameters ​

メソッドパラメータのJava 1.8リフレクション用のメタデータを生成します。

-module-name name (JVM) ​

生成される .kotlin_module ファイルのカスタム名を設定します。

-no-jdk ​

Javaランタイムをクラスパスに自動的に含めないようにします。

-no-reflect ​

Kotlinリフレクション(kotlin-reflect.jar)をクラスパスに自動的に含めないようにします。

-no-stdlib (JVM) ​

Kotlin/JVM stdlib(kotlin-stdlib.jar)およびKotlinリフレクション(kotlin-reflect.jar)をクラスパスに自動的に含めないようにします。

-script-templates classnames[,] ​

スクリプト定義テンプレートクラスです。完全修飾クラス名を使用し、カンマ(,)で区切ります。

Experimental

-Xadd-modules=module[,]

初期モジュールに加えて解決するルートモジュールを指定します。モジュールパス上のすべてのモジュールを解決するには、値に ALL-MODULE-PATH を設定します。複数のモジュールはカンマ(,)で区切ります。

たとえば、incubatorモジュールを解決する場合:

bash
kotlinc -Xadd-modules=jdk.incubator.vector
Experimental

-Xdump-directory

-Xphases-to-dump-before コンパイラオプションのダンプファイルディレクトリを設定します。

Experimental

-Xjvm-expose-boxed

モジュール内のすべてのインライン値クラス(inline value classes)のボックス化バージョンと、それらを使用する関数のボックス化バリアントを生成し、両方をJavaからアクセスできるようにします。詳細については、JavaからKotlinを呼び出すガイドのインライン値クラスを参照してください。

Experimental

-Xnullability-annotations

特定のJavaパッケージからのNull可能性アノテーション(nullability annotations)をKotlinコンパイラがどのように解釈するかを設定します。

サポートされているアノテーションと設定オプションの完全なリストについては、Nullability annotationsを参照してください。

Kotlin/JSコンパイラオプション ​

Kotlin/JSコンパイラは、KotlinソースファイルをJavaScriptコードにコンパイルします。 KotlinからJSへのコンパイルを行うコマンドラインツールは kotlinc-js です。

共通オプションに加えて、Kotlin/JSコンパイラには以下に挙げるオプションがあります。

-libraries path ​

.meta.js および .kjsm ファイルを含むKotlinライブラリへのパス(システムのパス区切り文字で区切る)。

-main {call|noCall} ​

実行時に main 関数を呼び出すかどうかを定義します。

-meta-info ​

メタデータを含む .meta.js および .kjsm ファイルを生成します。JSライブラリを作成するときにこのオプションを使用します。

-module-kind {umd|commonjs|amd|plain} ​

コンパイラによって生成されるJSモジュールの種類:

さまざまな種類のJSモジュールおよびそれらの違いの詳細については、こちらの記事を参照してください。

-no-stdlib (JS) ​

デフォルトのKotlin/JS stdlibをコンパイル依存関係に自動的に含めないようにします。

-output filepath ​

コンパイル結果の出力先ファイルを設定します。値には、ファイル名を含む .js ファイルへのパスを指定する必要があります。

-output-postfix filepath ​

指定されたファイルの内容を出力ファイルの末尾に追加します。

-output-prefix filepath ​

指定されたファイルの内容を出力ファイルの先頭に追加します。

-source-map ​

ソースマップを生成します。

-source-map-base-dirs path ​

指定されたパスをベースディレクトリとして使用します。ベースディレクトリは、ソースマップ内の相対パスを計算するために使用されます。

-source-map-embed-sources {always|never|inlining} ​

ソースファイルをソースマップ内に埋め込みます。

-source-map-names-policy {simple-names|fully-qualified-names|no} ​

Kotlinコードで宣言した変数名と関数名をソースマップに追加します。

設定説明出力例
simple-names変数名と単純な関数名が追加されます。(デフォルト)main
fully-qualified-names変数名と完全修飾関数名が追加されます。com.example.kjs.playground.main
no変数名や関数名は追加されません。N/A

-source-map-prefix ​

ソースマップ内のパスに指定されたプレフィックスを追加します。

-target {es5|es2015|es2020} ​

指定されたECMAバージョン向けのJSファイルを生成します。

Experimental

-Xenable-implementing-interfaces-from-typescript

JavaScript/TypeScriptから、@JsExport アノテーションを付けてエクスポートされたKotlinインターフェースの実装を許可します。

-Xes-long-as-bigint ​

モダンJavaScript(ES2020)へのコンパイル時に、Kotlinの Long 値を表すためにJavaScriptの BigInt 型のサポートを有効にします。 このオプションは es5 および es2015 ターゲットにのみ必要です。es2020 ターゲットでは、このオプションがデフォルトで有効になっています。

Experimental

-Xsuspend-lambda-exporting

@JsExport 宣言内で宣言されたsuspendラムダ式のエクスポートを、JavaScriptの async 関数として許可します。

Kotlin/Nativeコンパイラオプション ​

Kotlin/Nativeコンパイラは、Kotlinソースファイルをサポートされているプラットフォーム向けのネイティブバイナリにコンパイルします。 Kotlin/Nativeコンパイルのコマンドラインツールは kotlinc-native です。

共通オプションに加えて、Kotlin/Nativeコンパイラには以下に挙げるオプションがあります。

-enable-assertions (-ea) ​

生成されたコードで実行時アサーションを有効にします。

-entry name (-e name) ​

修飾されたエントリポイント名を指定します。

-g ​

デバッグ情報の出力を有効にします。このオプションは最適化レベルを低下させるため、-opt オプションと組み合わせるべきではありません。

-generate-test-runner (-tr) ​

プロジェクトからユニットテストを実行するためのアプリケーションを生成します。

-generate-no-exit-test-runner (-trn) ​

明示的なプロセス終了(exit)を行わずにユニットテストを実行するアプリケーションを生成します。

-include-binary path (-ib path) ​

生成されたklibファイル内に外部バイナリをパックします。

-library path (-l path) ​

ライブラリとリンクします。Kotlin/Nativeプロジェクトでのライブラリの使用方法については、Kotlin/Nativeライブラリを参照してください。

-library-version version (-lv version) ​

ライブラリのバージョンを設定します。

-linker-option ​

バイナリのビルド中にリンカーに引数を渡します。これは、何らかのネイティブライブラリに対してリンクを行う場合に使用できます。

-linker-options args ​

バイナリのビルド中にリンカーに複数の引数を渡します。引数は空白で区切ります。

-list-targets ​

利用可能なハードウェアターゲットを一覧表示します。

-manifest path ​

マニフェスト付加(addend)ファイルを提供します。

-module-name name (Native) ​

コンパイルモジュールの名前を指定します。 このオプションは、Objective-Cにエクスポートされる宣言の名前プレフィックスを指定するためにも使用できます: KotlinフレームワークにカスタムのObjective-Cプレフィックス/名前を指定するにはどうすればよいですか?

-native-library path (-nl path) ​

ネイティブビットコードライブラリを含めます。

-no-default-libs ​

コンパイラとともに配布されるビルド済みのプラットフォームライブラリとユーザーコードのリンクを無効にします。

-nomain ​

main エントリポイントが外部ライブラリによって提供されることを前提とします。

-nopack ​

ライブラリをklibファイルにパックしません。

-nostdlib ​

stdlibとリンクしません。

-opt ​

コンパイルの最適化を有効にし、実行時パフォーマンスが向上したバイナリを生成します。最適化レベルを低下させる -g オプションと組み合わせることは推奨されません。

-output name (-o name) ​

出力ファイルの名前を設定します。

-produce output (-p output) ​

出力ファイルの種類を指定します:

  • program
  • static
  • dynamic
  • framework
  • library
  • bitcode

-repo path (-r path) ​

ライブラリの検索パス。詳細については、ライブラリ検索シーケンスを参照してください。

-target target ​

ハードウェアターゲットを設定します。利用可能なターゲットのリストを表示するには、-list-targets オプションを使用します。

Experimental

-Xccall-mode

cinterop経由でインポートされたCまたはObjective-Cライブラリ向けの新しい相互運用モードを有効にします。

Experimental

-Xoverride-konan-properties=min.version.*

Kotlinのデフォルトよりも低いサポート対象のAppleターゲットバージョンを設定します。例:

bash
kotlinc -Xoverride-konan-properties=minVersion.ios=14.0
kotlinc -Xoverride-konan-properties=minVersion.macos=11.0
kotlinc -Xoverride-konan-properties=minVersion.tvos=14.0
kotlinc -Xoverride-konan-properties=minVersion.watchos=7.0