Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルする

Red Hat build of Quarkus 3.15

Red Hat Customer Content Services

法律上の通知

概要

このガイドでは、Red Hat build of Quarkus Getting Started プロジェクトをネイティブ実行可能ファイルにコンパイルする方法と、ネイティブ実行可能ファイルを設定してテストする方法を説明します。

Red Hat build of Quarkus ドキュメントへのフィードバックの提供

エラーを報告したり、ドキュメントを改善したりするには、Red Hat Jira アカウントにログインし、課題を送信してください。Red Hat Jira アカウントをお持ちでない場合は、アカウントを作成するように求められます。

手順

次のリンクをクリックして チケットを作成します。
Summary に課題の簡単な説明を入力します。
Description に課題や機能拡張の詳細な説明を入力します。問題があるドキュメントのセクションへの URL も記載してください。
Submit をクリックすると、課題が作成され、適切なドキュメントチームに転送されます。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージをご覧ください。

第1章 Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルする

アプリケーション開発者は、Red Hat build of Quarkus 3.15 を使用して、OpenShift Container Platform 環境およびサーバーレス環境で実行される、Java で書かれたマイクロサービスを作成できます。Quarkus アプリケーションは、通常の Java アプリケーションとして (Java 仮想マシン (JVM) 上で) 実行することも、ネイティブ実行可能ファイルにコンパイルすることもできます。ネイティブ実行可能ファイルにコンパイルされたアプリケーションは、対応する Java アプリケーションよりもメモリーフットプリントが小さく、短時間で起動します。

このガイドでは、Red Hat build of Quarkus 3.15 Getting Started プロジェクトをネイティブ実行可能ファイルにコンパイルする方法と、ネイティブ実行可能ファイルを設定してテストする方法を説明します。Red Hat build of Quarkus スタートガイドで作成したアプリケーションが必要になります。

Red Hat build of Quarkus を使用したネイティブ実行可能ファイルのビルドでは、以下を説明します。

Podman または Docker などのコンテナーランタイムを使用して、シングルコマンドでネイティブ実行可能ファイルをビルドする
生成されたネイティブ実行可能ファイルを使用して、カスタムコンテナーイメージを作成する
OpenShift Container Platform Docker ビルドストラテジーを使用して、コンテナーイメージを作成する
Quarkus ネイティブアプリケーションを OpenShift Container Platform にデプロイする
ネイティブ実行可能ファイルを設定する
ネイティブ実行可能ファイルをテストする

前提条件

JAVA_HOME 環境変数を設定して Java SDK の場所を指定している。
- Red Hat build of OpenJDK は、Red Hat カスタマーポータルにログインしてソフトウェアダウンロードページからダウンロードできます。
Open Container Initiative (OCI) と互換性のあるコンテナーランタイム (Podman、Docker など)。
Quarkus Getting Started プロジェクトを完了している。
- Quarkus Getting Started プロジェクトのビルド方法は、Red Hat build of Quarkus のスタートガイドを参照してください。
- もしくは、Quarkus Quickstarts アーカイブをダウンロードするか、Quarkus Quickstarts Git リポジトリーを複製します。プロジェクトのサンプルは getting-started ディレクトリーにあります。

1.1. ネイティブ実行可能ファイルの作成

ネイティブバイナリーは、特定のオペレーティングシステムおよび CPU アーキテクチャー上で実行するために作成された実行可能ファイルです。

以下は、ネイティブ実行可能ファイルの例をいくつか示しています。

Linux AMD 64 ビット用の ELF バイナリー
Windows AMD 64 ビット用の EXE バイナリー
ARM 64 ビット用の ELF バイナリー

注記

Red Hat build of Quarkus では、Linux x86-64 または AArch64 ビット用の ELF バイナリーのみがサポートされています。

ネイティブ実行可能ファイルを構築する利点の 1 つは、Java 仮想マシン (JVM) を含むアプリケーションと依存関係が 1 つのファイルにパッケージ化されることです。アプリケーションのネイティブ実行可能ファイルには、次の項目が含まれています。

コンパイルされたアプリケーションコード
必要な Java ライブラリー
アプリケーションの起動時間を短縮し、ディスクとメモリーのフットプリントを最小限に抑えるための仮想マシン (VM) の縮小バージョン。これは、アプリケーションコードとその依存関係に合わせて調整されています。

Quarkus アプリケーションからネイティブ実行可能ファイルを生成する場合は、コンテナ内ビルドまたはローカルホストビルドのいずれかを選択できます。次の表は、使用可能なビルドオプションとその説明を示しています。

表1.1 ネイティブ実行可能ファイルの生成に使用できるビルドオプション
ビルドオプション	必須	用途	結果	利点
コンテナ内ビルド - サポート対象	コンテナーランタイム (Podman や Docker など)	デフォルトの `registry.access.redhat.com/quarkus/mandrel-for-jdk-21-rhel8:23.1` ビルダーイメージ	ホストの CPU アーキテクチャーを使用する Linux 64 ビット実行可能ファイル	GraalVM はローカルで設定する必要がないため、CI パイプラインの実行効率が向上します。
ローカルホストビルド - アップストリームでのみサポート対象	GraalVM または Mandrel のローカルインストール	`quarkus.native.builder-image` プロパティーのデフォルトのローカルインストール	ビルドが実行されるマシンと同じオペレーティングシステムおよび CPU アーキテクチャーを持つ実行可能ファイル	Docker や Podman などのツールを使用できない、または使用しない開発者向けの代替手段。総じて、コンテナ内ビルドアプローチよりも高速です。

重要

Red Hat build of Quarkus 3.15 は、GraalVM Mandrel の製品化されたディストリビューションである Java 21 ベースの Red Hat build of Quarkus Native Builder イメージ (quarkus/mandrel-for-jdk-21-rhel8) を使用したネイティブ Linux 実行可能ファイルのビルドのみをサポートします。Quarkus コミュニティーでは他のイメージも利用できますが、それらは製品ではサポートされていないため、Red Hat によるサポートが必要な実稼働ビルドには使用しないでください。
ソースが 17 に基づいて記述され、Java 18 - 21 の機能が使用されていないアプリケーションでも、Java 21 ベースの Mandrel 23.1 ベースイメージを使用して、そのアプリケーションのネイティブ実行可能ファイルをコンパイルできます。
Red Hat build of Quarkus は、Oracle GraalVM Community Edition (CE)、Mandrel コミュニティーエディション、またはその他の GraalVM ディストリビューションを使用したネイティブ実行可能ファイルのビルドをサポートしていません。詳細は、Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルするを参照してください。

1.1.1. コンテナ内ビルドを使用してネイティブ実行可能ファイルを生成する

ネイティブ実行可能ファイルを作成し、ネイティブイメージテストを実行するには、コンテナ内ビルド用に Red Hat build of Quarkus が提供する native プロファイルを使用します。

前提条件

Podman または Docker がインストールされている。
コンテナーは、8 GB 以上のメモリーにアクセスできる。
オプション: Quarkus CLI がインストールされている。これは、ネイティブ実行可能ファイルをビルドする方法の 1 つとして使用できます。詳細は、Quarkus CLI のインストールを参照してください。

注記

Quarkus CLI は、Quarkus プロジェクトの作成、更新、ビルドなどのタスクを含む開発目的で使用されます。Red Hat は、実稼働環境での Quarkus CLI の使用をサポートしていません。

手順

Getting Started プロジェクトの pom.xml ファイルを開き、プロジェクトに native プロファイルが含まれていることを確認します。

<profiles>
  <profile>
    <id>native</id>
    <activation>
      <property>
        <name>native</name>
      </property>
    </activation>
    <properties>
      <skipITs>false</skipITs>
      <quarkus.package.type>native</quarkus.package.type>
    </properties>
  </profile>
</profiles>

次のいずれかの方法を使用して、ネイティブ実行可能ファイルをビルドします。
- Maven を使用:
  - Docker の場合:
    ./mvnw package -Dnative -Dquarkus.native.container-build=true
  - Podman の場合:
    ./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
- Quarkus CLI を使用:
  - Docker の場合:
    quarkus build --native -Dquarkus.native.container-build=true
  - Podman の場合:
    quarkus build --native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
    手順を実行した結果
    これらのコマンドを実行すると、target ディレクトリーに *-runner バイナリーが作成されます。その場合は、以下が適用されます。
  - *-runner ファイルは、Quarkus が生成するビルドされたネイティブバイナリーです。
  - target ディレクトリーは、Maven アプリケーションをビルドするときに Maven が作成するディレクトリーです。
    重要
    Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析および最適化の際にメモリーを大量に消費します。quarkus.native.native-image-xmx 設定プロパティーを設定して、ネイティブコンパイル時に使用されるメモリーの量を制限できます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。
ネイティブ実行可能ファイルを実行するには、以下のコマンドを入力します。
```
./target/*-runner
```

関連情報

ネイティブ実行可能ファイルの設定プロパティー

1.1.2. ローカルホストビルドを使用してネイティブ実行可能ファイルを生成する

Docker または Podman を使用しない場合は、ネイティブ実行可能ファイルの作成と実行に Quarkus ローカルホストビルドオプションを使用します。

ローカルホストビルドアプローチを使用すると、コンテナーを使用した場合と比べて高速になるため、Linux オペレーティングシステムを使用するマシンに適しています。

重要

Red Hat build of Quarkus では、本番環境での次の手順の使用はサポートされていません。この方法は、テストで、もしくは Docker や Podman が使用できない場合のバックアップアプローチとしてのみ使用してください。

前提条件

Quarkus の Building a native executable ガイドに従って正しく設定された、Mandrel または GraalVm のローカルインストール。
- GraalVM インストールの場合は、native-image もインストールされている必要があります。
オプション: Quarkus CLI がインストールされている。これは、ネイティブ実行可能ファイルをビルドする方法の 1 つとして使用できます。詳細は、Quarkus CLI のインストールを参照してください。

注記

手順

GraalVM または Mandrel の場合は、次のいずれかの方法を使用してネイティブ実行可能ファイルをビルドします。
- Maven を使用:
```
./mvnw package -Dnative
```
- Quarkus CLI を使用:
```
quarkus build --native
```
  手順を実行した結果
  これらのコマンドを実行すると、target ディレクトリーに *-runner バイナリーが作成されます。その場合は、以下が適用されます。
  - *-runner ファイルは、Quarkus が生成するビルドされたネイティブバイナリーです。
  - target ディレクトリーは、Maven アプリケーションをビルドするときに Maven が作成するディレクトリーです。
    注記
    ネイティブ実行可能ファイルをビルドすると、quarkus.profile プロパティーで変更されない限り、prod プロファイルが有効になります。
ネイティブ実行可能ファイルを実行します。
```
./target/*-runner
```

関連情報

詳細は、Quarkus の「ネイティブ実行可能ファイルの構築」ガイドのネイティブ実行可能ファイルの作成セクションを参照してください。

1.2. カスタムコンテナーイメージの作成

以下のいずれかの方法を使用して、Quarkus アプリケーションからコンテナーイメージを作成できます。

手動によるコンテナーの作成
OpenShift Container Platform Docker ビルドを使用してコンテナーを作成

重要

Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析と最適化中に大量のメモリーが消費されます。quarkus.native.native-image-xmx 設定プロパティーを設定して、ネイティブコンパイル時に使用されるメモリーの量を制限できます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。

1.2.1. 手動によるコンテナーの作成

Linux AMD64 用のアプリケーションを使用して、コンテナーイメージを手動で作成できます。Quarkus ネイティブコンテナーを使用してネイティブイメージを生成すると、そのネイティブイメージは Linux AMD64 をターゲットとする実行可能ファイルを作成します。ホストオペレーティングシステムが Linux AMD64 ではない場合は、バイナリーを直接実行できず、手動でコンテナーを作成する必要があります。

Quarkus Getting Started プロジェクトには、以下の内容と共に src/main/docker ディレクトリーに Dockerfile.native が含まれます。

FROM registry.access.redhat.com/ubi8/ubi-minimal:8.10
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application

EXPOSE 8080
USER 1001

ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

注記

Universal Base Image (UBI)

次のリストは、Dockerfile での使用に適したイメージを示しています。

Red Hat Universal Base Image 8 (UBI8)。このベースイメージは、コンテナー化されたすべてのアプリケーション、ミドルウェア、ユーティリティーのベースレイヤーになるように設計されています。
```
registry.access.redhat.com/ubi8/ubi:8.10
```
Red Hat Universal Base Image 8 Minimal (UBI8-minimal)。microdnf をパッケージマネージャーとして使用する、最小化された UBI8 イメージ。
```
registry.access.redhat.com/ubi8/ubi-minimal:8.10
```
すべての Red Hat Base イメージは、コンテナーイメージカタログサイトで入手できます。

手順

次のいずれかの方法を使用して、ネイティブ Linux 実行可能ファイルをビルドします。

Docker:

./mvnw package -Dnative -Dquarkus.native.container-build=true

Podman:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

次のいずれかの方法を使用して、コンテナーイメージをビルドします。

Docker:

docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

Podman

podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

次のいずれかの方法を使用して、コンテナーを実行します。

Docker:

docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

Podman:

podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

1.2.2. OpenShift Docker ビルドを使用してコンテナーを作成する

OpenShift Container Platform Docker ビルドストラテジーを使用して、Quarkus アプリケーションのコンテナーイメージを作成できます。このストラテジーは、クラスター内のビルド設定を使用してコンテナーイメージを作成します。

前提条件

OpenShift Container Platform クラスターとインストールされている oc ツールの最新バージョンにアクセスできる。oc のインストールについては、CLI ツールガイドの OpenShift CLI のインストール を参照してください。
OpenShift Container Platform API エンドポイントの URL。

手順

OpenShift CLI にログインします。
```
oc login -u <username_url>
```
OpenShift に新規プロジェクトを作成します。
```
oc new-project <project_name>
```

src/main/docker/Dockerfile.native ファイルに基づいてビルド設定を作成します。

cat src/main/docker/Dockerfile.native | oc new-build --name <build_name> --strategy=docker --dockerfile -

プロジェクトをビルドします。

oc start-build <build_name> --from-dir .

プロジェクトを OpenShift Container Platform にデプロイします。
```
oc new-app <build_name>
```
サービスを公開するには、以下を実行します。
```
oc expose svc/<build_name>
```

1.3. ネイティブ実行可能ファイルの設定プロパティー

設定プロパティーは、ネイティブ実行可能ファイルの生成方法を定義します。application.properties ファイルを使用して、Quarkus アプリケーションを設定できます。

設定プロパティー

以下の表は、ネイティブ実行可能ファイルの生成方法を定義するよう設定できる設定プロパティーのリストです。

プロパティー	説明	型	デフォルト
`quarkus.native.debug.enabled`	デバッグを有効にし、別の `.debug` ファイルにデバッグシンボルを生成します。`quarkus.native.container-build` と使用すると、Red Hat build of Quarkus は、ネイティブイメージからのデバッグ情報を分割する `objcopy` ユーティリティーをインストールする `binutils` パッケージを含む Red Hat Enterprise Linux または他の Linux ディストリビューションのみをサポートします。	boolean	`false`
`quarkus.native.resources.excludes`	ネイティブイメージに追加するべきではないリソースパスに一致する glob のコンマ区切りリスト。	文字列のリスト
`quarkus.native.additional-build-args`	ビルドプロセスにパスする追加の引数。	文字列のリスト
`quarkus.native.enable-http-url-handler`	HTTP URL ハンドラーを有効にします。これにより、HTTP URL に対して `URL.openConnection()` を実行できるようになります。	boolean	`true`
`quarkus.native.enable-https-url-handler`	HTTPS URL ハンドラーを有効にします。これにより、HTTPS URL に対して `URL.openConnection()` を実行できるようになります。	boolean	`false`
`quarkus.native.enable-all-security-services`	ネイティブイメージにすべてのセキュリティーサービスを追加します。	boolean	`false`
`quarkus.native.add-all-charsets`	ネイティブイメージにすべてのキャラクターセットを追加します。これにより、イメージサイズが大きくなります。	boolean	`false`
`quarkus.native.graalvm-home`	GraalVM ディストリビューションのパスが含まれます。	string	`${GRAALVM_HOME:}`
`quarkus.native.java-home`	JDK のパスが含まれます。	file	`${java.home}`
`quarkus.native.native-image-xmx`	ネイティブイメージを生成するために使用する Java の最大ヒープサイズ。	string
`quarkus.native.debug-build-process`	ネイティブイメージのビルドを実行する前に、デバッガーがビルドプロセスにアタッチするまで待機します。GraalVM インターナルの知識のあるユーザーにとって、これは高度なオプションになります。	boolean	`false`
`quarkus.native.publish-debug-build-process-port`	`debug-build-process` が `true` の場合は、docker でビルドする際にデバッグポートを公開します。	boolean	`true`
`quarkus.native.cleanup-server`	ネイティブイメージサーバーを再起動します。	boolean	`false`
`quarkus.native.enable-isolates`	メモリー管理を改善するために分離を有効にします。	boolean	`true`
`quarkus.native.enable-fallback-images`	ネイティブイメージが失敗した場合に、JVM ベースのフォールバックイメージを作成します。	boolean	`false`
`quarkus.native.enable-server`	ネイティブイメージサーバーを使用します。これによりコンパイルが高速化されますが、キャッシュ無効化の問題により変更が失われる可能性があります。	boolean	`false`
`quarkus.native.auto-service-loader-registration`	すべての `META-INF/services` エントリーを自動的に登録します。	boolean	`false`
`quarkus.native.dump-proxies`	検査用にすべてのプロキシーのバイトコードをダンプします。	boolean	`false`
`quarkus.native.container-build`	コンテナーランタイムを使用するビルド。デフォルトで Docker が使用されます。	boolean	`false`
`quarkus.native.builder-image`	イメージをビルドするための Docker イメージ。	string	`registry.access.redhat.com/quarkus/mandrel-for-jdk-21-rhel8:23.1`
`quarkus.native.container-runtime`	イメージのビルドに使用されるコンテナーランタイム。たとえば、Docker などがあります。	string
`quarkus.native.container-runtime-options`	コンテナーランタイムにパスするオプション。	文字列のリスト
`quarkus.native.enable-vm-inspection`	イメージの VM イントロスペクションを有効化します。	boolean	`false`
`quarkus.native.full-stack-traces`	イメージのフルスタックトレースを有効化します。	boolean	`true`
`quarkus.native.enable-reports`	呼び出しパスと、含まれるパッケージ、クラス、メソッドのレポートを生成します。	boolean	`false`
`quarkus.native.report-exception-stack-traces`	フルスタックトレースを使用して例外を報告します。	boolean	`true`
`quarkus.native.report-errors-at-runtime`	ランタイム時にエラーを報告します。これにより、サポートされていない機能を使用すると、ランタイムでアプリケーションが失敗する可能性があります。	boolean	`false`
`quarkus.native.resources.includes`	ネイティブイメージに追加する必要のあるリソースパスに一致する glob のコンマ区切りリスト。すべてのプラットフォームで、パス区切り文字としてスラッシュ (`/`) 文字を使用します。glob の開始文字をスラッシュにしてはいけません。たとえば、ソースツリーに `src/main/resources/ignored.png` と `src/main/resources/foo/selected.png` があり、依存関係 JAR の 1 つに `bar/some.txt` ファイルが含まれ、`quarkus.native.resources.includes` が `foo/,bar//*.txt` に設定されていると、`src/main/resources/foo/selected.png` ファイルと `bar/some.txt` ファイルがネイティブイメージに含まれますが、`src/main/resources/ignored.png` は含まれません。詳細は、サポートされている glob 機能をリストした次の表を参照してください。	文字列のリスト

ビルド設定中に、プロジェクト内で共通のパターンまたは場所を共有する一連のファイルまたはリソースを含める場合は、glob パターンを使用できます。

たとえば、複数の設定ファイルを含むディレクトリーがある場合は、glob パターンを使用してそのディレクトリー内のすべてのファイルを含めることができます。

以下に例を示します。

quarkus.native.resources.includes = my/config/files/*

次の例は、ネイティブイメージに追加するリソースパスに一致する glob のコンマ区切りリストを示しています。これらのパターンにより、クラスパスで見つかったすべての .png イメージがネイティブイメージに追加されるほか、サブディレクトリーの下にネストされている場合でも、フォルダーバーの下の .txt で終わるすべてのファイルが追加されます。

 quarkus.native.resources.includes = **/*.png,bar/**/*.txt

サポートされている glob 機能

次の表は、サポートされる glob 機能とその説明をリスト化したものです。

文字	機能の説明
`*`	スラッシュ (`/`) を含まない、空の可能性もある文字列を照合します。
`**`	スラッシュ (`/`) を含むかもしれない、空の可能性もある文字列を照合します。
`?`	1 つの文字と一致しますが、スラッシュとは一致しません。
`[abc]`	括弧内に指定された 1 文字を照合しますが、スラッシュは照合しません。
`[a-z]`	ブラケットで指定した範囲の文字の 1 つと一致しますが、スラッシュとは一致しません。
`[!abc]`	ブラケットで指定していない文字の 1 つと一致しますが、スラッシュとは一致しません。
`[!a-z]`	ブラケットで指定した範囲外の文字の 1 つと一致しますが、スラッシュとは一致しません。
`{one,two,three}`	コンマで区切られた代替のトークンを照合します。トークンには、ワイルドカード、ネストされた論理和指定子、範囲が含まれます。
`\`	エスケープ文字。エスケープには、`application.properties` パーサー、MicroProfile Config リストコンバーター、および Glob パーサーの 3 つのレベルがあります。3 つのレベルはすべて、バックスラッシュをエスケープ文字として使用します。

関連情報

Red Hat build of Quarkus アプリケーションの設定

1.3.1. Red Hat build of Quarkus ネイティブコンピレーションのメモリー消費を設定する

手順

以下のいずれかの方法を使用して quarkus.native.native-image-xmx プロパティーに値を設定し、ネイティブイメージのビルドタイム中のメモリー消費を制限します。
- application.properties ファイルを使用します。
```
quarkus.native.native-image-xmx=<maximum_memory>
```
- システムプロパティーの設定
```
mvn package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.native-image-xmx=<maximum_memory>
```
  このコマンドは、Docker を使用してネイティブ実行可能ファイルをビルドします。Podman を使用するには、-Dquarkus.native.container-runtime=podman 引数を追加します。

注記

たとえば、メモリー制限を 8 GB に設定するには、quarkus.native.native-image-xmx=8g を入力します。値は、2MB より大きい 1024 の倍数にする必要があります。メガバイトを示す m または M、ギガバイトを示す g または G の文字を追加します。

1.4. ネイティブ実行可能ファイルをテストする

ネイティブ実行可能ファイルの機能をテストするには、ネイティブモードでアプリケーションをテストします。@QuarkusIntegrationTest アノテーションを使用してネイティブ実行可能ファイルをビルドし、HTTP エンドポイントに対してテストを実行します。

重要

次の例は、GraalVM または Mandrel のローカルインストールを使用してネイティブ実行可能ファイルをテストする方法を示しています。テストを実行する前に、次の点を考慮してください。

ネイティブ実行可能ファイルの作成で説明されているように、Red Hat build of Quarkus はこのシナリオをサポートしていません。
ここでテストするネイティブ実行可能ファイルは、ホストのオペレーティングシステムとアーキテクチャーに一致する必要があります。したがって、ネイティブバイナリーが macOS 上のコンテナー内にビルドされている場合、この手順は使用できません。

手順

pom.xml ファイルを開き、build セクションに次の要素が含まれていることを確認します。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>${surefire-plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
            <configuration>
                <systemPropertyVariables>
                    <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                    <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                    <maven.home>${maven.home}</maven.home>
                </systemPropertyVariables>
            </configuration>
        </execution>
    </executions>
</plugin>

Maven Failsafe プラグイン (maven-failsafe-plugin) は結合テストを実行し、生成されたネイティブ実行可能ファイルの場所を示します。

src/test/java/org/acme/GreetingResourceIT.java ファイルを開き、次のコンテンツが含まれていることを確認します。
```
package org.acme;

import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest 1
public class GreetingResourceIT extends GreetingResourceTest { 2

    // Execute the same tests but in native mode.
}
```
1
テストの前に、ネイティブファイルからアプリケーションを開始する別のテストランナーを使用します。実行可能ファイルは、Maven Failsafe プラグインで設定された native.image.path システムプロパティーを使用して取得されます。
2
この例は、GreetingResourceTest を拡張しますが、新しいテストを作成することも可能です。

テストを実行します。

./mvnw verify -Dnative

以下の例は、このコマンドの出力を示しています。

./mvnw verify -Dnative
....

GraalVM Native Image: Generating 'getting-started-1.0.0-SNAPSHOT-runner' (executable)...
========================================================================================================================
[1/8] Initializing...                                                                                    (6.6s @ 0.22GB)
 Java version: 21.0.4+7-LTS, vendor version: Mandrel-23.1.4.0-1b1
 Graal compiler: optimization level: 2, target machine: x86-64-v3
 C compiler: gcc (redhat, x86_64, 13.2.1)
 Garbage collector: Serial GC (max heap size: 80% of RAM)
 2 user-specific feature(s)
 - io.quarkus.runner.Feature: Auto-generated class by Red&#160;Hat build of Quarkus from the existing extensions
 - io.quarkus.runtime.graal.DisableLoggingFeature: Disables INFO logging during the analysis phase
[2/8] Performing analysis...  [******]                                                                  (40.0s @ 2.05GB)
  10,318 (86.40%) of 11,942 types reachable
  15,064 (57.36%) of 26,260 fields reachable
  52,128 (55.75%) of 93,501 methods reachable
   3,298 types,   109 fields, and 2,698 methods registered for reflection
      63 types,    68 fields, and    55 methods registered for JNI access
       4 native libraries: dl, pthread, rt, z
[3/8] Building universe...                                                                               (5.9s @ 1.31GB)
[4/8] Parsing methods...      [**]                                                                       (3.7s @ 2.08GB)
[5/8] Inlining methods...     [***]                                                                      (2.0s @ 1.92GB)
[6/8] Compiling methods...    [******]                                                                  (34.4s @ 3.25GB)
[7/8] Layouting methods...    [**]                                                                       (4.1s @ 1.78GB)
[8/8] Creating image...       [**]                                                                       (4.5s @ 2.31GB)
  20.93MB (48.43%) for code area:    33,233 compilation units
  21.95MB (50.80%) for image heap:  285,664 objects and 8 resources
 337.06kB ( 0.76%) for other data
  43.20MB in total

....


[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:integration-test (default) @ getting-started ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.GreetingResourceIT
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2024-09-27 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Quarkus 3.15.3.SP1-redhat-00002) started in 0.038s. Listening on: http://0.0.0.0:8081
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.696 s - in org.acme.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:verify (default) @ getting-started ---

注記

Quarkus は、ネイティブイメージが起動するのを 60 秒間待機してから、自動的にネイティブテストに失敗します。この期間は、quarkus.test.wait-time システムプロパティーを設定することで変更できます。

以下のコマンドを使用して、待機時間を延長できます。この場合の <duration> は待機時間 (秒単位) です。

./mvnw verify -Dnative -Dquarkus.test.wait-time=<duration>

注記

デフォルトでは、quarkus.test.native-image-profile プロパティーで変更されていない限り、ネイティブテストは prod プロファイルを使用して実行されます。

1.4.1. ネイティブ実行可能ファイルとして実行する場合のテストを除外する

ネイティブ実行可能ファイルに対してテストを実行する場合、たとえばアプリケーションの HTTP エンドポイントと対話するなどの、ブラックボックステストのみを実行できます。

注記

ブラックボックス とは、ブラックボックステストなど、製品またはプログラムの隠された内部動作を指します。

テストはネイティブでは実行されないため、Java 仮想マシン (JVM) でテストを実行する場合のようにアプリケーションのコードにリンクすることはできません。したがって、ネイティブテストでは Bean を注入できません。

JVM とネイティブ実行の間でテストクラスを共有し、@DisabledOnIntegrationTest アノテーションを使用して特定のテストを除外して、その JVM 上でのみテストを実行できます。

1.4.2. 既存のネイティブ実行可能ファイルのテスト

Failsafe Maven プラグインを使用すると、既存の実行可能ビルドに対してテストを実行できます。ビルド後に、バイナリーで複数のテストセットを段階的に実行できます。

注記

Quarkus で生成したネイティブ実行可能ファイルをテストするには、利用可能な Maven コマンドを使用します。コマンドラインを使用してこのタスクを完了できる同等の Quarkus CLI コマンドはありません。

手順

ビルド済みのネイティブ実行可能ファイルに対してテストを実行します。
```
./mvnw test-compile failsafe:integration-test -Dnative
```
このコマンドは、Failsafe Maven プラグインを使用して、既存のネイティブイメージに対してテストを実行します。
あるいは、以下のコマンドを使用してネイティブ実行可能ファイルへのパスを指定することもできます。<path> は、ネイティブイメージパスになります。
```
./mvnw test-compile failsafe:integration-test -Dnative.image.path=<path>
```

1.5. 関連情報

改訂日時: 2025-03-24

法律上の通知

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルする

Red Hat build of Quarkus ドキュメントへのフィードバックの提供

多様性を受け入れるオープンソースの強化

第1章 Red Hat build of Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルする

1.1. ネイティブ実行可能ファイルの作成

1.1.1. コンテナ内ビルドを使用してネイティブ実行可能ファイルを生成する

1.1.2. ローカルホストビルドを使用してネイティブ実行可能ファイルを生成する

1.2. カスタムコンテナーイメージの作成

1.2.1. 手動によるコンテナーの作成

1.2.2. OpenShift Docker ビルドを使用してコンテナーを作成する

1.3. ネイティブ実行可能ファイルの設定プロパティー

1.3.1. Red Hat build of Quarkus ネイティブコンピレーションのメモリー消費を設定する

1.4. ネイティブ実行可能ファイルをテストする

1.4.1. ネイティブ実行可能ファイルとして実行する場合のテストを除外する

1.4.2. 既存のネイティブ実行可能ファイルのテスト

1.5. 関連情報

法律上の通知

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links