|
| 1 | +#### toolchain |
| 2 | +--- |
| 3 | +Use Maven toolchains to run Liberty Maven Plugin goals with a specific JDK. This allows you to control the Java version used by Liberty during build, dev mode, and server operations, even when the system default JDK is different. |
| 4 | + |
| 5 | +Maven Toolchains are used to ensure consistent and reproducible builds by allowing projects to explicitly select a required JDK, independent of the system’s default Java installation. For more details, see the [Maven Toolchains Plugin documentation](https://maven.apache.org/plugins/maven-toolchains-plugin/). |
| 6 | + |
| 7 | +Note: Support for Maven Toolchains in Liberty Maven Plugin is available from version 3.12.0 onwards. |
| 8 | + |
| 9 | + |
| 10 | +###### Overview |
| 11 | + |
| 12 | +Maven toolchains allow you to select a JDK from `~/.m2/toolchains.xml` based on requirements (for example, a Java version). |
| 13 | + |
| 14 | +The Liberty Maven Plugin supports toolchains through the `jdkToolchain` configuration element. |
| 15 | +When `jdkToolchain` is configured: |
| 16 | + |
| 17 | +- Liberty server goals that run server commands (for example, `create`, `start`, `stop`, `status`) attempt to run those commands with the selected toolchain JDK. |
| 18 | +- In dev mode (`dev`), the plugin uses the configured toolchain version when determining effective Java compiler options and when running tests through the Surefire and Failsafe plugins. |
| 19 | + |
| 20 | + |
| 21 | +###### Prerequisites |
| 22 | + |
| 23 | +1. Configure a JDK toolchain in `~/.m2/toolchains.xml`. |
| 24 | + |
| 25 | +Example: |
| 26 | +```xml |
| 27 | +<?xml version="1.0" encoding="UTF-8"?> |
| 28 | +<toolchains> |
| 29 | + <toolchain> |
| 30 | + <type>jdk</type> |
| 31 | + <provides> |
| 32 | + <version>11</version> |
| 33 | + <vendor>ibm</vendor> |
| 34 | + </provides> |
| 35 | + <configuration> |
| 36 | + <jdkHome>/path/to/jdk-11</jdkHome> |
| 37 | + </configuration> |
| 38 | + </toolchain> |
| 39 | +</toolchains> |
| 40 | +``` |
| 41 | + |
| 42 | + |
| 43 | +###### Configuration |
| 44 | + |
| 45 | +Configure the Liberty Maven Plugin with `jdkToolchain`. |
| 46 | + |
| 47 | +The `jdkToolchain` element corresponds to the `<provides>` section of a `jdk` toolchain in `~/.m2/toolchains.xml`. These requirements are passed through to Maven's ToolchainManager to select a matching JDK. |
| 48 | + |
| 49 | +For details on the `toolchains.xml` format and the `<provides>` keys, see the Maven [Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html) guide. |
| 50 | + |
| 51 | +| Parameter | Description | Required | |
| 52 | +| -------- | ----------- |----------------| |
| 53 | +| version | JDK toolchain version to use. | Typically set. | |
| 54 | +| vendor | JDK toolchain vendor to use. | No | |
| 55 | + |
| 56 | +Example: |
| 57 | +```xml |
| 58 | +<plugin> |
| 59 | + <groupId>io.openliberty.tools</groupId> |
| 60 | + <artifactId>liberty-maven-plugin</artifactId> |
| 61 | + <version>...</version> |
| 62 | + <configuration> |
| 63 | + <jdkToolchain> |
| 64 | + <version>11</version> |
| 65 | + <!-- Optional: include vendor if you need to distinguish between toolchains --> |
| 66 | + <!-- <vendor>ibm</vendor> --> |
| 67 | + </jdkToolchain> |
| 68 | + </configuration> |
| 69 | +</plugin> |
| 70 | +``` |
| 71 | + |
| 72 | + |
| 73 | +###### How it works |
| 74 | + |
| 75 | +When `jdkToolchain` is configured, the Liberty Maven Plugin uses Maven's toolchain lookup to find a matching JDK in `~/.m2/toolchains.xml`. |
| 76 | + |
| 77 | +- If a matching toolchain is found, the plugin uses that toolchain to determine a `JAVA_HOME` and runs Liberty server commands using that `JAVA_HOME`. |
| 78 | +- If no matching toolchain is found (or `jdkHome` is not available), the plugin logs a warning and runs using the same JDK that is used to run Maven. |
| 79 | + |
| 80 | +If `JAVA_HOME` is already set in `server.env` or `jvm.options`, or is provided through Maven project properties (for example, `liberty.env.JAVA_HOME` or `jvmOptions` properties), that configuration takes precedence. In that case, the plugin logs a warning and does not apply the toolchain. |
| 81 | + |
| 82 | + |
| 83 | +###### Dev mode |
| 84 | + |
| 85 | +Dev mode (`liberty:dev`) uses the configured `jdkToolchain` in two places: |
| 86 | + |
| 87 | +1. Java compilation settings |
| 88 | + |
| 89 | + When a Liberty toolchain version is configured, dev mode uses that version when determining the effective Java compiler options (`release`, `source`, `target`). If the Maven Compiler Plugin is configured with a different toolchain version, dev mode logs a warning and uses the Liberty toolchain version as the effective Java version for compiler options. |
| 90 | + |
| 91 | +2. Unit and integration test toolchains |
| 92 | + |
| 93 | + Dev mode integrates with: |
| 94 | + |
| 95 | + When a Liberty toolchain version is configured, dev mode sets the effective Surefire/Failsafe `jdkToolchain` version used for test execution. If Surefire/Failsafe has no toolchain configuration, dev mode applies the Liberty toolchain version. If Surefire/Failsafe specifies a different toolchain version, dev mode logs a warning and uses the Liberty toolchain version. |
| 96 | + |
| 97 | + - `maven-surefire-plugin` (`test`) |
| 98 | + - `maven-failsafe-plugin` (`integration-test`) |
| 99 | + |
| 100 | + |
| 101 | +###### Rules and flows |
| 102 | + |
| 103 | +- **No `jdkToolchain` configured** |
| 104 | + |
| 105 | + Liberty Maven Plugin does not perform toolchain lookup. Server goals and dev mode run using the Maven JVM and plugin defaults. |
| 106 | + |
| 107 | +- **`jdkToolchain` configured, but no matching toolchain is available** |
| 108 | + |
| 109 | + Liberty Maven Plugin logs a warning and runs using the same JDK that is used to run Maven. |
| 110 | + |
| 111 | +- **`JAVA_HOME` set for the server (`server.env`, `jvm.options`, or Maven project properties)** |
| 112 | + |
| 113 | + `JAVA_HOME` configured for the server takes precedence over the toolchain. This includes values set directly in `server.env` or `jvm.options`, as well as values provided through Maven project properties that generate those files (for example, `liberty.env.JAVA_HOME` or `jvmOptions` properties). In these cases, Liberty Maven Plugin logs a warning and does not apply the toolchain. |
| 114 | + |
| 115 | +- **Dev mode compilation** |
| 116 | + |
| 117 | + If a Liberty toolchain version is configured, dev mode aligns compiler options to that version. The Liberty toolchain has higher precedence, so if the Maven Compiler Plugin specifies a different Java version, the plugin logs a warning and falls back to the Liberty toolchain JDK. |
| 118 | + |
| 119 | + **Example - Dev mode compilation using a different Maven Compiler Plugin toolchain version** |
| 120 | + |
| 121 | + Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-compiler-plugin` is set to use JDK 17: |
| 122 | + |
| 123 | + ``` |
| 124 | + [WARNING] Liberty Maven Plugin jdkToolchain configuration (version 11) does not match the Maven Compiler Plugin jdkToolchain configuration (version 17). The Liberty Maven Plugin jdkToolchain configuration will be used for compilation. |
| 125 | + ``` |
| 126 | + |
| 127 | +- **Dev mode tests (Surefire/Failsafe)** |
| 128 | + |
| 129 | + If a Liberty toolchain version is configured, dev mode uses that version for Surefire/Failsafe toolchain settings. The Liberty toolchain has higher precedence, so if the Surefire/Failsafe Plugin specifies a different Java version, the plugin logs a warning and falls back to the Liberty toolchain JDK. |
| 130 | + |
| 131 | + **Example - Dev mode tests using a different Surefire toolchain version** |
| 132 | + |
| 133 | + Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-surefire-plugin` is set to use JDK 17: |
| 134 | + |
| 135 | + ``` |
| 136 | + [WARNING] Liberty Maven Plugin jdkToolchain configuration (version 11) does not match the maven-surefire-plugin jdkToolchain configuration (version 17). The Liberty Maven Plugin jdkToolchain configuration will be used for test execution. |
| 137 | + ``` |
| 138 | + |
| 139 | + |
| 140 | +###### Troubleshooting |
| 141 | + |
| 142 | +**If you see a warning indicating that no toolchain is available, verify:** |
| 143 | +- Your `~/.m2/toolchains.xml` exists and contains a `<jdkHome>` entry. |
| 144 | +- The `version` (and optional `vendor`) matches your Liberty `jdkToolchain` configuration. |
| 145 | + |
| 146 | +**Example - Different version of toolchain JDK in toolchain.xml** |
| 147 | + |
| 148 | +Configured toolchain JDK 11 for Liberty Maven Plugin, but added only JDK 17 in the toolchain.xml |
| 149 | +``` |
| 150 | +[WARNING] CWWKM4100W: Toolchain configured for liberty server but jdkHome is not configured in .m2/toolchain.xml. |
| 151 | +``` |
| 152 | + |
| 153 | +**If you see a warning that toolchain is not honored because JAVA_HOME is configured:** |
| 154 | + |
| 155 | +- Check `server.env` and `jvm.options` for `JAVA_HOME`. |
| 156 | +- Check your Maven project properties for values that set `JAVA_HOME`, such as `liberty.env.JAVA_HOME` or `jvmOptions` properties. |
| 157 | +- Remove or adjust these settings if you want the toolchain JDK to be used. |
| 158 | + |
| 159 | +**Example - JAVA_HOME specified in server.env** |
| 160 | + |
| 161 | +Added a `JAVA_HOME` variable in the server.env |
| 162 | +``` |
| 163 | +[WARNING] CWWKM4101W: The toolchain JDK configuration for goal stop is not honored because the JAVA_HOME property is specified in the server.env or jvm.options file |
| 164 | +``` |
0 commit comments