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.jarWindowsでは、区切り文字(空白、
=、;、,)を含むコンパイラ引数を渡す場合、 それらの引数をダブルクォーテーション(")で囲んでください。$ 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
コンパイラのバージョンを表示します。
-X
高度なオプションに関する情報を表示して終了します。これらのオプションは現在不安定です。 それらの名前や動作は予告なしに変更される可能性があります。
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)が、無視できる結果と高階関数からの意味のある結果を区別できるようにします。
-Xallow-reified-type-in-catch
inline 関数の catch 節で、具現化された(reified)Throwable 型パラメータのサポートを有効にします。
-Xcollection-literals
ブラケット構文 [] によるコレクションリテラルのサポートを有効にします。
-Xcompiler-plugin-order={plugin.before>plugin.after}
コンパイラプラグインの実行順序を設定します。コンパイラは plugin.before を先に実行し、その後に plugin.after を実行します。
3つ以上のプラグインに対して複数の順序ルールを定義できます。例:
kotlinc -Xcompiler-plugin-order=plugin.first>plugin.middle
kotlinc -Xcompiler-plugin-order=plugin.middle>plugin.lastこれにより、以下の実行順序になります:
plugin.firstplugin.middleplugin.last
コンパイラプラグインが存在しない場合、対応するルールは無視されます。
以下のプラグインをそのIDで設定できます:
| コンパイラプラグイン | プラグインID |
|---|---|
all-open, kotlin-spring | org.jetbrains.kotlin.allopen |
| AtomicFU | org.jetbrains.kotlinx.atomicfu |
| Compose | androidx.compose.compiler.plugins.kotlin |
js-plain-objects | org.jetbrains.kotlinx.jspo |
jvm-abi-gen | org.jetbrains.kotlin.jvm.abi |
| kapt | org.jetbrains.kotlin.kapt3 |
| Lombok | org.jetbrains.kotlin.lombok |
no-arg, kotlin-jpa | org.jetbrains.kotlin.noarg |
| Parcelize | org.jetbrains.kotlin.parcelize |
| Power-assert | org.jetbrains.kotlin.powerassert |
| SAM with receiver | org.jetbrains.kotlin.samWithReceiver |
| Serialization | org.jetbrains.kotlinx.serialization |
この実行順序はコンパイラプラグインのバックエンドのみを制御し、フロントエンドは制御しません。
-Xdata-flow-based-exhaustiveness
when 式に対するデータフローベースの網羅性チェックを有効にします。
-Xexplicit-context-arguments
コンテキストパラメータに対する明示的なコンテキスト引数を有効にします。
これにより、呼び出し側でコンテキスト引数を渡すことでオーバーロードの曖昧さを解決できます。
-Xklib-ir-inliner
Kotlin/Native、Kotlin/JS、およびKotlin/Wasmでモジュール内インライン化(intra-module inlining)を有効にするかどうかを設定します。デフォルトでは有効です。
このオプションは以下のモードをサポートしています:
disabled: Kotlin/Native、Kotlin/JS、およびKotlin/Wasmのモジュール内インライン化を無効にします。full: モジュール間インライン化を有効にします。
-Xintrinsic-const-evaluation
改良されたコンパイル時定数を有効にします。
-Xname-based-destructuring
コンパイラがプロパティ名に基づいて分解宣言をどのように解釈するかを設定します。
このオプションは以下のモードをサポートしています:
only-syntax: 既存の分解宣言の動作を変更することなく、名前ベースの分解宣言の明示的な形式を有効にします。name-mismatch: データクラスにおける位置ベースの分解宣言がプロパティ名と一致しない変数名を使用している場合に警告を報告します。complete: 括弧を使用した短縮形式の名前ベースの分解宣言を有効にし、角括弧構文による位置ベースの分解宣言も引き続きサポートします。
-Xphases-to-dump-before
IRローワリング(lowering)のコンパイルステージ後にダンプファイルを作成するには、ExternalPackageParentPatcherLowering に設定します。Kotlin/JVMの出力ディレクトリは、-Xdump-directory コンパイラオプションで設定します。
-Xrepl
Kotlin REPLを起動します。
kotlinc -Xrepl-Xreturn-value-checker
コンパイラが無視された結果をどのように報告するかを設定します:
disable: 未使用の戻り値チェッカーを無効にします(デフォルト)。check: チェッカーを有効にし、マークされた関数からの無視された結果に対して警告を報告します。full: チェッカーを有効にし、プロジェクト内のすべての関数をマークされたものとして扱い、無視された結果に対して警告を報告します。
警告の管理
-nowarn
コンパイル中のすべての警告を抑制します。
-Werror
すべての警告をコンパイルエラーとして扱います。
-Wextra
該当する場合に警告を発する追加の宣言、式、および型のコンパイラチェックを有効にします。
-Xrender-internal-diagnostic-names
警告とともに関係する内部診断名を出力します。これは、-Xwarning-level オプション用に設定する DIAGNOSTIC_NAME を特定するのに役立ちます。
-Xwarning-level
特定のコンパイラ警告の重大度レベルを設定します:
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'たとえば、コンパイラオプションとソースファイルを分けるために、複数の引数ファイルを渡すこともできます。
$ kotlinc @compiler.options @classesファイルが現在のディレクトリと異なる場所にある場合は、相対パスを使用してください。
$ kotlinc @options/compiler.options hello.ktKotlin/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ホームディレクトリを使用します。
-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[,]
スクリプト定義テンプレートクラスです。完全修飾クラス名を使用し、カンマ(,)で区切ります。
-Xadd-modules=module[,]
初期モジュールに加えて解決するルートモジュールを指定します。モジュールパス上のすべてのモジュールを解決するには、値に ALL-MODULE-PATH を設定します。複数のモジュールはカンマ(,)で区切ります。
たとえば、incubatorモジュールを解決する場合:
kotlinc -Xadd-modules=jdk.incubator.vector-Xdump-directory
-Xphases-to-dump-before コンパイラオプションのダンプファイルディレクトリを設定します。
-Xjvm-expose-boxed
モジュール内のすべてのインライン値クラス(inline value classes)のボックス化バージョンと、それらを使用する関数のボックス化バリアントを生成し、両方をJavaからアクセスできるようにします。詳細については、JavaからKotlinを呼び出すガイドのインライン値クラスを参照してください。
-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モジュールの種類:
umd- Universal Module Definition モジュールcommonjs- CommonJS モジュールamd- Asynchronous Module Definition モジュール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ファイルを生成します。
-Xenable-implementing-interfaces-from-typescript
JavaScript/TypeScriptから、@JsExport アノテーションを付けてエクスポートされたKotlinインターフェースの実装を許可します。
-Xes-long-as-bigint
モダンJavaScript(ES2020)へのコンパイル時に、Kotlinの Long 値を表すためにJavaScriptの BigInt 型のサポートを有効にします。 このオプションは es5 および es2015 ターゲットにのみ必要です。es2020 ターゲットでは、このオプションがデフォルトで有効になっています。
-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)
出力ファイルの種類を指定します:
programstaticdynamicframeworklibrarybitcode
-repo path (-r path)
ライブラリの検索パス。詳細については、ライブラリ検索シーケンスを参照してください。
-target target
ハードウェアターゲットを設定します。利用可能なターゲットのリストを表示するには、-list-targets オプションを使用します。
-Xccall-mode
cinterop経由でインポートされたCまたはObjective-Cライブラリ向けの新しい相互運用モードを有効にします。
-Xoverride-konan-properties=min.version.*
Kotlinのデフォルトよりも低いサポート対象のAppleターゲットバージョンを設定します。例:
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