Quarkus and Gradle

To scaffold a Gradle project you can either use the Quarkus CLI or the Quarkus Maven plugin:

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.

From inside a Quarkus project, you can obtain a list of the available extensions with:

You can enable an extension using:

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.

You can install all extensions which match a globbing pattern:

Quarkus comes with a built-in development mode. You can start it with:

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:

You also can add environment variables to the development environment:

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:

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:

An additional system property suspend can be used to suspend the JVM, when launched in debug mode. suspend supports the following values:

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:

and enjoy a highly productive environment.

IntelliJ IDEA

In IntelliJ IDEA:

In a separated terminal or in the embedded terminal, run:

Enjoy!

Apache NetBeans

In NetBeans:

In a separated terminal or the embedded terminal, go to the project root and run:

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.

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:

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.

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 for JDK 21.

Criar um executável nativo utilizando:

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:

Run the native tests using:

This task depends on quarkusBuild, so it will generate the native image before running the 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:

This task depends on both test and quarkusBuild tasks. The final artifact will be produced before running tests.

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.

Quarkus Gradle plugin supports the generation of Uber-Jars by specifying a quarkus.package.jar.type argument as follows:

When building an Uber-Jar you can specify entries that you want to exclude from the generated jar by using the --ignored-entry argument:

The entries are relative to the root of the generated Uber-Jar. You can specify multiple entries by adding extra --ignored-entry arguments.

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:

There are multiple configuration sources that influence Quarkus builds, mentioned in the order of their priority. The Quarkus build uses the prod configuration profile:

Quarkus application builds are ran in isolated processes using Gradle’s worker API. This includes the Quarkus application build and Quarkus code generation. This is necessary to properly pass the configuration from the quarkus extension and Gradle project properties to Quarkus' code generator / application builder.

The JVM settings of the processes performing the code generation and/or Quarkus build can be configured as follows. See JavaForkOptions for details.

Gradle’s build cache is a very efficient mechanism to improve the overall build runtime, by reusing previously generated outputs (see Incremental build for technical details).

The Quarkus plugin leverages the Gradle mechanisms of up-to-date checks and the build cache. The build cache can be local or local plus a remote cache server or, if configured in CI environments, remote in the sense of retrieving and storing the whole cache as an artifact, for example using Gradle’s GitHub action or directly/manually GitHub’s GitHub’s cache action.

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.

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 Gradle plugin works with builds that have the Gradle’s configuration cache enabled, but the configuration cache is disabled for some of the Quarkus tasks. This means, that the Quarkus plugin does not break such Gradle builds. The current state of compatibility is shown in the following table: