コマンドラインオプション

ネイティブイメージの設定オプションは、次のカテゴリに分類されます。

ビルドオプション：ビルドオプションのヘルプについては、native-image --help を実行してください。
追加ビルドオプション：追加ビルドオプションのヘルプについては、native-image --help-extra を実行してください。
専門家向けビルドオプション：専門家向けオプションのヘルプについては、native-image --expert-options を実行してください。

GraalVM のバージョンによっては、native-image ビルダーのオプションが異なる場合があります。

ネイティブイメージオプションは、**ホスト側**オプションと**実行時**オプションの2つのカテゴリに分類することもできます。

**ホスト側オプション**：ビルドプロセスを設定します。たとえば、ネイティブバイナリに含まれるものや、そのビルド方法に影響を与えます。これらのオプションは、プレフィックス -H: を使用します。
**実行時オプション**：プレフィックス -R: を使用して、ネイティブバイナリをビルドするときの初期値を指定します。実行時のデフォルトのプレフィックスは -XX: です（これはアプリケーション固有であり、ネイティブイメージによって義務付けられていません）。

これらのオプションの定義方法と使用方法の詳細については、com.oracle.svm.core.option パッケージのドキュメントを参照してください。

ビルドオプション #

ビルドオプションのヘルプについては、native-image --help を実行してください。

-cp, -classpath, --class-path <ディレクトリおよびZIP/JARファイルのクラス検索パス>：クラスファイルの検索対象となるディレクトリ、JARアーカイブ、ZIPアーカイブの、:（Windowsでは;）で区切られたリスト
-p <モジュールパス>, --module-path <モジュールパス>：ディレクトリの、:（Windowsでは;）で区切られたリスト。各ディレクトリはモジュールのディレクトリです。
--add-modules <モジュール名>[,<モジュール名>...]：初期モジュールに加えて解決するルートモジュールを追加します。<モジュール名>には、ALL-DEFAULT、ALL-SYSTEM、ALL-MODULE-PATH を指定することもできます。
-D<名前>=<値>：システムプロパティを設定します。
-J<フラグ>：native-imageビルダーを実行するJVMに直接オプションを渡します。
--diagnostics-mode：診断出力を有効にします：クラスの初期化、置換など。
--enable-preview：クラスがこのリリースのプレビュー機能に依存することを許可します。
--enable-native-access <モジュール名>[,<モジュール名>...]：制限されたネイティブ操作を実行することが許可されているモジュールを有効にします。<モジュール名>には、ALL-UNNAMED を指定することもできます。
--verbose：詳細出力を有効にします。
--version：製品バージョンを出力して終了します。
--help：このヘルプメッセージを出力します。
--help-extra：標準以外のオプションに関するヘルプを出力します。
--auto-fallback：可能であればスタンドアロンの実行可能ファイルをビルドします。
--color：ビルド出力の色付け（always、never、またはauto）
--configure-reflection-metadata：呼び出されていないメソッドの反射オブジェクトの実行時インスタンス化を有効にします。
--emit：ビルドの結果として追加のデータを出力します。たとえば、詳細なビルドレポートを出力するにはbuild-reportを使用します：--emit build-reportまたは--emit build-report=report.html
--enable-all-security-services：生成されたネイティブ実行可能ファイルにすべてのセキュリティサービスクラスを追加します。
--enable-http：ネイティブ実行可能ファイルでHTTPサポートを有効にします。
--enable-https：ネイティブ実行可能ファイルでHTTPSサポートを有効にします。
--enable-monitoring：VMが実行時に検査できるようにする監視機能を有効にします。コンマ区切りのリストには、heapdump、jfr、jvmstat、jmxserver（実験的）、jmxclient（実験的）、threaddump、またはall（非推奨の動作：引数が指定されていない場合はallにデフォルト設定）を含めることができます。例：--enable-monitoring=heapdump,jfr。
--enable-sbom：受動的な検査のために、ソフトウェア部品表（SBOM）を実行可能ファイルまたは共有ライブラリに埋め込みます。コンマ区切りのリストには、cyclonedx、strict（引数が指定されていない場合はcyclonedxにデフォルト設定）、またはネイティブ実行可能ファイルの出力ディレクトリにSBOMを保存するためのexportを含めることができます。オプションのstrictフラグは、クラスをSBOM内のライブラリに一致させることができない場合、ビルドを中断します。例：--enable-sbom=cyclonedx,strict。（GraalVM Community Editionでは使用できません。）
--enable-url-protocols：有効にするURLプロトコルのコンマ区切りのリスト
--features：完全修飾されたFeature 実装クラスのコンマ区切りのリスト
--force-fallback：フォールバックネイティブ実行可能ファイルのビルドを強制します。
--gc=<値>：ネイティブイメージガベージコレクターの実装を選択します。<値>に使用できるオプションは、G1ガベージコレクター（GraalVM Community Editionでは使用できません）のG1、Epsilonガベージコレクターのepsilon、シリアルガベージコレクター（デフォルト）のserialです。
--initialize-at-build-time：ネイティブ実行可能ファイルの生成中に初期化されるパッケージとクラス（および暗黙的にそれらのすべてのスーパークラス）のコンマ区切りのリスト。空の文字列はすべてのパッケージを指定します。
--initialize-at-run-time：実行時に初期化する必要があり、生成中には初期化しないパッケージとクラス（および暗黙的にそれらのすべてのサブクラス）のコンマ区切りのリスト。現在、空の文字列はサポートされていません。
--install-exit-handlers：java.lang.Terminator終了ハンドラーを提供します。
--libc：使用するlibc実装を選択します。使用可能な実装は、glibc、musl、bionicです。
--link-at-build-time：ネイティブ実行可能ファイルのビルド時に型が完全に定義されていることを要求します。引数なしで使用すると、オプションのスコープ内のすべてのクラスが完全に定義されている必要があります。
--link-at-build-time-paths：指定されたクラスパスまたはモジュールパスエントリ内のすべての型が、ネイティブ実行可能ファイルのビルド時に完全に定義されていることを要求します。
--list-cpu-features：ターゲットプラットフォーム固有のCPU機能を表示して終了します。
--list-modules：観測可能なモジュールをリストして終了します。
--native-compiler-options：クエリコードコンパイルに使用されるカスタムCコンパイラオプションを提供します。
--native-compiler-path：クエリコードコンパイルとリンクに使用されるCコンパイラへのカスタムパスを提供します。
--native-image-info：ネイティブツールチェーンの情報と実行可能ファイルのビルド設定を表示します。
--no-fallback：スタンドアロンのネイティブ実行可能ファイルをビルドするか、エラーを報告します。
--parallelism：ネイティブ実行可能ファイルの生成中に同時に使用するスレッドの最大数を指定します。
--pgo：AOTコンパイル済みコードのプロファイルガイド付き最適化のために収集されたデータを読み取るファイルのコンマ区切りのリストを提供します（何も指定されていない場合は *default.iprof* から読み取ります）。各ファイルには、JSON形式でシリアル化された単一のPGOProfilesオブジェクトが含まれており、オプションでgzipによって圧縮されます。（GraalVM Community Editionでは使用できません。）
--pgo-instrument：*default.iprof* ファイルにプロファイルガイド付き最適化のためのデータを集めるために、AOTコンパイル済みコードをインストルメントします。（GraalVM Community Editionでは使用できません。）
--pgo-sampling：プロファイルガイド付き最適化のためにデータを集めるために、AOTコンパイル済みコードをサンプリングすることによってプロファイリングを実行します。（GraalVM Community Editionでは使用できません。）
--shared：共有ライブラリをビルドします。
--silent：ビルド出力を抑制します。
--static：静的にリンクされた実行可能ファイルをビルドします（libcとzlibの静的ライブラリが必要です）。
--static-nolibc：libcを動的にリンクして静的にリンクされた実行可能ファイルをビルドします。
--target：native-imageのコンパイルターゲットを選択します（<OS>-<アーキテクチャ>形式）。ホストのOSとアーキテクチャのペアにデフォルト設定されます。
--trace-class-initialization：クラスの初期化がトレースされる完全修飾クラス名のコンマ区切りのリストを提供します。
--trace-object-instantiation：オブジェクトのインスタンス化がトレースされる完全修飾クラス名のコンマ区切りのリストを提供します。
-O<レベル>：利用可能なバリアントは、最速のビルド時間のためのb、サイズのためのs、最適化なしの0、基本的な最適化の1、積極的な最適化の2、最高の性能のためのすべての最適化（プロファイルガイド付き最適化で自動的に有効化）の3です。
-da、-da[:[パッケージ名]|:[クラス名]、disableassertions[:[パッケージ名]|:[クラス名]：実行時に指定された粒度でアサーションを無効にします。
-dsa、-disablesystemassertions：実行時にすべてのシステムクラスのアサーションを無効にします。
-ea、-ea[:[パッケージ名]|:[クラス名]、enableassertions[:[パッケージ名]|:[クラス名]：実行時に指定された粒度でアサーションを有効にします。
-esa、-enablesystemassertions：実行時にすべてのシステムクラスのアサーションを有効にします。
-g：デバッグ情報を生成します。
-march：特定のマシンタイプ用の命令を生成します。AMD64ではx86-64-v3、AArch64ではarmv8-aにデフォルト設定されます。最高の互換性のために-march=compatibilityを使用するか、ネイティブ実行可能ファイルが同じマシンまたは同じCPU機能を持つマシンにデプロイされる場合は、最高の性能のために-march=nativeを使用します。使用可能なすべてのマシンタイプをリストするには、-march=listを使用します。
-o：生成される出力ファイルの名前。

追加ビルドオプション #

追加オプションのヘルプについては、native-image --help-extra を実行してください。

--exclude-config：コンマ区切りのクラスパス/モジュールパスパターンとリソースパターンのペアの構成を除外します。たとえば、--exclude-config foo.jar,META-INF\/native-image\/.*.propertiesは、foo.jarという名前のすべてのJARファイル内のMETA-INF/native-imageにあるすべてのプロパティファイルを無視します。
--expert-options：専門家向けのイメージビルドオプションをリストします。
--expert-options-all：専門家向けのすべてのイメージビルドオプションをリストします（自己責任で使用してください）。Extra help availableとマークされたオプションには、--expert-options-detailで表示できるヘルプが含まれています。
--expert-options-detail：コンマ区切りのオプション名のリストに対して、利用可能なすべてのヘルプを表示します。すべてのオプションの追加ヘルプを表示するには、*を渡します。
--configurations-path <オプション設定ディレクトリの検索パス>：オプション設定ディレクトリとして扱われるディレクトリの区切られたリスト。
--debug-attach[=<ポートまたはホスト:ポート (* はすべてのインターフェースにバインドすることを意味するホストとして使用できます)>]：ネイティブ実行可能ファイルの生成中にデバッガーにアタッチします（デフォルトポートは8000）。
--diagnostics-mode：イメージビルド情報を診断ディレクトリにログすることを有効にします。
--dry-run：ビルドに使用されるコマンドラインを出力します。
--bundle-create[=new-bundle.nib]：イメージのビルドに加えて、後でそのイメージを再ビルドできるネイティブイメージバンドルファイル（*.nibfile）を作成します。バンドルファイルが渡されると、指定された名前でバンドルが作成されます。それ以外の場合は、イメージ名からバンドルファイル名が導出されます。両方のバンドルオプションは、dry-runとcontainerで拡張できます。
- dry-run：実際のネイティブ実行可能ファイルのビルドを行わずに、バンドル操作のみを実行します。
- container: コンテナイメージをセットアップし、そのコンテナ内からネイティブ実行ファイルの生成を実行します。Podmanまたはrootless Dockerがインストールされている必要があります。利用可能な場合は、Podmanが優先され、rootless Dockerはフォールバックとして使用されます。=<container-tool>としてどちらかを指定すると、特定のツールの使用が強制されます。
- dockerfile=<Dockerfile>: Oracle Linux 8ベースイメージ for GraalVMに基づくデフォルトではなく、ユーザーが提供したDockerfileを使用します。
--bundle-apply=some-bundle.nib[,dry-run][,container[=<container-tool>][,dockerfile=<Dockerfile>]]: 指定されたバンドルファイルから、ネイティブイメージでバンドルを作成するために元々渡された引数とファイルと全く同じ引数とファイルを使用してイメージがビルドされます。--bundle-applyの後に追加の--bundle-createが渡された場合、指定されたバンドル引数と、その後渡された追加の引数を基に新しいバンドルが書き込まれることに注意してください。例：native-image --bundle-apply=app.nib --bundle-create=app_dbg.nib -g は、指定されたapp.nibバンドルに基づいて新しいバンドルapp_dbg.nibを作成します。新しいバンドルは-gオプションを使用する点を除き、両方のバンドルは同じです。
-E<env-var-key>[=<env-var-value>]: ネイティブ実行ファイルの生成中に、指定された環境変数にネイティブイメージがアクセスできるようにします。オプションの<env-var-value>が指定されていない場合、環境変数の値は、ネイティブイメージが呼び出された環境から取得されます。
-V<key>=<value>: native-image.propertiesファイル内のプレースホルダーに値を提供します。
--add-exports: 値<module>/<package>=<target-module>(,<target-module>)は、モジュールの宣言に関係なく、<package>を<target-module>にエクスポートするように<module>を更新します。<target-module>は、すべての名前なしモジュールにエクスポートするためにALL-UNNAMEDにすることができます。
--add-opens: 値<module>/<package>=<target-module>(,<target-module>)は、モジュールの宣言に関係なく、<package>を<target-module>に開くように<module>を更新します。
--add-reads: 値<module>=<target-module>(,<target-module>)は、モジュールの宣言に関係なく、<module>が<target-module>を読み取れるように更新します。<target-module>は、すべての名前なしモジュールを読み取るためにALL-UNNAMEDにすることができます。

便利なオプション一覧 #

ユーザーにとって便利または必要な、高度なオプションがいくつかあります。たとえば、native-imageビルダーのグラフをダンプするオプションや、ビルドプロセス中にさまざまな統計情報を印刷するオプションなどです。

ビルド出力とビルドレポート #

ネイティブイメージは、ビルドプロセス中にさまざまな統計情報を含む、情報豊富なビルド出力を提供します。JSONベースの機械可読形式のビルド出力は、-H:BuildOutputJSONFileオプションを使用して要求でき、後で監視ツールで処理できます。JSONファイルは、build-output-schema-v0.9.3.jsonで定義されているJSONスキーマに対して検証されます。追加情報を含む包括的なレポートは、--emit build-reportオプションを使用して要求できます。

注：--emit build-reportオプションは、GraalVM Community Editionでは使用できません。

グラフダンプ #

ネイティブイメージは、グラフダンプ、ロギング、カウンター、その他のすべてのオプションをGraalVMデバッグ環境から再利用しました。これらのGraalVMオプションは、ホストされたオプション（native-imageビルダーのグラフをダンプする場合）と、ランタイムオプション（ランタイム時に動的コンパイル中にグラフをダンプする場合）の両方として使用できます。

期待どおりに動作するGraalコンパイラのオプションには、Dump、DumpOnError、Log、MethodFilter、およびダンプハンドラーのファイル名とポートを指定するオプションが含まれます。例：

-H:Dump= -H:MethodFilter=ClassName.MethodName: native-imageビルダーのコンパイラグラフをダンプします。
-XX:Dump= -XX:MethodFilter=ClassName.MethodName: ランタイム時にコンパイルグラフをダンプします。