diff --git a/README.adoc b/README.adoc index 9a3e939..cfa7547 100644 --- a/README.adoc +++ b/README.adoc @@ -20,42 +20,30 @@ The multi-release JAR support works in two parts: compilation and testing. [id='mr-jar-compilation'] ==== Compilation -Compilation works by providing extra executions of the compiler plugin in order to build the additional JAR layers. The +Compilation works by providing extra executions of the compiler plugin in order to build the additional JAR layers. The base layer is built by the standard `default-compile` execution. After that, Maven profiles are activated based on the -presence of extra layer source directories (e.g. `src/main/java9`, `src/main/java10` etc.). These profiles contain +presence of extra layer source directories (e.g. `src/main/java18`, `src/main/java19` etc.). These profiles contain additional executions of the compiler plugin which compile the sources in the layer directory, while putting the output of the previous step on the class path. -Each present layer is in turn compiled with the results of all the previous layers on the classpath in the correct order. -The additional layer class files are output under the `target/classes` directory in the appropriate location for +Each present layer is in turn compiled with the results of all the previous layers on the classpath in the correct +order. The additional layer class files are output under the `target/classes` directory in the appropriate location for multi-release JAR layers. In order to select the correct class files for the given Java version, the `` property is used. This prevents accidental usage of APIs which are only present in later versions than the one -being compiled. However there is a limitation to this strategy: Java 9 and later do not provide runtime information -for non-standard Java 8 classes such as `sun.misc.Unsafe`. If your project needs to compile against these classes, -you must use the dependency plugin as described <>. - -Note that by default, building Java 8 sources does not use the `` property. To enable this feature, -create a file (which may be empty) in your project root named `build-release-8`. +being compiled. [id='mr-jar-testing'] ==== Testing -Testing using `maven-surefire-plugin` is supported by running the project unit tests on -every supported Java version. In order to do so, it is expected that the following system -property or properties are set as needed: +Testing using `maven-surefire-plugin` is supported by running the project unit tests on every supported Java version. +In order to do so, it is expected that the following system property or properties are set as needed: -* `java8.home`: this property must be set to the location of a Java 8 JDK installation -* `java9.home`: this property must be set to the location of a Java 9 JDK installation -* `java10.home`: this property must be set to the location of a Java 10 JDK installation * `java11.home`: this property must be set to the location of a Java 11 JDK installation -* `java12.home`: this property must be set to the location of a Java 12 JDK installation -* `java13.home`: this property must be set to the location of a Java 13 JDK installation -* `java14.home`: this property must be set to the location of a Java 14 JDK installation -* `java15.home`: this property must be set to the location of a Java 15 JDK installation -* `java16.home`: this property must be set to the location of a Java 16 JDK installation * `java17.home`: this property must be set to the location of a Java 17 JDK installation +* `java18.home`: this property must be set to the location of a Java 18 JDK installation +* `java19.home`: this property must be set to the location of a Java 19 JDK installation In order to simplify development, it is recommended to project maintainers to set these properties in your personal Maven `settings.xml` file. @@ -73,7 +61,7 @@ To configure a multi-release JAR, you need the following pieces of information: [id='mr-jar-base-layer'] ==== Step 1: Base layer version -Choose your base layer version. This can be Java 8 or anything later. Configure the version by configuring the +Choose your base layer version. This can be Java 11 or anything later. Configure the version by configuring the `release` property in the `default-compile` execution of `maven-compiler-plugin`: [source,xml] @@ -84,17 +72,14 @@ Choose your base layer version. This can be Java 8 or anything later. Configur default-compile - 8 + 11 ---- -If the `build-release-8` property is present in the root of your project, then this step is automatically done for you. - -Note that a single-layer Java 8 build does not support the `release` element because the -corresponding `javac` option is only present in JDK 9 and later. +If the `build-release-11` property is present in the root of your project, then this step is automatically done for you. [id='mr-jar-highest-layer'] ==== Step 2: Highest layer version @@ -113,34 +98,20 @@ able to compile every version of Java sources from oldest to newest. The sources for your base layer continue to reside in `src/main/java` and `src/test/java`. Additional layers are in directories whose names correspond to the version of Java that -is targeted by that directory. For example, sources which are specific to Java 9 and later -would be in `src/main/java9`, whereas sources which are specific to Java 11 and later would -be in `src/main/java11`. +is targeted by that directory. For example, sources which are specific to Java 18 and later +would be in `src/main/java18`, whereas sources which are specific to Java 19 and later would +be in `src/main/java19`. If you have a class that needs an alternative version for a given Java version, you only need to provide the replacement source file in the directory corresponding to the _oldest_ -version that supports the alternative source. It is not necessary to copy identical classes into +version that supports the alternative source. It is not necessary to copy identical classes into more than one layer; doing so will increase the size of the resultant artifact needlessly. -There are restrictions on these directories. You may only provide sources that correspond +There are restrictions on these directories. You may only provide sources that correspond to sources that exist in the base layer - that is, it is a violation of the MR JAR specification to provide -sources that introduce new APIs only in later Java versions. The JDK does enforce this at run time. +sources that introduce new APIs only in later Java versions. The JDK does enforce this at run time. In addition, providing additional public members in later versions is generally not recommended. -[id='mr-jar-sun-misc'] -=== Missing JDK APIs - -If your project relies on APIs which are not in the Java SE specification (for example, -classes such as `sun.misc` which are present in the `jdk.unsupported` module in Java 9 and -later), and your base layer targets Java 8, you must take an additional step. - -Since these APIs are not included in the class database that `javac` uses to compile (even -though they are present at run time), stubs of the extra classes must be included but only during -compilation. - -To automatically perform this step, create a file in your project root named `build-include-jdk-misc`. -The contents of this file do not matter; it can be empty or it can contain text referring to this document. - [id='mr-jar-gh-actions'] === Using MR JAR functions with GitHub Actions @@ -150,7 +121,7 @@ version(s) by way of a setup action, and then passing the location of each addit At the time of this writing, the commonly-used `actions/setup-java` does not provide useful environment variables for multiple JDK installs, so it is recommended to instead use the `AdoptOpenJDK/install-jdk` action instead. -As an example, for a project that is built on Java 11 but must also be tested against JDK 8, 9, and 10, your `build.yml` +As an example, for a project that is built on Java 17 but must also be tested against JDK 11 your `build.yml` might look something like this: [source,yaml] @@ -165,33 +136,21 @@ jobs: name: Checkout - uses: AdoptOpenJDK/install-jdk@v1 - name: Set up JDK 11 - with: - version: 11 - - - uses: AdoptOpenJDK/install-jdk@v1 - name: Set up JDK 10 - with: - version: 10 - targets: 'JAVA_HOME_10' - - - uses: AdoptOpenJDK/install-jdk@v1 - name: Set up JDK 9 + name: Set up JDK 17 with: - version: 9 - targets: 'JAVA_HOME_9' + version: 17 - uses: AdoptOpenJDK/install-jdk@v1 - name: Set up JDK 8 + name: Set up JDK 11 with: - version: 8 - targets: 'JAVA_HOME_8' + version: 11 + targets: 'JAVA_HOME_11' - name: Build - run: mvn -B verify --file pom.xml -Djava8.home=$JAVA_HOME_8 -Djava9.home=$JAVA_HOME_9 -Djava10.home=$JAVA_HOME_10 + run: mvn -B verify --file pom.xml -Djava11.home=$JAVA_HOME_11 ---- -Note that this configuration causes the default `JAVA_HOME` environment to be set to JDK 11. +Note that this configuration causes the default `JAVA_HOME` environment to be set to JDK 17. [id='build-control-files'] == Build control files reference @@ -199,17 +158,10 @@ Note that this configuration causes the default `JAVA_HOME` environment to be se [cols="1m,2,1",options="header"] |=== |File name|Purpose|Reference -|build-release-8|Use the `` option to set Java 8 for the base layer.|<> -|build-include-jdk-misc|Include the `jdk-misc` dependency for Java 8 builds.|<> -|build-test-java8|Run tests for Java 8 when `java8.home` is set and JDK 9 or later is used.|<> -|build-test-java9|Run tests for Java 9 when `java9.home` is set and JDK 10 or later is used.|<> -|build-test-java10|Run tests for Java 10 when `java10.home` is set and JDK 11 or later is used.|<> -|build-test-java11|Run tests for Java 11 when `java11.home` is set and JDK 12 or later is used.|<> -|build-test-java12|Run tests for Java 12 when `java12.home` is set and JDK 13 or later is used.|<> -|build-test-java13|Run tests for Java 13 when `java13.home` is set and JDK 14 or later is used.|<> -|build-test-java14|Run tests for Java 14 when `java14.home` is set and JDK 15 or later is used.|<> -|build-test-java15|Run tests for Java 15 when `java15.home` is set and JDK 16 or later is used.|<> -|build-test-java16|Run tests for Java 16 when `java16.home` is set and JDK 17 or later is used.|<> +|build-release-11|Use the `` option to set Java 11 for the base layer.|<> +|build-test-java11|Run tests for Java 11 when `java11.home` is set and JDK 17 or later is used.|<> |build-test-java17|Run tests for Java 17 when `java17.home` is set and JDK 18 or later is used.|<> +|build-test-java18|Run tests for Java 18 when `java18.home` is set and JDK 19 or later is used.|<> +|build-test-java19|Run tests for Java 19 when `java19.home` is set and JDK 20 or later is used.|<> |=== diff --git a/pom.xml b/pom.xml index 4cd6b7c..0b87af9 100644 --- a/pom.xml +++ b/pom.xml @@ -254,13 +254,13 @@ - - prepare-agent - - prepare-agent - - generate-test-resources - + + prepare-agent + + prepare-agent + + generate-test-resources + @@ -436,12 +436,12 @@ - compile-java8-release-flag + compile-java11-release-flag - ${basedir}/build-release-8 + ${basedir}/build-release-11 - [9,) + [11,) @@ -456,7 +456,7 @@ compile - 8 + 11 @@ -465,762 +465,244 @@ - - - include-jdk-misc - - - ${basedir}/build-include-jdk-misc - - [9,) - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - default-compile - compile - - compile - - - 8 - - - - - - - - - org.jboss - jdk-misc - ${version.jdk-misc} - true - - - - - - - - - - - java9-test-classpath - - [9,10) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/9 - - ${project.build.outputDirectory} - - - - - - - - - - - - java8-test - - [9,) - - java8.home - - - ${basedir}/build-test-java8 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java8-test - test - - test - - - ${java8.home}/bin/java - - ${java8.home}/lib/tools.jar - - - - - - - - - - - - java9-mr-build - - [9,) - - ${basedir}/src/main/java9 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java9 - compile - - compile - - - 9 - - ${project.basedir}/src/main/java9 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - - - - - - - - java10-test-classpath - - [10,11) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/10 - - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java9-test - - [10,) - - java9.home - - - ${basedir}/build-test-java9 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java9-test - test - - test - - - ${java9.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/9 - - ${project.build.outputDirectory} - - - - - - - - - - - - java10-mr-build - - [10,) - - ${basedir}/src/main/java10 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java10 - compile - - compile - - - 10 - - ${project.basedir}/src/main/java10 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - - - - - - - - java11-test-classpath - - [11,12) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/11 - - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java10-test - - [11,) - - java10.home - - - ${basedir}/build-test-java10 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java10-test - test - - test - - - ${java10.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/10 - - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java11-mr-build - - [11,) - - ${basedir}/src/main/java11 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java11 - compile - - compile - - - 11 - - ${project.basedir}/src/main/java11 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - - - - - - - - java12-test-classpath - - [12,13) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/12 - - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java11-test - - [12,) - - java11.home - - - ${basedir}/build-test-java11 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java11-test - test - - test - - - ${java11.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/11 - - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java12-mr-build - - [12,) - - ${basedir}/src/main/java12 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java12 - compile - - compile - - - 12 - - ${project.basedir}/src/main/java12 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - - + - + - java13-test-classpath - - [13,14) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/13 - - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - + java17-test-classpath + + [17,18) + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + default-test + + ${project.build.outputDirectory}/META-INF/versions/17 + + ${project.build.outputDirectory} + + + + + + + - + - java12-test - - [13,) - - java12.home - - - ${basedir}/build-test-java12 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java12-test - test - - test - - - ${java12.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/12 - - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - + java11-test + + [17,) + + java11.home + + + ${basedir}/build-test-java11 + + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + java11-test + test + + test + + + ${java11.home}/bin/java + ${project.build.outputDirectory}/META-INF/versions/11 + + ${project.build.outputDirectory} + + + + + + + - + - java13-mr-build - - [13,) - - ${basedir}/src/main/java13 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java13 - compile - - compile - - - 13 - - ${project.basedir}/src/main/java13 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - + java17-mr-build + + [17,) + + ${basedir}/src/main/java17 + + + + + + org.apache.maven.plugins + maven-compiler-plugin + + + compile-java17 + compile + + compile + + + 17 + + ${project.basedir}/src/main/java17 + + true + + + + + + maven-jar-plugin + + + + true + + + + + + - + - + - java14-test-classpath - - [14,15) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/14 - - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - + java18-test-classpath + + [18,19) + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + default-test + + ${project.build.outputDirectory}/META-INF/versions/18 + + ${project.build.outputDirectory}/META-INF/versions/17 + ${project.build.outputDirectory} + + + + + + + - + - java13-test - - [14,) - - java13.home - - - ${basedir}/build-test-java13 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java13-test - test - - test - - - ${java13.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/13 - - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - + java17-test + + [18,) + + java17.home + + + ${basedir}/build-test-java17 + + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + java17-test + test + + test + + + ${java17.home}/bin/java + ${project.build.outputDirectory}/META-INF/versions/17 + + ${project.build.outputDirectory} + + + + + + + - + - java14-mr-build - - [14,) - - ${basedir}/src/main/java14 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java14 - compile - - compile - - - 14 - - ${project.basedir}/src/main/java14 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - + java18-mr-build + + [18,) + + ${basedir}/src/main/java18 + + + + + + org.apache.maven.plugins + maven-compiler-plugin + + + compile-java18 + compile + + compile + + + 18 + + ${project.basedir}/src/main/java18 + + true + + + + + + maven-jar-plugin + + + + true + + + + + + - + - + - java15-test-classpath + java19-test-classpath - [15,16) + [19,20) @@ -1231,14 +713,10 @@ default-test - ${project.build.outputDirectory}/META-INF/versions/15 + ${project.build.outputDirectory}/META-INF/versions/19 - ${project.build.outputDirectory}/META-INF/versions/14 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 + ${project.build.outputDirectory}/META-INF/versions/18 + ${project.build.outputDirectory}/META-INF/versions/17 ${project.build.outputDirectory} @@ -1249,16 +727,16 @@ - + - java14-test + java18-test - [15,) + [19,) - java14.home + java18.home - ${basedir}/build-test-java14 + ${basedir}/build-test-java18 @@ -1268,20 +746,16 @@ maven-surefire-plugin - java14-test + java18-test test test - ${java14.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/14 + ${java18.home}/bin/java + ${project.build.outputDirectory}/META-INF/versions/18 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 + ${project.build.outputDirectory}/META-INF/versions/17 ${project.build.outputDirectory} @@ -1292,13 +766,13 @@ - + - java15-mr-build + java19-mr-build - [15,) + [19,) - ${basedir}/src/main/java15 + ${basedir}/src/main/java19 @@ -1308,15 +782,15 @@ maven-compiler-plugin - compile-java15 + compile-java19 compile compile - 15 + 19 - ${project.basedir}/src/main/java15 + ${project.basedir}/src/main/java19 true @@ -1336,262 +810,6 @@ - - - - - - - - java16-test-classpath - - [16,17) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/16 - - ${project.build.outputDirectory}/META-INF/versions/15 - ${project.build.outputDirectory}/META-INF/versions/14 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java15-test - - [16,) - - java15.home - - - ${basedir}/build-test-java15 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java15-test - test - - test - - - ${java15.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/15 - - ${project.build.outputDirectory}/META-INF/versions/14 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java16-mr-build - - [16,) - - ${basedir}/src/main/java16 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java16 - compile - - compile - - - 16 - - ${project.basedir}/src/main/java16 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - - - - - - - - java17-test-classpath - - [17,18) - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - default-test - - ${project.build.outputDirectory}/META-INF/versions/17 - - ${project.build.outputDirectory}/META-INF/versions/16 - ${project.build.outputDirectory}/META-INF/versions/15 - ${project.build.outputDirectory}/META-INF/versions/14 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java16-test - - [17,) - - java16.home - - - ${basedir}/build-test-java16 - - - - - - org.apache.maven.plugins - maven-surefire-plugin - - - java16-test - test - - test - - - ${java16.home}/bin/java - ${project.build.outputDirectory}/META-INF/versions/16 - - ${project.build.outputDirectory}/META-INF/versions/15 - ${project.build.outputDirectory}/META-INF/versions/14 - ${project.build.outputDirectory}/META-INF/versions/13 - ${project.build.outputDirectory}/META-INF/versions/12 - ${project.build.outputDirectory}/META-INF/versions/11 - ${project.build.outputDirectory}/META-INF/versions/10 - ${project.build.outputDirectory}/META-INF/versions/9 - ${project.build.outputDirectory} - - - - - - - - - - - - java17-mr-build - - [17,) - - ${basedir}/src/main/java17 - - - - - - org.apache.maven.plugins - maven-compiler-plugin - - - compile-java17 - compile - - compile - - - 17 - - ${project.basedir}/src/main/java17 - - true - - - - - - maven-jar-plugin - - - - true - - - - - - - - +