The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

QuarkusとMaven

Mavenを使用して、新しいプロジェクトを作成し、エクステンションを追加または削除し、開発モードを起動し、アプリケーションをデバッグし、アプリケーションをjar、ネイティブ実行可能ファイル、またはコンテナに適した実行可能ファイルにビルドします。Mavenプロジェクトのメタデータを使用して、お気に入りのIDEにプロジェクトをインポートします。

新規プロジェクトの作成

次のように新しいMavenプロジェクトの枠組を生成することができます。

コマンドラインインタフェース
quarkus create app my-groupId:my-artifactId

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.9.4:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=my-artifactId"

CLIを使用している場合、次のように利用可能なオプションのリストを取得することが可能です。

quarkus create app --help

Maven コマンドを使用している場合、次の表が create コマンドに渡すことができる属性の一覧です。

属性 デフォルト値 Description

projectGroupId

org.acme.sample

作成されたプロジェクトのグループID

projectArtifactId

mandatory

作成されたプロジェクトのアーティファクトID。これを渡さないと、インタラクティブモードがトリガされます。

projectVersion

1.0.0-SNAPSHOT

作成されたプロジェクトのバージョン

platformGroupId

io.quarkus.platform

ターゲットプラットフォームのグループID

platformArtifactId

quarkus-bom

ターゲットプラットフォームBOMのアーティファクトID

platformVersion

Quarkus Extension Registry が現在推奨しているバージョン

プロジェクトで使用したいプラットフォームのバージョンを指定します。バージョンの範囲を指定することもでき、その場合は指定した範囲の最新のものが使用されます。

javaVersion

17

プロジェクトで使用したいJavaのバージョン

className

省略された場合は作成されない

生成されたリソースの完全修飾名

path

/hello

リソースパス、 className が設定されている場合のみ関連します。

extensions

[]

プロジェクトに追加するエクステンションのリスト (カンマ区切り)

quarkusRegistryClient

true

Quarkus がオンラインレジストリーを使用して拡張カタログを解決するかどうか。これが false に設定されている場合、拡張カタログは、定義された (またはデフォルトの) プラットフォーム BOM に絞り込まれます。

デフォルトでは、コマンドは io.quarkus.platform:quarkus-bom:3.9.4 のプラットフォーム・リリースをターゲットにします(希望するプラットフォーム・リリースの座標が指定されていない場合)。

プロジェクトは、渡された artifactId にちなんだ名前のディレクトリーに生成されます。ディレクトリーが既に存在する場合は、生成に失敗します。

ネイティブモードと jvm モード用の Dockerfile も src/main/docker に生成されています。イメージのビルドとコンテナーの実行の指示は、これらの Dockerfile に書かれています。

エクステンションへの対応

Quarkusプロジェクトの内部から、利用可能なエクステンションのリストを取得することができます。

コマンドラインインタフェース
quarkus extension
Maven
./mvnw quarkus:list-extensions

以下を使ってエクステンションを追加できます。

コマンドラインインタフェース
quarkus extension add hibernate-validator
Maven
./mvnw quarkus:add-extension -Dextensions='hibernate-validator'

エクステンションは、カンマ区切りのリストを使用して渡されます。

エクステンション名は、エクステンションのGAV名です。例えば、 io.quarkus:quarkus-agroal です。ただし、部分名を渡すこともでき、Quarkusは正しいエクステンションを見つけるために最善を尽くします。例えば、 agroalAgroalagro は、 io.quarkus:quarkus-agroal に展開されます。エクステンションが見つからない場合、または複数のエクステンションが一致する場合は、コマンド結果に赤いチェックマーク❌が表示されます。

$ ./mvnw quarkus:add-extensions -Dextensions=jdbc,agroal,non-exist-ent
[...]
❌ Multiple extensions matching 'jdbc'
     * io.quarkus:quarkus-jdbc-h2
     * io.quarkus:quarkus-jdbc-mariadb
     * io.quarkus:quarkus-jdbc-postgresql
     Be more specific e.g using the exact name or the full gav.
✅ Adding extension io.quarkus:quarkus-agroal
❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
[...]

グロブパターンに一致するすべてのエクステンションをインストールすることができます。

コマンドラインインタフェース
quarkus extension add smallrye-*
Maven
./mvnw quarkus:add-extension -Dextensions='smallrye-*'

javac オプションの設定

Maven プラグインは javac を使用し、デフォルトでは maven-compiler-plugin から javac に渡すコンパイラフラグをピックアップします。

開発モード のように、プラグインが使用するコンパイラフラグをカスタマイズする必要がある場合は、 plugin ブロックに configuration セクションを追加し、 maven-compiler-plugin を設定するときと同じように compilerArgs プロパティを設定します。 source , target , jvmArgs を設定することもできます。 たとえば、 --enable-preview を JVM と javac の両方に渡す場合、次のように行います:

<plugin>
  <groupId>${quarkus.platform.group-id}</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.platform.version}</version>

  <configuration>
    <source>${maven.compiler.source}</source>
    <target>${maven.compiler.target}</target>
    <compilerArgs>
      <arg>--enable-preview</arg>
    </compilerArgs>
    <jvmArgs>--enable-preview</jvmArgs>
  </configuration>

  ...
</plugin>

Quarkus Mavenプラグイン自体は、Mavenによって起動されたJVMで実行され、一部の(まれな)Quarkusエクステンションではビルド中にアプリケーションクラスをロードする必要があるため、Mavenを実行しているJVMに同じフラグを渡すことが必要になる場合があります。

そのために MAVEN_OPTS が使用できます:

コマンドラインインタフェース
MAVEN_OPTS='--enable-preview' quarkus build
Maven
MAVEN_OPTS='--enable-preview' ./mvnw install

または 、プロジェクトのルートにファイル .mvn/jvm.config を作成すれば、 MAVEN_OPTS を設定しなくても、そのファイルに記述したオプションが Maven に取り込まれます。

開発モード

Quarkusには開発モードが組み込まれています。以下でアプリケーションを実行します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev

その後、アプリケーションのソース、リソース、および設定を更新することができます。変更は実行中のアプリケーションに自動的に反映されます。変更がすぐに反映されるので、UIやデータベースにまたがった開発をするのに最適です。

Devモードでは、バックグラウンド・コンパイルによるホット・デプロイメントが可能です。つまり、Javaファイルやリソース・ファイルを変更してブラウザを更新すると、その変更が自動的に反映されます。これは、Javaファイルやリソースファイルを変更してブラウザを更新すると、その変更が自動的に反映されることを意味します。ブラウザを更新すると、ワークスペースのスキャンが行われ、変更が検出されると、Javaファイルがコンパイルされ、アプリケーションが再デプロイされ、再デプロイされたアプリケーションによってリクエストが処理されます。コンパイルやデプロイに問題があった場合は、エラーページでお知らせします。

CTRL+C を押して、アプリケーションを停止します。

デフォルトでは、 quarkus:dev はデバッグホストを localhost に設定します (セキュリティー上の理由から)。これを変更する必要がある場合、例えばすべてのホストでデバッグを有効にしたい場合は、 -DdebugHost オプションを次のように使用します。

コマンドラインインタフェース
quarkus dev -DdebugHost=0.0.0.0
Maven
./mvnw quarkus:dev -DdebugHost=0.0.0.0

リモート開発モード

開発モードをリモートで使用することができるので、コンテナー環境(OpenShiftなど)でQuarkusを実行して、ローカルファイルに加えられた変更をすぐに確認できるようにすることができます。

これにより、実際にアプリを実行するのと同じ環境で、同じサービスにアクセスしながら開発することができます。

本番環境では使用しないでください。開発環境でのみ使用してください。本番環境のアプリケーションを開発モードで実行してはいけません。

これを行うには、 mutable-jar 形式を使用して、ミュータブルアプリケーションをビルドする必要があります。 application.properties で以下のプロパティーを設定してください。

quarkus.package.type=mutable-jar (1)
quarkus.live-reload.password=changeit (2)
quarkus.live-reload.url=http://my.cluster.host.com:8080 (3)
1 これは、QuarkusにMutable-jar形式を使用するように指示します。ミュータブルアプリケーションには、Quarkusのデプロイメント時間の部分も含まれているため、より多くのディスクスペースを占有します。普通に実行した場合は、イミュータブルアプリケーションと同じ速度で起動し、同じメモリーを使用しますが、devモードで起動することもできます。
2 リモート側とローカル側の通信を安全に保つためのパスワードです。
3 アプリがdevモードで実行されるURL。これはローカル側でのみ必要なので、プロパティー ファイルから除外して、コマンド ラインでシステム プロパティーとして指定するとよいでしょう。

mutable-jar は、通常のQuarkus jarをビルドするのと同じ方法で発行することでビルドされます。つまり以下のように発行できます:

コマンドラインインタフェース
quarkus build
Maven
./mvnw install

リモートホストでQuarkusを起動する前に、環境変数 QUARKUS_LAUNCH_DEVMODE=true を設定します。ベアメタルを使用している場合は、 export QUARKUS_LAUNCH_DEVMODE=true コマンドで設定し、適切に java -jar …​ コマンドでアプリケーションを実行します。

アプリケーションをdocker経由で実行する場合は、 docker run コマンドに -e QUARKUS_LAUNCH_DEVMODE=true を追加してイメージを起動します。アプリケーションが起動すると、ログに次のような行が表示されるはずです: Profile dev activated. Live Coding activated .

リモート側にはMavenなどの開発ツールを入れる必要はありません。新しいQuarkusアプリケーションで生成される通常の fast-jar Dockerfileがあれば大丈夫です。ベアメタルのQuarkus runner jarを起動している場合は、通常のdevmodeを実行しようとしないでください。

ここで、 remote-dev コマンドを使用して、ローカルエージェントをリモートホストに接続する必要があります。

./mvnw quarkus:remote-dev -Dquarkus.live-reload.url=http://my-remote-host:8080

これで、ブラウザーを更新するたびに、ローカルで行った変更がリモートアプリですぐに表示されるようになります。これは、HTTP ベースのロングポーリングトランスポートを介して行われ、HTTP 呼び出しを介してローカルワークスペースとリモートアプリケーションを同期します。

HTTP 機能を使用したくない場合は、URL を指定せずに remote-dev コマンドを実行するだけです。このモードでは、コマンドはローカルアプリケーションを継続的に再構築するので、 odo や rsync のような外部ツールを使ってリモートアプリケーションに同期することができます。

全ての設定オプションは以下の通りです:

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

デフォルト

Whether Quarkus should enable its ability to not do a full restart when changes to classes are compatible with JVM instrumentation. If this is set to true, Quarkus will perform class redefinition when possible.

Environment variable: QUARKUS_LIVE_RELOAD_INSTRUMENTATION

Show more

boolean

false

The names of additional resource files to watch for changes, triggering a reload on change. Directories are not supported.

Environment variable: QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES

Show more

list of string

Password used to use to connect to the remote dev-mode application

Environment variable: QUARKUS_LIVE_RELOAD_PASSWORD

Show more

string

URL used to use to connect to the remote dev-mode application

Environment variable: QUARKUS_LIVE_RELOAD_URL

Show more

string

The amount of time to wait for a remote dev connect or reconnect

Environment variable: QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

Show more

Duration

30S

The amount of time to wait between attempts when connecting to the server side of remote dev

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_INTERVAL

Show more

Duration

2S

The maximum number of attempts when connecting to the server side of remote dev

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS

Show more

int

10

期間フォーマットについて

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます:

  • 数値の後に hms が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

リモート開発モードを使用する際には SSL を使用することを推奨しますが、たとえ暗号化されていない接続を使用していても、パスワードが直接ネットワーク上で送信されることはありません。最初の接続リクエストでは、パスワードは初期状態のデータでハッシュ化され、それ以降のリクエストでは、サーバーによって生成されたランダムなセッションIDと、POSTリクエストのためのボディコンテンツ、DELETEリクエストのためのパス、そしてリプレイ攻撃を防ぐためのインクリメントカウンタでハッシュ化されます。

デバッグ

開発モードでは、Quarkusはデフォルトでデバッグモードを有効にして起動し、JVMをサスペンドせずにポート 5005 をリッスンします。

この動作は、 debug システム・プロパティーに以下の値のいずれかを与えることで変更できます。

  • false - JVM はデバッグモードを無効にして起動します。

  • true - JVM はデバッグモードで起動され、5005 ポートをリッスンします。

  • client - JVM はクライアントモードで起動し、localhost:5005 に接続を試みます。

  • {port} - JVM はデバッグモードで開始され、{port} でリッスンします

追加のシステム・プロパティー suspend は、デバッグ・モードで起動されたときに JVM をサスペンドするために使用できます。suspend は以下の値をサポートしています。

  • y または true - デバッグモードの JVM 起動が中断されます。

  • n または false - デバッグモードの JVM をサスペンドせずに起動します。

また、JVM をサスペンドした状態で、デバッグモードで Quarkus アプリケーションを実行することもできます。

コマンドラインインタフェース
quarkus dev -Dsuspend -Ddebug
Maven
./mvnw quarkus:dev -Dsuspend -Ddebug

次に、デバッガーを localhost:5005 にアタッチします。

IDE でインポートする

プロジェクトが生成されたら 、お気に入りのIDEでインポートできます。 唯一の要件は、Mavenプロジェクトをインポートできることです。

Eclipse

Eclipse で、 File → Import をクリックします。ウィザードで、 Maven → Existing Maven Project を選択します。次の画面で、プロジェクトのルートの場所を選択します。次の画面では、見つかったモジュールのリストが表示されるので、生成されたプロジェクトを選択して Finish をクリックします。

別のターミナルで、以下を実行します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev

では、生産性の高い環境を楽しんで下さい。

IntelliJ IDEA

IntelliJ IDEA:

  1. IntelliJ IDEAの内部から File → New → Project From Existing Sources…​ を選択するか、ウェルカム・ダイアログからであれば、 Import project を選択してください。

  2. プロジェクトの root を選択します。

  3. Import project from external model および Maven を選択します。

  4. Next を数回クリックします (必要に応じてさまざまなオプションを確認してください)。

  5. 最後の画面で Finish をクリックします。

別のターミナルや組込ターミナルで、以下を実行します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev

楽しんでください!

Apache NetBeans

NetBeans:

  1. File → Open Project を選択

  2. プロジェクトの root を選択します。

  3. Open Project をクリックしてください。

別のターミナルまたは組込ターミナルで、プロジェクトのルートに移動して次を実行します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev

楽しんでください!

Visual Studio Code

VS Codeでプロジェクトディレクトリーを開きます。Java Extension Pack (Javaエクステンションのセットをグループ化したもの) をインストールしている場合、プロジェクトは Maven プロジェクトとしてロードされます。

Quarkus アプリケーションのビルドクラスパスのツリーのログ取得

通常、アプリケーション(Mavenプロジェクト)の依存関係は、 mvn dependency:tree コマンドを使用して表示することができます。しかし、Quarkusアプリケーションの場合、このコマンドはアプリケーションの実行時の依存関係のみを表示します。Quarkusのビルドプロセスは、アプリケーションで使用されているエクステンションのデプロイメント依存関係を元のアプリケーションのクラスパスに追加するので、どの依存関係とどのバージョンがビルドクラスパスで終わるかを知ることは便利です。幸いにも、 quarkus-bootstrap Mavenプラグインには、アプリケーションのビルド依存関係ツリーを表示する build-tree ゴールが含まれています。

プロジェクトで ./mvnw quarkus:dependency-tree を実行すると、次のような出力が得られるはずです。

[INFO] --- quarkus-maven-plugin:3.9.4:dependency-tree (default-cli) @ getting-started ---
[INFO] org.acme:getting-started:jar:1.0.0-SNAPSHOT
[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:3.9.4 (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:3.9.4 (compile)
[INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:3.9.4 (compile)
[INFO]    │  │  ├─ commons-beanutils:commons-beanutils:jar:1.9.3 (compile)
[INFO]    │  │  │  ├─ commons-logging:commons-logging:jar:1.2 (compile)
[INFO]    │  │  │  └─ commons-collections:commons-collections:jar:3.2.2 (compile)
...

ゴールは、以下のオプションのパラメーターを受け入れます。

  • mode - デフォルト値は prod で、本番ビルドの依存関係ツリーを表示します。または、値 test を受け入れてテスト依存関係ツリーを表示し、dev を受け入れて開発モードの依存関係ツリーを表示します。

  • outputFile - 依存関係ツリーを永続化するファイルを指定します。

  • appendOutput - デフォルト値は false で、コマンドへの出力を outputFile パラメーターで指定されたファイルに追加するか、上書きするかを示します。

オフライン開発とテスト向けの Maven アーティファクトの依存関係のダウンロード

Quarkus エクステンションの依存関係は、アプリケーションの実行時クラスパスに到達する実行時エクステンションの依存関係と、アプリケーションのビルド時にのみ Quarkus によって解決されてビルドクラスパスを作成するデプロイメント (またはビルド時) のエクステンションの依存関係に分けられます。アプリケーション開発者は、Quarkus エクステンションのランタイムアーティファクトにのみ依存関係を表現することが期待されています。結果として、デプロイメントエクステンションの依存関係は、Quarkus エクステンションの依存関係モデル (maven-dependency-plugingo-offline-maven-plugin など) を認識しない Maven プラグインには表示されません。つまり、これらのプラグインを使用してすべてのアプリケーションの依存関係を事前にダウンロードして、後でオフラインモードでアプリケーションをビルドおよびテストできるようにすることはできません。

Quarkus アプリケーションをオフラインでビルドおよびテストするユースケースを有効にするために、quarkus-maven-plugin には、以下のようにコマンドラインから呼び出すことができる go-offline ゴールが含まれています。

./mvnw quarkus:go-offline

このゴールは、アプリケーションの実行時、ビルド時、テスト、および開発モードのすべての依存関係を解決し、これらを設定されたローカルの Maven リポジトリーにダウンロードします。

ネイティブ実行可能ファイルの構築

ネイティブ実行可能ファイルにより、Quarkusアプリケーションはコンテナーやサーバーレスのワークロードに最適です。

GRAALVM_HOME が設定され、GraalVM for JDK 21の最新リリースを指しているようにして下さい。 Maven の設定 に示されているように、あなたの pom.xml が適切な native プロファイルを持っているようにして下さい。

次のようにネイティブ実行可能ファイルの作成

コマンドラインインタフェース
quarkus build --native
Maven
./mvnw install -Dnative

ネイティブ実行可能ファイルが target/ に存在します。

ネイティブの実行ファイルで統合テストを実行するには、適切な Maven プラグインが設定 されているようにし、 verify ゴールを起動します。

$ ./mvnw verify -Dnative
...
[quarkus-quickstart-runner:50955]     universe:     391.96 ms
[quarkus-quickstart-runner:50955]      (parse):     904.37 ms
[quarkus-quickstart-runner:50955]     (inline):   1,143.32 ms
[quarkus-quickstart-runner:50955]    (compile):   6,228.44 ms
[quarkus-quickstart-runner:50955]      compile:   9,130.58 ms
[quarkus-quickstart-runner:50955]        image:   2,101.42 ms
[quarkus-quickstart-runner:50955]        write:     803.18 ms
[quarkus-quickstart-runner:50955]      [total]:  33,520.15 ms
[INFO]
[INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.quickstart.GreetingResourceIT
Executing [/Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
2019-02-28 16:52:42,020 INFO  [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
2019-02-28 16:52:42,021 INFO  [io.quarkus] (main) Installed features: [cdi, rest]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

...

コンテナーフレンドリーな実行可能ファイルをビルドする

ネイティブ実行可能ファイルは、お使いのオペレーティングシステムに固有のものになります。コンテナー内で実行される実行ファイルを作成するには、次のようにします。

コマンドラインインタフェース
quarkus build --native -Dquarkus.native.container-build=true
Maven
./mvnw install -Dnative -Dquarkus.native.container-build=true

作成された実行ファイルは64bitのLinux実行ファイルとなりますので、OSによっては実行可能でなくなる可能性があります。しかし、今回はDockerコンテナにコピーするため問題ありません。なお、この場合、ビルド自体もDockerコンテナで実行されるため、ローカルにGraalVMがインストールされている必要はありません。

デフォルトでは、ネイティブ実行可能ファイルは quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 Dockerイメージを使用して生成されます。

異なるDockerイメージでネイティブ実行可能ファイルをビルドしたい場合(例えば、異なるGraalVMのバージョンを使用するなど)、 -Dquarkus.native.builder-image=<image name> のbuild引数を使用してください。

利用可能なDockerイメージのリストは quay.io にあります。Quarkusのバージョンが、利用可能な全てのイメージと互換性があるとは限りません。

Maven の設定

プロジェクトのスキャフォールドを使用していない場合は、以下の要素を pom.xml に追加してください

<properties>
    <skipITs>true</skipITs> (1)
</properties>

<dependencyManagement>
    <dependencies>
        <dependency> (2)
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin> (3)
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.platform.version}</version>
            <extensions>true</extensions> (4)
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                        <goal>generate-code</goal>
                        <goal>generate-code-tests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin> (5)
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <systemPropertyVariables>
                    <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                    <maven.home>${maven.home}</maven.home>
                </systemPropertyVariables>
            </configuration>
        </plugin>
        <plugin> (6)
            <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>
    </plugins>
</build>

<profiles>
    <profile> (7)
        <id>native</id>
        <properties> (8)
            <quarkus.package.type>native</quarkus.package.type>
            <skipITs>false</skipITs> (9)
        </properties>
    </profile>
</profiles>
1 すべてのビルドで統合テストの実行を無効にします (テスト名は *IT で、@QuarkusIntegrationTest のアノテーションが付けられています)。これらのテストを常に実行するには、このプロパティーを削除するか、値を false に設定するか、ビルドを実行するときにコマンドラインで -DskipITs=false を設定します。+ 後述するように、これは native プロファイルでオーバーライドされます。
2 オプションで、BOMファイルを使用して、異なるQuarkus依存関係のバージョンを省略することができます。
3 ビルドプロセスにフックするQuarkus Mavenプラグインを使用します。
4 Mavenプラグインのエクステンションを有効にすると、Quarkus MavenLifecycleParticipant が登録され、ビルド中に使用されるQuarkusクラスローダが適切にクローズされるようになります。 generate-codegenerate-code-tests のゴールでは、Quarkusアプリケーションブートストラップが初期化され、 build のゴール(本番アプリケーションを実際にビルドしてパッケージ化する)で再利用されます。 quarkus-maven-pluginbuild ゴールでは、Quarkus のクラスローダが適切にクローズされます。しかし、 generate-code または generate-code-testsbuild の間でビルドが失敗すると、Quarkus augmentation classloaderは適切に閉じられず、Windows OSのクラスパス上にたまたまあったJARファイルがロックされる可能性があります。
5 システムのプロパティーを maven-surefire-plugin に追加します。+ maven.home は、 ${maven.home}/conf/settings.xml にカスタム設定がある場合にのみ必要です。
6 ビルドによって生成されたアーティファクトを統合テストでテストする場合は、次のプラグイン設定を追加します。テスト名 *IT@QuarkusIntegrationTest のアノテーションが付けられたテストは、ビルドによって生成されたアーティファクト (JAR ファイル、コンテナーイメージなど) に対して実行されます。詳細については、xref:getting-started-testing.adoc#quarkus-integration-test 統合テストガイドを参照してください。+ maven.home は、${maven.home}/conf/settings.xml にカスタム設定がある場合にのみ必要です。
7 ネイティブ実行可能ファイルのビルドには、特定の native プロファイルを使用します。
8 native パッケージタイプを有効にします。そのため、ビルドはネイティブ実行可能ファイルを生成します。
9 ネイティブイメージをビルドする際には、常に統合テストを実行します(テスト名は *IT で、アノテーションは @QuarkusIntegrationTest )。+ ネイティブ・イメージのビルド時に統合テストを実行しない場合は、このプロパティを完全に削除するか、その値を true に設定してください。

fast-jar の使用

fast-jar は、デフォルトの quarkus パッケージタイプです。

ビルドの結果は、 quarkus-app という名前の target の下のディレクトリーです。

アプリケーションを実行するには、次のようにします: java -jar target/quarkus-app/quarkus-run.jar

生成された jar を正常に実行するためには、 quarkus-app ディレクトリのすべての内容が必要です。いずれかのファイルが欠落していると、アプリケーションが起動しなかったり、正しく機能しない可能性があります。
fast-jar パッケージングでは、どの依存関係のjarにクラスやリソースが含まれているかという情報がインデックス化されているため、レガシーのQuarkus jarよりも起動が少し速く、メモリ消費量もわずかに少ないアーティファクトを作成できます。このため、クラスやリソースをロードする際に、 レガシー jar が必要とするクラスパス上のすべての jar を検索する必要がなくなります。

Uber-Jar 作成

Quarkus Mavenプラグインは、 application.properties .Quarkus Mavenプラグインで quarkus.package.type=uber-jar 設定オプションを指定することで、UberJar の生成をサポートしています。

元の jar は target ディレクトリーに残っていますが、.original のサフィックスを含むように名前が変更されます。

Uber-jar をビルドする際に、 quarkus.package.ignored-entries 設定オプションを使用して生成された jar から除外したいエントリーを指定することができます。

デフォルトでは、Uber-Jar の作成は、アプリケーションの依存関係に存在する可能性のある 署名ファイルを除外します。

Uber-Jarの最終的な名前は、Mavenのビルド設定 finalName オプションで設定できます。

Uber-Jar のファイル名のサフィックス

デフォルトでは、quarkus.package.runner-suffix 設定オプションを使用してカスタムファイルを設定することによってオーバーライドされない限り、生成された uber JAR ファイル名には -runner 接尾辞が付きます。ランナーサフィックスが不要な場合は、quarkus.package.add-runner-suffix 設定オプションを false に設定することで無効にできます。この場合、uber JAR は、アプリケーションモジュールに対して maven-jar-plugin によって生成された元の JAR ファイルを置き換えます。

Uber-Jarファイルをメインプロジェクトのアーティファクトとして添付する

Uber-Jar ファイル名が元のプロジェクト JAR ファイル名に runner などのサフィックスを付加して作成される限り、Uber-Jar ファイル名のサフィックスは Uber-Jar アーティファクトの Maven アーティファクト分類子としても使用されます。Uber-Jar をメイン・プロジェクト・アーティファクトとして添付するには、2 つの方法があります (分類子なし):

  1. quarkus.package.add-runner-suffix=false をセットする。これは、ファイル名のサフィックスの追加を無効にし、ファイルシステム上のオリジナル・プロジェクトJARを置き換える;

  2. quarkus:build ゴールの attachRunnerAsMainArtifact パラメータを true に設定する。

マルチモジュールプロジェクトでの作業

デフォルトでは、Quarkusは別のモジュール内のCDI Bean を検出しません。

マルチモジュールプロジェクトのモジュールで CDI Bean 検出を有効にする最善の方法は、それが quarkus-maven-plugin で既に設定されているメインアプリケーションモジュールでない限り、jandex-maven-plugin を含めることです。自動的にインデックスされます。

<build>
  <plugins>
    <plugin>
      <groupId>io.smallrye</groupId>
      <artifactId>jandex-maven-plugin</artifactId>
      <version>3.1.6</version>
      <executions>
        <execution>
          <id>make-index</id>
          <goals>
            <goal>jandex</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

このトピックの詳細については、CDI ガイドの Bean 検出 セクションを参照してください。

Mavenテストプラグインの設定

maven-surefire-plugin および maven-failsafe-plugin の設定は、ほとんどのケースで機能します。しかし、追加の設定が必要になる場合もあります。

Quarkusでは、テストフェーズでアプリケーションの依存関係を再解決して、テスト用のクラスパスを設定する必要がある場合があるためです。 以前のビルドフェーズで使用された元のMavenリゾルバはテストプロセスでは使用できず、その結果、Quarkusは新しいリゾルバを初期化する必要があります。 新しいリゾルバが正しく初期化されるように、関連する設定オプションをテストプロセスに渡す必要があります。

Mavenユーザー設定

Maven ビルドプロセスが Maven ディストリビューションに含まれるデフォルトの mvn スクリプトを使用して起動されなかった場合など、Maven ユーザー設定ファイルへのパスをテストプロセスに渡す必要があります。 それは次の方法で行うことができます:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <systemPropertyVariables>
                    <!-- skip -->
                    <maven.settings>${session.request.userSettingsFile.absolutePath}</maven.settings>
                </systemPropertyVariables>
            </configuration>
        </plugin>

認証されたHTTPSによるリモートリポジトリアクセス

リモート Maven リポジトリが 認証された HTTPS アクセス設定 を必要とする場合、以下のプロパティの一部またはすべてをテストプラグインに渡す必要があります:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <systemPropertyVariables>
                    <!-- skip -->
                    <javax.net.ssl.keyStoreType>${javax.net.ssl.keyStoreType}</javax.net.ssl.keyStoreType>
                    <javax.net.ssl.keyStore>${javax.net.ssl.keyStore}</javax.net.ssl.keyStore>
                    <javax.net.ssl.keyStorePassword>${javax.net.ssl.keyStorePassword}</javax.net.ssl.keyStorePassword>
                    <javax.net.ssl.trustStore>${javax.net.ssl.trustStore}</javax.net.ssl.trustStore>
                    <javax.net.ssl.trustStorePassword>${javax.net.ssl.trustStorePassword}</javax.net.ssl.trustStorePassword>
                </systemPropertyVariables>
            </configuration>
        </plugin>

特定の設定プロファイルでビルド

Quarkusは、対象となる環境に応じて特定の設定を提供するために、 設定プロファイルをサポートしています。

以下のタイプのコマンドを持つシステムプロパティー quarkus.profile により、プロファイルは Maven ビルドのコマンドで直接提供できます。

コマンドラインインタフェース
quarkus build -Dquarkus.profile=profile-name-here
Maven
./mvnw install -Dquarkus.profile=profile-name-here

ただし、プロジェクトプロパティー、Quarkus Maven プラグイン設定プロパティー、または Quarkus Maven プラグイン設定で設定されたシステムプロパティーを使用して、プロジェクトの POM ファイルでプロファイルを直接指定することもできます。

優先順位の高い順 (優先順位が高い方が先):

1. Quarkus Maven プラグイン設定で設定されたシステムプロパティー
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <configuration>
          <systemProperties>
            <quarkus.profile>prod-aws</quarkus.profile> (1)
          </systemProperties>
        </configuration>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 このプロジェクトのデフォルトの設定プロファイルは prod-aws です。
2. Quarkus Maven プラグインの設定プロパティー
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <configuration>
          <properties>
            <quarkus.profile>prod-aws</quarkus.profile> (1)
          </properties>
        </configuration>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 このプロジェクトのデフォルトの設定プロファイルは prod-aws です。
3. プロジェクトプロパティ
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <properties>
    <quarkus.profile>prod-aws</quarkus.profile> (1)
    ...
  </properties>
...
</project>
1 このプロジェクトのデフォルトの設定プロファイルは prod-aws です。
どのアプローチを選択しても、プロファイルは quarkus.profile システムプロパティーまたは QUARKUS_PROFILE 環境変数で引き続きオーバーライドすることができます。

1つのモジュールから複数のアーティファクトの作成

いくつかの特定のユースケースでは、同じモジュールからアプリケーションのいくつかのアーティファクトをビルドすることが興味深い場合があります。典型的な例は、さまざまな設定プロファイルを使用してアプリケーションをビルドする場合です。

この場合、Quarkus Maven プラグイン設定に必要な数の実行を追加することができます。

以下は、同じアプリケーションの 2 つのビルド (1 つは prod-oracle プロファイルを使用し、もう 1 つは prod-postgresql プロファイルを使用) を生成する Quarkus Maven プラグイン設定の例です。

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          <execution>
            <id>oracle</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-oracle</quarkus.profile> (1)
                <quarkus.package.output-directory>oracle-quarkus-app</quarkus.package.output-directory> (2)
              </properties>
            </configuration>
          </execution>
          <execution>
            <id>postgresql</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-postgresql</quarkus.profile> (3)
                <quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory> (4)
              </properties>
            </configuration>
          </execution>
        </executions>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 プラグインの最初の実行のデフォルトの設定プロファイルは prod-oracle です。
2 プラグインの最初の実行の出力ディレクトリーは、専用ディレクトリーを持つために、quarkus-app ではなく oracle-quarkus-app に設定されます。
3 プラグインの 2 回目の実行のデフォルトの設定プロファイルは prod-postgresql です。
4 プラグインの 2 回目の実行の出力ディレクトリーは、専用ディレクトリーを持つために、quarkus-app ではなく postgresql-quarkus-app に設定されます。
上記の設定では、両方のプロファイルビルドが同じ依存関係を使用するため、アプリケーションに Oracle ドライバーと PostgreSQL ドライバーの依存関係を追加すると、両方のドライバーが両方のビルドに表示されることになります。

プロファイル固有の依存関係を他のプロファイルから分離するために、JDBC ドライバーをオプションの依存関係としてアプリケーションに追加できますが、それらを必要とする各プロファイルに含まれるように設定されます。以下に例を示します。

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>${postgresql.driver.version}</version>
      <optional>true</optional> (1)
    </dependency>
  </dependencies>
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          ...
          <execution>
            <id>postgresql</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-postgresql</quarkus.profile>
                <quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory>
                <quarkus.package.filter-optional-dependencies>true</quarkus.package.filter-optional-dependencies> (2)
                <quarkus.package.included-optional-dependencies>org.postgresql:postgresql::jar</quarkus.package.included-optional-dependencies> (3)
              </properties>
            </configuration>
          </execution>
        </executions>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 PostgreSQLのJDBCドライバは、オプションの依存関係として定義されています。
2 後方互換性の理由から、オプションの依存関係をフィルタリングする必要があることを明示的に示す必要があります。
3 PostgreSQLのJDBCドライバに対応するオプションの依存関係のみが、最終的な成果物として期待されます。
quarkus.package.included-optional-dependencies タグで宣言するオプションの依存関係が複数ある場合は、それらが , で区切られていることを確認してください (例: org.postgresql:postgresql::jar,com.foo: bar::jar)。

プロジェクト出力の設定

プロジェクトのビルドの出力を定義するための設定オプションがいくつかあります。これらは他の設定プロパティーと同じように application.properties で提供されています。

プロパティーは以下の通りです:

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

デフォルト

The requested output type.

The default built in types are 'jar' (which will use 'fast-jar'), 'legacy-jar' for the pre-1.12 default jar packaging, 'uber-jar', 'mutable-jar' (for remote development mode), 'native' and 'native-sources'.

Environment variable: QUARKUS_PACKAGE_TYPE

Show more

string

jar

Whether the created jar will be compressed. This setting is not used when building a native image

Environment variable: QUARKUS_PACKAGE_COMPRESS_JAR

Show more

boolean

false

If the Implementation information should be included in the runner jar’s MANIFEST.MF.

Environment variable: QUARKUS_PACKAGE_MANIFEST_ADD_IMPLEMENTATION_ENTRIES

Show more

boolean

true

The entry point of the application. This can either be a fully qualified name of a standard Java class with a main method, or io.quarkus.runtime.QuarkusApplication.

If your application has main classes annotated with io.quarkus.runtime.annotations.QuarkusMain then this can also reference the name given in the annotation, to avoid the need to specify fully qualified names in the config.

Environment variable: QUARKUS_PACKAGE_MAIN_CLASS

Show more

string

Files that should not be copied to the output artifact

Environment variable: QUARKUS_PACKAGE_USER_CONFIGURED_IGNORED_ENTRIES

Show more

list of string

List of all the dependencies that have been defined as optional to include into the final package of the application. Each optional dependency needs to be expressed in the following format:

groupId:artifactId:classifier:type

With the classifier and type being optional.

If the type is missing, the artifact is assumed to be of type jar.

This parameter is optional, if absent, no optional dependencies will be included into the final package of the application.

For backward compatibility reasons, this parameter is ignored by default and can be enabled by setting the parameter quarkus.package.filter-optional-dependencies to true.

This parameter is meant to be used in modules where multi-builds have been configured to avoid getting a final package with unused dependencies.

Environment variable: QUARKUS_PACKAGE_INCLUDED_OPTIONAL_DEPENDENCIES

Show more

list of string

Flag indicating whether the optional dependencies should be filtered out or not.

This parameter is meant to be used in modules where multi-builds have been configured to avoid getting a final package with unused dependencies.

Environment variable: QUARKUS_PACKAGE_FILTER_OPTIONAL_DEPENDENCIES

Show more

boolean

false

The suffix that is applied to the runner jar and native images

Environment variable: QUARKUS_PACKAGE_RUNNER_SUFFIX

Show more

string

-runner

Indicates whether the generated binary file (uber-jar or native image) should have the runner suffix appended. Turning off the runner suffix in case of the uber-jar package type, the original build system (Maven, Gradle, etc) built JAR will be replaced with the Quarkus built uber JAR.

Environment variable: QUARKUS_PACKAGE_ADD_RUNNER_SUFFIX

Show more

boolean

true

The output folder in which to place the output, this is resolved relative to the build systems target directory.

Environment variable: QUARKUS_PACKAGE_OUTPUT_DIRECTORY

Show more

string

The name of the final artifact

Environment variable: QUARKUS_PACKAGE_OUTPUT_NAME

Show more

string

Whether to automate the creation of AppCDS. This has no effect when a native binary is needed and will be ignored in that case. Furthermore, this option only works for Java 11+ and is considered experimental for the time being. Finally, care must be taken to use the same exact JVM version when building and running the application.

Environment variable: QUARKUS_PACKAGE_CREATE_APPCDS

Show more

boolean

false

When AppCDS generation is enabled, if this property is set, then the JVM used to generate the AppCDS file will be the JVM present in the container image. The builder image is expected to have the 'java' binary on its PATH. This flag is useful when the JVM to be used at runtime is not the same exact JVM version as the one used to build the jar. Note that this property is consulted only when quarkus.package.create-appcds=true and it requires having docker available during the build.

Environment variable: QUARKUS_PACKAGE_APPCDS_BUILDER_IMAGE

Show more

string

Whether creation of the AppCDS archive should run in a container if available.

Normally, if either a suitable container image to create the AppCDS archive inside of can be determined automatically or if one is explicitly set using the quarkus.package.appcds-builder-image setting, the AppCDS archive is generated by running the JDK contained in the image as a container.

If this option is set to false, a container will not be used to generate the AppCDS archive. Instead, the JDK used to build the application is also used to create the archive. Note that the exact same JDK version must be used to run the application in this case.

Ignored if quarkus.package.create-appcds is set to false.

Environment variable: QUARKUS_PACKAGE_APPCDS_USE_CONTAINER

Show more

boolean

true

This is an advanced option that only takes effect for the mutable-jar format.

If this is specified a directory of this name will be created in the jar distribution. Users can place jar files in this directory, and when re-augmentation is performed these will be processed and added to the class-path.

Note that before reaugmentation has been performed these jars will be ignored, and if they are updated the app should be reaugmented again.

Environment variable: QUARKUS_PACKAGE_USER_PROVIDERS_DIRECTORY

Show more

string

This option only applies when using fast-jar or mutable-jar. If this option is true then a list of all the coordinates of the artifacts that made up this image will be included in the quarkus-app directory. This list can be used by vulnerability scanners to determine if your application has any vulnerable dependencies.

Environment variable: QUARKUS_PACKAGE_INCLUDE_DEPENDENCY_LIST

Show more

boolean

true

An advanced option that will decompile generated and transformed bytecode into the 'decompiled' directory. This is only taken into account when fast-jar is used.

Environment variable: QUARKUS_PACKAGE_DECOMPILER_ENABLED

Show more

boolean

false

The directory into which to save the Vineflower tool if it doesn’t exist

Environment variable: QUARKUS_PACKAGE_DECOMPILER_JAR_DIRECTORY

Show more

string

${user.home}/.quarkus

If set to true, it will result in the Quarkus writing the transformed application bytecode to the build tool’s output directory. This is useful for post-build tools that need to scan the application bytecode - for example for offline code-coverage tools. For example, if using Maven, enabling this feature will result in the classes in target/classes being updated with the versions that result after Quarkus has applied its transformations. Setting this to true however, should be done with a lot of caution and only if subsequent builds are done in a clean environment (i.e. the build tool’s output directory has been completely cleaned).

Environment variable: QUARKUS_PACKAGE_WRITE_TRANSFORMED_BYTECODE_TO_BUILD_OUTPUT

Show more

boolean

false

Custom manifest attributes to be added to the main section of the MANIFEST.MF file. An example of the user defined property: quarkus.package.manifest.attributes."Entry-key1"=Value1 quarkus.package.manifest.attributes."Entry-key2"=Value2

Environment variable: QUARKUS_PACKAGE_MANIFEST_ATTRIBUTES

Show more

Map<String,String>

Custom manifest sections to be added to the MANIFEST.MF file. An example of the user defined property: quarkus.package.manifest.manifest-sections."Section-Name"."Entry-Key1"=Value1 quarkus.package.manifest.manifest-sections."Section-Name"."Entry-Key2"=Value2

Environment variable: QUARKUS_PACKAGE_MANIFEST_MANIFEST_SECTIONS

Show more

Map<String,Map<String,String>>

JVMモードでのカスタムテスト設定プロファイル

デフォルトでは、JVMモードのQuarkusテストは、 test 設定プロファイルを使用して実行されます。Quarkusの設定プロファイルに慣れていない場合は、 設定プロファイル のドキュメントで必要な情報がすべて説明されていますので、そちらを参照してください。

ただし、以下に示すMaven SurefireおよびMaven Failsafe構成で、テストにカスタム構成プロファイルを使用することは可能です。これは、例えば、デフォルトのテストデータベースではない特定のデータベースを使用してテストを実行する必要がある場合に便利です。

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>${failsafe-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
1 foo 設定プロファイルがテストの実行に使用されます。

今のところ、ネイティブモードでカスタムテスト設定プロファイルを使用することはできません。ネイティブテストは常に prod プロファイルを使用して実行されます。

ブートストラップ Maven プロパティー

Quarkus ブートストラップには、アプリケーションのランタイムとビルド時間の依存関係を解決するために使用される Maven リゾルバーの実装が含まれています。Quarkus Maven リゾルバーは、ビルド、テスト、または開発モードを起動したのと同じ Maven コマンドラインから初期化されます。通常、設定を追加する必要はありません。ただし、テストモード、開発モード、または IDE でアプリケーションの依存関係を適切に解決するために、追加の設定オプションが必要になる場合があります。

たとえば、Maven テストプラグイン (surefirefailsafe など) は、デフォルトでは、ビルドシステムのプロパティーを実行中のテストに伝搬しません。つまり、MavenCLI によって設定されたシステムプロパティーの一部は、テスト用に初期化された Quarkus Maven リゾルバーでは使用できないため、メインの Maven ビルドとは異なる設定を使用して、テストの依存関係が解決される可能性があります。

以下は、Quarkus bootstrap Maven resolverが初期化時にチェックするシステムプロパティのリストです。

プロパティ名 デフォルト値 Description

maven.home

MAVEN_HOME envvar

Maven のホームディレクトリは、コマンドラインで -gs 引数を使って明示的に提供されていない限り、グローバル設定ファイルの解決に使用されます。

maven.settings

~/.m2/settings.xml

カスタム設定ファイルが -s 引数で提供されていない限り、このプロパティを使用してリゾルバにカスタム Maven 設定ファイルを指定できます。

maven.repo.local

~/.m2/repository

これがデフォルトのものや `settings.xml`で設定されたものと異なる場合、このプロパティを使用して、カスタムのローカル Maven リポジトリ・ディレクトリを構成することができます。

maven.top-level-basedir

none

このプロパティーは、Maven リゾルバーがワークスペース内の最上位の Maven プロジェクトを識別する際に役立つ場合があります。デフォルトでは、Maven リゾルバーは、親モジュールの POM 関係をナビゲートすることによってプロジェクトのワークスペースを検出します。ただし、モジュールの親として表示されていないアグリゲーターモジュールを使用しているプロジェクトレイアウトが存在する可能性があります。この場合、このプロパティーは、QuarkusMaven リゾルバーがワークスペースを適切に検出できるようにサポートします。

quarkus.bootstrap.effective-model-builder

false

デフォルトでは、Quarkus Maven リゾルバーは、プロジェクトのレイアウトを検出するときにプロジェクトの POM を直接読み取ります。ほとんどの場合、これは十分に機能し、比較的高速ですが、raw POM を読み取ることには限界があります。たとえば、POM のプロファイルにモジュールが含まれている場合、これらのモジュールは検出されません。このシステムプロパティーにより、raw のモデルではなく、適切に補間された効果的な POM モデルに基づいたプロジェクトのレイアウト検出が可能になります。このオプションがデフォルトで有効になっていない理由は、たとえば CI テスト時間を増加させるなど、大幅に時間がかかると思われるからです。デフォルトで使用できるより良いアプローチが見つかるまで、このオプションが必要なプロジェクトは、これを有効にする必要があります。

上記のこれらのシステムプロパティーは、たとえば、以下のように surefire および/または failsafe プラグイン設定に追加できます。

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <maven.home>${maven.home}</maven.home> (1)
            <maven.repo.local>${settings.localRepository}</maven.repo.local> (2)
            <maven.settings>${session.request.userSettingsFile.path}</maven.settings> (3)
            <maven.top-level-basedir>${session.topLevelProject.basedir.absolutePath}</maven.top-level-basedir> (4)
            <quarkus.bootstrap.effective-model-builder>true</quarkus.bootstrap.effective-model-builder> (5)
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
1 Maven CLI によって設定された maven.home システムプロパティーをテストに伝達します。
2 テスト用のMavenローカルリポジトリのディレクトリを設定
3 テスト用の Maven 設定ファイルを設定します
4 テスト用のトップレベルのプロジェクト・ディレクトリを指定
5 効果的なPOMベースのプロジェクト・レイアウト・ディスカバリーを有効化

トップレベルとマルチモジュールのプロジェクトディレクトリ

Mavenでは、トップレベルのプロジェクト(プロジェクトのプロパティとして公開されています。 ${session.topLevelProject.basedir.absolutePath})と、マルチモジュールのプロジェクトディレクトリ(プロパティとして公開されています。 ${maven.multiModuleProjectDirectory})という概念があるようです。これらのディレクトリは常に一致するとは限りません。

maven.multiModuleProjectDirectory は、Maven コード自体が参照することを意図しており、ユーザーコードが頼るべきものではありません。なので、もし便利だと思っても、自分の責任で使ってくださいね。

${maven.multiModuleProjectDirectory} は、mvn コマンドが起動された現在のディレクトリー (または -f 引数で指定されたディレクトリー) から開始してワークスペースファイルシステムツリーを上る子として .mvn ディレクトリーを含む最初のディレクトリーに解決されます。ただし、.mvn ディレクトリーが見つからなかった場合は、${maven.multiModuleProjectDirectory} は、mvn コマンドが起動されたディレクトリー (または -f 引数の対象となるディレクトリー) を指すようになります。

${session.topLevelProject.basedir.absolutePath} は、mvn コマンドが起動されたディレクトリー、または指定されている場合は -f 引数の対象となるディレクトリーのいずれかを指します。

Quarkus プロジェクト情報

Quarkus Maven プラグインには、info (現在は 'experimental' とマークされています) と呼ばれるゴールが含まれています。これは、インポートされた Quarkus プラットフォーム BOM やプロジェクトの依存関係で見つかった Quarkus エクステンションなど、プロジェクトに関する Quarkus 固有の情報をログに記録するものです。マルチモジュールプロジェクトでは、quarkus:info は、実行されている現在のモジュールが、アプリケーションのメインモジュールであると想定します。

quarkus:info によって生成されたレポートには、現在 Quarkus Maven プラグイン情報が含まれていませんが、将来のリリースで追加される予定です。

単純なプロジェクトの info 出力の例を以下に示します。

[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:info
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:3.9.4:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs: (1)
[INFO]   io.quarkus.platform:quarkus-bom:pom:3.9.4
[INFO]   io.quarkus.platform:quarkus-camel-bom:pom:3.9.4
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom: (2)
[INFO]   io.quarkus:quarkus-rest
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-camel-bom: (3)
[INFO]   org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io: (4)
[INFO]   io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
1 プロジェクトにインポートされた Quarkus プラットフォーム BOM (親 POM によってインポートされた BOM も報告されます)
2 quarkus-bom によって管理される直接的な Quarkus エクステンションの依存関係
3 quarkus-camel-bom によって管理される直接的な Quarkus エクステンションの依存関係
4 Quarkus BOM によって管理されていないが、Quarkus 拡張レジストリーにある直接的な Quarkus 拡張の依存関係
また、quarkus:info は、Quarkus エクステンションレジストリーにない Quarkus エクステンションがプロジェクトの依存関係に存在する場合は報告し、'不明なオリジン' であることを示します。

揃っていないバージョンの強調表示

quarkus:info は、Quarkusの基本的な依存関係のバージョンのずれが検出された場合、そのハイライトも行います。例えば、依存関係から camel-quarkus-rabbitmq エクステンションを削除し、 quarkus-bom によって管理されている quarkus-rest 依存関係に`2.6.3.Final` <version> 要素を追加することで、前述のプロジェクトを修正し、 quarkus:info を再度実行すると、次のように表示されます:

[INFO] --- quarkus-maven-plugin:3.9.4:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs:
[INFO]   io.quarkus.platform:quarkus-bom:pom:3.9.4
[INFO]   io.quarkus.platform:quarkus-camel-bom:pom:3.9.4 | unnecessary (1)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom:
[INFO]   io.quarkus:quarkus-resteasy-reactive:2.6.3.Final | misaligned (2)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-camel-bom:
[INFO]   org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO]   io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
[INFO]
[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'
1 quarkus-camel-bom のインポートは、Quarkus のエクステンションがプロジェクトの依存関係にないため、 'unnecessary' と報告されるようになりました。
2 quarkus-resteasy-reactive` のバージョン 2.6.3.Final は、プロジェクトにインポートされた Quarkus プラットフォーム BOM によって管理されているバージョン (3.9.4) と整合性がないと報告されるようになりました。

Quarkus プロジェクト更新

QuarkusMaven プラグインによって提供される quarkus:update ゴール (現在は 'experimental' としてマークされています) を使用して、プロジェクトで利用可能な Quarkus 関連の更新があるかどうかを確認できます。たとえば、プロジェクトに存在する関連する Quarkus プラットフォーム の BOM やプラットフォーム以外の Quarkus エクステンションの新リリースが挙げられます。マルチモジュールプロジェクトでは、update ゴールはメインの Quarkus アプリケーションモジュールから実行されることを想定しています。

この時点で、quarkus:update のゴールは、推奨される更新を実際に適用するのではなく、単にその内容と手動で適用する方法を報告します。
Quarkus Maven プラグインのバージョンは、現在更新レポートに含まれていませんが、将来のリリースで追加される予定です。

quarkus:update が機能する方法では、最初に、プロジェクトのすべての直接的な Quarkus エクステンションの依存関係が収集されます (Quarkus プラットフォームの BOM によって管理されるものと、管理されないけれども Quarkus エクステンションレジストリーにあるもの)。次に、設定された Quarkus エクステンションレジストリー (通常は registry.quarkus.io) が、最新の推奨/サポートされる Quarkus プラットフォームバージョンおよびそれらと互換性のあるプラットフォーム以外の Quarkus エクステンションについてクエリーされます。続いて、アルゴリズムは、プロジェクトで見つかったすべてのエクステンションの最新の互換性のある組み合わせを選択します (そのような組み合わせが実際に存在する場合)。そうでない場合は、更新は提案されません。

Kogito、Camel、および Quarkus 2.7.1.Final に基づく Quarkus プラットフォームで利用可能なコア Quarkus エクステンションを含むプロジェクトがあると想定する場合、quarkus:update の出力は以下のようになります。

[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:update
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:3.9.4:update (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:update goal is experimental, its options and output might change in future versions
[INFO]
[INFO] Recommended Quarkus platform BOM updates: (1)
[INFO] Update: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.9.4
[INFO] Update: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final -> 3.9.4
1 現在推奨されている Quarkus プラットフォームの BOM 更新のリスト
通常、単一のプロジェクトプロパティーを使用してすべての Quarkus プラットフォーム BOM を管理しますが、現在の実装はその点を十分に考慮しておらず、各 BOM の更新が個別に報告されます。

プロジェクトを変更して、プロジェクトからCamel Quarkusエクステンションをすべて削除し、 quarkus-resteasy-reactive エクステンションのバージョンを 2.6.3.Final 、QuarkusプラットフォームのBOMに含まれていない quarkus-prettytime0.2.0 にダウングレードすると、 quarkus:update は次のような報告をします:

[INFO] Recommended Quarkus platform BOM updates: (1)
[INFO] Update: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.9.4
[INFO] Remove: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final (2)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom:
[INFO] Update: io.quarkus:quarkus-resteasy-reactive:2.6.3.Final -> remove version (managed) (3)
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO] Update: io.quarkiverse.prettytime:quarkus-prettytime:0.2.0 -> 0.2.1 (4)
1 プロジェクトに対して現在推奨されている Quarkus プラットフォームの BOM 更新のリスト
2 プロジェクトにCamel Quarkusエクステンションが含まれていないことから、BOMインポートを削除することが推奨されます。
3 quarkus-bom によって管理されていることから、 quarkus-resteasy-reactive の古いバージョンを削除することが推奨されます。
4 quarkus-prettytime エクステンションの最新の互換性のあるバージョン

Quarkus プロジェクト修正

前述のように、quarkus:info は、Quarkus プラットフォームとエクステンションのバージョンを報告するだけでなく、プロジェクトで使用されるエクステンションのバージョンがインポートされた Quarkus プラットフォームの BOM と互換性があることを確認するために、バージョンの整合性をすばやくチェックします。不整合が検出された場合、以下の警告メッセージがログに記録されます。

[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'

rectify オプションが有効な場合、quarkus:update は、最新の推奨される Quarkus バージョンの更新を提案する代わりに、プロジェクトで見つかったエクステンションの依存関係バージョンを現在インポートされている Quarkus プラットフォームの BOM に合わせるための更新手順をログに記録します。

関連コンテンツ