reorder: simpler 6 to 8 compatibility first, older 5- after
diff --git a/src/site/apt/examples/module-info.apt.vm b/src/site/apt/examples/module-info.apt.vm
index a65dcbc..48669a4 100644
--- a/src/site/apt/examples/module-info.apt.vm
+++ b/src/site/apt/examples/module-info.apt.vm
@@ -45,11 +45,17 @@
[]
- JDK 9 only supports compilations for
- Java 6 and above, so projects wanting to be compatible with Java 5 or below need to use two different JDKs. With
- {{{/guides/mini/guide-using-toolchains.html}toolchains}} it is quite easy to achieve this. Be aware that you will
- need at least Maven 3.3.1 to specify a custom jdkToolchain in your plugin configuration. You could add a jdkToolchain
- to do base-compile execution-block as well referring to JDK 5.
+ Notice that, in addition, JDK 9 only supports compilations for Java 6 and above, so projects wanting to be compatible with Java 5 or below need
+ to use two different JDKs for the 2 executions. With {{{/guides/mini/guide-using-toolchains.html}toolchains}} configuration, it is
+ quite easy to achieve this, even if a little bit more complex.
+
+* Java 6 to 8 Compatibility
+
+ In case you want the project to be Java 6, 7 or 8 compatible, you can simply use JDK 9 for both execution blocks.
+
+ The easiest way is to use Java 9 as the runtime for Maven, by setting <<<JAVA_HOME=/path/to/jdk-9>>> before running <<<mvn>>>.
+ But if you want to use an older Java runtime for Maven, you can use the maven-toolchain-plugin to specify the shared JDK (supported since Maven 2.0.9)
+ or a custom jdkToolchain (supported since Maven 3.3.1) and refer to the JDK 9 installation on your system.
+-------
<project>
@@ -67,7 +73,62 @@
<configuration>
<release>9</release>
<!-- no excludes: compile everything to ensure module-info contains right entries -->
- <!-- required when JAVA_HOME is JDK 8 or below -->
+ </configuration>
+ </execution>
+ <execution>
+ <id>base-compile</id>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <!-- recompile everything for target VM except the module-info.java -->
+ <excludes>
+ <exclude>module-info.java</exclude>
+ </excludes>
+ </configuration>
+ </execution>
+ </executions>
+ <!-- defaults for compile and testCompile -->
+ <configuration>
+ <release>6</release><!-- or 7 or 8 depending on compatibility expectations -->
+ <!-- Only required when Maven runtime JAVA_HOME isn't at least Java 9 and when haven't configured the maven-toolchains-plugin -->
+ <jdkToolchain>
+ <version>9</version>
+ </jdkToolchain>
+ </configuration>
+ </plugin>
+ </plugins>
+ [...]
+ </build>
+ [...]
+</project>
++-------
+
+* Java 5 or below Compatibility
+
+ Given Maven 3 requires newer Java release at runtime, you'll absolutely need to use Toolchains to use a JDK different from
+ Maven runtime.
+
+ Be aware that you will need at least Maven 3.3.1 to specify a custom jdkToolchain in your plugin configuration.
+ You could add a jdkToolchain to do base-compile execution-block as well referring to JDK 5.
+
++-------
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <id>default-compile</id>
+ <configuration>
+ <release>9</release>
+ <!-- no excludes: compile everything to ensure module-info contains right entries -->
+ <!-- toolchain required when JAVA_HOME is JDK 8 or below -->
<jdkToolchain>
<version>9</version>
</jdkToolchain>
@@ -78,8 +139,8 @@
<goals>
<goal>compile</goal>
</goals>
- <!-- recompile everything for target VM except the module-info.java -->
<configuration>
+ <!-- recompile everything for target VM except the module-info.java -->
<excludes>
<exclude>module-info.java</exclude>
</excludes>
@@ -102,55 +163,3 @@
[...]
</project>
+-------
-
- In case you want the project to be Java 6 compatible, the easiest to do this is to use Java 9 for both execution
- blocks. You can use the maven-toolchain-plugin to specify the shared JDK (supported since Maven 2.0.9) or a custom
- jdkToolchain (supported since Maven 3.3.1) and refer to the JDK 9 installation on your system. Or simply use Java 9
- as the runtime for Maven by setting <<<JAVA_HOME=/path/to/jdk-9>>>.
-
-+-------
-<project>
- [...]
- <build>
- [...]
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>${project.version}</version>
- <executions>
- <execution>
- <id>default-compile</id>
- <configuration>
- <release>9</release>
- <!-- no excludes: compile everything to ensure module-info contains right entries -->
- </configuration>
- </execution>
- <execution>
- <id>base-compile</id>
- <goals>
- <goal>compile</goal>
- </goals>
- <!-- recompile everything for target VM except the module-info.java -->
- <configuration>
- <excludes>
- <exclude>module-info.java</exclude>
- </excludes>
- </configuration>
- </execution>
- </executions>
- <!-- defaults for compile and testCompile -->
- <configuration>
- <release>6</release><!-- or 7 or 8 depending on compatibility expectations -->
- <!-- Only required when JAVA_HOME isn't at least Java 9 and when haven't configured the maven-toolchains-plugin -->
- <jdkToolchain>
- <version>9</version>
- </jdkToolchain>
- </configuration>
- </plugin>
- </plugins>
- [...]
- </build>
- [...]
-</project>
-+-------
