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

ネイティブ・イメージを構成するオプションは、次のカテゴリで提供されます:

• ビルド・オプション: ビルド・オプションのヘルプについては、native-image --helpを実行します。
• 追加のビルド・オプション: 追加のビルド・オプションのヘルプについては、native-image --help-extraを実行します。
• エキスパート・ビルド・オプション: エキスパート・オプションのヘルプについては、native-image --expert-optionsを実行します。

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

ネイティブ・イメージ・オプションは、ホスト型オプション、または実行時オプションとして分類されることもあります。

• ホスト型オプション: ビルド・プロセスを構成します。たとえば、ネイティブ・バイナリに含まれる内容やビルド方法に影響します。これらのオプションでは、接頭辞-H:が使用されます。
• 実行時オプション: 接頭辞-R:を使用して、ネイティブ・バイナリをビルドする際の初期値を指定します。実行時のデフォルトの接頭辞は-XX:です(これはアプリケーション固有であり、ネイティブ・イメージに必須のものではありません)。

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

ビルド・オプション

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

• -cp, -classpath, --class-path <class search path of directories and ZIP/JAR files>: クラス・ファイルを検索するディレクトリ、JARアーカイブおよびZIPアーカイブの: (Windowsでは;)区切りリスト
• -p <module path>, --module-path <module path>: ディレクトリの: (Windowsでは;)区切りリスト。各ディレクトリは、モジュールのディレクトリです。
• --add-modules <module name>[,<module name>...]: 初期モジュールに加えて解決するルート・モジュールを追加します。<module name>には、ALL-DEFAULT、ALL-SYSTEM、ALL-MODULE-PATHも指定できます
• -D<name>=<value>: システム・プロパティを設定します
• -J<flag>: native-imageビルダーを実行するJVMにオプションを直接渡します
• --diagnostics-mode: クラスの初期化、置換などの診断出力を有効にします。
• --enable-preview: このリリースのプレビュー機能をクラスが利用できるようにします
• --enable-native-access <module name>[,<module name>...]: 制限されたネイティブ操作の実行を許可されているモジュールを有効にします。<module name>は、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プロトコルをカンマ区切りでリストします
• --exact-reachability-metadata: リフレクション、リソース、JNIおよびシリアライズの正確でユーザーフレンドリな処理を有効にします
• --exact-reachability-metadata-path: 指定されたクラスパス・エントリまたはモジュール・パス・エントリのすべてのタイプからのリフレクション、リソース、JNIおよびシリアライズの正確な処理をトリガーします
• --features: 完全修飾機能実装クラスのカンマ区切りリスト
• --force-fallback: フォールバック・ネイティブ実行可能ファイルのビルドを強制します
• --gc=<value>: ネイティブ・イメージ・ガベージ・コレクタの実装を選択します。<value>で使用可能なオプションは、G1ガベージ・コレクタではG1 (GraalVM Community Editionでは使用できません)、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: AOTコンパイルされたコードをインストゥルメントして、プロファイルに基づく最適化のためのデータをdefault.iprofファイルに収集します。(GraalVM Community Editionでは使用できません。)
• --pgo-sampling: AOTコンパイルされたコードをサンプリングして、プロファイリングを実行し、プロファイルに基づく最適化のためのデータを収集します。(GraalVM Community Editionでは使用できません。)
• --shared: 共有ライブラリをビルドします
• --silent: ビルド出力を抑制します
• --static: 静的にリンクされた実行可能ファイルをビルドします(libcおよびzlib静的ライブラリが必要です)
• --static-nolibc: libcが動的にリンクされた、静的にリンクされた実行可能ファイルをビルドします
• --target: native-imageのコンパイル・ターゲットを選択します(<OS>-<architecture>形式)。デフォルトはホストのOSとアーキテクチャのペアです。
• --trace-object-instantiation: オブジェクトのインスタンス化がトレースされる完全修飾クラス名のカンマ区切りリストを指定します
• -O<level>: コードの最適化を制御します。使用可能なオプションは次のとおりです: b - 最速のビルド時間の最適化、s - サイズの最適化、0 - 最適化なし、1 - 基本の最適化、2 - 積極的な最適化、3 - 最適なパフォーマンスのためのすべての最適化(プロファイルに基づく最適化(PGO)で自動的に有効になります)
• -da、-da[:[packagename]|:[classname]、disableassertions[:[packagename]|:[classname]: 実行時に指定した粒度でアサーションを無効にします
• -dsa、-disablesystemassertions: 実行時にすべてのシステム・クラス内のアサーションを無効にします
• -ea、-ea[:[packagename]|:[classname]、enableassertions[:[packagename]|:[classname]: 実行時に指定した粒度でアサーションを有効にします
• -esa、-enablesystemassertions: 実行時にすべてのシステム・クラス内でアサーションを有効にします
• -g: デバッグ情報を生成します
• -march: 特定のマシン・タイプの命令を生成します。デフォルトは、AMD64ではx86-64-v3、AArch64ではarmv8-aです。ネイティブ実行可能ファイルが同じマシンまたは同じCPU機能を持つマシンにデプロイされる場合、最高の互換性のために-march=compatibilityを使用するか、最高のパフォーマンスを得るために-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内のpropertiesファイルがすべて無視されます。
• --expert-options: エキスパート用のイメージ・ビルド・オプションをリストします
• --expert-options-all: エキスパート用のすべてのイメージ・ビルド・オプションをリストします(各自の責任で使用)Extra help availableとマークされたオプションには、--expert-options-detailで表示できるヘルプが含まれています
• --expert-options-detail: カンマ区切りリストとして指定したオプションに関するすべてのヘルプを表示します。*を渡すと、それを含むすべてのオプションの追加ヘルプが表示されます
• --configurations-path <search path of option-configuration directories>: オプション構成ディレクトリとして扱われるディレクトリのカンマ区切りリストです
• --debug-attach[=<port or host:port (* can be used as host meaning bind to all interfaces)>]: ネイティブ実行可能ファイルの生成時にデバッガにアタッチします(デフォルト・ポートは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>: GraalVMのOracle Linux 8ベース・イメージに基づくデフォルトではなく、ユーザーが指定した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>)は、モジュール宣言に関係なく、<target-module>を読み取るように<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: 実行時にコンパイル・グラフがダンプされます。

システム・プロパティ

-D<system.property>=<value>オプション構文を使用して、イメージ構築時にシステム・プロパティを定義できます。native-imageツールのシステム・プロパティを設定しますが、このプロパティは生成された実行可能ファイルに含まれません。ただし、JDKシステム・プロパティは生成された実行可能ファイルに含まれており、実行時に表示されます。

たとえば:

• -D<system.property>=<value>は、ビルド時にのみ表示されます。このシステム・プロパティがネイティブ実行可能ファイルでアクセスされると、nullが返されます。
• -Djava.version=24は、デフォルトで値がバイナリにコピーされるため、ビルド時とネイティブ実行可能ファイルの両方に表示されます。

次のシステム・プロパティは、生成された実行可能ファイルに自動的にコピーされます。

名前	説明
file.separator	ファイル・セパレータ
file.encoding	デフォルト・ロケールの文字エンコーディング
java.version	Java Runtime Environmentのバージョン
java.version.date	リリースの一般提供(GA)の日付
java.class.version	Javaクラスの形式のバージョン番号
java.runtime.version	Java Runtime Environmentのバージョン
java.specification.name	Java Runtime Environmentの仕様名
java.specification.vendor	Java Runtime Environmentの仕様のベンダー
java.specification.version	Java仮想マシンの仕様バージョン
java.vm.specification.name	Java仮想マシンの仕様名
java.vm.specification.vendor	Java仮想マシンの実装のベンダー
java.vm.specification.version	Java仮想マシンの仕様バージョン
line.separator	行区切り文字
native.encoding	ホスト環境の文字エンコーディングを指定します
org.graalvm.nativeimage.kind	イメージが共有ライブラリまたは実行可能ファイルとして構築されるかどうかを指定します
path.separator	パス区切り文字
stdout.encoding	System.outおよびSystem.errのエンコーディングを指定します
sun.jnu.encoding	コマンドラインを介して渡された値の解析時のエンコーディングを指定します

関連ドキュメント

• ビルド構成
• ビルドの概要