You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by mb...@apache.org on 2025/02/16 06:08:43 UTC
(maven-compiler-plugin) branch master updated: Update docs for Maven 4 and release option
This is an automated email from the ASF dual-hosted git repository.
mbuenger pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-compiler-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new f79c7fd Update docs for Maven 4 and release option
f79c7fd is described below
commit f79c7fd79ee92cf966ec421bfcf71dea4f1bbcd8
Author: Matthias Bünger <Bu...@users.noreply.github.com>
AuthorDate: Sun Feb 16 07:08:39 2025 +0100
Update docs for Maven 4 and release option
---
src/site/apt/examples/set-compiler-release.apt.vm | 72 ++--------------------
.../examples/set-compiler-source-and-target.apt.vm | 21 ++++---
src/site/apt/index.apt.vm | 15 +++--
src/site/site.xml | 3 +-
4 files changed, 30 insertions(+), 81 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..c0e57d7 100644
--- a/src/site/apt/examples/set-compiler-release.apt.vm
+++ b/src/site/apt/examples/set-compiler-release.apt.vm
@@ -28,15 +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
+ For example, you have JDK 17 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}},
+ means that, unlike the old <<<-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,67 +75,8 @@ 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.
-
- Conditional parametrization is required for the Compiler Plugin version below <<<3.13.0>>>
- or compilerId different that <<<javac>>>.
-
- This may be done through the use of a profile:
-
-+-----
-<project>
- [...]
- <profiles>
- [...]
- <profile>
- <id>set-compiler-release</id>
- <activation>
- <jdk>[9,)</jdk>
- </activation>
- <properties>
- <maven.compiler.release>8</maven.compiler.release>
- </properties>
- </profile>
- [...]
- </profiles>
- [...]
-</project>
-+-----
-
- Since version <<<3.13.0>>> of the Compiler Plugin together with the default <<<javac>>> compilerId you don't need conditional parametrisation of <<<release>>>.
- The <<<release>>> parameter will only be effective for Java 9 or above, otherwise the <<<source>>> and <<<target>>> will be passed to the compiler.
-
- So you can simply configure as:
-
-+-----
-<project>
- [...]
- <build>
- [...]
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <release>8</release>
- <source>8</source>
- <target>8</target>
- </configuration>
- </plugin>
- </plugins>
- [...]
- </build>
- [...]
-</project>
-+-----
-
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..78ef38e 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,9 @@ 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 263b8b7..dc2b27c 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -29,8 +29,13 @@
${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.
- Other compilers than <<<javac>>> can be used.
+ default compiler used to compile Java sources is <<<javac>>>.
+ If you want to use another compiler, refer to the {{{./non-javac-compilers.html} guide: Using Non-Javac Compilers}}.
+
+ 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/en/java/javase/17/docs/specs/man/javac.html}}.>
@@ -70,11 +75,9 @@ ${project.name}
To provide you with better understanding on some usages of the Compiler
Plugin, you can take a look into the following examples:
- * {{{./examples/compile-using-different-jdk.html}Compile Using A Different JDK}}
-
- * {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
+ * {{{./examples/compile-using-different-jdk.html}Compile using A Different JDK}}
- * {{{./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 64a8680..c7c1f72 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -34,8 +34,7 @@ under the License.
</menu>
<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"/>