mvn io.quarkus.platform:quarkus-maven-plugin:3.15.1:create \
-DprojectGroupId=my-groupId \
-DprojectArtifactId=my-artifactId
projectArtifactId
mandatory
The artifact id of the created project. Not passing it triggers the interactive mode.
projectVersion
1.0.0-SNAPSHOT
The version of the created project
platformGroupId
io.quarkus.platform
The group id of the target platform.
platformArtifactId
quarkus-bom
The artifact id of the target platform BOM.
platformVersion
The version currently recommended by the
Quarkus Extension Registry
The version of the platform you want the project to use. It can also accept a version range, in which case the latest from the specified range will be used.
javaVersion
The version of Java you want the project to use.
className
Not created if omitted
The fully qualified name of the generated resource
/hello
The resource path, only relevant if
className
is set.
extensions
The list of extensions to add to the project (comma-separated)
quarkusRegistryClient
Whether Quarkus should use the online registry to resolve extension catalogs. If this is set to false, the extension catalog will be narrowed to the defined (or default) platform BOM.
By default, the command will target the
io.quarkus.platform:quarkus-bom:3.15.1
platform release (unless the coordinates of the desired platform release have been specified).
The project is generated in a directory named after the passed artifactId.
If the directory already exists, the generation fails.
A pair of Dockerfiles for native and jvm mode are also generated in
src/main/docker
.
Instructions to build the image and run the container are written in those Dockerfiles.
The extension name is the GAV name of the extension: e.g.,
io.quarkus:quarkus-agroal
.
However, you can pass a partial name, and Quarkus will do its best to find the right extension.
For example,
agroal
,
Agroal
, or
agro
will expand to
io.quarkus:quarkus-agroal
.
If no extension is found or more than one extension matches, you will see a red check mark ❌ in the command result.
$ ./mvnw quarkus:add-extensions -Dextensions=jdbc,agroal,non-exist-ent
[...]
❌ Multiple extensions matching 'jdbc'
* io.quarkus:quarkus-jdbc-h2
* io.quarkus:quarkus-jdbc-mariadb
* io.quarkus:quarkus-jdbc-postgresql
Be more specific e.g using the exact name or the full gav.
✅ Adding extension io.quarkus:quarkus-agroal
❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
[...]
You can install all extensions which match a globbing pattern :
quarkus extension add smallrye-*
Maven
./mvnw quarkus:add-extension -Dextensions='smallrye-*'
The Quarkus Maven plugin makes use of
javac
,
and by default it picks up compiler flags to pass to
javac
from
maven-compiler-plugin
.
If you need to customize the compiler flags used by the plugin, like in
development mode
, add a
configuration
section to the
plugin
block and set the
compilerArgs
property just as you would when configuring
maven-compiler-plugin
.
You can also set
source
,
target
, and
jvmArgs
.
For example, to pass
--enable-preview
to both the JVM and
javac
:
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<configuration>
<source>${maven.compiler.source}</source>
<target>${maven.compiler.target}</target>
<compilerArgs>
<arg>--enable-preview</arg>
</compilerArgs>
<jvmArgs>--enable-preview</jvmArgs>
</configuration>
</plugin>
Because the Quarkus Maven plugin itself runs in the JVM started by Maven,
and because some (rare) Quarkus extensions need to load application classes during the build,
it may be necessary to pass the same flags to the JVM running Maven.
To that end, you can use
MAVEN_OPTS
:
MAVEN_OPTS='--enable-preview' quarkus build
Maven
MAVEN_OPTS='--enable-preview' ./mvnw install
Alternatively
, you can simply create the file
.mvn/jvm.config
at the root of your project:
and any options you put in that file will be picked up by Maven, without having to set
MAVEN_OPTS
.
You can then update the application sources, resources and configurations.
The changes are automatically reflected in your running application.
This is great to do development spanning UI and database as you see changes reflected immediately.
Dev mode enables hot deployment with background compilation, which means
that when you modify your Java files or your resource files and refresh your browser these changes will automatically take effect.
This works too for resource files like the configuration property file.
The act of
refreshing the browser triggers a scan of the workspace, and if any changes are detected the Java files are compiled,
and the application is redeployed, then your request is serviced by the redeployed application. If there are any issues
with compilation or deployment an error page will let you know.
使用
CTRL+C
来停止应用程序。
By default,
quarkus:dev
sets the debug host to
localhost
(for security reasons). If you need to change this, for example to enable debugging on all hosts, you can use the
-DdebugHost
option like so:
quarkus dev -DdebugHost=0.0.0.0
Maven
./mvnw quarkus:dev -DdebugHost=0.0.0.0
It is possible to use development mode remotely, so that you can run Quarkus in a container environment (such as OpenShift)
and have changes made to your local files become immediately visible.
This allows you to develop in the same environment you will actually run your app in, and with access to the same services.
This tells Quarkus to use the mutable-jar format. Mutable applications also include the deployment time parts of Quarkus,
so they take up a bit more disk space. If run normally they start just as fast and use the same memory as an immutable application,
however they can also be started in dev mode.
The password that is used to secure communication between the remote side and the local side.
The URL that your app is going to be running in dev mode at. This is only needed on the local side, so you
may want to leave it out of the properties file and specify it as a system property on the command line.
The
mutable-jar
is then built in the same way that a regular Quarkus jar is built, i.e. by issuing:
quarkus build
Maven
./mvnw install
Before you start Quarkus on the remote host set the environment variable
QUARKUS_LAUNCH_DEVMODE=true
. If you are
on bare metal you can set it via the
export QUARKUS_LAUNCH_DEVMODE=true
command and then run the application with the proper
java -jar …
command to run the application.
If you plan on running the application via Docker, then you’ll need to add
-e QUARKUS_LAUNCH_DEVMODE=true
to the
docker run
command.
When the application starts you should now see the following line in the logs:
Profile dev activated. Live Coding activated
. You will also need to give the application the rights to update the deployment resources by adding
RUN chmod o+rw -R /deployments
after the
COPY
commands into your Dockerfile. For security reasons, this option should not be added to the production Dockerfile.
The remote side does not need to include Maven or any other development tools. The normal
fast-jar
Dockerfile
that is generated with a new Quarkus application is all you need. If you are using bare metal launch the Quarkus runner
jar, do not attempt to run normal dev mode.
Now every time you refresh the browser you should see any changes you have made locally immediately visible in the remote
app. This is done via an HTTP based long polling transport, that will synchronize your local workspace and the remote
application via HTTP calls.
If you do not want to use the HTTP feature then you can simply run the
remote-dev
command without specifying the URL.
In this mode the command will continuously rebuild the local application, so you can use an external tool such as odo or
rsync to sync to the remote application.
All the config options are shown below:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Whether Quarkus should enable its ability to not do a full restart when changes to classes are compatible with JVM instrumentation. If this is set to true, Quarkus will perform class redefinition when possible.
Environment variable:
QUARKUS_LIVE_RELOAD_INSTRUMENTATION
The names of additional resource files to watch for changes, triggering a reload on change. Directories are
not
supported.
Environment variable:
QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES
The amount of time to wait between attempts when connecting to the server side of remote dev
Environment variable:
QUARKUS_LIVE_RELOAD_RETRY_INTERVAL
About the Duration format
To write duration values, use the standard
java.time.Duration
format.
See the
Duration#parse() Java API documentation
for more information.
You can also use a simplified format, starting with a number:
It is recommended you use SSL when using remote dev mode, however even if you are using an unencrypted connection
your password is never sent directly over the wire. For the initial connection request the password is hashed with the
initial state data, and subsequent requests hash it with a random session id generated by the server and any body contents
for POST requests, and the path for DELETE requests, as well as an incrementing counter to prevent replay attacks.
In development mode, Quarkus starts by default with debug mode enabled, listening to port
5005
without suspending the JVM.
This behavior can be changed by giving the
debug
system property one of the following values:
Once you have a
project generated
, you can import it in your favorite IDE.
The only requirement is the ability to import a Maven project.
Eclipse
In Eclipse, click on:
File → Import
.
In the wizard, select:
Maven → Existing Maven Project
.
On the next screen, select the root location of the project.
The next screen list the found modules; select the generated project and click on
Finish
. Done!
In a separated terminal, run:
quarkus dev
Maven
./mvnw quarkus:dev
and enjoy a highly productive environment.
IntelliJ IDEA
In IntelliJ IDEA:
From inside IntelliJ IDEA select
File → New → Project From Existing Sources…
or, if you are on the welcome dialog, select
Import project
.
Select the project root
Select
Import project from external model
and
Maven
Next a few times (review the different options if needed)
On the last screen click on Finish
Usually, dependencies of an application (which is a Maven project) could be displayed using
mvn dependency:tree
command. In case of a Quarkus application, however, this command will list only the runtime dependencies of the application.
Given that the Quarkus build process adds deployment dependencies of the extensions used in the application to the original application classpath, it could be useful to know which dependencies and which versions end up on the build classpath.
Luckily, the
quarkus
Maven plugin includes the
dependency-tree
goal which displays the build dependency tree for the application.
Executing
./mvnw quarkus:dependency-tree
on your project should result in an output similar to:
[INFO] --- quarkus-maven-plugin:3.15.1:dependency-tree (default-cli) @ getting-started ---
[INFO] org.acme:getting-started:jar:1.0.0-SNAPSHOT
[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:3.15.1 (compile)
[INFO] ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:3.15.1 (compile)
[INFO] │ ├─ io.quarkus:quarkus-core-deployment:jar:3.15.1 (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)
The goal accepts the following optional parameters:
mode - the default value is prod, i.e. the production build dependency tree. Alternatively, it accepts values test to display the test dependency tree and dev to display the dev mode dependency tree;
outputFile - specifies the file to persist the dependency tree to;
appendOutput - the default value is false, indicates whether the output to the command should be appended to the file specified with the outputFile parameter or it should be overridden.
Quarkus extension dependencies are divided into the runtime extension dependencies that end up on the application runtime classpath and the deployment (or build time) extension dependencies that are resolved by Quarkus only at application build time to create
the build classpath. Application developers are expected to express dependencies only on the runtime artifacts of Quarkus extensions. As a consequence, the deployment extension dependencies aren’t visible to Maven plugins that aren’t aware of the Quarkus
extension dependency model, such as the maven-dependency-plugin, go-offline-maven-plugin, etc. That means those plugins can not be used to pre-download all the application dependencies to be able to build and test the application later in offline mode.
To enable the use-case of building and testing a Quarkus application offline, the quarkus-maven-plugin includes the go-offline goal that could be called from the command line like this:
./mvnw quarkus:go-offlineThis goal will resolve all the runtime, build time, test and dev mode dependencies of the application downloading them to the configured local Maven repository.
Native executables make Quarkus applications ideal for containers and serverless workloads.
Make sure to have GRAALVM_HOME configured and pointing to the latest release of GraalVM for JDK 21.
Verify that your pom.xml has the proper native profile as shown in Maven configuration .
使用以下方法创建一个原生可执行文件：
quarkus build --nativeMaven
./mvnw install -DnativeA native executable will be present in target/.
To run Integration Tests on the native executable, make sure to have the proper Maven plugin configured and launch the verify goal.
$ ./mvnw verify -Dnative
[quarkus-quickstart-runner:50955] universe: 391.96 ms
[quarkus-quickstart-runner:50955] (parse): 904.37 ms
[quarkus-quickstart-runner:50955] (inline): 1,143.32 ms
[quarkus-quickstart-runner:50955] (compile): 6,228.44 ms
[quarkus-quickstart-runner:50955] compile: 9,130.58 ms
[quarkus-quickstart-runner:50955] image: 2,101.42 ms
[quarkus-quickstart-runner:50955] write: 803.18 ms
[quarkus-quickstart-runner:50955] [total]: 33,520.15 ms
[INFO]
[INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.quickstart.GreetingResourceIT
Executing [/Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
2019-02-28 16:52:42,020 INFO [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
2019-02-28 16:52:42,021 INFO [io.quarkus] (main) Installed features: [cdi, rest]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
The native executable will be specific to your operating system.
To create an executable that will run in a container, use the following:
quarkus build --native -Dquarkus.native.container-build=trueMaven
./mvnw install -Dnative -Dquarkus.native.container-build=trueThe produced executable will be a 64-bit Linux executable, so depending on your operating system, it may no longer be runnable.
However, it’s not an issue as we are going to copy it to a Docker container.
Note that in this case the build itself runs in a Docker container too, so you don’t need to have GraalVM installed locally.
By default, the native executable will be generated using the quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 Docker image.
If you want to build a native executable with a different Docker image (for instance to use a different GraalVM version),
use the -Dquarkus.native.builder-image=<image name> build argument.
The list of the available Docker images can be found on quay.io .
Be aware that a given Quarkus version might not be compatible with all the images available.
<dependency> (2)
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-bom</artifactId>
<version>${quarkus.platform.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin> (3)
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions> (4)
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
<goal>generate-code-tests</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin> (5)
<groupId>org.apache.maven.plugins</groupId>
<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>
<plugin> (6)
<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>
</plugins>
</build>
<profiles>
<profile> (7)
<id>native</id>
<properties> (8)
<quarkus.native.enabled>true</quarkus.native.enabled>
<skipITs>false</skipITs> (9)
</properties>
</profile>
</profiles>
Disable running of integration tests (test names *IT and annotated with @QuarkusIntegrationTest) on all builds. To run these tests all the time, either remove this property, set its value to false, or set -DskipITs=false on the command line when you run the build.native profile.
Optionally use a BOM file to omit the version of the different Quarkus dependencies.
Use the Quarkus Maven plugin that will hook into the build process.
Enabling Maven plugin extensions will register a Quarkus MavenLifecycleParticipant which will make sure the Quarkus classloaders used during the build are properly closed. During the generate-code and generate-code-tests goals the Quarkus application bootstrap is initialized and re-used in the build goal (which actually builds and packages a production application). The Quarkus classloaders will be properly closed in the build goal of the quarkus-maven-plugin. However, if the build fails in between the generate-code or generate-code-tests and build then the Quarkus augmentation classloader won’t be properly closed, which may lead to locking of JAR files that happened to be on the classpath on Windows OS.
Add system properties to maven-surefire-plugin.maven.home is only required if you have custom configuration in ${maven.home}/conf/settings.xml.
If you want to test the artifact produced by your build with Integration Tests, add the following plugin configuration. Test names *IT and annotated with @QuarkusIntegrationTest will be run against the artifact produced by the build (JAR file, container image, etc). See the Integration Testing guide for more info.maven.home is only required if you have custom configuration in ${maven.home}/conf/settings.xml.
Use a specific native profile for native executable building.
Enable the native package type. The build will therefore produce a native executable.
Always run integration tests when building a native image (test names *IT and annotated with @QuarkusIntegrationTest).true.
In order to successfully run the produced jar, you need to have the entire contents of the quarkus-app directory. If any of the files are missing, the application will not start or
might not function correctly.
The fast-jar packaging results in creating an artifact that starts a little faster and consumes slightly less memory than a legacy Quarkus jar
because it has indexed information about which dependency jar contains classes and resources. It can thus avoid the lookup into potentially every jar
on the classpath that the legacy jar necessitates, when loading a class or resource.
Quarkus Maven plugin supports the generation of Uber-Jars by specifying a quarkus.package.jar.type=uber-jar configuration option in your application.properties
(or <quarkus.package.jar.type>uber-jar</quarkus.package.jar.type> in your pom.xml).
The original jar will still be present in the target directory, but it will be renamed to contain the .original suffix.
When building an Uber-Jar you can specify entries that you want to exclude from the generated jar by using the quarkus.package.ignored-entries configuration
option, this takes a comma separated list of entries to ignore.
Uber-Jar creation by default excludes signature files that might be present in the dependencies of the application.
Uber-Jar’s final name is configurable via a Maven’s build settings finalName option.
By default the generated uber JAR file name will have the -runner suffix, unless it was overriden by configuring a custom one with quarkus.package.runner-suffix configuration option.
If the runner suffix is not desired, it can be disabled by setting quarkus.package.jar.add-runner-suffix configuration option to false, in which case the uber JAR will replace the original JAR
file generated by maven-jar-plugin for the application module.
As long as an Uber-Jar file name is created by appending a suffix, such as runner, to the original project JAR file name, the Uber-Jar file name suffix will also be used as the Maven
artifact classifier for the Uber-Jar artifact. There are two ways to attach an Uber-Jar as the main project artifact (without the classifier):
set quarkus.package.jar.add-runner-suffix=false, which will disable the addition of the file name suffix and, by doing that, will replace the original project JAR on the file system;
set attachRunnerAsMainArtifact parameter of the quarkus:build goal to true.
By default, Quarkus will not discover CDI beans inside another module.
The best way to enable CDI bean discovery for a module in a multi-module project would be to include the jandex-maven-plugin,
unless it is the main application module already configured with the quarkus-maven-plugin, in which case it will be indexed automatically.
<build>
<plugins>
<plugin>
<groupId>io.smallrye</groupId>
<artifactId>jandex-maven-plugin</artifactId>
<version>3.2.2</version>
<executions>
<execution>
<id>make-index</id>
<goals>
<goal>jandex</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build> More information on this topic can be found on the Bean Discovery section of the CDI guide.
maven-surefire-plugin and maven-failsafe-plugin configurations showed above will work in most cases. However, there could be cases when extra configuration will be required.
The reason is that, Quarkus may need to re-resolve application dependencies during the test phase to set up the test classpath for the tests. The original Maven resolver used in previous build phases
will not be available in the test process and, as a conseqence, Quarkus will need to initialize a new one. To make sure the new resolver is initialized correctly, the relevant configuration options
will need to be passed to the test process.
A path to the Maven user settings file may need to be passed to test processes, for example, in case the Maven build process was not launched using the default mvn scripts included in the Maven distribution.
It could be done in the following way:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<!-- skip -->
<maven.settings>${session.request.userSettingsFile.absolutePath}</maven.settings>
</systemPropertyVariables>
</configuration>
</plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<!-- skip -->
<javax.net.ssl.keyStoreType>${javax.net.ssl.keyStoreType}</javax.net.ssl.keyStoreType>
<javax.net.ssl.keyStore>${javax.net.ssl.keyStore}</javax.net.ssl.keyStore>
<javax.net.ssl.keyStorePassword>${javax.net.ssl.keyStorePassword}</javax.net.ssl.keyStorePassword>
<javax.net.ssl.trustStore>${javax.net.ssl.trustStore}</javax.net.ssl.trustStore>
<javax.net.ssl.trustStorePassword>${javax.net.ssl.trustStorePassword}</javax.net.ssl.trustStorePassword>
</systemPropertyVariables>
</configuration>
</plugin>
Quarkus supports configuration profiles in order to provide a specific configuration according to the target environment.
The profile can be provided directly in the Maven build’s command thanks to the system property quarkus.profile with a command of type:
quarkus build -Dquarkus.profile=profile-name-hereMaven
./mvnw install -Dquarkus.profile=profile-name-hereHowever, it is also possible to specify the profile directly in the POM file of the project using project properties, the Quarkus Maven plugin configuration properties or system properties set in the Quarkus Maven plugin configuration.
In order of precedence (greater precedence first):
1. System properties set in the Quarkus Maven plugin configuration
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<build>
<plugins>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<configuration>
<systemProperties>
<quarkus.profile>prod-aws</quarkus.profile> (1)
</systemProperties>
</configuration>
</plugin>
</plugins>
</build>
</project>
2. Quarkus Maven plugin configuration properties
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<build>
<plugins>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<configuration>
<properties>
<quarkus.profile>prod-aws</quarkus.profile> (1)
</properties>
</configuration>
</plugin>
</plugins>
</build>
</project>
3. Project properties
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<properties>
<quarkus.profile>prod-aws</quarkus.profile> (1)
</properties>
</project>
In some particular use cases, it can be interesting to build several artifacts of your application from the same module.
A typical example is when you want to build your application with different configuration profiles.
In that case, it is possible to add as many executions as needed to the Quarkus Maven plugin configuration.
Below is an example of a Quarkus Maven plugin configuration that will produce two builds of the same application: one using the prod-oracle profile and the other one using the prod-postgresql profile.
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<build>
<plugins>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<executions>
<execution>
<id>oracle</id>
<goals>
<goal>build</goal>
</goals>
<configuration>
<properties>
<quarkus.profile>prod-oracle</quarkus.profile> (1)
<quarkus.package.output-directory>oracle-quarkus-app</quarkus.package.output-directory> (2)
</properties>
</configuration>
</execution>
<execution>
<id>postgresql</id>
<goals>
<goal>build</goal>
</goals>
<configuration>
<properties>
<quarkus.profile>prod-postgresql</quarkus.profile> (3)
<quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory> (4)
</properties>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
The output directory of the first execution of the plugin is set to oracle-quarkus-app instead of quarkus-app to have a dedicated directory.
The default configuration profile of the second execution of the plugin is prod-postgresql.
The output directory of the second execution of the plugin is set to postgresql-quarkus-app instead of quarkus-app to have a dedicated directory.
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dependencies>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>${postgresql.driver.version}</version>
<optional>true</optional> (1)
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<executions>
<execution>
<id>postgresql</id>
<goals>
<goal>build</goal>
</goals>
<configuration>
<properties>
<quarkus.profile>prod-postgresql</quarkus.profile>
<quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory>
<quarkus.package.jar.filter-optional-dependencies>true</quarkus.package.jar.filter-optional-dependencies> (2)
<quarkus.package.jar.included-optional-dependencies>org.postgresql:postgresql::jar</quarkus.package.jar.included-optional-dependencies> (3)
</properties>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
For backward compatibility reasons, it is necessary to explicitly indicate that the optional dependencies need to be filtered.
Only the optional dependency corresponding to the JDBC driver of PostgreSQL is expected in the final artifact.
There are a several configuration options that will define what the output of your project build will be.
These are provided in application.properties the same as any other config property.
这些属性显示如下：
Configuration property fixed at build time - All other configuration properties are overridable at runtime
fast-jarThe "fast JAR" packaging type. uber-jarThe "Uber-JAR" packaging type. mutable-jarThe "mutable JAR" packaging type (for remote development mode). legacy-jarThe "legacy JAR" packaging type. This corresponds to the packaging type used in Quarkus before version 1.12.
fast-jarThe "fast JAR" packaging type.
quarkus.package.jar.compress
Whether the created jar will be compressed. This setting is not used when building a native image
Environment variable: QUARKUS_PACKAGE_JAR_COMPRESS
Specify whether the
Implementation
information should be included in the runner jar’s MANIFEST.MF.
Environment variable:
QUARKUS_PACKAGE_JAR_MANIFEST_ADD_IMPLEMENTATION_ENTRIES
Custom manifest attributes to be added to the main section of the MANIFEST.MF file. An example of the user defined property: quarkus.package.jar.manifest.attributes."Entry-key1"=Value1 quarkus.package.jar.manifest.attributes."Entry-key2"=Value2
Environment variable:
QUARKUS_PACKAGE_JAR_MANIFEST_ATTRIBUTES__ATTRIBUTE_NAME_
Custom manifest sections to be added to the MANIFEST.MF file. An example of the user defined property: quarkus.package.jar.manifest.sections."Section-Name"."Entry-Key1"=Value1 quarkus.package.jar.manifest.sections."Section-Name"."Entry-Key2"=Value2
Environment variable:
QUARKUS_PACKAGE_JAR_MANIFEST_SECTIONS__SECTION_NAME_
List of all the dependencies that have been defined as optional to include into the final package of the application. Each optional dependency needs to be expressed in the following format:
groupId:artifactId[:[classifier][:[type]]]
With the classifier and type being optional (note that the brackets (
[]
) denote optionality and are not a part of the syntax specification). The group ID and artifact ID must be present and non-empty.
If the type is missing, the artifact is assumed to be of type
jar
.
This parameter is optional; if absent, no optional dependencies will be included into the final package of the application.
For backward compatibility reasons, this parameter is ignored by default and can be enabled by setting the parameter
quarkus.package.jar.filter-optional-dependencies
to
true
.
This parameter is meant to be used in modules where multi-builds have been configured to avoid getting a final package with unused dependencies.
Environment variable:
QUARKUS_PACKAGE_JAR_INCLUDED_OPTIONAL_DEPENDENCIES
This parameter is meant to be used in modules where multi-builds have been configured to avoid getting a final package with unused dependencies.
Environment variable:
QUARKUS_PACKAGE_JAR_FILTER_OPTIONAL_DEPENDENCIES
Indicates whether the generated JAR file should have the runner suffix appended. Only applicable to the
JarType#UBER_JAR uber-JAR output type
. If disabled, the JAR built by the original build system (Maven, Gradle, etc.) will be replaced with the Quarkus-built uber-JAR.
Environment variable:
QUARKUS_PACKAGE_JAR_ADD_RUNNER_SUFFIX
Whether to automate the creation of AppCDS. Furthermore, this option only works for Java 11+ and is considered experimental for the time being. Finally, care must be taken to use the same exact JVM version when building and running the application.
Environment variable:
QUARKUS_PACKAGE_JAR_APPCDS_ENABLED
When AppCDS generation is enabled, if this property is set, then the JVM used to generate the AppCDS file will be the JVM present in the container image. The builder image is expected to have the 'java' binary on its PATH. This flag is useful when the JVM to be used at runtime is not the same exact JVM version as the one used to build the jar. Note that this property is consulted only when
quarkus.package.jar.appcds.enabled=true
and it requires having docker available during the build.
Environment variable:
QUARKUS_PACKAGE_JAR_APPCDS_BUILDER_IMAGE
Normally, if either a suitable container image to use to create the AppCDS archive can be determined automatically or if one is explicitly set using the
quarkus.<package-type>.appcds.builder-image
setting, the AppCDS archive is generated by running the JDK contained in the image as a container.
If this option is set to
false
, a container will not be used to generate the AppCDS archive. Instead, the JDK used to build the application is also used to create the archive. Note that the exact same JDK version must be used to run the application in this case.
Ignored if
quarkus.package.jar.appcds.enabled
is set to
false
.
Environment variable:
QUARKUS_PACKAGE_JAR_APPCDS_USE_CONTAINER
If this is specified a directory of this name will be created in the jar distribution. Users can place jar files in this directory, and when re-augmentation is performed these will be processed and added to the class-path.
Note that before reaugmentation has been performed these jars will be ignored, and if they are updated the app should be reaugmented again.
Environment variable:
QUARKUS_PACKAGE_JAR_USER_PROVIDERS_DIRECTORY
If this option is true then a list of all the coordinates of the artifacts that made up this image will be included in the quarkus-app directory. This list can be used by vulnerability scanners to determine if your application has any vulnerable dependencies. Only supported for the
JarType#FAST_JAR fast JAR
and
JarType#MUTABLE_JAR mutable JAR
output types.
Environment variable:
QUARKUS_PACKAGE_JAR_INCLUDE_DEPENDENCY_LIST
Enable decompilation of generated and transformed bytecode into the
decompiled
directory.
Environment variable:
QUARKUS_PACKAGE_JAR_DECOMPILER_ENABLED
The entry point of the application. This can either be a fully qualified name of a standard Java class with a main method, or
io.quarkus.runtime.QuarkusApplication
.
If your application has main classes annotated with
io.quarkus.runtime.annotations.QuarkusMain
then this can also reference the name given in the annotation, to avoid the need to specify fully qualified names in the config.
Environment variable:
QUARKUS_PACKAGE_MAIN_CLASS
The directory into which the output package(s) should be written. Relative paths are resolved from the build systems target directory.
Environment variable:
QUARKUS_PACKAGE_OUTPUT_DIRECTORY
Setting this switch to
true
will cause Quarkus to write the transformed application bytecode to the build tool’s output directory. This is useful for post-build tools that need to scan the application bytecode (for example, offline code-coverage tools).
For example, if using Maven, enabling this feature will result in the classes in
target/classes
being replaced with classes that have been transformed by Quarkus.
Setting this to
true
, however, should be done with a lot of caution and only if subsequent builds are done in a clean environment (i.e. the build tool’s output directory has been completely cleaned).
Environment variable:
QUARKUS_PACKAGE_WRITE_TRANSFORMED_BYTECODE_TO_BUILD_OUTPUT
By default, Quarkus tests in JVM mode are run using the
test
configuration profile. If you are not familiar with Quarkus
configuration profiles, everything you need to know is explained in the
Configuration Profiles Documentation
.
It is however possible to use a custom configuration profile for your tests with the Maven Surefire and Maven Failsafe
configurations shown below. This can be useful if you need for example to run some tests using a specific database which is not
your default testing database.
<project>
[...]
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<quarkus.test.profile>foo</quarkus.test.profile> (1)
<buildDirectory>${project.build.directory}</buildDirectory>
[...]
</systemPropertyVariables>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${failsafe-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<quarkus.test.profile>foo</quarkus.test.profile> (1)
<buildDirectory>${project.build.directory}</buildDirectory>
[...]
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
[...]
</project>
It is not possible to use a custom test configuration profile in native mode for now. Native tests are always run using the
prod
profile.
Quarkus bootstrap includes a Maven resolver implementation that is used to resolve application runtime and build time dependencies. The Quarkus Maven resolver is initialized from the same Maven command line that launched the build, test or dev mode. Typically, there is no need to add any extra configuration for it. However, there could be cases where an extra configuration option may be necessary to properly resolve application dependencies in test or dev modes, or IDEs.
Maven test plugins (such as
surefire
and
failsafe
), for example, are not propagating build system properties to the running tests by default. Which means some system properties set by the Maven CLI aren’t available for the Quarkus Maven resolver initialized for the tests, which may result in test dependencies being resolved using different settings than the main Maven build.
Here is a list of system properties the Quarkus bootstrap Maven resolver checks during its initialization.
maven.home
MAVEN_HOME
envvar
The Maven home dir is used to resolve the global settings file unless it was explicitly provided on the command line with the
-gs
argument
maven.settings
~/.m2/settings.xml
Unless the custom settings file has been provided with the
-s
argument, this property can be used to point the resolver to a custom Maven settings file
maven.repo.local
~/.m2/repository
This property could be used to configure a custom local Maven repository directory, if it is different from the default one and the one specified in the
settings.xml
maven.top-level-basedir
This property may be useful to help the Maven resolver identify the top-level Maven project in the workspace. By default, the Maven resolver will be discovering a project’s workspace by navigating the parent-module POM relationship. However, there could be project layouts that are using an aggregator module which isn’t appearing as the parent for its modules. In this case, this property will help the Quarkus Maven resolver to properly discover the workspace.
quarkus.bootstrap.effective-model-builder
false
By default, the Quarkus Maven resolver is reading project’s POMs directly when discovering the project’s layout. While in most cases it works well enough and relatively fast, reading raw POMs has its limitation. E.g. if a POM includes modules in a profile, these modules will not be discovered. This system property enables project’s layout discovery based on the effective POM models, that are properly interpolated, instead of the raw ones. The reason this option is not enabled by default is it may appear to be significantly more time-consuming that could increase, e.g. CI testing times. Until there is a better approach found that could be used by default, projects that require it should enable this option.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<maven.home>${maven.home}</maven.home>
(1)
<maven.repo.local>${settings.localRepository}</maven.repo.local>
(2)
<maven.settings>${session.request.userSettingsFile.path}</maven.settings>
(3)
<maven.top-level-basedir>${session.topLevelProject.basedir.absolutePath}</maven.top-level-basedir>
(4)
<quarkus.bootstrap.effective-model-builder>true</quarkus.bootstrap.effective-model-builder>
(5)
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
[...]
</project>
In Maven there appears to be a notion of the top-level project (that is exposed as a project property
${session.topLevelProject.basedir.absolutePath}
)
and the multi-module project directory (that is available as property
${maven.multiModuleProjectDirectory}
). These directories might not always match!
The
${maven.multiModuleProjectDirectory}
will be resolved to the first directory that contains
.mvn
directory as its child going up the workspace file system tree
starting from the current directory (or the one specified with the
-f
argument) from which the
mvn
command was launched. If the
.mvn
directory was not found, however,
the
${maven.multiModuleProjectDirectory}
will be pointing to the directory from which the
mvn
command was launched (or the one targeted with the
-f
argument).
The
${session.topLevelProject.basedir.absolutePath}
will be pointing either to the directory from which the
mvn
command was launched or to the directory targeted with
the
-f
argument, if it was specified.
The Quarkus Maven plugin includes a goal called
info
(currently marked as 'experimental') that logs Quarkus-specific information about the project, such as: the imported Quarkus platform BOMs and the Quarkus extensions found among the project dependencies.
In a multi-module project
quarkus:info
will assume that the current module, in which it is executed, is the main module of the application.
[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:info
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:3.15.1:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs: (1)
[INFO] io.quarkus.platform:quarkus-bom:pom:3.15.1
[INFO] io.quarkus.platform:quarkus-camel-bom:pom:3.15.1
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom: (2)
[INFO] io.quarkus:quarkus-rest
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-camel-bom: (3)
[INFO] org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io: (4)
[INFO] io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
Quarkus platform BOMs imported in the project (BOMs imported by parent POMs will also be reported)
Direct Quarkus extension dependencies managed by the
quarkus-bom
Direct Quarkus extension dependencies managed by the
quarkus-camel-bom
Direct Quarkus extensions dependencies that aren’t managed by Quarkus BOMs but found in the Quarkus extension registry
quarkus:info
will also highlight basic Quarkus dependency version misalignments, in case they are detected. For example, if we modify the project mentioned above by removing the
camel-quarkus-rabbitmq
extension from the dependencies and adding a
2.6.3.Final
<version>
element to the
quarkus-rest
dependency that is managed by the
quarkus-bom
and then run
quarkus:info
again, we’ll see something like:
[INFO] --- quarkus-maven-plugin:3.15.1:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs:
[INFO] io.quarkus.platform:quarkus-bom:pom:3.15.1
[INFO] io.quarkus.platform:quarkus-camel-bom:pom:3.15.1 | unnecessary (1)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom:
[INFO] io.quarkus:quarkus-resteasy-reactive:2.6.3.Final | misaligned (2)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-camel-bom:
[INFO] org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO] io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
[INFO]
[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'
The
quarkus-camel-bom
import is now reported as 'unnecessary' since none of the Quarkus extensions it includes are found among the project dependencies
The version
2.6.3.Final
of the
quarkus-resteasy-reactive
is now reported as being misaligned with the version managed by the Quarkus platform BOM imported in the project, which is 3.15.1
The
quarkus:update
goal (currently marked as 'experimental') provided by the Quarkus Maven plugin can be used to check whether there are Quarkus-related updates available for a project, such as: new releases of the relevant Quarkus platform BOMs and non-platform Quarkus extensions present in the project. In a multi-module project the
update
goal is meant to be executed from the main Quarkus application module.
The way
quarkus:update
works, first, all the direct Quarkus extension dependencies of the project are collected (those that are managed by the Quarkus platform BOMs and those that aren’t but found in the Quarkus extension registries). Then the configured Quarkus extension registries (typically the
registry.quarkus.io
) will be queried for the latest recommended/supported Quarkus platform versions and non-platform Quarkus extensions compatible with them. The algorithm will then select the latest compatible combination of all the extensions found in the project, assuming such a combination actually exists. Otherwise, no updates will be suggested.
Assuming we have a project including Kogito, Camel and core Quarkus extensions available in the Quarkus platform based on Quarkus
2.7.1.Final
, the output of the
quarkus:update
would look like:
[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:update
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:3.15.1:update (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:update goal is experimental, its options and output might change in future versions
[INFO]
[INFO] Recommended Quarkus platform BOM updates: (1)
[INFO] Update: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.15.1
[INFO] Update: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final -> 3.15.1
[INFO] Recommended Quarkus platform BOM updates: (1)
[INFO] Update: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.15.1
[INFO] Remove: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final (2)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom:
[INFO] Update: io.quarkus:quarkus-resteasy-reactive:2.6.3.Final -> remove version (managed) (3)
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO] Update: io.quarkiverse.prettytime:quarkus-prettytime:0.2.0 -> 0.2.1 (4)
Given that the project does not include any Camel Quarkus extensions, the BOM import is recommended to be removed
An outdated version of the
quarkus-resteasy-reactive
is recommended to be removed in favor of the one managed by the
quarkus-bom
The latest compatible version of the
quarkus-prettytime
extension
As was mentioned above,
quarkus:info
, besides reporting Quarkus platform and extension versions, performs a quick version alignment check, to make sure the extension versions used in the project are compatible with the imported Quarkus platform BOMs. If misalignments are detected, the following warning message will be logged:
[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'
When the
rectify
option is enabled,
quarkus:update
, instead of suggesting the latest recommended Quarkus version updates, will log update instructions to simply align the extension dependency versions found in the project with the currently imported Quarkus platform BOMs.
Import in your IDE
Logging Quarkus application build classpath tree
Downloading Maven artifact dependencies for offline development and testing
构建一个本地可执行文件
Build a container friendly executable
Maven configuration
Using fast-jar
Uber-Jar Creation
Working with multi-module projects
Maven test plugin configuration
Building with a specific configuration profile
Building several artifacts from a single module
Configuring the Project Output
Custom test configuration profile in JVM mode
Bootstrap Maven properties
Quarkus project info
Highlighting misaligned versions
Quarkus project update
Quarkus project rectify
