Skip to content

smallrye/smallrye-parent

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

badge License smallrye parent?color=green

SmallRye Parent

Define Maven setup for all SmallRye projects.

Multi-Release JARs

Starting with version 13, the SmallRye Parent POM provides a framework for multi-release JAR build and test.

Functional overview

The multi-release JAR support works in two parts: compilation and testing.

Compilation

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/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 multi-release JAR layers.

In order to select the correct class files for the given Java version, the <release> property is used. This prevents accidental usage of APIs which are only present in later versions than the one being compiled.

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:

  • java11.home: this property must be set to the location of a Java 11 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

  • java20.home: this property must be set to the location of a Java 20 JDK installation

  • java21.home: this property must be set to the location of a Java 21 JDK installation

In order to simplify development, it is recommended to project maintainers to set these properties in your personal Maven settings.xml file.

Extra unit tests are run for a given platform whenever a newer version than that platform was used to build the project and the appropriate control file is found (see Build control files reference).

Configuration

To configure a multi-release JAR, you need the following pieces of information:

  • The minimum (oldest) version of Java that will be supported by the project

  • The maximum (newest) version of Java for which your project has sources

Step 1: Base layer version

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:

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <release>11</release>
      </configuration>
    </execution>
  </executions>
</plugin>

If the build-release-11, build-release-17, or build-release-21 file is present in the root of your project, then this step is automatically done for you, for the corresponding version. Only one such file should be present.

Step 2: Highest layer version

Configure the jdk.min.version property as described above to match either:

  • The maximum (newest) Java version for which sources exist in your project, or

  • Some Java version higher than that

This is the version of Java that will build all of your layers, so it necessarily must be able to compile every version of Java sources from oldest to newest.

Step 3: Source directories

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 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 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 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. In addition, providing additional public members in later versions is generally not recommended.

Using MR JAR functions with GitHub Actions

Using this functionality with GitHub Actions is relatively simple. It entails adding the additional JDK version(s) by way of a setup action, and then passing the location of each additional JDK to the build.

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:

jobs:
  build:
    runs-on: ubuntu-latest
    name: Build using Maven

    steps:
      - uses: actions/checkout@v2
        name: Checkout

      - uses: actions/setup-java@v3
        name: Set up JDKs
        with:
          distribution: temurin
          java-version: |
            11
            17

      - name: Build
        run: mvn -B verify --file pom.xml -Djava11.home=${{env.JAVA_HOME_11_X64}}

Note that this configuration causes the default JAVA_HOME environment to be set to JDK 17.

Build control files reference

These build control files are tested only for their presence. They do not need to have any content (i.e. they can be zero-sized).

File name Purpose Reference

build-release-11

Use the <release> option to set Java 11 for the base layer.

Step 1: Base layer version

build-release-17

Use the <release> option to set Java 17 for the base layer.

Step 1: Base layer version

build-release-21

Use the <release> option to set Java 21 for the base layer.

Step 1: Base layer version

build-test-java11

Run tests for Java 11 when java11.home is set and JDK 17 or later is used.

Testing

build-test-java17

Run tests for Java 17 when java17.home is set and JDK 18 or later is used.

Testing

build-test-java18

Run tests for Java 18 when java18.home is set and JDK 19 or later is used.

Testing

build-test-java19

Run tests for Java 19 when java19.home is set and JDK 20 or later is used.

Testing

build-test-java20

Run tests for Java 20 when java20.home is set and JDK 21 or later is used.

Testing

build-test-java21

Run tests for Java 21 when java21.home is set and JDK 22 or later is used.

Testing

Release Process

The process to release smallye-parent is described in the Release Process wiki page.