バージョン:

QuarkusとGradle

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

新規プロジェクトの作成

Gradleプロジェクトを生成するには、 Quarkus CLIまたはQuarkus Mavenプラグインを使用できます:

コマンドラインインタフェース

quarkus create app my-groupId:my-artifactId \
    --extensions=resteasy-reactive,resteasy-reactive-jackson \
    --gradle

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

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.8.6.1:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -Dextensions="resteasy-reactive,resteasy-reactive-jackson" \
    -DbuildTool=gradle

mvn io.quarkus:quarkus-maven-plugin:3.8.6.1:create を起動すると、Maven プラグインはユーザー入力を要求します。 -B を Maven コマンドに渡すことで、この対話型モードを無効にすることが出来ます (デフォルト値を使用します)。

Kotlin DSLを使用したい場合は、 gradle の代わりに gradle-kotlin-dsl を使用してください。

Quarkusプロジェクトのスキャフォールドは、プロジェクトにGradleラッパー( ./gradlew )を自動的にインストールします。

スタンドアロンのGradleを使用したい場合は、Gradle 8.5 を使用してください。

プロジェクトは、渡されたartifactIdにちなんだ名前のディレクトリに生成されます。

ネイティブモードとJVMモード用の一対のDockerfilesも src/main/docker で生成されます。これらのDockerfileには、イメージをビルドしてコンテナを実行する手順が書かれています。

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

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

しかし、以下に示す Gradle ビルド設定でテスト用のカスタム設定プロファイルを使用することは可能です。これは例えば、デフォルトのテストデータベースではない特定のデータベースを使ってテストを実行する必要がある場合に便利です。

Groovy DSL

test {
    systemProperty "quarkus.test.profile", "foo" (1)
}

1	`foo` 設定プロファイルがテストの実行に使用されます。

Kotlin DSL

tasks.test {
    systemProperty("quarkus.test.profile", "foo") (1)
}

1	`foo` 設定プロファイルがテストの実行に使用されます。

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

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

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

コマンドラインインタフェース

quarkus extension

Gradle

./gradlew listExtensions

以下を使ってエクステンションを有効化できます。

コマンドラインインタフェース

quarkus extension add hibernate-validator

Gradle

./gradlew addExtension --extensions='hibernate-validator'

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

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

$ ./gradlew addExtension --extensions="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-*

Gradle

./gradlew addExtension --extensions='smallrye-*'

開発モード

Quarkusには開発モードが組み込まれています。以下のコマンドで起動することができます:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

この方法で実行する場合、継続的テストの使い勝手は同じにはなりません。gradleはデーモンとして実行されるため、Quarkusは「きれいな」テスト出力を描くことができず、出力のログを取るだけになってしまうからです。

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

quarkusDev は、バックグラウンドでのコンパイルによるホットデプロイを可能にします。つまり、Java ファイルやリソースファイルを変更してブラウザを更新すると、これらの変更が自動的に有効になります。これは、設定プロパティーファイルのようなリソースファイルにも適用されます。ブラウザをリフレッシュする行為は、ワークスペースのスキャンをトリガし、変更が検出された場合、Javaファイルがコンパイルされ、アプリケーションが再配置されると、あなたの要求は再配置されたアプリケーションによって処理されます。コンパイルやデプロイに問題がある場合は、エラーページでお知らせします。

CTRL+C を叩いてアプリケーションを停止させます。

開発環境が動作する作業ディレクトリーを変更することができます:

Groovy DSL

quarkusDev {
    workingDirectory = rootProject.layout.projectDirectory.asFile
}

Kotlin DSL

tasks.quarkusDev {
    workingDirectory = rootProject.layout.projectDirectory.asFile
}

デフォルトでは、 quarkusDev タスクは compileJava コンパイラ・オプションを使用します。これらは、タスクの compilerArgs プロパティーを設定することで上書きすることができます。

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

コマンドラインインタフェース

quarkus dev -DdebugHost=0.0.0.0

Gradle

./gradlew --console=plain quarkusDev -DdebugHost=0.0.0.0

また、開発環境に環境変数を追加することもできます：

Groovy DSL

quarkusDev {
    environmentVariables = [FOO_VALUE: 'abc', BAR_VALUE: 'def']
}

Kotlin DSL

tasks.quarkusDev {
    environmentVariables.set(mapOf("FOO_VALUE" to "abc", "BAR_VALUE" to "def"))
}

このプラグインは quarkusDev の設定も公開しています。この設定を使って依存関係を宣言すると、その依存関係の使用が開発モードに制限されます。 quarkusDev の設定は以下のように使用できます。

Groovy DSL

dependencies {
    quarkusDev 'io.quarkus:quarkus-jdbc-h2'
}

Kotlin DSL

dependencies {
    quarkusDev("io.quarkus:quarkus-jdbc-h2")
}

リモート開発モード

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

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

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

そのためには、 mutable-jar のフォーマットを使って mutable アプリケーションを構築する必要があります。 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

Gradle

./gradlew build

リモートホストで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 コマンドを使用し、ローカルエージェントをリモートホストに接続する必要があります。

./gradlew quarkusRemoteDev -Dquarkus.live-reload.url=http://my-remote-host:8080

これでブラウザを更新するたびに、ローカルで行った変更がリモートアプリにすぐに表示されるようになりました。

すべての設定項目を以下に示します。

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

Configuration property	タイプ	デフォルト
`quarkus.live-reload.instrumentation` 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`
`quarkus.live-reload.watched-resources` 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	文字列のリスト
`quarkus.live-reload.password` Password used to use to connect to the remote dev-mode application Environment variable: `QUARKUS_LIVE_RELOAD_PASSWORD` Show more	string
`quarkus.live-reload.url` URL used to use to connect to the remote dev-mode application Environment variable: `QUARKUS_LIVE_RELOAD_URL` Show more	string
`quarkus.live-reload.connect-timeout` The amount of time to wait for a remote dev connect or reconnect Environment variable: `QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT` Show more	Duration	`30S`
`quarkus.live-reload.retry-interval` 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`
`quarkus.live-reload.retry-max-attempts` 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`

Configuration property

タイプ

デフォルト

quarkus.live-reload.instrumentation

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

boolean

false

quarkus.live-reload.watched-resources

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

文字列のリスト

quarkus.live-reload.password

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

Environment variable: QUARKUS_LIVE_RELOAD_PASSWORD

string

quarkus.live-reload.url

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

Environment variable: QUARKUS_LIVE_RELOAD_URL

string

quarkus.live-reload.connect-timeout

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

Environment variable: QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

Duration

30S

quarkus.live-reload.retry-interval

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

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_INTERVAL

Duration

2S

quarkus.live-reload.retry-max-attempts

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

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS

int

10

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

期間の値を書くには、標準の java.time.Duration フォーマットを使います。詳細は Duration#parse() Java API documentation を参照してください。

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

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

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

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

デバッグ

開発モードでは、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

Gradle

./gradlew --console=plain quarkusDev -Dsuspend -Ddebug

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

IDEへのインポート

プロジェクトが生成されたら、好きなIDEでインポートできます。唯一の要件は、Gradleプロジェクトをインポートできることです。

Eclipse

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

別のターミナルで、次を実行します:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

そして、生産性の高い環境をお楽しみください。

IntelliJ IDEA

IntelliJ IDEAの場合:

IntelliJ IDEAの内部から File → New → Project From Existing Sources… を選択するか、ウェルカム・ダイアログからであれば、 Import project を選択してください。
プロジェクトのルートを選択します。
Import project from external model を選択して Gradle
Next を数回(必要に応じてオプションを確認)
最後の画面でFinishをクリックします。

別の端末や組込端末で、次を実行します:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

楽しんで!

Apache NetBeans

NetBeansの場合:

File → Open Project を選択
プロジェクトのルートを選択します。
Open Project をクリックしてください。

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

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

楽しんで!

Visual Studio Code

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

オフラインでの開発やテストのための依存ファイルのダウンロード

Quarkusのエクステンションの依存関係は、アプリケーションの実行時クラスパス上で終わる実行時エクステンションの依存関係と、ビルドクラスパスを作成するためにアプリケーションのビルド時にQuarkusによってのみ解決されるデプロイメント（またはビルド時）エクステンションの依存関係に分けられます。アプリケーション開発者は、Quarkusのエクステンションの実行時アーティファクトにのみ依存関係を表現することが期待されます。

オフラインでQuarkusアプリケーションを構築してテストするというユースケースを可能にするために、プラグインには quarkusGoOffline タスクが含まれており、コマンドラインから次のように呼び出すことができます。

./gradlew quarkusGoOffline

このタスクは、アプリケーションの実行時、ビルド時、テスト、開発モードのすべての依存関係をGradleのキャッシュに解決します。実行すると、 --offline フラグを付けて quarkus タスクを安全に実行できるようになります。

ネイティブ実行可能ファイルのビルド

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

GRAALVM_HOME を設定し、最新リリースのGraalVM for JDK 21 を指しているようにして下さい。

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

コマンドラインインタフェース

quarkus build --native

Gradle

./gradlew build -Dquarkus.package.type=native

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

ネイティブ関連のプロパティーは、 application.properties ファイルにコマンドライン引数として追加するか、 quarkusBuild タスクに追加することができます。 quarkusBuild タスクの設定は以下のように行います:

Groovy DSL

quarkusBuild {
    nativeArgs {
        containerBuild = true (1)
        builderImage = "quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21" (2)
    }
}

1	`quarkus.native.container-build` プロパティーに `true` をセット
2	`quarkus.native.builder-image` プロパティに `quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21` をセット

Kotlin DSL

tasks.quarkusBuild {
    nativeArgs {
        "container-build" to true (1)
        "builder-image" to "quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21" (2)
    }
}

1	`quarkus.native.container-build` プロパティーに `true` をセット
2	`quarkus.native.builder-image` プロパティに `quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21` をセット

Gradle Groovy DSL を使用する場合、プロパティーキーは小文字のキャメルケース表記に従わなければなりません。例: container-build は無効なので、 containerBuild で置き換えてください。この制限は Gradle Kotlin DSL には適用されません。

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

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

コマンドラインインタフェース

quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.

Gradle

./gradlew build -Dquarkus.package.type=native -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のバージョンが、利用可能な全てのイメージと互換性があるとは限りません。

ネイティブテストの実行

次のようにネイティブテストを実行します:

./gradlew testNative

このタスクは quarkusBuild に依存しているので、テストを実行する前にネイティブイメージを生成します。

デフォルトでは、 native-test のソースセットは、 main と test のソースセットに基づいています。ソースセットを追加することも可能です。たとえば、統合テストが integrationTest のソースセットにある場合は、次のように指定します。

Groovy DSL

quarkus {
    sourceSets {
        extraNativeTest = sourceSets.integrationTest
    }
}

Kotlin DSL

quarkus {
    sourceSets {
        setExtraNativeTest(sourceSets["integrationTest"])
    }
}

結合テストの実行

（ @QuarkusIntegrationTest でアノテーションされた）Quarkus結合テストは、Quarkusが生成したアーティファクトで実行されます。これらのテストは、 src/integrationTest/java ディレクトリに配置し、それを使用して実行することができます。

./gradlew quarkusIntTest

このタスクは test と quarkusBuild タスクに依存しています。最終的なアーティファクトは、テストを実行する前に生成されます。

fast-jar の使用

fast-jar がデフォルトの quarkus パッケージタイプになりました。 ./gradlew build コマンドの結果、 build の下に quarkus-app という名前の新しいディレクトリが作成されます。

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

生成された jar を正常に実行するためには、 quarkus-app ディレクトリのすべての内容が必要です。いずれかのファイルが欠落していると、アプリケーションが起動しなかったり、正しく機能しない可能性があります。

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

UberJar のビルド

Quarkus Gradleプラグインは、以下のように --uber-jar 引数を指定して UberJar の生成をサポートしています。

コマンドラインインタフェース

quarkus build -Dquarkus.package.type=uber-jar

Gradle

./gradlew build -Dquarkus.package.type=uber-jar

UberJar を作成する際に、 --ignored-entry 引数を使用して生成された jar から除外したいエントリーを指定することができます。

./gradlew quarkusBuild -Dquarkus.package.type=uber-jar --ignored-entry=META-INF/file1.txt

エントリーは、生成された Uber-Jar のルートからの相対的なものです。追加の --ignored-entry 引数を追加することで、複数のエントリーを指定することができます。

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

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

マルチモジュールプロジェクトのモジュールでCDI Bean検出を有効にするベストの方法は、モジュールが、メインアプリケーションモジュールで、すでにquarkus-maven-pluginで設定されていない限り、 META-INF/beans.xml ファイルをインクルードすることです。モジュールが、メインアプリケーションモジュールで、すでにquarkus-maven-pluginで設定されている場合は、自動的にインデックスが作成されます。

あるいは、 META-INF/beans.xml ファイルの代わりに使える非公式の Gradle Jandex プラグインもあります。

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

アプリケーションの発行

Gradle で正しい依存関係のバージョンが使用されていることを担保するために、BOM はビルドファイル内で enforcedPlatform として宣言されています。デフォルトでは、 maven-publish プラグインは、この enforcedPlatform を理由にアプリケーションの公開を阻止します。 build.gradle ファイルに以下の設定を追加することで、この検証をスキップすることができます。

Groovy DSL

tasks.withType(GenerateModuleMetadata).configureEach {
    suppressedValidationErrors.add('enforced-platform')
}

Kotlin DSL

tasks.withType<GenerateModuleMetadata>().configureEach {
    suppressedValidationErrors.add("enforced-platform")
}

Quarkusのビルドの設定

Quarkusのビルドに影響を与える設定ソースは複数あり、優先順位順に説明しています。Quarkusのビルドでは、 prod の設定プロファイルが使用されます:

システムプロパティ（例： ./gradlew -Dquarkus.package.type=fast-jar … ）
システム環境 (例: QUARKUS_PACKAGE_TYPE=fast-jar ./gradlew … )
quarkus エクステンションの quarkusBuildProperties を介した設定。例えば:
```
quarkus {
    quarkusBuildProperties {
        set("package.type", "uber-jar")
    }
}
```
Gradleプロジェクトプロパティによる設定（例： ./gradlew -Pquarkus.package.type=fast-jar )
プロジェクトの application.properties 、 application.yaml 、 application.yml ファイル、およびプロジェクトの application-prod.properties 、 application-prod.yaml 、 application-prod.yml ファイルからの設定

Quarkusプラグインでは、3.0から上記の優先順位が変更されました。古いバージョンのQuarkus Gradleプラグインでは、Gradleビルドの設定よりも application.properties が優先されました。

Quarkus Gradleプラグインは、設定の読み込みと解析に"標準"のQuarkusのメカニズムを使用します。Quarkus 3.0では、 application.properties に加えて、 application.(yaml|yml) のサポートが追加されました。また、3.0では、SmallRye Configで利用できるすべてのメカニズムが、暗黙のうちにQuarkus Gradleプラグインでも利用できるようになっています。

Quarkusのビルドに使用される有効な設定オプションを表示するには、 quarkusShowEffectiveConfig タスクを使用します。 --save-config-properties コマンドラインオプションを指定した場合、設定プロパティはファイル build/<final-name>.quarkus-build.properties にも保存されます。

Gradle キャッシング / タスク入力

デフォルトでは、 quarkus. で始まるシステムプロパティーと、 QUARKUS_ で始まる環境変数 (`~/.env`からの環境変数を含む) は、Gradle タスクの入力とみなされます。つまり、これらのシステムプロパティーへの変更のみが、Gradle のリビルドをトリガーして最新を保ちます。他のシステムプロパティーや環境変数を変更しても、Quarkus の Gradle タスク入力は変更されず、不要なリビルドがトリガーされることはありません。

quarkus.quarkusBuildProperties または Quarkus application.* 設定ファイルを介して指定された設定プロパティーは、すべて Gradle タスク入力とみなされます。つまり、これらのファイルを変更するたびにリビルドが実行されます。。

Quarkus ビルドが quarkus. で始まらないシステムプロパティー (または QUARKUS_`で始まらない環境変数) を参照する場合は、Quarkus ビルドエクステンションを介して参照する必要があります。たとえば、 `application.properties ファイルが次のような環境変数を参照するとします。

greeting.message=${FOO_MESSAGE:Hello!}

この場合、"caching relevant" として明示的に宣言する必要があります。

quarkus {
   cachingRelevantProperties.add("FOO_MESSAGE")
   // Note: `cachingRelevantProperties` accepts regular expressions
}

ビルドワーカー

Quarkusアプリケーションのビルドは、GradleのワーカーAPIを使用して、分離されたプロセスで実行されます。これには、QuarkusアプリケーションのビルドとQuarkusのコード生成が含まれます。これは、 quarkus エクステンションと Gradle プロジェクトのプロパティから Quarkus のコード生成/アプリケーションビルダーに設定を適切に渡すために必要です。

コード生成やQuarkusビルドを実行するプロセスのJVM設定は、次のように設定できます。詳細については、 JavaForkOptions を参照してください。

Groovy DSL

plugins {
    id 'java'
    id 'io.quarkus'
}

quarkus {
    buildForkOptions {
        maxHeapSize = '2g'
    }
    codeGenForkOptions {
        maxHeapSize = '128m'
    }
}

Kotlin DSL

plugins {
    java
    id("io.quarkus")
}

quarkus {
    buildForkOptions {
        maxHeapSize = '2g'
    }
    codeGenForkOptions {
        maxHeapSize = '128m'
    }
}

キャッシュされたビルドアーティファクト

Gradleのビルドキャッシュは、以前に生成した出力を再利用することで、ビルド全体の実行時間を改善する非常に効率的な仕組みです（技術的な詳細は Incremental build を参照して下さい）。

Quarkusプラグインは、最新のチェックとビルドキャッシュというgradleのメカニズムを活用します。ビルドキャッシュは、ローカル、ローカル＋リモートキャッシュサーバー、またはCI環境で構成されている場合は、 GradleのGitHubアクションや直接/手動でGitHubの GitHubのキャッシュアクションを使用するなど、キャッシュ全体をアーティファクトとして取得し保存する意味でリモートとすることができます。

Quarkus Gradle プラグインは、何が、どの環境 (CI またはローカル開発) にキャッシュされているかを考慮します。uber-jar やネイティブバイナリーなどの大きなアーティファクトは CI ではキャッシュされませんが、ローカル開発環境ではキャッシュされます。

Quarkus Gradleプラグインは、 CI 環境変数が存在する場合、 CI環境 を検出します。

次の表は、さまざまな Quarkus パッケージタイプが非 CI 環境と CI 環境でどのようにキャッシュされるかを示しています。タスクの出力が キャッシュ されない場合も up-to-date は適用されることに注意してください。

Quarkus アプリケーションのビルドは 3 つのタスクに分かれています。 `quarkusBuild`タスクは、ビルドされた Quarkus アプリケーションを提供する役割を担っています。quarkusDependenciesBuild と quarkusAppPartsBuild のタスクは、内部タスクとみなされます (予告なく変更される可能性があります)。詳細は以下を参照してください。

Quarkusパッケージタイプ

備考

キャッシング（非CI）

キャッシング（CI）

fast-jar, jar

依存関係 jar は、 quarkus-app/lib/ ディレクトリーに個別のファイルとして、そのまま保存されます。 quarkusAppPartsBuild タスクは、 fast-jar パッケージタイプのアプリケーションをビルドします。これにより、generated ピースのキャッシュが可能になります。 quarkus-app/lib/ ディレクトリー内の依存関係を除くすべての 生成された ピースのキャッシュが可能になります。 quarkusDependenciesBuild タスクは、Gradle メカニズムを介して依存関係を収集するために使用されます。その後、 quarkusBuild タスクは quarkusAppPartsBuild タスクと quarkusDependenciesBuild タスクの出力をアセンブルします。注記: パッケージタイプが明示的に設定されていない場合は、 fast-jar (または -jar) がデフォルトになります。

✅

mutable-jar, uber-jar, native, native-sources

quarkusBuild タスクは、Quarkusアプリケーションのビルドを担当します。

quarkusAppPartsBuild および quarkusDependenciesBuild タスクは uber-jar に対しては何も行いません。

✅

❌

legacy-jar, legacy

legacy-jar のビルドは、ディレクトリ構造が異なることと、 modified-*.jar のファイルが生成されたとみなされることを除き、 fast-jar のビルドと同様に動作します。

✅

ローカル開発環境では、より大きなキャッシュアーティファクトを保存（および取得）するコスト（時間）は、Quarkusアプリケーションを再ビルドするコストよりも低くなります。つまり、Quarkus Gradleプラグインは、非CI環境において、uber-jarやネイティブバイナリのような潜在的に大きな成果物をキャッシュすることができます。コードベースのさまざまな状態に対してビルドを実行するCI環境（メインブランチのすべてのコミットに対してCIを実行することを想定）では、ビルドされた（そして大きな）成果物をビルドキャッシュに追加すると、ビルドキャッシュが不必要に大きくなり、例えば、キャッシュできる成果物の総量が10GBに制限されているGitHubでは問題になります。

背景：Gradleには、ビルドのパフォーマンスを向上させるために、2つの関連するメカニズムが働いています:

up-to-date チェックでタスクの入力と出力が変更されていない場合は、タスクの実行をスキップできます。たとえば Java のコンパイルタスクの場合、ライブラリーの依存関係とソースファイル (入力) が変更され、コンパイルされたクラスファイル (出力) が引き続き使用可能であれば、コンパイルをスキップできます。
ビルドキャッシュは、（キャッシュ可能な）タスクの出力をローカルビルドキャッシュに保存することができます。タスクの出力は、キャッシュから復元することができます。

up-to-date チェックとビルドキャッシュの相互作用の利点には、入力と出力のモデリングコストが伴います。入力には、ファイルやディレクトリーだけでなく、ビルド時に使用された Java のバージョン、オペレーティングシステム、ワーキングディレクトリー、設定オプションなども含まれます。つまり、タスク操作の出力に影響を与えるすべてが、タスクの入力として宣言される必要があります。

Gradle設定キャッシュ

Quarkus Gradleプラグインは、 Gradleの設定キャッシュを有効にしているビルドで動作しますが、Quarkusタスクでは設定キャッシュは無効になっています。つまり、Quarkusプラグインは、そのようなGradleビルドを壊さないということです。

QuarkusとGradle

新規プロジェクトの作成

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

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

開発モード

リモート開発モード

デバッグ

IDEへのインポート

オフラインでの開発やテストのための依存ファイルのダウンロード

ネイティブ実行可能ファイルのビルド

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

ネイティブテストの実行

結合テストの実行

fast-jar の使用

UberJar のビルド

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

アプリケーションの発行

Quarkusのビルドの設定

Gradle キャッシング / タスク入力

ビルドワーカー

キャッシュされたビルドアーティファクト

Gradle設定キャッシュ

関連コンテンツ

同じトピックについて