(doc) Add example on using --release javac option
diff --git a/src/site/apt/examples/set-compiler-release.apt.vm b/src/site/apt/examples/set-compiler-release.apt.vm
new file mode 100644
index 0000000..671b9d2
--- /dev/null
+++ b/src/site/apt/examples/set-compiler-release.apt.vm
@@ -0,0 +1,82 @@
+ ------
+ Setting the --release of the Java Compiler
+ ------
+ Mahmoud Anouti
+ ------
+ 2019-12-20
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Setting the <<<--release>>> of the Java Compiler
+
+ Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
+ option to specify against which Java SE release you want to build the project.
+ For example, you have JDK 11 installed and used by Maven, but you want to
+ build the project against Java 8.
+ The <<<--release>>> option ensures that the code is compiled following the
+ rules of the programming language of the specified release, and that generated
+ classes target the release as well as the public API of that release. This
+ means that, unlike the
+ {{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}},
+ the compiler will detect and generate an error when using APIs that don't exist
+ in previous releases of Java SE.
+
+ Since version 3.6 of the Compiler Plugin, this option can be provided either
+ via a property:
+
++-----
+<project>
+ [...]
+ <properties>
+ <maven.compiler.release>8</maven.compiler.release>
+ </properties>
+ [...]
+</project>
++-----
+
+ or by configuring the plugin directly:
+
++-----
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <release>8</release>
+ </configuration>
+ </plugin>
+ </plugins>
+ [...]
+ </build>
+ [...]
+</project>
++-----
+
+ <<Note:>> The value in the <<<release>>> parameter follows the new version naming scheme adopted
+ since Java 9. As such, the release number does not start with 1.x anymore. Also note that the
+ supported <<<release>>> targets include the release of the currently used JDK plus a limited number
+ of previous releases.
diff --git a/src/site/apt/examples/set-compiler-source-and-target.apt.vm b/src/site/apt/examples/set-compiler-source-and-target.apt.vm
index 8a051b6..c02b52d 100644
--- a/src/site/apt/examples/set-compiler-source-and-target.apt.vm
+++ b/src/site/apt/examples/set-compiler-source-and-target.apt.vm
@@ -75,9 +75,10 @@
<<Note:>> Merely setting the <<<target>>> option does not guarantee that your code actually runs on a JRE with the
specified version. The pitfall is unintended usage of APIs that only exist in later JREs which would make your code
fail at runtime with a linkage error. To avoid this issue, you can either configure the compiler's boot classpath
- to match the target JRE or use the
+ to match the target JRE, or use the
{{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}}
- to verify your code doesn't use unintended APIs. In the same way, setting the <<<source>>> option does not guarantee
- that your code actually compiles on a JDK with the specified version. To compile your code with a specific JDK
- version, different than the one used to launch Maven, refer to the
- {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.
+ to verify your code doesn't use unintended APIs, or better yet use the
+ {{{../examples/set-compiler-release.html}<<<release>>> option supported since JDK 9}}.
+ In the same way, setting the <<<source>>> option does not guarantee that your code actually compiles on a JDK with
+ the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven,
+ refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index 1fcf71c..38e0eb1 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -83,6 +83,8 @@
* {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
+ * {{{./examples/set-compiler-release.html}Compile Using the --release javac Option (supported since JDK 9)}}
+
* {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}}
* {{{./examples/pass-compiler-arguments.html}Pass Compiler Arguments}}
diff --git a/src/site/site.xml b/src/site/site.xml
index f38ad60..c93a729 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -35,6 +35,7 @@
<menu name="Examples">
<item name="Compile Using A Different JDK" href="examples/compile-using-different-jdk.html"/>
<item name="Compile Using -source and -target javac Options" href="examples/set-compiler-source-and-target.html"/>
+ <item name="Compile Using the --release javac Option (JDK 9+)" href="examples/set-compiler-release.html"/>
<item name="Compile Using Memory Allocation Enhancements" href="examples/compile-with-memory-enhancements.html"/>
<item name="Pass Compiler Arguments" href="examples/pass-compiler-arguments.html"/>
<item name="Non-javac compilerIds" href="non-javac-compilers.html"/>
