Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/smallrye/smallrye-parent

Maven Parent POM
https://github.com/smallrye/smallrye-parent

Last synced: 12 days ago
JSON representation

Maven Parent POM

Awesome Lists containing this project

README 

          
:ci: https://github.com/smallrye/smallrye-parent/actions?query=workflow%3A%22SmallRye+Build%22

:doctype: book



image:https://github.com/smallrye/smallrye-parent/workflows/SmallRye%20Build/badge.svg?branch=main[link={ci}]

image:https://img.shields.io/github/license/thorntail/thorntail.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"]

image:https://img.shields.io/maven-central/v/io.smallrye/smallrye-parent?color=green[]



= SmallRye Parent



Define Maven setup for all SmallRye projects.



[id='mr-jars']

== Multi-Release JARs

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



[id='mr-jar-overview']

=== Functional overview



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

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 `` property is used.

This prevents accidental usage of APIs which are only present in later versions than the one

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:



* `java17.home`: this property must be set to the location of a Java 17 JDK installation

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

* `java25.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 <>).



=== 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



[id='mr-jar-base-layer']

==== Step 1: Base layer version



Choose your base layer version.  This can be Java 17 or anything later.  Configure the version by configuring the

`release` property in the `default-compile` execution of `maven-compiler-plugin`:



[source,xml]

----



  maven-compiler-plugin

  

    

      default-compile

      

        17

      

    

  



----



If the `build-release-17`, `build-release-21`, or `build-release-25` 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.



[id='mr-jar-highest-layer']

==== 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.



[id='mr-jar-source-dirs']

==== 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.



[id='mr-jar-gh-actions']

=== 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 25 but must also be tested against JDK 17 your `build.yml`

might look something like this:



[source,yaml]

----

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: |

            17

            25



      - name: Build

        run: mvn -B verify --file pom.xml -Djava17.home=${{env.JAVA_HOME_17_X64}}

----



See also link:https://github.com/actions/setup-java#readme[the README for `actions/setup-java`].



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



[id='build-control-files']

== 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).



[cols="1m,2,1",options="header"]

|===

|File name|Purpose|Reference

|build-release-17|Use the `` option to set Java 17 for the base layer.|<>

|build-release-21|Use the `` option to set Java 21 for the base layer.|<>

|build-release-25|Use the `` option to set Java 21 for the base layer.|<>

|build-test-java17|Run tests for Java 17 when `java17.home` is set and JDK 18 or later is used.|<>

|build-test-java21|Run tests for Java 21 when `java21.home` is set and JDK 22 or later is used.|<>

|build-test-java25|Run tests for Java 25 when `java25.home` is set and JDK 26 or later is used.|<>

|===



[id='release-process']

== Release Process



The process to release smallye-parent is described in the https://github.com/smallrye/smallrye/wiki/Release-Process[Release Process wiki page].