Developing and compiling your Quarkus applications with Apache Maven

Procedure

1. In a command terminal, enter the following command to verify that Maven is using JDK 11 and that the Maven version is 3.6.3 or higher:

   mvn --version

   Copy to Clipboard Toggle word wrap
2. If the preceding command does not return JDK 11, add the path to JDK 11 to the PATH environment variable and enter the preceding command again.

3. To use the Quarkus Maven plug-in to create a new project, use one of the following methods:

   • Enter the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformArtifactId=quarkus-universe-bom \
         -DplatformVersion=1.7.6.Final-redhat-00014 \
         -DclassName="<classname>"

     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
     • <classname>: The fully qualified name of the generated resource, for example org.acme.quarkus.sample.HelloResource

   • Create the project in interactive mode:

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create

     Copy to Clipboard Toggle word wrap

     When prompted, enter the required attribute values.

     Note

     Alternatively, you can create your project using the default values for the project attributes by entering the following command:

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create -B

     The following table lists the attributes that you can define with the create command:

     Expand

     Attribute	Default Value	Description
     projectGroupId	org.acme.sample	A unique identifier of your project.
     projectArtifactId	none	The name of your project and your project directory. If you do not specify the projectArtifactId, the Maven plug-in starts the interactive mode. If the directory already exists, the generation fails.
     projectVersion	1.0-SNAPSHOT	The version of your project.
     platformGroupId	io.quarkus	The group id of your platform. All the existing platforms are provided by io.quarkus. However, you can change the default value.
     platformArtifactId	quarkus-universe-bom	The artifact id of your platform BOM. To use the locally built Quarkus add quarkus-universe-bom to your pom.xml file.
     platformVersion	The latest platform version	The version of the platform you want to use for your project. You can provide a version range and the Maven plug-in uses the latest version.
     className	None	The fully qualified name of the generated resource. After the application is created, the REST endpoint is exposed at the following URL: http://localhost:8080/$path If you use the default path, the URL is http://localhost:8080/hello.
     path	/hello	The resource path, only if you set the className.
     extensions	[]	The list of extensions you want to add to your project separated by comma.

     Show more

Procedure

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

2. Add the Quarkus GAV (group, artifact, version) and use the quarkus-universe-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-plugin.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>

   Copy to Clipboard Toggle word wrap

3. Add the Quarkus Maven plug-in:

   <build>
       <plugins>
           <plugin>
               <groupId>io.quarkus</groupId>
               <artifactId>quarkus-maven-plugin</artifactId>
               <version>${quarkus-plugin.version}</version>
               <executions>
                   <execution>
                       <goals>
                           <goal>build</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>

   Copy to Clipboard Toggle word wrap

4. Optional: To build a native application, add a specific native profile that includes the Maven Surefire and Maven Failsafe plug-ins and enable the native package type:

   <profiles>
       <profile>
           <id>native</id>
           <properties>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
           <build>
               <plugins>
                   <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>
                                   <systemProperties>
                                       <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                                   </systemProperties>
                               </configuration>
                           </execution>
                       </executions>
                   </plugin>
               </plugins>
           </build>
       </profile>
   </profiles>

   Copy to Clipboard Toggle word wrap

   Tests that include IT in their names are annotated @NativeImageTest are run against the native executable.

Procedure

1. Navigate to your Quarkus project directory.

2. To list the available extensions, enter the following command:

   ./mvnw quarkus:list-extensions

   Copy to Clipboard Toggle word wrap

3. To add an extension to your project, enter the following command where <extension> is the group, artifact, 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

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 jdbc, agroal, and non-exist-ent in the name:

   ./mvnw quarkus:add-extension -Dextensions=jdbc,agroal,non-exist-ent

   Copy to Clipboard Toggle word wrap

   This command returns the following result:

   ❌ 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?
   [...]

   Copy to Clipboard Toggle word wrap

5. To install all extensions that a specific text string returns, enter the extension name or partial name after -Dextensions=. The following example searches for and installs all extensions that begin with hibernate-:

   ./mvnw quarkus:add-extension -Dextensions="hibernate-*"

   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. On the next screen, select the root location of the project. A list of the found modules appears.
4. Select the generated project and click Finish.

5. To start your application, enter the following command in a new terminal window:

   ./mvnw compile 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 Finish.

6. To start your application, enter the following command in a new terminal window:

   ./mvnw compile 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. To start your application, enter the following command in a new terminal window:

   ./mvnw compile 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. The project loads as a Maven project.

Procedure

1. Open the application.properties file in a text editor.

2. Edit the values of properties that you want to change and save the file.

   The following table list the properties that you can change:

   Expand

   Property	Description	Type	Default
   quarkus.package.main-class	The entry point of the application. In most cases, you should change this value.	string	io.quarkus.runner.GeneratedMain
   quarkus.package.type	The requested output type.	string	jar
   quarkus.package.uber-jar	Whether or not the Java runner should be packed as an uber-JAR.	boolean	false
   quarkus.package.manifest.add-implementation-entries	Whether or not the implementation information should be included in the runner JAR file’s MANIFEST.MF file.	boolean	true
   quarkus.package.user-configured-ignored-entries	Files that should not be copied to the output artifact.	string (list)
   quarkus.package.runner-suffix	The suffix that is applied to the runner JAR file.	string	-runner
   quarkus.package.output-directory	The output folder for the application build. This is resolved relative to the build system target directory.	string
   quarkus.package.output-name	The name of the final artifact.	string

   Show more

Procedure

1. Add the plug-in configuration to the pom.xml file:

   <project>
       [...]
         <plugin>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-bootstrap-maven-plugin</artifactId>
             <version>${quarkus-plugin.version}</version>
         </plugin>
       [...]
   </project>

   Copy to Clipboard Toggle word wrap

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

   ./mvnw quarkus-bootstrap:build-tree

   Copy to Clipboard Toggle word wrap

3. The output of this command should be similar to the following example:

   [INFO] --- quarkus-bootstrap-maven-plugin:1.7:build-tree (default-cli) @ getting-started ---
   [INFO] org.acme:getting-started:jar:1.0-SNAPSHOT
   [INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:1.7 (compile)
   [INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:1.7 (compile)
   [INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:1.7 (compile)
   [INFO]    │  │  ├─ commons-beanutils:commons-beanutils:jar:1.9.3 (compile)
   [INFO]    │  │  │  ├─ commons-logging:commons-logging:jar:1.2 (compile)
   [INFO]    │  │  │  └─ commons-collections:commons-collections:jar:3.2.2 (compile)
   ...

   Copy to Clipboard Toggle word wrap

Procedure

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

   <profiles>
       <profile>
           <id>native</id>
           <properties>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
       </profile>
   </profiles>

   Copy to Clipboard Toggle word wrap
   Note

   Using Quarkus native profile allows you to run both the native executable and the native image tests.

2. Build a native executable using one of the following methods:

   1. Build a native executable with Docker:

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

      Copy to Clipboard Toggle word wrap

   2. Build a native executable with Podman:

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

      Copy to Clipboard Toggle word wrap

      These commands create the getting-started-*-runner binary in the target directory.

      Important

      Compiling a Quarkus application to a native executable consumes a lot 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.

3. Run the native executable:

   ./target/getting-started-*-runner

   Copy to Clipboard Toggle word wrap

   When you build the native executable the prod profile is enabled and the Quarkus native tests run using the prod profile. You can change this using the quarkus.test.native-image-profile property.

Procedure

1. Open the pom.xml file and verify that the native profile contains 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 failsafe-maven-plugin runs integration test and indicates the location of the produced native executable.

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

   package org.acme.quickstart;
   
   
   import io.quarkus.test.junit.NativeImageTest;
   
   @NativeImageTest 

   1

   
   public class NativeGreetingResourceIT extends GreetingResourceTest { 

   2

   
   
       // Run the same tests
   
   }

   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 using the native.image.path system property configured in the Failsafe Maven Plugin.

   2

   This example extends the GreetingResourceTest, but you can also create a new test.

3. Run the test:

   ./mvnw verify -Pnative

   Copy to Clipboard Toggle word wrap

   The following example shows the output of this command:

   ./mvnw verify -Pnative
   ...
   [getting-started-1.0-SNAPSHOT-runner:18820]     universe:     587.26 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      (parse):   2,247.59 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]     (inline):   1,985.70 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]    (compile):  14,922.77 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      compile:  20,361.28 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        image:   2,228.30 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        write:     364.35 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      [total]:  52,777.76 ms
   [INFO]
   [INFO] --- maven-failsafe-plugin:2.22.1:integration-test (default) @ getting-started ---
   [INFO]
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running org.acme.quickstart.NativeGreetingResourceIT
   Executing [/data/home/gsmet/git/quarkus-quickstarts/getting-started/target/getting-started-1.0-SNAPSHOT-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=build/quarkus.log]
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 0.002s. Listening on: http://[::]:8081
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.387 s - in org.acme.quickstart.NativeGreetingResourceIT
   ...

   Copy to Clipboard Toggle word wrap
   Note

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

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

   ./mvnw verify -Pnative -Dquarkus.test.native-image-wait-time=<duration>

   Copy to Clipboard Toggle word wrap

Procedure

1. To start Quarkus in development mode, enter the following command in the directory that contains your Quarkus application pom.xml file:

   ./mvnw quarkus:dev

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

3. 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. Your request is then serviced by the redeployed application. 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.

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

   ./mvnw quarkus:dev -Dsuspend

   Copy to Clipboard Toggle word wrap

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

   ./mvnw quarkus:dev -Ddebug=false

   Copy to Clipboard Toggle word wrap

Control the debugger through 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. Change the value of the suspend system property. This property is used when Quarkus starts in debug mode.

   • y or true: The debug mode JVM launch suspends.
   • n or false: The debug mode JVM starts without suspending.

Control the debugger from the command line

1. To start your Quarkus application in debug mode with JVM, enter the following command:

   ./mvnw compile quarkus:dev -Ddebug

   Copy to Clipboard Toggle word wrap
2. Attach a debugger to localhost:5005.