Sync documentation of main branch

quarkusio · Nov 16, 2024 · 7aefc14 · 7aefc14
1 parent 0e2b8e7
commit 7aefc14
Show file tree

Hide file tree

Showing 5 changed files with 264 additions and 6 deletions.
diff --git 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
+<extensionJvmOptions> <!-- disable JVM options from all the extensions --> <disableAll>true</disableAll> </extensionJvmOptions>* or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example <extensionJvmOptions> <disableFor> <!-- disable JVM options from all the extensions with groupId org.acme --> <extension>org.acme</extension> <!-- disable JVM options configured by io.quarkiverse:quarkus-magic --> <extension>io.quarkiverse:quarkus-magic</extension> </disableFor> </extensionJvmOptions>
+--
+|`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
+<extensionJvmOptions> <!-- disable JVM options from all the extensions --> <disableAll>true</disableAll> </extensionJvmOptions>* or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example <extensionJvmOptions> <disableFor> <!-- disable JVM options from all the extensions with groupId org.acme --> <extension>org.acme</extension> <!-- disable JVM options configured by io.quarkiverse:quarkus-magic --> <extension>io.quarkiverse:quarkus-magic</extension> </disableFor> </extensionJvmOptions>
+--
+|`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
+<extensionJvmOptions> <!-- disable JVM options from all the extensions --> <disableAll>true</disableAll> </extensionJvmOptions>* or specifying a groupId:artifactId:classifier artifact pattern to disable options provided by the matching subset of extensions, for example <extensionJvmOptions> <disableFor> <!-- disable JVM options from all the extensions with groupId org.acme --> <extension>org.acme</extension> <!-- disable JVM options configured by io.quarkiverse:quarkus-magic --> <extension>io.quarkiverse:quarkus-magic</extension> </disableFor> </extensionJvmOptions>
+--
+|`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
@@ -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.<option-name>=<option-value>`
+| Optional
+| Standard Java command line option that should be added to command line launching an application in dev mode
+
+| `dev-mode.jvm-option.xx.<option-name>=<option-value>`
+| 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+]
+----
+            <plugin>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-extension-maven-plugin</artifactId>
+                <version>${quarkus.version}</version>
+                <executions>
+                    <execution>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>extension-descriptor</goal>
+                        </goals>
+                        <configuration>
+                            <devMode>
+                                <jvmOptions>
+                                    <add-modules>jdk.incubator.vector</add-modules>
+                                    <enable-preview/>
+                                    <enable-native-access>ALL-UNNAMED</enable-native-access>
+                                </jvmOptions>
+                                <xxJvmOptions>
+                                    <UseThreadPriorities>false</UseThreadPriorities>
+                                </xxJvmOptions>
+                                <lockJvmOptions>agentlib:jdwp</lockJvmOptions>
+                                <lockXxJvmOptions>TieredStopAtLevel</lockXxJvmOptions>
+                            </devMode>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+----
+
+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/<username>/app/target/acme-app-dev.jar
+[DEBUG] Launching JVM with command line: /home/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.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/<username>/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
@@ -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/<username>/jdk/bin/java''. Working directory: /home/<username>/gradle-app/build/classes/java/main Command: /home/<username>/jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home/<username>/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/<username>/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/<username>/jdk/bin/java''. Working directory: /home/<username>/gradle-app/build/classes/java/main Command: /home/<username>/jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home/<username>/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/<username>/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/...ides/images/extension-maturity_matrix.svg → ...ides/images/extension-maturity-matrix.svg b/...ides/images/extension-maturity_matrix.svg → ...ides/images/extension-maturity-matrix.svg
diff --git 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/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.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/<username>/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+]
+----
+            <plugin>
+                <groupId>${quarkus.platform.group-id}</groupId>
+                <artifactId>quarkus-maven-plugin</artifactId>
+                <version>${quarkus.platform.version}</version>
+                <configuration>
+                    <extensionJvmOptions>
+                        <disableAll>false</disableAll>
+                    </extensionJvmOptions>
+                </configuration>
+            </plugin>
+----
+Or disable Java options provided by specific extensions by configuring Maven coordinates patterns, such as
+[source,xml,subs=attributes+]
+----
+            <plugin>
+                <groupId>${quarkus.platform.group-id}</groupId>
+                <artifactId>quarkus-maven-plugin</artifactId>
+                <version>${quarkus.platform.version}</version>
+                <configuration>
+                    <extensionJvmOptions>
+                        <disableFor>
+                            <extension>org.acme:quarkus-red</extension>
+                        </disableFor>
+                    </extensionJvmOptions>
+                </configuration>
+            </plugin>
+----
+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/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.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/<username>/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.