This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new bb1ee8b5 Add guides to targeting a Java version and multi-release JARs
bb1ee8b5 is described below
commit bb1ee8b567e308c6fb6b54ce7e408332a61566d7
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:57:21 2026 +0000
Add guides to targeting a Java version and multi-release JARs
---
content/filtered-resources/.htaccess | 3 +
content/markdown/guides/mini/guide-java-target.md | 142 ++++++++++++++++++
.../guides/mini/guide-multi-release-jars.md | 158 +++++++++++++++++++++
content/markdown/guides/mini/index.txt | 2 +
content/markdown/whatsnewinmaven4.md | 2 +-
content/site.xml | 2 +
6 files changed, 308 insertions(+), 1 deletion(-)
diff --git a/content/filtered-resources/.htaccess
b/content/filtered-resources/.htaccess
index 7f7b0c2c..4959d228 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -30,6 +30,9 @@ Redirect Permanent /scm/scms-overview.html
/pom-scm-urls.html#Supported_SCMs
Redirect Permanent /plugins/maven-checkstyle-plugin/customize.html
/plugins/maven-checkstyle-plugin/examples/custom-checker-config.html
Redirect Permanent /plugins/maven-checkstyle-plugin/howto.html
/plugins/maven-checkstyle-plugin/usage.html
Redirect Permanent /plugins/maven-checkstyle-plugin/tips.html
/plugins/maven-checkstyle-plugin/examples/multi-module-config.html
+Redirect Permanent
/plugins/maven-compiler-plugin/examples/set-compiler-release.html
/guides/mini/guide-java-target.html
+Redirect Permanent
/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html
/guides/mini/guide-java-target.html#Using_the_source_and_target_Options
+Redirect Permanent /plugins/maven-compiler-plugin/multirelease.html
/guides/mini/guide-multi-release-jars.html
Redirect Permanent /plugins/maven-artifact-plugin/reproducible.html
/guides/mini/guide-reproducible-builds.html#Reading_the_artifact.3Acompare_output
Redirect Permanent /shared/maven-archiver/examples/classpath.html
/guides/mini/guide-manifest.html#Setting_Up_the_Classpath
diff --git a/content/markdown/guides/mini/guide-java-target.md
b/content/markdown/guides/mini/guide-java-target.md
new file mode 100644
index 00000000..3df1a94a
--- /dev/null
+++ b/content/markdown/guides/mini/guide-java-target.md
@@ -0,0 +1,142 @@
+<!--
+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.
+-->
+
+
+# Guide to Targeting a Java Version
+
+A project often has to be built with a newer JDK than the Java version it
supports at runtime. This guide shows how to tell the [Compiler
Plugin](/plugins/maven-compiler-plugin/) which Java version to compile for.
+
+## Using the release Option
+
+Starting with JDK 9, the `javac` executable accepts the `--release` option to
specify against which Java SE release you want to build the project. For
example, you have JDK 21 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 that release as well as the public
API of that release. Unlike the older [...]
+
+The option can be provided either through the `maven.compiler.release`
property:
+
+```xml
+<project>
+ [...]
+ <properties>
+ <maven.compiler.release>17</maven.compiler.release>
+ </properties>
+ [...]
+</project>
+```
+
+or by configuring the plugin directly with its
[`release`](/plugins/maven-compiler-plugin/compile-mojo.html#release) parameter:
+
+```xml
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.16.0</version>
+ <configuration>
+ <release>17</release>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
+```
+
+The value follows [Java's version-string scheme (JEP
223)](https://openjdk.org/jeps/223) adopted with Java 9, so the release number
does not start with `1.` any more: write `8`, not `1.8`. The supported
`release` values are the release of the JDK in use plus a limited number of
previous releases.
+
+### Building on JDK 8
+
+The `--release` option is not supported by JDK 8. Since version 3.13.0 of the
Compiler Plugin, with the default `javac` compiler id, the `release` parameter
is only effective on Java 9 and later; on JDK 8 the plugin passes `source` and
`target` to the compiler instead. A project that targets Java 8 and is built on
JDK 8 as well as on JDK 9 or later can therefore set all three:
+
+```xml
+<configuration>
+ <release>8</release>
+ <source>8</source>
+ <target>8</target>
+</configuration>
+```
+
+With an older plugin version, or a `compilerId` other than `javac`, activate
`maven.compiler.release` only on JDK 9 and later, with a profile:
+
+```xml
+<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>
+```
+
+## Using the source and target Options
+
+Use `-source` and `-target` only when `release` is not available, for example
with a plugin version older than 3.13.0 on JDK 8. The `javac` executable
accepts them to compile for a different Java version than the one it runs on,
and the Compiler Plugin passes them on through its
[`source`](/plugins/maven-compiler-plugin/compile-mojo.html#source) and
[`target`](/plugins/maven-compiler-plugin/compile-mojo.html#target) parameters.
Use the version-string scheme of JEP 223 here too.
+
+To use the Java 8 language features and produce classes that are compatible
with a Java 8 JVM, add the two properties, which are the user properties of the
plugin parameters:
+
+```xml
+<project>
+ [...]
+ <properties>
+ <maven.compiler.source>8</maven.compiler.source>
+ <maven.compiler.target>8</maven.compiler.target>
+ </properties>
+ [...]
+</project>
+```
+
+or configure the plugin directly:
+
+```xml
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.16.0</version>
+ <configuration>
+ <source>8</source>
+ <target>8</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
+```
+
+Setting `target` does not guarantee that the code runs on a JRE of that
version. Unintended use of APIs that only exist in later JREs makes the code
fail at runtime with a linkage error. To avoid this, use the `release` option,
configure the compiler's boot classpath to match the target JRE, or verify the
API usage with the [Animal Sniffer Maven
Plugin](https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/).
+
+In the same way, setting `source` does not guarantee that the code compiles on
a JDK of that version. To compile with a specific JDK that differs from the one
running Maven, see the [Guide to Using
Toolchains](/guides/mini/guide-using-toolchains.html).
+
+## See Also
+
+- [Guide to Using Toolchains](/guides/mini/guide-using-toolchains.html)
+- [Guide to Multi-Release JARs](/guides/mini/guide-multi-release-jars.html)
diff --git a/content/markdown/guides/mini/guide-multi-release-jars.md
b/content/markdown/guides/mini/guide-multi-release-jars.md
new file mode 100644
index 00000000..3df6de32
--- /dev/null
+++ b/content/markdown/guides/mini/guide-multi-release-jars.md
@@ -0,0 +1,158 @@
+<!--
+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.
+-->
+
+
+# Guide to Multi-Release JARs
+
+[JEP 238](https://openjdk.org/jeps/238) introduced multi-release JARs: one JAR
that holds Java-version-dependent classes, where the runtime picks the best
matching version of each class. Building one spans two plugins. The [Compiler
Plugin](/plugins/maven-compiler-plugin/) compiles the sources once per Java
version, and the [JAR Plugin](/plugins/maven-jar-plugin/) packages the result.
+
+## The Problem
+
+A library must stay compatible with earlier Java versions but would like to
use new JDK features when it runs on a newer one. For example, `java.nio.file`
was added in Java 7 and handles files much better, while Maven itself still
required Java 6 at the time.
+
+Without multi-release JARs there are two solutions:
+
+1. Compile with the targeted JDK (Java 6) and use reflection. The code is
guaranteed to be Java 6 compatible, but the reflective part is hard to verify.
+
+ ```java
+ if (isAtLeastJava7()) {
+ Method toPathMethod = f.getClass().getMethod("toPath");
+ Object toPathInstance = toPathMethod.invoke(f);
+ Method isSymbolicLink =
Class.forName("java.nio.file.Files").getMethod("isSymbolicLink");
+ ...
+ } else {
+ // compare absoluteFile with canonicalFile
+ ...
+ }
+ ```
+
+2. Compile with the required JDK (Java 7), but with `source` and `target` set
to the lowest version (1.6). The danger is that you cannot ensure that all code
is Java 6 compatible. Depending on the code structure, [Animal
Sniffer](https://www.mojohaus.org/animal-sniffer/) can help.
+
+ ```java
+ if (isAtLeastJava7()) {
+ return Files.isSymbolicLink(f.toPath());
+ } else {
+ // compare absoluteFile with canonicalFile
+ ...
+ }
+ ```
+
+## The Solution
+
+A multi-release JAR keeps the base classes at the root and the
version-specific ones under `META-INF/versions`:
+
+```
+A.class
+B.class
+C.class
+D.class
+META-INF/MANIFEST.MF { Multi-Release: true }
+ versions/9/A.class
+ B.class
+ 10/A.class
+ C.class
+```
+
+With the `Multi-Release: true` attribute in the manifest, the Java runtime
also looks inside `META-INF/versions` for version-specific classes. Without it,
only the base classes are used. The
[`maven-jar-plugin`](/plugins/maven-jar-plugin/jar-mojo.html#detectMultiReleaseJar)
adds the attribute by itself when the JAR contains a `META-INF/versions`
directory (`detectMultiReleaseJar`, enabled by default). To set it explicitly,
add it with the archive configuration, see [Working with Manifest [...]
+
+```xml
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>3.5.1</version>
+ <configuration>
+ <archive>
+ <manifestEntries>
+ <Multi-Release>true</Multi-Release>
+ </manifestEntries>
+ </archive>
+ </configuration>
+</plugin>
+```
+
+The Compiler Plugin can place the output of an execution in
`META-INF/versions/${release}` for you: set
[`release`](/plugins/maven-compiler-plugin/compile-mojo.html#release) together
with
[`multiReleaseOutput`](/plugins/maven-compiler-plugin/compile-mojo.html#multiReleaseOutput)
to `true` in an additional execution.
+
+## Challenges
+
+The theory is simple, but in practice multi-release JARs get complex. Think
twice before turning a JAR into one, because such JARs are hard to read,
maintain and test. Applications rarely need this, unless the application is
widely distributed and you do not control the targeted Java runtime. Libraries
should ask: do I need this new Java feature? Can I make this Java version the
new requirement? Would an `if`/`else` as in the first solution above be
acceptable?
+
+Keep these facts in mind:
+
+- All classes must stay in sync. If you add a method to one class, add it to
the other versions as well. Letting all multi-release classes implement an
interface, and only calling the interface methods from the base code, reduces
the risk. The best protection is to test the JAR with all targeted Java
versions.
+- The Java compiler must be called once per Java version, either with multiple
Maven projects or modules, or with extra compiler executions in the POM (as
older projects with a `module-info` do, see the [Compiler Plugin's
`module-info`
example](/plugins/maven-compiler-plugin/examples/module-info.html)).
+- The `Multi-Release: true` attribute is only recognized when the classes are
in a JAR, so you cannot test the classes in
`target/classes/META-INF/versions/${release}/`.
+- IDEs support one JDK per Maven project, whereas with multi-release JARs you
want to choose it per source folder.
+
+## Patterns
+
+There are several patterns to build a multi-release JAR with Maven.
Integration tests for each pattern, built from the same sources, are in the
[Compiler Plugin's `multirelease-patterns`
directory](https://github.com/apache/maven-compiler-plugin/tree/master/src/it/multirelease-patterns).
+
+### Pattern 1: Maven Multimodule
+
+The [first pattern](https://github.com/hboutemy/maven-jep238) came from the
Maven team. The requirements were:
+
+- one Maven call to compile, test and package the JAR,
+- it must work with IDEs,
+- developers should not have to change how they work, and the configuration
stays simple.
+
+The only solution that covers the first two points is to split the code into a
multimodule project, where every module is a standard Maven project with close
to no specific configuration. You can run it in two ways:
+
+- Build with the highest required JDK and use `release` to make sure each
module only uses matching APIs and syntax. As the version-specific code is
isolated, the tests can run with a higher Java runtime.
+- Use [toolchains](/guides/mini/guide-using-toolchains.html) if you really
want to compile and test with the matching Java version.
+
+The downside is that a hierarchical structure is required although the result
is a single artifact.
+
+### Pattern 2: Multi Project
+
+[This
solution](https://web.archive.org/web/2020/http://word-bits.flurg.com/multrelease-jars/)
responds to the multimodule setup. The requirements are almost the same, but
the project must not switch to a multimodule format, so the parts are separate
Maven projects. One project holds the base code and becomes the multi-release
JAR in the end.
+
+The first build needs at least three Maven calls: compile the base, build all
version-specific projects, and build the main project again, now including the
version-specific classes extracted from their JARs. The setup is compact but
has cyclic dependencies, which needs some tricks and complicates releasing:
SNAPSHOTs must be installed in the local repository, and a release needs two
releases of the base project.
+
+### Pattern 3: Single Project
+
+These variants keep everything in one Maven project without a multimodule
layout, and need one Maven call to compile and package. Every Java version gets
its own source folder and output folder, and the outputs are combined just
before packaging.
+
+- [Single
Project](https://in.relation.to/2017/02/13/building-multi-release-jars-with-maven/):
not covered is how to test every class.
+- [Multi-Release
Parent](http://www.russgold.net/sw/2018/04/easier-than-it-looks/): replaces the
Ant plugin with extra executions of the `maven-compiler-plugin` and is set up
as a parent POM, so other projects can reuse it. It uses toolchains to build
each class with its matching Java version, so you always get the full JAR, and
Surefire is called once.
+- [CI server](https://github.com/codehaus-plexus/plexus-languages): only
specifies executions for the sources of a specific Java version and does not
use toolchains, but the JDK that runs Maven. Only the sources up to that Java
version are compiled and tested, so it relies on a CI server where every
targeted Java version is available. If the CI build succeeds, all classes were
tested with their matching Java version.
+
+### Pattern 4: Maven Extension and Plugin
+
+The
[`multi-release-jar-maven-plugin`](https://github.com/metlos/multi-release-jar-maven-plugin)
introduces a packaging type and a plugin that takes care of the multiple
executions of the `maven-compiler-plugin`, configured through its
`perReleaseConfiguration`. Not covered is how to test every class.
+
+### Summary
+
+| | Maven Multimodule | Multi Project | Single project (runtime) | Single
project (toolchains) | Maven extension and plugin |
+|:---|:---:|:---:|:---:|:---:|:---:|
+| Number of projects | 1 | 1 + number of Java versions | 1 | 1 | 1 |
+| Builds to package | 1 | 2 + number of Java versions | 1 | 1 | 1 |
+| Builds per project to test | 1 | 1 | number of Java versions | 1 | N/A (a) |
+| Simple Maven project layout | No | Yes | Yes | Yes | Yes |
+| Additional POM adjustments (b) | 1 (c) | number of Java versions (d) |
number of Java versions (e) | unknown | number of Java versions (g) |
+| Includes module descriptor | No (h) | No (h) | Yes | Yes | Yes |
+| IDE support (i) | Yes | Yes | No | No | No |
+
+- (a) The project can only run with the highest required JDK, so the code
cannot be tested on all JDKs.
+- (b) The number of executions added to the default lifecycle; it reflects the
complexity of the POM.
+- (c) The multimodule pattern uses the `maven-assembly-plugin` to assemble the
multi-release JAR.
+- (d) The multi project pattern uses the `maven-dependency-plugin` to unpack
the version-specific dependency into its matching output directory.
+- (e) A profile per required Java version holds an extra execution for that
version.
+- (g) The extension and plugin hides the multiple executions in
`perReleaseConfiguration`.
+- (h) Requires `--patch-module` on a dependency.
+- (i) With IDE support, all classes are recognized and can be tested within
the IDE.
diff --git a/content/markdown/guides/mini/index.txt
b/content/markdown/guides/mini/index.txt
index fb0bf472..90164985 100644
--- a/content/markdown/guides/mini/index.txt
+++ b/content/markdown/guides/mini/index.txt
@@ -33,4 +33,6 @@ under the License.
- [Using Extensions]($prefix/guide-using-extensions.html)
- [Building For Different
Environments]($prefix/guide-building-for-different-environments.html)
- [Using Toolchains]($prefix/guide-using-toolchains.html)
+- [Targeting a Java Version]($prefix/guide-java-target.html)
+- [Building Multi-Release JARs]($prefix/guide-multi-release-jars.html)
- [Injecting POM Properties via
settings.xml](/examples/injecting-properties-via-settings.html)
diff --git a/content/markdown/whatsnewinmaven4.md
b/content/markdown/whatsnewinmaven4.md
index 7d03798c..39607873 100644
--- a/content/markdown/whatsnewinmaven4.md
+++ b/content/markdown/whatsnewinmaven4.md
@@ -661,7 +661,7 @@ The Maven issue tracker provides a [full list of all
resolved issues of Maven 4.
[3]: https://en.wikipedia.org/wiki/Java_Platform_Module_System
[4]:
https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms
[5]: https://www.youtube.com/watch?v=ZD_YxTmQ16Q&t=16710s
-[6]:
https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-release.html
+[6]: https://maven.apache.org/guides/mini/guide-java-target.html
[7]: https://maven.apache.org/guides/mini/guide-using-toolchains.html
[8]: https://maarten.mulders.it/2021/03/introduction-to-maven-toolchains/
[9]: https://issues.apache.org/jira/projects/MNG/issues/MNG-8061
diff --git a/content/site.xml b/content/site.xml
index faa19790..48176ed2 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -168,6 +168,8 @@ under the License.
<item name="Building for Different Environments"
href="/guides/mini/guide-building-for-different-environments.html"/>
<item name="Using Toolchains"
href="/guides/mini/guide-using-toolchains.html"/>
+ <item name="Targeting a Java Version"
href="/guides/mini/guide-java-target.html"/>
+ <item name="Building Multi-Release JARs"
href="/guides/mini/guide-multi-release-jars.html"/>
<item name="Maven CI Friendly Version"
href="/guides/mini/guide-maven-ci-friendly.html"/>
</item>