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

QuarkusとGradle

Use Gradle to create a new project, add or remove extensions, launch development mode, debug your application, and build your application into a jar, native executable, or container-friendly executable. Import your project into your favorite IDE using Gradle project metadata.

新規プロジェクトの作成

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

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

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

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.6.0:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -Dextensions="resteasy-reactive,resteasy-reactive-jackson" \
    -DbuildTool=gradle
If you just launch mvn io.quarkus.platform:quarkus-maven-plugin:3.6.0:create the Maven plugin asks for user inputs. You can disable this interactive mode (and use default values) by passing -B to the Maven command.
Kotlin DSLを使用したい場合は、 gradle の代わりに gradle-kotlin-dsl を使用してください。

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

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

プロジェクトは、渡された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プロジェクトの内部から、利用可能なエクステンションのリストを取得することができます。

CLI
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 {
    workingDir = rootProject.projectDir
}
Kotlin DSL
tasks.quarkusDev {
    workingDir = rootProject.projectDir.toString()
}

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

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

CLI
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

list of string

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
期間フォーマットについて

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

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with 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アプリケーションを実行することもできます。

CLI
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の場合:

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

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

  3. Import project from external model を選択して Gradle

  4. Next を数回(必要に応じてオプションを確認)

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

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

コマンドラインインタフェース
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

お楽しみください！

Apache NetBeans

NetBeansの場合:

  1. File → Open Project を選択

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

  3. 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アプリケーションはコンテナーやサーバーレスのワークロードに最適です。

Make sure to have GRAALVM_HOME configured and pointing to the latest release of 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 の設定プロファイルが使用されます:

  1. システムプロパティ（例： ./gradlew -Dquarkus.package.type=fast-jar …​ ）

  2. System environment (for example QUARKUS_PACKAGE_TYPE=fast-jar ./gradlew …​)

  3. quarkus エクステンションの quarkusBuildProperties を介した設定。 例えば:

    quarkus {
    quarkusBuildProperties {
        set("package.type", "uber-jar")
    }
}

  4. Gradleプロジェクトプロパティによる設定（例： ./gradlew -Pquarkus.package.type=fast-jar )

  5. プロジェクトの 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 caching / task inputs

By default, system properties starting with quarkus. and environment variables, including those from ~/.env, starting with QUARKUS_, are considered as inputs for the Gradle tasks. This means that only changes to those system properties or environment variables will cause Gradle’s up-to-date to trigger a rebuild. Changes to other system properties or environment variables do not change Quarkus' Gradle task inputs and do not trigger an unnecessary rebuild.

Configuration properties specified via quarkus.quarkusBuildProperties or via the Quarkus application.* configuration files are all considered as Gradle task inputs, in other words: every change in these files causes a rebuild.

If your Quarkus build references system properties that do not start with quarkus. (or environment variables that do not start with QUARKUS_), you must reference those via the Quarkus build extension. For example, if your application.properties file references an environment variable like this:

greeting.message=${FOO_MESSAGE:Hello!}

it must be explicitly declared as "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のキャッシュ アクションを使用するなど、キャッシュ全体をアーティファクトとして取得し保存する意味でリモートとすることができます。

The Quarkus Gradle plugin cares about what is cached in which environment (CI or local development). Big artifacts like uber-jars and native binaries are not cached in CI, but are cached in local development environments.

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

How the various Quarkus package types are cached in non-CI and CI environments is described in the following table. Note that even if a task’s output is not cached, the up-to-date checks still apply.

The Quarkus application build is split across three tasks. The quarkusBuild task is responsible to provide a built Quarkus application. The tasks quarkusDependenciesBuild and quarkusAppPartsBuild are considered internal tasks (may change at any time w/o prior notice). See below for details.

Quarkus package type

備考

キャッシング（非CI）

キャッシング（CI）

fast-jar, jar

Dependency jars are stored unmodified as individual files in the quarkus-app/lib/ directory. All other files in the quarkus-app/ directory are generated.

The quarkusAppPartsBuild task builds fast-jar package-type applications and allows caching of the generated pieces, which is everything except the dependencies in the quarkus-app/lib/ directory. The quarkusDependenciesBuild task is used to collect the dependencies via Gradle mechanisms. The quarkusBuild task then assembles the outputs of the quarkusAppPartsBuild and quarkusDependenciesBuild tasks.

Note: fast-jar (or -jar) is the default if no package type has been explicitly configured.

✅

✅

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 checks allow a task’s execution to be skipped, if the inputs and outputs of the tasks did not change. For example, consider a Java compile tasks: if the library dependencies and the source files (the inputs) did not change and the compiled class files (the outputs) are still available, compilation can be skipped.

  • ビルドキャッシュは、（キャッシュ可能な）タスクの出力をローカルビルドキャッシュに保存することができます。タスクの 出力 は、キャッシュから復元することができます。

The benefits of up-to-date checks and the interaction of the build cache come with the cost of modeling the inputs and outputs. Inputs are not only files or directories, but also the Java version used during the build, the operating system, the working directory, configuration options, and so on. So everything that influences the output of a task action must be declared as an input of the task.

Gradle設定キャッシュ

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

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by