This is an automated email from the ASF dual-hosted git repository.
mbuenger pushed a commit to branch maven-compiler-plugin-3.x
in repository https://gitbox.apache.org/repos/asf/maven-compiler-plugin.git
The following commit(s) were added to refs/heads/maven-compiler-plugin-3.x by
this push:
new 5449407 [MCOMPILER-529] Update docs about version schema (Maven 3)
5449407 is described below
commit 5449407f106ad6257471f9e7caa5fbe58c06ada9
Author: Matthias Bünger <[email protected]>
AuthorDate: Tue Feb 11 17:05:57 2025 +0100
[MCOMPILER-529] Update docs about version schema (Maven 3)
This PR updates several parts of the documentation for Maven 3 based on JDK
8 and aligns the docs to the new Java version schema. In particular on the
front page it's mentioned that "8" is the default, where in the code it's
actual "1.8" - but I wanted to keep docs consistent here.
---
src/site/apt/examples/set-compiler-release.apt.vm | 18 ++++++++++--------
.../examples/set-compiler-source-and-target.apt.vm | 22 +++++++++++++++-------
src/site/apt/index.apt.vm | 20 ++++++++------------
src/site/site.xml | 2 +-
4 files changed, 34 insertions(+), 28 deletions(-)
diff --git a/src/site/apt/examples/set-compiler-release.apt.vm
b/src/site/apt/examples/set-compiler-release.apt.vm
index 3befe70..11e04ee 100644
--- a/src/site/apt/examples/set-compiler-release.apt.vm
+++ b/src/site/apt/examples/set-compiler-release.apt.vm
@@ -28,14 +28,14 @@
Setting the <<<--release>>> of the Java Compiler
- Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
+ Starting with 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
+ means that, unlike the old
{{{../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.
@@ -76,18 +76,20 @@ Setting the <<<--release>>> of the Java Compiler
</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
+ <<Note:>> The value in the <<<release>>> parameter follows
+ {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP
223)}}} 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.
* Usage on JDK 8
- The <<<--release>>> option is not supported using JDK 8. To enable a project
that targets Java 8
- to be built using JDK 8 and also JDK 9 or later requires the conditional
usage of the
- <<<--release>>> option.
+ The <<<--release>>> option is not supported using JDK 8.
+ However, since Compiler plugin version <<<3.13.0>>> you can use the
<<<release>>> property also on JDK 8.
+ The plugin will convert it to <<<source>>> and <<<target>>> automatically.
- Conditional parametrization is required for the Compiler Plugin version
below <<<3.13.0>>>
+ To enable a project that targets Java 8 to be built using JDK 8 and also JDK
9 or later requires the conditional
+ usage of the <<<--release>>> option, when using a plugin version below
<<<3.13.0>>>
or compilerId different that <<<javac>>>.
This may be done through the use of a profile:
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 c02b52d..e4e3812 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
@@ -28,21 +28,25 @@
Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
+ (If you're are using version <<<3.13.0>>> or newer of the Compiler Plugin,
use the recommended
+ {{{../examples/set-compiler-release.html}<<<maven.compiler.release>>>
property}}.)
+
Sometimes when you may need to compile a certain project to a different
version than what you are currently using. The <<<javac>>> can accept
such command using <<<-source>>> and <<<-target>>>. The Compiler Plugin
can also be configured to provide these options during compilation.
+ You have to set the version following {{{https://openjdk.org/jeps/223}Java's
new Version-String Scheme (JEP 223)}}}.
- For example, if you want to use the Java 8 language features (<<<-source
1.8>>>)
- and also want the compiled classes to be compatible with JVM 1.8 (<<<-target
1.8>>>),
- you can either add the two following properties, which are the default
property names for the plugin parameters:
+ For example, if you want to use the Java 8 language features and also want
the compiled classes to be compatible
+ with JVM 8 (former 1.8) you can either add the two following properties,
which are the default property names
+ for the plugin parameters:
+-----
<project>
[...]
<properties>
- <maven.compiler.source>1.8</maven.compiler.source>
- <maven.compiler.target>1.8</maven.compiler.target>
+ <maven.compiler.source>8</maven.compiler.source>
+ <maven.compiler.target>8</maven.compiler.target>
</properties>
[...]
</project>
@@ -61,8 +65,8 @@ Setting the <<<-source>>> and <<<-target>>> of the Java
Compiler
<artifactId>maven-compiler-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <source>1.8</source>
- <target>1.8</target>
+ <source>8</source>
+ <target>8</target>
</configuration>
</plugin>
</plugins>
@@ -79,6 +83,10 @@ Setting the <<<-source>>> and <<<-target>>> of the Java
Compiler
{{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal
Sniffer Maven Plugin}}
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}}.
+ Since plugin version <<<3.13.0>>> you can use the <<<release>>> property
also on JDK 8.
+ The compiler plugin will convert it to <<<source>>> and <<<target>>>
automatically.
+
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 c8e2be6..59b089e 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -29,20 +29,16 @@
${project.name}
The Compiler Plugin is used to compile the sources of your project. The
- default compiler used to compile Java sources is javax.tools.JavaCompiler.
- If you want to force the plugin to use <<<javac>>>, you must configure the
plugin option
{{{./compile-mojo.html#forceJavacCompilerUse}<<<forceJavacCompilerUse>>>}}.
+ default compiler used to compile Java sources is <<<javac>>>.
+ If you want to use another compiler, refer to the {{{./non-javac-compilers}
guide: Using Non-Javac Compilers}}.
- Also note that at present the default <<<source>>> setting is <<<1.8>>> and
the default <<<target>>>
- setting is <<<1.8>>>, independently of the JDK you run Maven with.
- You are highly encouraged to change these defaults by setting <<<source>>>
and <<<target>>>
- as described in
- {{{./examples/set-compiler-source-and-target.html}Setting the -source and
-target of the Java Compiler}}.
-
- Other compilers than <<<javac>>> can be used and work has already started
- on AspectJ, .NET, and C#.
+ At present the default <<<source>>> and the default <<<target>>> setting are
both <<<8>>>,
+ independently of the JDK you run Maven with.
+ You are highly encouraged to change these defaults by setting the
<<<release>>> option as described in the
+ {{{./examples/set-compiler-release.html}guide: Compile Using The
<<<--release>>> javac Option}}.
<<NOTE:>> <To know more about the JDK javac, please see:
-
{{https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html}}.>
+ {{https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html}}.>
* Goals Overview
@@ -83,7 +79,7 @@ ${project.name}
* {{{./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/set-compiler-release.html}Compile Using The --release javac
Option}}
* {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory
Allocation Enhancement}}
diff --git a/src/site/site.xml b/src/site/site.xml
index 3e9ce47..b13207d 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -35,7 +35,7 @@ under the License.
<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 the --release javac Option"
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"/>
