Developing and compiling your Red Hat build of Quarkus applications with Apache Maven

Procedure

1. 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

   Copy to Clipboard Toggle word wrap
2. 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.

3. 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.0.redhat-00002:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus.platform \
         -DplatformArtifactId=quarkus-bom \
         -DplatformVersion=3.27.0.redhat-00002
         -DpackageName=getting.started

     Copy to Clipboard Toggle word wrap

     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.0.redhat-00002:create

     Copy to Clipboard Toggle word wrap

     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.0.redhat-00002:create -B

   • Use the Quarkus CLI. Enter the following command:

     quarkus create app my-groupId:my-artifactId --package-name=getting.started

     Copy to Clipboard Toggle word wrap

     • You can also get the list of available options with:

       quarkus create app --help

       Copy to Clipboard Toggle word wrap

Procedure

1. Open the pom.xml file in a text editor.

2. 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.0.redhat-00002</quarkus.platform.version>
       <surefire-plugin.version>3.1.2</surefire-plugin.version>
       <skipITs>true</skipITs>
   </properties>

   Copy to Clipboard Toggle word wrap

3. 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>

   Copy to Clipboard Toggle word wrap

4. 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>

   Copy to Clipboard Toggle word wrap
   Note

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

5. 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>

   Copy to Clipboard Toggle word wrap
   • 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 Red Hat build of Quarkus" guide.

Procedure

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

2. From the list of available versions, the code.quarkus.redhat.com application selects the latest release of Red Hat build of Quarkus by default.

   Note

   The code.quarkus.redhat.com application uses the latest release of Red Hat 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.

3. Specify basic details about your project:

   

   View larger image

   
   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.redhat.com displays for you after you generate your project

        Note

        Red Hat provides support for using code.quarkus.redhat.com to create Quarkus Maven projects only.

4. Specify additional details about your application project:

   1. To display the fields that contain further application details, select More options.

      

      View larger image

      
   2. 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.

   3. Select whether you want code.quarkus.redhat.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.redhat.com application automatically uses the latest release of Red Hat 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.

5. 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 Red Hat build of Quarkus platform release. Red Hat 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.

   

6. 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
7. To save the archive with the generated project files to your machine, select Download the ZIP.
8. Extract the contents of the archive.

Verification

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

Procedure

1. Navigate to your Quarkus project directory.

2. List all of the available extensions in one of the following ways:

   • Using Maven:

     ./mvnw quarkus:list-extensions

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus extension --installable

     Copy to Clipboard Toggle word wrap

3. 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>"

     Copy to Clipboard Toggle word wrap

     For example, to add the Agroal extension, enter the following command:

     ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-agroal"

     Copy to Clipboard Toggle word wrap

   • 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>'

     Copy to Clipboard Toggle word wrap

4. 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

   Copy to Clipboard Toggle word wrap

   This command returns the following result:

   [SUCCESS] ✅  Extension io.quarkus:quarkus-agroal has been installed

   Copy to Clipboard Toggle word wrap

   Similarly, with the Quarkus CLI, you might enter:

   quarkus extension add 'agroal'

   Copy to Clipboard Toggle word wrap

CodeReady Studio or Eclipse

1. In CodeReady Studio or Eclipse, click File> Import.
2. Select Maven → Existing Maven Project.
3. Next, select the root location of the project. A list of the available modules appears.
4. Select the generated project, and click Finish.

5. Compile and start your application in one of the following ways:

   • Using Maven:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus dev

     Copy to Clipboard Toggle word wrap

IntelliJ

1. In IntelliJ, complete one of the following tasks:

   • Select File > New > Project From Existing Sources.
   • On the Welcome page, select Import project.
2. Select the project root directory.
3. Select Import project from external model, and then select Maven.
4. Review the options, and then click Next.
5. Click Create.

6. Compile and start your application in one of the following ways:

   • Using Maven:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus dev

     Copy to Clipboard Toggle word wrap

Apache NetBeans

1. Select File > Open Project.
2. Select the project root directory.
3. Click Open Project.

4. Compile and start your application in one of the following ways:

   • Using Maven:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus dev

     Copy to Clipboard Toggle word wrap

Visual Studio Code

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

Procedure

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

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

   Expand

   Table 1.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)

   Show more

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

2. Add the following property:

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

   Copy to Clipboard Toggle word wrap

3. Build the application:

   ./mvnw clean package

   Copy to Clipboard Toggle word wrap

4. Verify that the resulting application JAR file is named:

   my-quarkus-custom-app-name.jar

   Copy to Clipboard Toggle word wrap

1. Run the following command to test your application:

Procedure

1. 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>

   Copy to Clipboard Toggle word wrap
   • The Maven Failsafe plugin (maven-failsafe-plugin) runs the integration test and indicates the location of the native executable that is generated.

2. 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.
   }

   Copy to Clipboard Toggle word wrap

   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.

3. Run the test:

   ./mvnw verify -Dnative

   Copy to Clipboard Toggle word wrap

   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.4.0-1b1
    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 Red Hat build of 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.0.redhat-00002) 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 ---

   Copy to Clipboard Toggle word wrap
   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>

   Copy to Clipboard Toggle word wrap
   Note
   • By default, native tests run by using the prod profile unless modified in the quarkus.test.integration-test-profile property.

Procedure

1. Switch to the directory that contains your Quarkus application pom.xml file.

2. To compile and start your Quarkus application in development mode, use one of the following methods:

   • Using Maven:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus dev

     Copy to Clipboard Toggle word wrap
3. Make changes to your application and save the files.

4. 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.

5. Optional: To wait for the debugger to attach before running the application, include -Dsuspend:

   ./mvnw quarkus:dev -Dsuspend

   Copy to Clipboard Toggle word wrap

6. Optional: To prevent the debugger from running, include -Ddebug=false:

   ./mvnw quarkus:dev -Ddebug=false

   Copy to Clipboard Toggle word wrap

Controlling the debugger by configuring system properties

1. 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.

2. 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.