Developing and compiling your IBM Enterprise Build of Quarkus applications with Apache Maven

As an application developer, you can use IBM Enterprise Build of Quarkus to create microservices-based applications written in Java that run on OpenShift Container Platform and serverless environments. Applications compiled to native executables have small memory footprints and fast startup times.

Use the Quarkus Apache Maven plugin to create a IBM Enterprise Build of Quarkus project.

Note: Where applicable, alternative instructions for using the Quarkus command-line interface (CLI) are provided. The Quarkus CLI is intended for development purposes, including tasks such as creating, updating, and building Quarkus projects. However, IBM does not support using the Quarkus CLI in production environments.

Prerequisites

You have installed OpenJDK 17 or 21.
- To download Red Hat build of OpenJDK, log in to the Red Hat Customer Portal and go to Software Downloads.
You have set the JAVA_HOME environment variable to specify the location of the Java SDK.
You have installed Apache Maven 3.9.9.
- To download Maven, go to the Apache Maven Project website.

About IBM Enterprise Build of Quarkus

IBM Enterprise Build of Quarkus is a Kubernetes-native Java stack optimized for containers and Red Hat OpenShift Container Platform. Quarkus is designed to work with popular Java standards, frameworks, and libraries such as Eclipse MicroProfile, Eclipse Vert.x, Apache Camel, Apache Kafka, Hibernate ORM with Jakarta Persistence, and Jakarta REST.

As a developer, you can choose the Java frameworks you want for your Java applications, which you can run in Java Virtual Machine (JVM) mode or compile and run in native mode. Quarkus provides a container-first approach to building Java applications. The container-first approach facilitates the containerization and efficient execution of microservices and functions. For this reason, Quarkus applications have a smaller memory footprint and faster startup times.

Quarkus also optimizes the application development process with capabilities such as unified configuration, automatic provisioning of unconfigured services, live coding, and continuous testing, which provides instant feedback on your code changes.

For information about the differences between the Quarkus community version and IBM Enterprise Build of Quarkus, see Differences between the Quarkus community version and IBM Enterprise Build of Quarkus.

About Apache Maven and IBM Enterprise Build of Quarkus

Apache Maven is a distributed build automation tool that is used in Java application development to create, manage, and build software projects.

To learn more about Apache Maven, see the Apache Maven documentation.

Maven repositories

A Maven repository stores Java libraries, plugins, and other build artifacts. Maven 2 Central Repository is the default public repository; however, repositories can also be private and internal within a company, allowing for the sharing of common artifacts among development teams. Repositories are also available from third parties.

You can use the IBM-hosted Maven repository with your Quarkus projects.

You declare project dependencies in the pom.xml file and configure access to the Maven repositories globally in your $HOME/.m2/settings.xml file. This helps ensure that your projects use certified IBM Enterprise Build of Quarkus artifacts without needing repository details to be included in the POM file of each project.

Maven plugins

Maven plugins are defined parts of a POM file that run one or more tasks. IBM Enterprise Build of Quarkus applications use the following Maven plugins:

Quarkus Maven plugin (quarkus-maven-plugin): Enables Maven to create Quarkus projects, packages your applications into JAR files, and provides a dev mode.
Maven Surefire plugin (maven-surefire-plugin): When Quarkus enables the test profile, the Maven Surefire plugin is used during the test phase of the build lifecycle to run unit tests on your application. The plugin generates text and XML files that contain the test reports.

Additional resources

Configuring your IBM Enterprise Build of Quarkus applications

Configuring the Maven settings.xml file for the online repository

To use the IBM-hosted Quarkus repository with your Quarkus Maven project, configure the settings.xml file for your user. Maven settings used with a repository manager or a repository on a shared server provide better control and manageability of projects.

Note: When you configure the repository by modifying the Maven settings.xml file, the changes apply to all of your Maven projects. If you want to apply the configuration to a specific project only, use the -s option and specify the path to the project-specific settings.xml file.

Procedure

Open the Maven $HOME/.m2/settings.xml file in a text editor or an integrated development environment (IDE).

Note: If no settings.xml file is present in the $HOME/.m2/ directory, copy the settings.xml file from the $MAVEN_HOME/conf/ directory into the $HOME/.m2/ directory.

Add the following lines to the <profiles> element of the settings.xml file:

<!-- Configure the IBM Enterpise Build of Quarkus Maven repository -->
<profile>
  &lt;id&gt;ibm-enterprise-maven-repository&lt;/id&gt;
  <repositories>
    <repository>
      &lt;id&gt;ibm-enterprise-maven-repository&lt;/id&gt;
      &lt;url&gt;https://maven.repository.ibm.com/releases/&lt;/url&gt;
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      &lt;id&gt;ibm-enterprise-maven-repository&lt;/id&gt;
      &lt;url&gt;https://maven.repository.ibm.com/releases/&lt;/url&gt;
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>

Add the following lines to the <activeProfiles> element of the settings.xml file and save the file.
```
&lt;activeProfile&gt;ibm-enterprise-maven-repository&lt;/activeProfile&gt;
```

Creating a IBM Enterprise Build of Quarkus project on the command line

Use the IBM Enterprise Build of Quarkus Maven plugin on the command line to create a Quarkus project by providing attributes and values on the command line or by using the plugin in interactive mode. You can also create a Quarkus project by using the Quarkus command-line interface (CLI). The resulting project includes the following elements:

The Maven structure
An associated unit test
A landing page that is accessible on http://localhost:8080 after you start the application
Example Dockerfile files for JVM and native mode in src/main/docker
The application configuration file

Prerequisites

You have installed OpenJDK 17 or 21.
- To download Red Hat build of OpenJDK, log in to the Red Hat Customer Portal and go to Software Downloads.
You have set the JAVA_HOME environment variable to specify the location of the Java SDK.
You have installed Apache Maven 3.9.9.
- To download Maven, go to the Apache Maven Project website.
Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to create a Quarkus project. For more information, see Installing the Quarkus CLI.

Note: The Quarkus CLI is intended for development purposes, including tasks such as creating, updating, and building Quarkus projects. However, IBM does not support using the Quarkus CLI in production environments.

Procedure

In a command terminal, enter the following command to verify that Maven is using OpenJDK 17 or 21 and that the Maven version is 3.9.9:
```
mvn --version
```
If the preceding command does not return OpenJDK 17 or 21, add the path to OpenJDK 17 or 21 to the PATH environment variable and enter the preceding command again.

To create a project, use one of the following methods:

Use the Quarkus Maven plugin. Enter the following command:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.27.1.redhat-00003:create \
    -DprojectGroupId=<project_group_id> \
    -DprojectArtifactId=<project_artifact_id> \
    -DplatformGroupId=com.redhat.quarkus.platform \
    -DplatformArtifactId=quarkus-bom \
    -DplatformVersion=3.27.1.redhat-00003
    -DpackageName=getting.started

In this command, replace the following values:

<project_group_id>: A unique identifier of your project
<project_artifact_id>: The name of your project and your project directory

Create the project in interactive mode:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.27.1.redhat-00003:create

When prompted, enter the required attribute values.

Note: You can also create your project by using the default values for the project attributes by entering the following command:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.27.1.redhat-00003:create -B

Use the Quarkus CLI. Enter the following command:
```
quarkus create app my-groupId:my-artifactId --package-name=getting.started
```
- You can also get the list of available options with:
  quarkus create app --help

Note: By default, the Quarkus Maven plugin uses the latest preferred quarkus-bom version. The quarkus-bom file aggregates extensions so that you can reference them from your applications to align the dependency versions. When you are offline, the Quarkus Maven plugin uses the latest preferred version of the quarkus-bom that it previously pulled from the Maven repository.

Creating a IBM Enterprise Build of Quarkus project by configuring the `pom.xml` file

You can use an existing Maven project to create a Quarkus project by configuring the Maven pom.xml file.

Procedure

Open the pom.xml file in a text editor.

Add the configuration properties that contain the following items:

The Maven Compiler plugin version
The Quarkus BOM groupID, artifactID, and version
The Maven Surefire plugin version
The skipITs property

<properties>
    <compiler-plugin.version>3.11.0</compiler-plugin.version>
    <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
    <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
    <quarkus.platform.version>3.27.1.redhat-00003</quarkus.platform.version>
    <surefire-plugin.version>3.1.2</surefire-plugin.version>
    <skipITs>true</skipITs>
</properties>

Add the Quarkus GAV (group, artifact, version) and use the quarkus-bom file to omit the versions of the different Quarkus dependencies:

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

Add the Quarkus Maven plugin, the Maven Compiler plugin, and the Maven Surefire plugin:

<build>
    <plugins>
        <plugin>
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.platform.version}</version>
            <extensions>true</extensions>
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                        <goal>generate-code</goal>
                        <goal>generate-code-tests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>${compiler-plugin.version}</version>
            <configuration>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
        <plugin>
            <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>
    </plugins>
</build>

Note: The maven-surefire-plugin runs the unit tests for your application.

Optional: To build a native application, add a specific native profile that includes the maven-failsafe-plugin:

<build>
    <plugins>
        ...
        <plugin>
            <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>
        <id>native</id>
        <activation>
            <property>
                <name>native</name>
            </property>
        </activation>
        <properties>
            <skipITs>false</skipITs>
            <quarkus.native.enabled>true</quarkus.native.enabled>
        </properties>
    </profile>
</profiles>

Tests that include IT in their names and contain the @QuarkusIntegrationTest annotation are run against the native executable.
For more details about how native mode differs from Java virtual machine (JVM) mode, see JVM and native building modes in the "Getting started with IBM Enterprise Build of Quarkus" guide.

Creating the Getting Started project by using code.quarkus.ibm.com

As an application developer, you can use the code.quarkus.ibm.com application to generate a Quarkus Maven project and automatically add and configure the extensions that you want to use in your application. In addition, code.quarkus.ibm.com automatically manages the configuration parameters that are required to compile your project into a native executable.

You can generate a Quarkus Maven project, including the following activities:

Specifying basic details about your application
Choosing the extensions that you want to include in your project
Generating a downloadable archive with your project files
Using custom commands for compiling and starting your application

Prerequisites

You have a web browser.
You have prepared your environment to use Apache Maven. For more information, see Preparing your environment.
You have configured your Quarkus Maven repository. To create a Quarkus application with Maven, use the IBM-hosted Quarkus repository that you configure in the $HOME/.m2/settings.xml file. For more information, see Configuring the Maven settings.xml file for the online repository.
Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to start Quarkus in dev mode.

For more information, see Installing the Quarkus CLI.

Procedure

On your web browser, go to https://code.quarkus.ibm.com.

From the list of available versions, the code.quarkus.ibm.com application selects the latest release of IBM Enterprise Build of Quarkus by default.

Note: The code.quarkus.ibm.com application uses the latest release of IBM Enterprise Build of Quarkus, which is the preferred option. However, after generating your project, you can manually change to an earlier BOM version in the pom.xml file if necessary, but the best practice is to keep the default.

Specify basic details about your project:
1. Enter a group name for your project. The name format follows the Java package naming convention; for example, org.acme.
2. Enter a name for the Maven artifacts generated by your project, such as code-with-quarkus.
3. Select the build tool you want to use to compile and start your application. The build tool that you choose determines the following setups:
  - The directory structure of your generated project
  - The format of configuration files that are used in your generated project
  - The custom build script and command for compiling and starting your application that code.quarkus.ibm.com displays for you after you generate your project
    
    Note: IBM provides support for using code.quarkus.ibm.com to create Quarkus Maven projects only.

Specify additional details about your application project:

To display the fields that contain further application details, select More options.
Enter a version you want to use for artifacts generated by your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is preferred; however, you can choose to specify a different versioning type.

Select whether you want code.quarkus.ibm.com to add starter code to your project. When you add extensions that are marked with "STARTER-CODE" to your project, you can enable this option to automatically create example class and resource files for those extensions when you generate your project. However, this option does not affect your generated project if you do not add any extensions that provide example code.

Note: The code.quarkus.ibm.com application automatically uses the latest release of IBM Enterprise Build of Quarkus. If necessary, you can manually change to an earlier BOM version in the pom.xml file after you generate your project, but the best practice is to keep the default.

Select the extensions that you want to use. The Quarkus application includes the extensions you select as dependencies. The Quarkus platform also ensures these extensions are compatible with future versions.

Important: Do not use the quarkus-rest and the quarkus-resteasy extensions in the same project. Both deliver similar capabilities, but how they operate is very different. Using quarkus-rest is preferred.

The quark icon () next to an extension indicates that the extension is part of the IBM Enterprise Build of Quarkus platform release. IBM prefers using extensions from the same platform because they are tested and verified together, making them easier to use and upgrade.

For extensions marked with "STARTER-CODE", you can enable the option to generate starter code automatically.

Screenshot of the list of extensions at the code.quarkus.ibm.com site that you can add to your project

To confirm your choices, select Generate your application. The dialog box that appears displays the following items:
- A link to download the archive that contains your generated project
- A command that you can use to compile and start your application
To save the archive with the generated project files to your machine, select Download the ZIP.
Extract the contents of the archive.

Verification

Compile and start your application in dev mode. For more information, see Compiling and starting the Quarkus Getting Started project.
Package and run your Getting Started project from the Quarkus CLI. For more information, see Packaging and running the Quarkus Getting Started application.

Additional resources

Support levels for IBM Enterprise Build of Quarkus extensions

Configuring the Java compiler

By default, the Quarkus Maven plugin passes compiler flags to javac command from maven-compiler-plugin.

Procedure

To customize the compiler flags used in development mode, add a configuration section to the plugin block and set the compilerArgs property. You can also set source, target, and jvmArgs. For example, to pass -verbose to the Java virtual machine (JVM) and javac commands, add the following configuration:

<plugin>
  <groupId>com.redhat.quarkus.platform</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.platform.version}</version>

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

  ...
</plugin>

Installing and managing extensions

In IBM Enterprise Build of Quarkus, you can use extensions to expand your application’s functionality and configure, boot, and integrate a framework into your application. This procedure shows you how to find and add extensions to your Quarkus project.

Prerequisites

You have created a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to manage your Quarkus extensions. For more information, see Installing the Quarkus CLI.

Procedure

Navigate to your Quarkus project directory.
List all of the available extensions in one of the following ways:
- Using Maven:
  ./mvnw quarkus:list-extensions
- Using the Quarkus CLI:
  quarkus extension --installable
Add an extension to your project by using one of the following methods:
- Using Maven, enter the following command where <extension> is the group, artifact, and version (GAV) of the extension that you want to add:
  ./mvnw quarkus:add-extension -Dextensions="<extension>"
  For example, to add the Agroal extension, enter the following command:
  ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-agroal"
- Using the Quarkus CLI, enter the following command where <extension> is the group, artifact, and version (GAV) of the extension that you want to add:
  quarkus extension add '<extension>'
To search for a specific extension, enter the extension name or partial name after -Dextensions=. The following example searches for extensions that contain the text agroal in the name:
```
./mvnw quarkus:add-extension -Dextensions=agroal
```
This command returns the following result:
```
[SUCCESS] ✅  Extension io.quarkus:quarkus-agroal has been installed
```
Similarly, with the Quarkus CLI, you might enter:
```
quarkus extension add 'agroal'
```

Importing your project into an IDE

Although you can develop your IBM Enterprise Build of Quarkus project in a text editor, you might find using an integrated development environment (IDE) easier. The following instructions guide you through importing your project into specific IDEs.

Prerequisites

You have a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which you can use to start your project in dev mode. For more information, see Installing the Quarkus CLI.

Procedure

Select the relevant procedure for your IDE.

CodeReady Studio or Eclipse

In CodeReady Studio or Eclipse, click File> Import.
Select Maven → Existing Maven Project.
Next, select the root location of the project. A list of the available modules appears.
Select the generated project, and click Finish.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

IntelliJ

In IntelliJ, complete one of the following tasks:
- Select File > New > Project From Existing Sources.
- On the Welcome page, select Import project.
Select the project root directory.
Select Import project from external model, and then select Maven.
Review the options, and then click Next.
Click Create.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Apache NetBeans

Select File > Open Project.
Select the project root directory.
Click Open Project.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Visual Studio Code

Install the Java Extension Pack.
In Visual Studio Code, open your project directory.

Verification

The project loads as a Maven project.

Configuring the IBM Enterprise Build of Quarkus project output

Before you build your application, you can control the build command output by changing the default values of the properties in the application.properties file.

Prerequisites

You have created a Quarkus Maven project.

Procedure

Go to the {project}/src/main/resources folder, and open the application.properties file in a text editor.

Add the properties that you want to change and save the file.

Table 1. Properties that you can change
Property	Description	Type	Default
`quarkus.native.enabled`	Enables native image generation. When set to `true`, the application is compiled into a native executable.	boolean	`false`
`quarkus.native.sources-only`	Generates only the native image sources without building the final native executable.	boolean	`false`
`quarkus.package.main-class`	Specifies the entry point of the application. In most cases, you must change this value.	string	`io.quarkus.runner.GeneratedMain`
`quarkus.package.jar.enabled`	Determines whether to build a JAR file. Set to `false` to prevent JAR creation.	boolean	`true`
`quarkus.package.jar.type`	Defines the type of JAR to build. Supported values are `fast-jar` (default), `uber-jar`, `mutable-jar`, and `legacy-jar` (deprecated). To prevent JAR generation entirely, set `quarkus.package.jar.enabled=false`.	string	`fast-jar`
`quarkus.package.type` (deprecated)	Deprecated. * Use `quarkus.package.jar.type` to configure the JAR type. * For native builds, set `quarkus.native.enabled` to `true`. * For native sources builds, also set `quarkus.native.sources-only` to `true`. * JAR building can be disabled by setting `quarkus.package.jar.enabled` to `false`.	string	`jar`
`quarkus.package.jar.manifest.add-implementation-entries`	Determines whether the implementation information is included in the runner JAR file’s `MANIFEST.MF`.	boolean	`true`
`quarkus.package.jar.user-configured-ignored-entries`	Specifies a list of files that must not be copied to the output artifact.	string (list)	(none)
`quarkus.package.runner-suffix`	Specifies the suffix applied to the runner JAR file.	string	`-runner`
`quarkus.package.output-directory`	Specifies the output folder for the application build. The path is resolved relative to the build system target directory.	string	(none)
`quarkus.package.output-name`	Specifies the name of the final build artifact.	string	(none)

Example: Configuring the application output name

You can customize the name of the application output by configuring the quarkus.package.output-name property in the application.properties file.

Open the src/main/resources/application.properties file.

Add the following property:

quarkus.package.output-name=my-quarkus-custom-app-name

Build the application:
```
./mvnw clean package
```
Verify that the resulting application JAR file is named:
```
my-quarkus-custom-app-name.jar
```

Customizing the output name helps align your build artifacts with your project conventions or deployment requirements.

Testing your IBM Enterprise Build of Quarkus application in JVM mode with a custom profile

Similar to any other running mode, configuration values for testing are read from the src/main/resources/application.properties file.

By default, the test profile is active during testing in Java virtual machine (JVM) mode, meaning that properties prefixed with %test take precedence. For example, when you run a test with the following configuration, the value returned for the property message is Test Value.

message=Hello
%test.message=Test Value

If the %test profile is inactive (dev, prod), the value returned for the property message is Hello.

For example, your application might require multiple test profiles to run a set of tests against different database instances. To do this, you must override the testing profile name, which can be done by setting the system property quarkus.test.profile when executing Maven. By doing so, you can control which sets of configuration values are active during the test.

To learn more about standard testing with the 'Starting With Quarkus' example, see Testing your IBM Enterprise Build of Quarkus application in the Getting started with IBM Enterprise Build of Quarkus guide.

Prerequisites

A Quarkus project created with Apache Maven.

Procedure

When running tests on a Quarkus application, the test configuration profile is set as active by default. However, you can change the profile to a custom profile by using the quarkus.test.profile system property.

Run the following command to test your application:
```
mvn test -Dquarkus.test.profile=<profile-name>
```

Note: You cannot use a custom test configuration profile in native mode. Native tests always run under the prod profile.

Logging the IBM Enterprise Build of Quarkus application build classpath tree

The Quarkus build process adds deployment dependencies of the extensions that you use in the application to the original application classpath. You can view the dependencies and versions included in the build classpath. The quarkus-maven-plugin Maven plugin includes the dependency-tree goal, which displays the build dependency tree for the application.

Prerequisites

You have created a Quarkus Maven application.

Procedure

To list the build dependency tree of your application, enter the following command:

./mvnw quarkus:dependency-tree

Example output. The exact output you see will differ from this example.

[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:3.27.1.redhat-00001 (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:3.27.1.redhat-00001 (compile)
[INFO]    │  ├─ io.quarkus:quarkus-resteasy-common-deployment:jar:3.27.1.redhat-00001 (compile)
[INFO]    │  │  ├─ io.quarkus:quarkus-resteasy-common:jar:3.27.1.redhat-00001 (compile)
[INFO]    │  │  │  ├─ org.jboss.resteasy:resteasy-core:jar:6.2.4.Final-redhat-00003 (compile)
[INFO]    │  │  │  │  ├─ jakarta.xml.bind:jakarta.xml.bind-api:jar:4.0.0.redhat-00008 (compile)
[INFO]    │  │  │  │  ├─ org.jboss.resteasy:resteasy-core-spi:jar:6.2.4.Final-redhat-00003 (compile)
[INFO]    │  │  │  │  ├─ org.reactivestreams:reactive-streams:jar:1.0.4.redhat-00003 (compile)
[INFO]    │  │  │  │  └─ com.ibm.async:asyncutil:jar:0.1.0.redhat-00010 (compile)
...

Note: The mvn dependency:tree command displays only the runtime dependencies of your application.

Producing a native executable

A native binary is an executable that is created to run on a specific operating system and CPU architecture.

The following list outlines some examples of a native executable:

An ELF binary for Linux AMD 64 bits
An EXE binary for Windows AMD 64 bits
An ELF binary for ARM 64 bits

Note: Only the ELF binary for Linux x86-64 or AArch64 bits is supported in IBM Enterprise Build of Quarkus.

One advantage of building a native executable is that your application and dependencies, including the Java Virtual Machine (JVM), are packaged into a single file. The native executable for your application contains the following items:

The compiled application code
The required Java libraries
A reduced version of the virtual machine (VM) for improved application startup times and minimal disk and memory footprint, which is also tailored for the application code and its dependencies

To produce a native executable from your Quarkus application, you can select either an in-container build or a local-host build. The following table explains the different building options that you can use:

Table 2. Building options for producing a native executable
Building option	Requires	Uses	Results in	Benefits
In-container build - Supported	A container runtime, for example, Podman or Docker	The default `registry.access.redhat.com/quarkus/mandrel-for-jdk-21-rhel8:23.1` builder image	A Linux 64-bit executable using the CPU architecture of the host	GraalVM does not need to be set up locally, which makes your CI pipelines run more efficiently
Local-host build - Only supported upstream	A local installation of GraalVM or Mandrel	Its local installation as a default for the `quarkus.native.builder-image` property	An executable that has the same operating system and CPU architecture as the machine on which the build is executed	An alternative for developers who are not allowed or do not want to use tools such as Docker or Podman. Overall, it is faster than the in-container build approach.

Important:

To build native Linux executables, IBM Enterprise Build of Quarkus supports using the Red Hat Build of Quarkus Native builder image (quarkus/mandrel-for-jdk-21-rhel8), which is based on GraalVM Mandrel.

While other images are available in the Quarkus community, the product does not support them. Use only supported images for production builds that require IBM support.
Applications whose source is written based on 17, with no Java 18 - 21 features used, can still compile a native executable of that application by using the Java 21-based Mandrel 23.1 base image.
IBM Enterprise Build of Quarkus does not support building native executables by using Oracle GraalVM Community Edition (CE), Mandrel community edition, or any other GraalVM distributions. For more information, see Compiling your IBM Enterprise Build of Quarkus applications to native executables.

Producing a native executable by using an in-container build

To create a native executable and run the native image tests, use the native profile that is provided by IBM Enterprise Build of Quarkus for an in-container build.

Prerequisites

Podman or Docker is installed.
The container has access to at least 8GB of memory.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to build a native executable. For more information, see Installing the Quarkus CLI.

Procedure

Open the Getting Started project pom.xml file, and verify that the project includes the native profile:

<profiles>
  <profile>
    <id>native</id>
    <activation>
      <property>
        <name>native</name>
      </property>
    </activation>
    <properties>
      <skipITs>false</skipITs>
      <quarkus.native.enabled>true</quarkus.native.enabled>
    </properties>
  </profile>
</profiles>

Build a native executable by using one of the following methods:

Using Maven:

For Docker:

./mvnw package -Dnative -Dquarkus.native.container-build=true

For Podman:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

Using the Quarkus CLI:

For Docker:

quarkus build --native -Dquarkus.native.container-build=true

For Podman:
```
quarkus build --native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
```
Step results

These commands create a *-runner binary in the target directory, where the following applies:
The *-runner file is the built native binary that Quarkus produces.

The target directory is a directory that Maven creates when you build a Maven application.

Important: Compiling a Quarkus application to a native executable consumes a large amount of memory during analysis and optimization. You can limit the amount of memory used during native compilation by setting the quarkus.native.native-image-xmx configuration property. Setting low memory limits might increase the build time.

To run the native executable, enter the following command:
```
./target/*-runner
```

Additional resources

Native executable configuration properties in the "Compiling your IBM Enterprise Build of Quarkus applications to native executables" guide.

Producing a native executable by using a local-host build

If you are not using Docker or Podman, use the Quarkus local-host build option to create and run a native executable.

Using the local-host build approach is faster than using containers and is suitable for machines that use a Linux operating system.

Important: IBM Enterprise Build of Quarkus does not support the use of the following procedure in production. Use this method only when testing or as a backup approach when Docker or Podman is not available.

Prerequisites

A local installation of Mandrel or GraalVm, correctly configured according to the Quarkus Building a native executable guide.
- Additionally, for a GraalVM installation, native-image must also be installed.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to build a native executable. For more information, see Installing the Quarkus CLI.

Procedure

For GraalVM or Mandrel, build a native executable by using one of the following methods:
- Using Maven:
  ./mvnw package -Dnative
- Using the Quarkus CLI:
  quarkus build --native
  Step results
  
  These commands create a *-runner binary in the target directory, where the following applies:
  - The *-runner file is the built native binary that Quarkus produces.
  - The target directory is a directory that Maven creates when you build a Maven application.
    
    Note: When you build the native executable, the prod profile is enabled unless modified in the quarkus.profile property.
Run the native executable:
```
./target/*-runner
```

Additional resources

For more information, see the Producing a native executable section of the Quarkus "Building a native executable" guide.

Creating a container manually

You can manually create a container image with your application for Linux AMD64. When you produce a native image by using the Quarkus Native container, the native image creates an executable that targets Linux AMD64. If your host operating system is different from Linux AMD64, you cannot run the binary directly and need to create a container manually.

Your Quarkus Getting Started project includes a Dockerfile.native in the src/main/docker directory with the following content:

FROM registry.access.redhat.com/ubi9-minimal:9.5
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application

EXPOSE 8080
USER 1001

ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

Note: .Universal Base Image (UBI)

The following list displays the suitable images for use with Dockerfiles.

IBM Universal Base Image 9 (UBI9). This base image is designed and engineered as the base layer for containerized applications, middleware, and utilities.
```
registry.access.redhat.com/ubi9/ubi:9.5
```
IBM Universal Base Image 9 Minimal (UBI9-minimal). A stripped-down UBI9 image that uses microdnf as a package manager.
```
registry.access.redhat.com/ubi9-minimal:9.5
```
All IBM Base images are available on the Container images catalog site.

Procedure

Build a native Linux executable by using one of the following methods:

Docker:

./mvnw package -Dnative -Dquarkus.native.container-build=true

Podman:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

Build the container image by using one of the following methods:

Docker:

docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

Podman

podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

Run the container by using one of the following methods:

Docker:

docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

Podman:

podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

Testing the native executable

Test the application in native mode to test the functionality of the native executable. Use the @QuarkusIntegrationTest annotation to build the native executable and run tests against the HTTP endpoints.

Important: The following example shows how to test a native executable with a local installation of GraalVM or Mandrel. Before you begin, consider the following points:

IBM Enterprise Build of Quarkus does not support this scenario, as outlined in Producing a native executable.
The native executable you are testing with here must match the operating system and architecture of the host. Therefore, this procedure does not work if the native binary is built in a container on macOS.

Procedure

Open the pom.xml file and verify that the build section has the following elements:

<plugin>
    <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>

The Maven Failsafe plugin (maven-failsafe-plugin) runs the integration test and indicates the location of the native executable that is generated.

Open the src/test/java/org/acme/GreetingResourceIT.java file and verify that it includes the following content:

package org.acme;

import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest (1)
public class GreetingResourceIT extends GreetingResourceTest { (2)

    // Execute the same tests but in native mode.
}

1	Use another test runner that starts the application from the native file before the tests. The executable is retrieved by using the `native.image.path` system property configured in the Maven Failsafe plugin.
2	This example extends the `GreetingResourceTest`, but you can also create a new test.

Run the test:

./mvnw verify -Dnative

The following example shows the output of this command:

./mvnw verify -Dnative
....

GraalVM Native Image: Generating 'getting-started-1.0.0-SNAPSHOT-runner' (executable)...
========================================================================================================================
[1/8] Initializing...                                                                                    (6.6s @ 0.22GB)
 Java version: 21.0.4+7-LTS, vendor version: Mandrel-23.1.9.0-1b2
 Graal compiler: optimization level: 2, target machine: x86-64-v3
 C compiler: gcc (redhat, x86_64, 13.2.1)
 Garbage collector: Serial GC (max heap size: 80% of RAM)
 2 user-specific feature(s)
 - io.quarkus.runner.Feature: Auto-generated class by Quarkus from the existing extensions
 - io.quarkus.runtime.graal.DisableLoggingFeature: Disables INFO logging during the analysis phase
[2/8] Performing analysis...  [******]                                                                  (40.0s @ 2.05GB)
  10,318 (86.40%) of 11,942 types reachable
  15,064 (57.36%) of 26,260 fields reachable
  52,128 (55.75%) of 93,501 methods reachable
   3,298 types,   109 fields, and 2,698 methods registered for reflection
      63 types,    68 fields, and    55 methods registered for JNI access
       4 native libraries: dl, pthread, rt, z
[3/8] Building universe...                                                                               (5.9s @ 1.31GB)
[4/8] Parsing methods...      [**]                                                                       (3.7s @ 2.08GB)
[5/8] Inlining methods...     [***]                                                                      (2.0s @ 1.92GB)
[6/8] Compiling methods...    [******]                                                                  (34.4s @ 3.25GB)
[7/8] Layouting methods...    [**]                                                                       (4.1s @ 1.78GB)
[8/8] Creating image...       [**]                                                                       (4.5s @ 2.31GB)
  20.93MB (48.43%) for code area:    33,233 compilation units
  21.95MB (50.80%) for image heap:  285,664 objects and 8 resources
 337.06kB ( 0.76%) for other data
  43.20MB in total

....


[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:integration-test (default) @ getting-started ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.GreetingResourceIT
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2024-09-27 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Quarkus 3.27.1.redhat-00001) started in 0.038s. Listening on: http://0.0.0.0:8081
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.696 s - in org.acme.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:verify (default) @ getting-started ---

Note: Quarkus waits 60 seconds for the native image to start before automatically failing the native tests. You can change this duration by configuring the quarkus.test.wait-time system property.

You can extend the wait time by using the following command, where <duration> is the wait time in seconds:

./mvnw verify -Dnative -Dquarkus.test.wait-time=<duration>

Note:

By default, native tests run by using the prod profile unless modified in the quarkus.test.integration-test-profile property.

Using IBM Enterprise Build of Quarkus development mode

Development (dev) mode enables hot deployment with background compilation, which means that when you modify your Java or resource files and then refresh your browser, the changes take effect immediately. This also applies to resource files, such as the configuration property file. You can use either Maven or the Quarkus command-line interface (CLI) to start Quarkus in development mode.

Prerequisites

You have created a Quarkus Maven application.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to start Quarkus in development mode. For more information, see Installing the Quarkus CLI.

Procedure

Switch to the directory that contains your Quarkus application pom.xml file.
To compile and start your Quarkus application in development mode, use one of the following methods:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev
Make changes to your application and save the files.
Refresh the browser to trigger a scan of the workspace.

If any changes are detected, the Java files are recompiled and the application is redeployed. The redeployed application then services your request. If there are any issues with compilation or deployment, an error page appears.

In development mode, the debugger is activated and listens on port 5005.
Optional: To wait for the debugger to attach before running the application, include -Dsuspend:
```
./mvnw quarkus:dev -Dsuspend
```
Optional: To prevent the debugger from running, include -Ddebug=false:
```
./mvnw quarkus:dev -Ddebug=false
```

Debugging your IBM Enterprise Build of Quarkus project

When IBM Enterprise Build of Quarkus starts in development mode, debugging is enabled by default, and the debugger listens on port 5005 without suspending the JVM. You can enable and configure the debugging feature of Quarkus from the command line or by configuring the system properties. You can also use the Quarkus CLI to debug your project.

Prerequisites

You have created a IBM Enterprise Build of Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to compile and debug your project. For more information, see Installing the Quarkus CLI.

Procedure

Use one of the following methods to control debugging:

Controlling the debugger by configuring system properties

Change one of the following values of the debug system property, where PORT is the port that the debugger is listening on:
- false: The JVM starts with debug mode disabled.
- true: The JVM starts in debug mode and is listening on port 5005.
- client: The JVM starts in client mode and tries to connect to localhost:5005.
- PORT: The JVM starts in debug mode and is listening on PORT.
To suspend the JVM while running in debug mode, set the value of the suspend system property to one of the following values:
- y or true: The debug mode JVM launch suspends.
- n or false: The debug mode JVM starts without suspending.

Controlling the debugger from the command line

To compile and start your Quarkus application in debug mode with a suspended JVM, use one of the following methods:
- Using Maven:
  ./mvnw quarkus:dev -Dsuspend
- Using the Quarkus CLI:
  quarkus dev --suspend

Enabling the debugger for specific host network interfaces

In development mode, by default, for security reasons, Quarkus sets the debug host interface to localhost.

To enable the debugger for a specific host network interface, you can use the -DdebugHost option by using one of the following methods:

Using Maven:

./mvnw quarkus:dev -DdebugHost=<host-ip-address>

Using the Quarkus CLI:

quarkus dev --debug-host=<host-ip-address>

Where <host-ip-address> is the IP address of the host network interface that you want to enable debugging on.

Note: To enable debugging on all host interfaces, replace <host-ip-address> with the following value:

0.0.0.0

Additional resources

Revised on 2025-12-17 15:50:34 UTC