Building Quarkus apps with Gradle
Creating a new project
To scaffold a Gradle project you can either use the Quarkus CLI or the Quarkus Maven plugin:
If you prefer using the Kotlin DSL, use gradle-kotlin-dsl instead of gradle .
|
Quarkus project scaffolding automatically installs the Gradle wrapper ( If you prefer to use a standalone Gradle installation, please use Gradle 7.5.1. |
The project is generated in a directory named after the passed artifactId.
A pair of Dockerfiles for native and JVM modes are also generated in src/main/docker
. Instructions to build the image and run the container are written in those Dockerfiles.
Custom test configuration profile in JVM mode
By default, Quarkus tests in JVM mode are run using the test
configuration profile. If you are not familiar with Quarkus configuration profiles, everything you need to know is explained in the Configuration Profiles Documentation.
It is however possible to use a custom configuration profile for your tests with the Gradle build configuration shown below. This can be useful if you need for example to run some tests using a specific database which is not your default testing database.
It is not possible to use a custom test configuration profile in native mode for now. Native tests are always run using the |
Dealing with extensions
From inside a Quarkus project, you can obtain a list of the available extensions with:
quarkus extension
./gradlew listExtensions
You can enable an extension using:
quarkus extension add 'hibernate-validator'
./gradlew addExtension --extensions='hibernate-validator'
Extensions are passed using a comma-separated list.
The extension name is the GAV name of the extension: e.g. io.quarkus:quarkus-agroal
. But you can pass a partial name and Quarkus will do its best to find the right extension. For example, agroal
, Agroal
or agro
will expand to io.quarkus:quarkus-agroal
. If no extension is found or if more than one extensions match, you will see a red check mark ❌ in the command result.
$ ./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?
[...]
You can install all extensions which match a globbing pattern:
quarkus extension add 'smallrye-*'
./gradlew addExtension --extensions='smallrye-*'
Development mode
Quarkus comes with a built-in development mode. You can start it with:
quarkus dev
./gradlew --console=plain quarkusDev
Note that if you run it this way the continuous testing experience will not be as nice, as gradle runs as a daemon Quarkus can’t draw the 'pretty' test output so falls back to just logging the output.
You can then update the application sources, resources and configurations. The changes are automatically reflected in your running application. This is great to do development spanning UI and database as you see changes reflected immediately.
quarkusDev
enables hot deployment with background compilation, which means that when you modify your Java files or your resource files and refresh your browser these changes will automatically take effect. This works too for resource files like the configuration property file. The act of refreshing the browser triggers a scan of the workspace, and if any changes are detected the Java files are compiled, and the application is redeployed, then your request is serviced by the redeployed application. If there are any issues with compilation or deployment an error page will let you know.
Hit CTRL+C
to stop the application.
You can change the working directory the development environment runs on:
By default, the |
By default, CLI
Gradle
|
The plugin also exposes a quarkusDev
configuration. Using this configuration to declare a dependency will restrict the usage of that dependency to development mode. The quarkusDev
configuration can be used as following:
Remote Development Mode
It is possible to use development mode remotely, so that you can run Quarkus in a container environment (such as OpenShift) and have changes made to your local files become immediately visible.
This allows you to develop in the same environment you will actually run your app in, and with access to the same services.
Do not use this in production. This should only be used in a development environment. You should not run production applications in dev mode. |
To do this you must build a mutable application, using the mutable-jar
format. Set the following properties in 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 | This tells Quarkus to use the mutable-jar format. Mutable applications also include the deployment time parts of Quarkus, so they take up a bit more disk space. If run normally they start just as fast and use the same memory as an immutable application, however they can also be started in dev mode. |
2 | The password that is used to secure communication between the remote side and the local side. |
3 | The URL that your app is going to be running in dev mode at. This is only needed on the local side, so you may want to leave it out of the properties file and specify it as a system property on the command line. |
The mutable-jar
is then built in the same way that a regular Quarkus jar is built, i.e. by issuing:
quarkus build
./gradlew build
Before you start Quarkus on the remote host set the environment variable QUARKUS_LAUNCH_DEVMODE=true
. If you are on bare metal you can set it via the export QUARKUS_LAUNCH_DEVMODE=true
command and then run the application with the proper java -jar …
command to run the application.
If you plan on running the application via Docker, then you’ll need to add -e QUARKUS_LAUNCH_DEVMODE=true
to the docker run
command. When the application starts you should now see the following line in the logs: Profile dev activated. Live Coding activated
.
The remote side does not need to include Maven or any other development tools. The normal fast-jar Dockerfile that is generated with a new Quarkus application is all you need. If you are using bare metal launch the Quarkus runner jar, do not attempt to run normal dev mode.
|
Now you need to connect your local agent to the remote host, using the remote-dev
command:
./gradlew quarkusRemoteDev -Dquarkus.live-reload.url=http://my-remote-host:8080
Now every time you refresh the browser you should see any changes you have made locally immediately visible in the remote app.
All the config options are shown below:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
类型 |
默认 |
|
---|---|---|
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: |
boolean |
|
The names of additional resource files to watch for changes, triggering a reload on change. Directories are not supported. Environment variable: |
list of string |
|
Password used to use to connect to the remote dev-mode application Environment variable: |
string |
|
URL used to use to connect to the remote dev-mode application Environment variable: |
string |
|
The amount of time to wait for a remote dev connect or reconnect Environment variable: |
|
|
The amount of time to wait between attempts when connecting to the server side of remote dev Environment variable: |
|
|
The maximum number of attempts when connecting to the server side of remote dev Environment variable: |
int |
|
About the Duration format
持续时间的格式使用标准的 您还可以提供以数字开头的持续时间值。 在这种情况下,如果该值仅包含一个数字,则转换器将该值视为秒。 否则, |
Debugging
In development mode, Quarkus starts by default with debug mode enabled, listening to port 5005
without suspending the JVM.
This behavior can be changed by giving the debug
system property one of the following values:
-
false
- the JVM will start with debug mode disabled -
true
- The JVM is started in debug mode and will be listening on port5005
-
client
- the JVM will start in client mode and attempt to connect tolocalhost:5005
-
{port}
- The JVM is started in debug mode and will be listening on{port}
An additional system property suspend
can be used to suspend the JVM, when launched in debug mode. suspend
supports the following values:
-
y
ortrue
- The debug mode JVM launch is suspended -
n
orfalse
- The debug mode JVM is started without suspending
You can also run a Quarkus application in debug mode with a suspended JVM using: CLI
Gradle
Then, attach your debugger to |
Import in your IDE
Once you have a project generated, you can import it in your favorite IDE. The only requirement is the ability to import a Gradle project.
Eclipse
In Eclipse, click on: File → Import
. In the wizard, select: Gradle → Existing Gradle Project
. On the next screen, select the root location of the project. The next screen list the found modules; select the generated project and click on Finish
. Done!
In a separated terminal, run:
quarkus dev
./gradlew --console=plain quarkusDev
and enjoy a highly productive environment.
IntelliJ IDEA
In IntelliJ IDEA:
-
From inside IntelliJ IDEA select
File → New → Project From Existing Sources…
or, if you are on the welcome dialog, selectImport project
. -
Select the project root
-
Select
Import project from external model
andGradle
-
Next a few times (review the different options if needed)
-
On the last screen click on Finish
In a separated terminal or in the embedded terminal, run:
quarkus dev
./gradlew --console=plain quarkusDev
Enjoy!
Apache NetBeans
In NetBeans:
-
Select
File → Open Project
-
Select the project root
-
Click on
Open Project
In a separated terminal or the embedded terminal, go to the project root and run:
quarkus dev
./gradlew --console=plain quarkusDev
Enjoy!
Visual Studio Code
Open the project directory in VS Code. If you have installed the Java Extension Pack (grouping a set of Java extensions), the project is loaded as a Gradle project.
Downloading dependencies for offline development and testing
Quarkus extension dependencies are divided into the runtime extension dependencies that end up on the application runtime classpath and the deployment (or build time) extension dependencies that are resolved by Quarkus only at application build time to create the build classpath. Application developers are expected to express dependencies only on the runtime artifacts of Quarkus extensions.
To enable the use-case of building and testing a Quarkus application offline, the plugin includes the quarkusGoOffline
task that could be called from the command line like this:
./gradlew quarkusGoOffline
This task will resolve all the runtime, build time, test and dev mode dependencies of the application to the Gradle cache. Once executed, you will be able to safely run quarkus task with --offline
flag.
Building a native executable
Native executables make Quarkus applications ideal for containers and serverless workloads.
Make sure to have GRAALVM_HOME
configured and pointing to the latest release of GraalVM version 22.3 (Make sure to use a Java 11 version of GraalVM).
Create a native executable using:
quarkus build --native
./gradlew build -Dquarkus.package.type=native
A native executable will be present in build/
.
Native related properties can either be added in application.properties
file, as command line arguments or in the quarkusBuild
task. Configuring the quarkusBuild
task can be done as following:
When using the Gradle Groovy DSL, property keys must follow lower camel case notation. e.g. |
Build a container friendly executable
The native executable will be specific to your operating system. To create an executable that will run in a container, use the following:
quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.
./gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true
The produced executable will be a 64-bit Linux executable, so depending on your operating system it may no longer be runnable. However, it’s not an issue as we are going to copy it to a Docker container. Note that in this case the build itself runs in a Docker container too, so you don’t need to have GraalVM installed locally.
By default, the native executable will be generated using the If you want to build a native executable with a different Docker image (for instance to use a different GraalVM version), use the The list of the available Docker images can be found on quay.io. Be aware that a given Quarkus version might not be compatible with all the images available. |
Running native tests
Run the native tests using:
./gradlew testNative
This task depends on quarkusBuild
, so it will generate the native image before running the tests.
By default, the |
Running integration tests
Quarkus integration tests (annotated with @QuarkusIntegrationTest
) will run on the artifact produced by Quarkus. Those tests can be placed in a src/integrationTest/java
directory and executed using:
./gradlew quarkusIntTest
This task depends on both test
and quarkusBuild
tasks. The final artifact will be produced before running tests.
Using fast-jar
fast-jar
is now the default quarkus package type. The result of ./gradlew build
command is a new directory under build
named quarkus-app
.
You can run the application using: java -jar build/quarkus-app/quarkus-run.jar
.
In order to successfully run the produced jar, you need to have the entire contents of the quarkus-app directory. If any of the files are missing, the application will not start or might not function correctly.
|
The fast-jar packaging results in creating an artifact that starts a little faster and consumes slightly less memory than a legacy Quarkus jar because it has indexed information about which dependency jar contains classes and resources. It can thus avoid the lookup into potentially every jar on the classpath that the legacy jar necessitates, when loading a class or resource.
|
Building Uber-Jars
Quarkus Gradle plugin supports the generation of Uber-Jars by specifying a quarkus.package.type
argument as follows:
quarkus build -Dquarkus.package.type=uber-jar
./gradlew build -Dquarkus.package.type=uber-jar
When building an Uber-Jar you can specify entries that you want to exclude from the generated jar by using the --ignored-entry
argument:
./gradlew quarkusBuild -Dquarkus.package.type=uber-jar --ignored-entry=META-INF/file1.txt
The entries are relative to the root of the generated Uber-Jar. You can specify multiple entries by adding extra --ignored-entry
arguments.
Working with multi-module projects
By default, Quarkus will not discover CDI beans inside another module.
The best way to enable CDI bean discovery for a module in a multi-module project would be to include a META-INF/beans.xml
file, unless it is the main application module already configured with the quarkus-maven-plugin, in which case it will be indexed automatically.
Alternatively, there is some unofficial Gradle Jandex plugins that can be used instead of the META-INF/beans.xml
file.
More information on this topic can be found on the Bean Discovery section of the CDI guide.
Publishing your application
In order to make sure the right dependency versions are being used by Gradle, the BOM is declared as an enforcedPlatform
in your build file. By default, the maven-publish
plugin will prevent you from publishing your application due to this enforcedPlatform
. This validation can be skipped by adding the following configuration in your build file: