Skip to content

Commit 7aefc14

Browse files
actions-useractions-user
committed
Sync documentation of main branch
1 parent 0e2b8e7 commit 7aefc14

File tree

5 files changed

+264
-6
lines changed

5 files changed

+264
-6
lines changed

‎_generated-doc/main/infra/quarkus-maven-plugin-goals.adoc‎

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1263,14 +1263,25 @@ a| [[quarkus-maven-plugin-goal-dev-environmentVariables]] environmentVariables
12631263
|`Map`
12641264
|
12651265

1266+
a| [[quarkus-maven-plugin-goal-dev-extensionJvmOptions]] extensionJvmOptions
1267+
1268+
[.description]
1269+
--
1270+
Extension dev mode JVM option filter configuration.
1271+
Allows disabling all JVM options configured by extensions, for example
1272+
<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>
1273+
--
1274+
|`ExtensionDevModeJvmOptionFilter`
1275+
|
1276+
12661277
a| [[quarkus-maven-plugin-goal-dev-forceC2]] forceC2
12671278

12681279
[.description]
12691280
--
12701281
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.
12711282
--
1272-
|`boolean`
1273-
|`${forceC2}`
1283+
|`Boolean`
1284+
|
12741285

12751286
a| [[quarkus-maven-plugin-goal-dev-jvmArgs]] jvmArgs
12761287

@@ -2932,14 +2943,25 @@ a| [[quarkus-maven-plugin-goal-remote-dev-environmentVariables]] environmentVari
29322943
|`Map`
29332944
|
29342945

2946+
a| [[quarkus-maven-plugin-goal-remote-dev-extensionJvmOptions]] extensionJvmOptions
2947+
2948+
[.description]
2949+
--
2950+
Extension dev mode JVM option filter configuration.
2951+
Allows disabling all JVM options configured by extensions, for example
2952+
<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>
2953+
--
2954+
|`ExtensionDevModeJvmOptionFilter`
2955+
|
2956+
29352957
a| [[quarkus-maven-plugin-goal-remote-dev-forceC2]] forceC2
29362958

29372959
[.description]
29382960
--
29392961
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.
29402962
--
2941-
|`boolean`
2942-
|`${forceC2}`
2963+
|`Boolean`
2964+
|
29432965

29442966
a| [[quarkus-maven-plugin-goal-remote-dev-jvmArgs]] jvmArgs
29452967

@@ -3416,14 +3438,25 @@ a| [[quarkus-maven-plugin-goal-test-environmentVariables]] environmentVariables
34163438
|`Map`
34173439
|
34183440

3441+
a| [[quarkus-maven-plugin-goal-test-extensionJvmOptions]] extensionJvmOptions
3442+
3443+
[.description]
3444+
--
3445+
Extension dev mode JVM option filter configuration.
3446+
Allows disabling all JVM options configured by extensions, for example
3447+
<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>
3448+
--
3449+
|`ExtensionDevModeJvmOptionFilter`
3450+
|
3451+
34193452
a| [[quarkus-maven-plugin-goal-test-forceC2]] forceC2
34203453

34213454
[.description]
34223455
--
34233456
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.
34243457
--
3425-
|`boolean`
3426-
|`${forceC2}`
3458+
|`Boolean`
3459+
|
34273460

34283461
a| [[quarkus-maven-plugin-goal-test-jvmArgs]] jvmArgs
34293462

‎_versions/main/guides/extension-metadata.adoc‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,22 @@ The following properties may appear in this file:
169169
| Optional
170170
| https://quarkus.io/guides/conditional-extension-dependencies[Dependency condition] that has to be satisfied for a conditional dependency on this extension to be activated
171171

172+
| `dev-mode.jvm-option.std.<option-name>=<option-value>`
173+
| Optional
174+
| Standard Java command line option that should be added to command line launching an application in dev mode
175+
176+
| `dev-mode.jvm-option.xx.<option-name>=<option-value>`
177+
| Optional
178+
| `-XX:` Java command line option that should be added to command line launching an application in dev mode
179+
180+
| `dev-mode.lock.jvm-options`
181+
| Optional
182+
| 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
183+
184+
| `dev-mode.lock.xx-jvm-options`
185+
| Optional
186+
| 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
187+
172188
|===
173189

174190
[[quarkus-config-roots]]
@@ -185,3 +201,70 @@ Same as `quarkus-config-roots.list`, this file may appear in a runtime extension
185201
== META-INF/quarkus-build-steps.list
186202

187203
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.
204+
205+
[[quarkus-extension-maven-plugin]]
206+
== Quarkus Extension Maven Plugin
207+
208+
The `quarkus-extension-maven-plugin` is configured in the runtime module of a Quarkus extension Maven project and serves the following purposes:
209+
210+
* validate extension metadata configuration;
211+
* generate extension metadata;
212+
* check whether extension dependencies conform to the Quarkus extension dependency model.
213+
214+
=== Dev mode JVM options
215+
216+
An extension may pre-configure certain Java command line options that should be added to the command line
217+
launching an application in Dev mode. Here is how such options can be configured in the `quarkus-extension-maven-plugin` configuration:
218+
219+
[source,xml,subs=attributes+]
220+
----
221+
<plugin>
222+
<groupId>io.quarkus</groupId>
223+
<artifactId>quarkus-extension-maven-plugin</artifactId>
224+
<version>${quarkus.version}</version>
225+
<executions>
226+
<execution>
227+
<phase>compile</phase>
228+
<goals>
229+
<goal>extension-descriptor</goal>
230+
</goals>
231+
<configuration>
232+
<devMode>
233+
<jvmOptions>
234+
<add-modules>jdk.incubator.vector</add-modules>
235+
<enable-preview/>
236+
<enable-native-access>ALL-UNNAMED</enable-native-access>
237+
</jvmOptions>
238+
<xxJvmOptions>
239+
<UseThreadPriorities>false</UseThreadPriorities>
240+
</xxJvmOptions>
241+
<lockJvmOptions>agentlib:jdwp</lockJvmOptions>
242+
<lockXxJvmOptions>TieredStopAtLevel</lockXxJvmOptions>
243+
</devMode>
244+
</configuration>
245+
</execution>
246+
</executions>
247+
</plugin>
248+
----
249+
250+
The `extension-descriptor` goal will generate `META-INF/quarkus-extension.properties` with the corresponding properties.
251+
And once an application that has a dependency on this extension is launched in Dev mode, the logs will look like
252+
[source,bash]
253+
----
254+
255+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
256+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED]
257+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector]
258+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: []
259+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) UseThreadPriorities: [false]
260+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) org.acme:quarkus-blue::jar locks JVM options [TieredStopAtLevel, agentlib:jdwp]
261+
[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.
262+
[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.
263+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Executable jar: /home/<username>/app/target/acme-app-dev.jar
264+
[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
265+
----
266+
267+
Note, there are a couple `INFO` messages informing the user that the values for certain options Quarkus uses
268+
by default in Dev mode were overridden by the extension preferences. Specifically, the C2 compiler was re-enabled
269+
and the debug mode was disabled. A user can still choose to enable the debug agent and disable the C2 compilter
270+
if necessary by explicitly setting the corresponding Quarkus Maven or Gradle plugin parameter values.

‎_versions/main/guides/gradle-tooling.adoc‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,91 @@ All the config options are shown below:
315315

316316
include::{generated-dir}/config/quarkus-core_quarkus.live-reload.adoc[opts=optional, leveloffset=+1]
317317

318+
=== Extension provided Dev mode Java options
319+
320+
Some extensions may provide pre-configured Java options that should be added to the command line launching an application in Dev mode.
321+
322+
Let's suppose there are couple of extensions `quarkus-blue` and `quarkus-red` in an application that provide Java options for Dev mode.
323+
The logs may look something like this
324+
[source,bash]
325+
----
326+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar
327+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-native-access: [ALL-UNNAMED]
328+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-modules: [jdk.incubator.vector]
329+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-preview: []
330+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-red::jar
331+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED]
332+
[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
333+
----
334+
335+
A user may choose to disable all the Java options provided by extensions by configuring `disableAll` parameter such as
336+
337+
[role="primary asciidoc-tabs-sync-groovy"]
338+
.Groovy DSL
339+
****
340+
[source,groovy]
341+
----
342+
quarkusDev {
343+
extensionJvmOptions{
344+
disableAll = true
345+
}
346+
}
347+
----
348+
****
349+
350+
[role="secondary asciidoc-tabs-sync-kotlin"]
351+
.Kotlin DSL
352+
****
353+
[source,kotlin]
354+
----
355+
tasks.quarkusDev {
356+
extensionJvmOptions{
357+
setDisableAll(true)
358+
}
359+
}
360+
----
361+
****
362+
363+
Or disable Java options provided by specific extensions by configuring Maven coordinates patterns, such as
364+
365+
[role="primary asciidoc-tabs-sync-groovy"]
366+
.Groovy DSL
367+
****
368+
[source,groovy]
369+
----
370+
quarkusDev {
371+
extensionJvmOptions{
372+
disableFor = ["org.acme:quarkus-red"]
373+
}
374+
}
375+
----
376+
****
377+
378+
[role="secondary asciidoc-tabs-sync-kotlin"]
379+
.Kotlin DSL
380+
****
381+
[source,kotlin]
382+
----
383+
tasks.quarkusDev {
384+
extensionJvmOptions{
385+
setDisableFor(mutableListOf("org.acme:quarkus-red"))
386+
}
387+
}
388+
----
389+
****
390+
391+
With this configuration the logs will look like
392+
393+
[source,bash]
394+
----
395+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar
396+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-native-access: [ALL-UNNAMED]
397+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] add-modules: [jdk.incubator.vector]
398+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] enable-preview: []
399+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Skipped JVM options from org.acme:quarkus-red::jar
400+
[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
401+
----
402+
318403
== Debugging
319404

320405
In development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM.

‎_versions/main/guides/images/extension-maturity_matrix.svg‎ renamed to ‎_versions/main/guides/images/extension-maturity-matrix.svg‎

File renamed without changes.

‎_versions/main/guides/maven-tooling.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,63 @@ your password is never sent directly over the wire. For the initial connection r
269269
initial state data, and subsequent requests hash it with a random session id generated by the server and any body contents
270270
for POST requests, and the path for DELETE requests, as well as an incrementing counter to prevent replay attacks.
271271

272+
=== Extension provided Dev mode Java options
273+
274+
Some extensions may provide pre-configured Java options that should be added to the command line launching an application in Dev mode.
275+
276+
Let's suppose there are couple of extensions `quarkus-blue` and `quarkus-red` in an application that provide Java options for Dev mode.
277+
The logs may look something like this
278+
[source,bash]
279+
----
280+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-red::jar
281+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED]
282+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
283+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED]
284+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector]
285+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: []
286+
[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
287+
----
288+
289+
A user may choose to disable all the Java options provided by extensions by configuring `disableAll` parameter such as
290+
[source,xml,subs=attributes+]
291+
----
292+
<plugin>
293+
<groupId>${quarkus.platform.group-id}</groupId>
294+
<artifactId>quarkus-maven-plugin</artifactId>
295+
<version>${quarkus.platform.version}</version>
296+
<configuration>
297+
<extensionJvmOptions>
298+
<disableAll>false</disableAll>
299+
</extensionJvmOptions>
300+
</configuration>
301+
</plugin>
302+
----
303+
Or disable Java options provided by specific extensions by configuring Maven coordinates patterns, such as
304+
[source,xml,subs=attributes+]
305+
----
306+
<plugin>
307+
<groupId>${quarkus.platform.group-id}</groupId>
308+
<artifactId>quarkus-maven-plugin</artifactId>
309+
<version>${quarkus.platform.version}</version>
310+
<configuration>
311+
<extensionJvmOptions>
312+
<disableFor>
313+
<extension>org.acme:quarkus-red</extension>
314+
</disableFor>
315+
</extensionJvmOptions>
316+
</configuration>
317+
</plugin>
318+
----
319+
With this configuration the logs will look like
320+
[source,bash]
321+
----
322+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
323+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED]
324+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector]
325+
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: []
326+
[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
327+
----
328+
272329
== Debugging
273330

274331
In development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM.

0 commit comments

Comments
 (0)