diff --git a/_generated-doc/main/infra/quarkus-maven-plugin-goals.adoc b/_generated-doc/main/infra/quarkus-maven-plugin-goals.adoc index ee77d659fa..69d963f1a1 100644 --- a/_generated-doc/main/infra/quarkus-maven-plugin-goals.adoc +++ b/_generated-doc/main/infra/quarkus-maven-plugin-goals.adoc @@ -1263,14 +1263,25 @@ a| [[quarkus-maven-plugin-goal-dev-environmentVariables]] environmentVariables |`Map` | +a| [[quarkus-maven-plugin-goal-dev-extensionJvmOptions]] extensionJvmOptions + +[.description] +-- +Extension dev mode JVM option filter configuration. +Allows disabling all JVM options configured by extensions, for example + true * or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example org.acme io.quarkiverse:quarkus-magic +-- +|`ExtensionDevModeJvmOptionFilter` +| + a| [[quarkus-maven-plugin-goal-dev-forceC2]] forceC2 [.description] -- This value is intended to be set to true when we want to require C2 compilation instead of preventing it from ever kicking in. Setting this will likely have a small negative effect on startup time and should only be done when it absolutely makes sense. -- -|`boolean` -|`${forceC2}` +|`Boolean` +| a| [[quarkus-maven-plugin-goal-dev-jvmArgs]] jvmArgs @@ -2932,14 +2943,25 @@ a| [[quarkus-maven-plugin-goal-remote-dev-environmentVariables]] environmentVari |`Map` | +a| [[quarkus-maven-plugin-goal-remote-dev-extensionJvmOptions]] extensionJvmOptions + +[.description] +-- +Extension dev mode JVM option filter configuration. +Allows disabling all JVM options configured by extensions, for example + true * or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example org.acme io.quarkiverse:quarkus-magic +-- +|`ExtensionDevModeJvmOptionFilter` +| + a| [[quarkus-maven-plugin-goal-remote-dev-forceC2]] forceC2 [.description] -- This value is intended to be set to true when we want to require C2 compilation instead of preventing it from ever kicking in. Setting this will likely have a small negative effect on startup time and should only be done when it absolutely makes sense. -- -|`boolean` -|`${forceC2}` +|`Boolean` +| a| [[quarkus-maven-plugin-goal-remote-dev-jvmArgs]] jvmArgs @@ -3416,14 +3438,25 @@ a| [[quarkus-maven-plugin-goal-test-environmentVariables]] environmentVariables |`Map` | +a| [[quarkus-maven-plugin-goal-test-extensionJvmOptions]] extensionJvmOptions + +[.description] +-- +Extension dev mode JVM option filter configuration. +Allows disabling all JVM options configured by extensions, for example + true * or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example org.acme io.quarkiverse:quarkus-magic +-- +|`ExtensionDevModeJvmOptionFilter` +| + a| [[quarkus-maven-plugin-goal-test-forceC2]] forceC2 [.description] -- This value is intended to be set to true when we want to require C2 compilation instead of preventing it from ever kicking in. Setting this will likely have a small negative effect on startup time and should only be done when it absolutely makes sense. -- -|`boolean` -|`${forceC2}` +|`Boolean` +| a| [[quarkus-maven-plugin-goal-test-jvmArgs]] jvmArgs diff --git a/_versions/main/guides/extension-metadata.adoc b/_versions/main/guides/extension-metadata.adoc index 2bd3af6873..36a4abef9c 100644 --- a/_versions/main/guides/extension-metadata.adoc +++ b/_versions/main/guides/extension-metadata.adoc @@ -169,6 +169,22 @@ The following properties may appear in this file: | Optional | https://quarkus.io/guides/conditional-extension-dependencies[Dependency condition] that has to be satisfied for a conditional dependency on this extension to be activated +| `dev-mode.jvm-option.std.=` +| Optional +| Standard Java command line option that should be added to command line launching an application in dev mode + +| `dev-mode.jvm-option.xx.=` +| Optional +| `-XX:` Java command line option that should be added to command line launching an application in dev mode + +| `dev-mode.lock.jvm-options` +| Optional +| A comma-separated list of standard Java command line options that should not be overridden by values that are pre-configured by the Quarkus Maven and Gradle plugins by default + +| `dev-mode.lock.xx-jvm-options` +| Optional +| A comma-separated list of `-XX:` Java command line options that should not be overridden by values that are pre-configured by the Quarkus Maven and Gradle plugins by default + |=== [[quarkus-config-roots]] @@ -185,3 +201,70 @@ Same as `quarkus-config-roots.list`, this file may appear in a runtime extension == META-INF/quarkus-build-steps.list This file may appear in a deployment extension artifact. It contains a list of classes that implement Quarkus build steps (methods annotated with `io.quarkus.deployment.annotations.BuildStep`). This file is generated as part of the extension project build process and must not be edited manually. + +[[quarkus-extension-maven-plugin]] +== Quarkus Extension Maven Plugin + +The `quarkus-extension-maven-plugin` is configured in the runtime module of a Quarkus extension Maven project and serves the following purposes: + +* validate extension metadata configuration; +* generate extension metadata; +* check whether extension dependencies conform to the Quarkus extension dependency model. + +=== Dev mode JVM options + +An extension may pre-configure certain Java command line options that should be added to the command line +launching an application in Dev mode. Here is how such options can be configured in the `quarkus-extension-maven-plugin` configuration: + +[source,xml,subs=attributes+] +---- + + io.quarkus + quarkus-extension-maven-plugin + ${quarkus.version} + + + compile + + extension-descriptor + + + + + jdk.incubator.vector + + ALL-UNNAMED + + + false + + agentlib:jdwp + TieredStopAtLevel + + + + + +---- + +The `extension-descriptor` goal will generate `META-INF/quarkus-extension.properties` with the corresponding properties. +And once an application that has a dependency on this extension is launched in Dev mode, the logs will look like +[source,bash] +---- + +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: [] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) UseThreadPriorities: [false] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) org.acme:quarkus-blue::jar locks JVM options [TieredStopAtLevel, agentlib:jdwp] +[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue enables the C2 compiler which is disabled by default in Dev mode for optimal performance. +[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue disables the Debug mode for optimal performance. Debugging can still be enabled in the Quarkus plugin configuration or with -Ddebug on the command line. +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Executable jar: /home//app/target/acme-app-dev.jar +[DEBUG] Launching JVM with command line: /home//jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home//app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home//.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-verion}/quarkus-class-change-agent-{quarkus-version}.jar --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -XX:-UseThreadPriorities -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home//app/target/acme-app-dev.jar +---- + +Note, there are a couple `INFO` messages informing the user that the values for certain options Quarkus uses +by default in Dev mode were overridden by the extension preferences. Specifically, the C2 compiler was re-enabled +and the debug mode was disabled. A user can still choose to enable the debug agent and disable the C2 compilter +if necessary by explicitly setting the corresponding Quarkus Maven or Gradle plugin parameter values. diff --git a/_versions/main/guides/gradle-tooling.adoc b/_versions/main/guides/gradle-tooling.adoc index 0ba1a19ae1..89251c264e 100644 --- a/_versions/main/guides/gradle-tooling.adoc +++ b/_versions/main/guides/gradle-tooling.adoc @@ -315,6 +315,91 @@ All the config options are shown below: include::{generated-dir}/config/quarkus-core_quarkus.live-reload.adoc[opts=optional, leveloffset=+1] +=== Extension provided Dev mode Java options + +Some extensions may provide pre-configured Java options that should be added to the command line launching an application in Dev mode. + +Let's suppose there are couple of extensions `quarkus-blue` and `quarkus-red` in an application that provide Java options for Dev mode. +The logs may look something like this +[source,bash] +---- +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-native-access: [ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-modules: [jdk.incubator.vector] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-preview: [] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-red::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED] +[INFO] [org.gradle.process.internal.DefaultExecHandle] Starting process 'command '/home//jdk/bin/java''. Working directory: /home//gradle-app/build/classes/java/main Command: /home//jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home//.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home//gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home//gradle-app/build/tmp/quarkusDev/quarkus-app-test-model.dat -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home//gradle-app/build/gradle-app-dev.jar +---- + +A user may choose to disable all the Java options provided by extensions by configuring `disableAll` parameter such as + +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] +---- +quarkusDev { + extensionJvmOptions{ + disableAll = true + } +} +---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +tasks.quarkusDev { + extensionJvmOptions{ + setDisableAll(true) + } +} +---- +**** + +Or disable Java options provided by specific extensions by configuring Maven coordinates patterns, such as + +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] +---- +quarkusDev { + extensionJvmOptions{ + disableFor = ["org.acme:quarkus-red"] + } +} +---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +tasks.quarkusDev { + extensionJvmOptions{ + setDisableFor(mutableListOf("org.acme:quarkus-red")) + } +} +---- +**** + +With this configuration the logs will look like + +[source,bash] +---- +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-native-access: [ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-modules: [jdk.incubator.vector] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-preview: [] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Skipped JVM options from org.acme:quarkus-red::jar +[INFO] [org.gradle.process.internal.DefaultExecHandle] Starting process 'command '/home//jdk/bin/java''. Working directory: /home//gradle-app/build/classes/java/main Command: /home//jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home//.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home//gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home//gradle-app/build/tmp/quarkusDev/quarkus-app-test-model.dat -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home//gradle-app/build/gradle-app-kotlin-dev.jar +---- + == Debugging In development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM. diff --git a/_versions/main/guides/images/extension-maturity_matrix.svg b/_versions/main/guides/images/extension-maturity-matrix.svg similarity index 100% rename from _versions/main/guides/images/extension-maturity_matrix.svg rename to _versions/main/guides/images/extension-maturity-matrix.svg diff --git a/_versions/main/guides/maven-tooling.adoc b/_versions/main/guides/maven-tooling.adoc index 2491ec6f31..67d7578f40 100644 --- a/_versions/main/guides/maven-tooling.adoc +++ b/_versions/main/guides/maven-tooling.adoc @@ -269,6 +269,63 @@ your password is never sent directly over the wire. For the initial connection r 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. +=== Extension provided Dev mode Java options + +Some extensions may provide pre-configured Java options that should be added to the command line launching an application in Dev mode. + +Let's suppose there are couple of extensions `quarkus-blue` and `quarkus-red` in an application that provide Java options for Dev mode. +The logs may look something like this +[source,bash] +---- +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-red::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: [] +[DEBUG] Launching JVM with command line: /home//jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home//app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home//.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home//app/target/acme-app-dev.jar +---- + +A user may choose to disable all the Java options provided by extensions by configuring `disableAll` parameter such as +[source,xml,subs=attributes+] +---- + + ${quarkus.platform.group-id} + quarkus-maven-plugin + ${quarkus.platform.version} + + + false + + + +---- +Or disable Java options provided by specific extensions by configuring Maven coordinates patterns, such as +[source,xml,subs=attributes+] +---- + + ${quarkus.platform.group-id} + quarkus-maven-plugin + ${quarkus.platform.version} + + + + org.acme:quarkus-red + + + + +---- +With this configuration the logs will look like +[source,bash] +---- +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector] +[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: [] +[DEBUG] Launching JVM with command line: /home//jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home//app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home//.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home//app/target/acme-app-dev.jar +---- + == Debugging In development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM.