Merge pull request #30301 from yrodiere/i8802-maven-opts

Clarify how to pass javac/JVM flags to the Quarkus Maven plugin

docs/src/main/asciidoc/_includes/devtools/maven-opts.adoc

@@ -0,0 +1,13 @@
+[source, bash, subs=attributes+, role="primary asciidoc-tabs-sync-cli"]
+.CLI
+----
+MAVEN_OPTS='--enable-preview' quarkus build
+----
+ifndef::devtools-no-maven[]
+ifdef::devtools-wrapped[+]
+[source, bash, subs=attributes+, role="secondary asciidoc-tabs-sync-maven"]
+.Maven
+----
+MAVEN_OPTS='--enable-preview' ./mvnw install
+----
+endif::[]

docs/src/main/asciidoc/maven-tooling.adoc

@@ -126,6 +126,55 @@ You can install all extensions which match a globbing pattern :
 :add-extension-extensions: smallrye-*
 include::{includes}/devtools/extension-add.adoc[]
 
+[[configuring-development-mode]]
+== Configuring `javac` options
+
+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 (for instance in <<dev-mode,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`:
+
+[source,xml]
+----
+<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>
+----
+
+[IMPORTANT]
+====
+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 https://maven.apache.org/configure.html#maven_opts-environment-variable[`MAVEN_OPTS`]:
+
+include::{includes}/devtools/maven-opts.adoc[]
+
+**Alternatively**, you can simply create the file
+https://maven.apache.org/configure.html#mvn-jvm-config-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`.
+====
+
 [[dev-mode]]
 == Development mode
 
@@ -219,39 +268,6 @@ 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.
 
-=== Configuring Development Mode
-
-By default, the Maven plugin picks up compiler flags to pass to
-`javac` from `maven-compiler-plugin`.
-
-If you need to customize the compiler flags used 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`:
-
-[source,xml]
-----
-<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>
-----
-
-
 == Debugging
 
 In development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM.