diff --git a/README.md b/README.md index 5c59c8d49..4d04cb183 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,8 @@ The Liberty Maven Plugin provides a number of goals for managing a Liberty serve The Liberty Maven Plugin is tested with Long-Term-Support (LTS) releases of Java. The plugin, as of release 3.10, supports Java 8, 11, 17 and 21. Versions 3.7 to 3.9.x support Java 8, 11 and 17. Prior to version 3.7, the plugin is supported on Java 8 and 11. +To control the JDK used by Liberty Maven Plugin goals and dev mode with Maven Toolchains, see the [toolchain documentation](docs/toolchain.md#toolchain). This feature will be available starting with Liberty Maven Plugin version 3.12.0. + #### Release 3.0 differences The new capabilities and behavior differences are summarized in the [Liberty Maven Plug-in 3.0](https://github.com/OpenLiberty/ci.maven/releases/tag/liberty-maven-3.0/) release notes. diff --git a/docs/common-parameters.md b/docs/common-parameters.md index 0517f4754..8371618f2 100644 --- a/docs/common-parameters.md +++ b/docs/common-parameters.md @@ -18,6 +18,7 @@ Parameters shared by all goals. | runtimeInstallDirectory | Local installation directory location of the Liberty server when the server is installed using the runtime archive, runtime artifact or repository option. The default value is `${project.build.directory}/liberty`. | No | | refresh | If true, re-install Liberty server into the local directory. This is only used when when the server is installed using the runtime archive or runtime artifact option. The default value is false. | No | | skip | If true, the specified goal is bypassed entirely. The default value is false. | No | +| jdkToolchain | Toolchain requirements (for example, `version` and `vendor`) used to select a JDK from `~/.m2/toolchains.xml` for Liberty server goals and dev mode. See [toolchain](toolchain.md#toolchain) for details. | No | #### Backward Compatibility diff --git a/docs/toolchain.md b/docs/toolchain.md new file mode 100644 index 000000000..3686cd500 --- /dev/null +++ b/docs/toolchain.md @@ -0,0 +1,164 @@ +#### toolchain +--- +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. + +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/). + +Note: Support for Maven Toolchains in Liberty Maven Plugin is available from version 3.12.0 onwards. + + +###### Overview + +Maven toolchains allow you to select a JDK from `~/.m2/toolchains.xml` based on requirements (for example, a Java version). + +The Liberty Maven Plugin supports toolchains through the `jdkToolchain` configuration element. +When `jdkToolchain` is configured: + +- Liberty server goals that run server commands (for example, `create`, `start`, `stop`, `status`) attempt to run those commands with the selected toolchain JDK. +- 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. + + +###### Prerequisites + +1. Configure a JDK toolchain in `~/.m2/toolchains.xml`. + +Example: +```xml + + + + jdk + + 11 + ibm + + + /path/to/jdk-11 + + + +``` + + +###### Configuration + +Configure the Liberty Maven Plugin with `jdkToolchain`. + +The `jdkToolchain` element corresponds to the `` section of a `jdk` toolchain in `~/.m2/toolchains.xml`. These requirements are passed through to Maven's ToolchainManager to select a matching JDK. + +For details on the `toolchains.xml` format and the `` keys, see the Maven [Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html) guide. + +| Parameter | Description | Required | +| -------- | ----------- |----------------| +| version | JDK toolchain version to use. | Typically set. | +| vendor | JDK toolchain vendor to use. | No | + +Example: +```xml + + io.openliberty.tools + liberty-maven-plugin + ... + + + 11 + + + + + +``` + + +###### How it works + +When `jdkToolchain` is configured, the Liberty Maven Plugin uses Maven's toolchain lookup to find a matching JDK in `~/.m2/toolchains.xml`. + +- 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`. +- 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. + +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. + + +###### Dev mode + +Dev mode (`liberty:dev`) uses the configured `jdkToolchain` in two places: + +1. Java compilation settings + + 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. + +2. Unit and integration test toolchains + + Dev mode integrates with: + + 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. + + - `maven-surefire-plugin` (`test`) + - `maven-failsafe-plugin` (`integration-test`) + + +###### Rules and flows + +- **No `jdkToolchain` configured** + + Liberty Maven Plugin does not perform toolchain lookup. Server goals and dev mode run using the Maven JVM and plugin defaults. + +- **`jdkToolchain` configured, but no matching toolchain is available** + + Liberty Maven Plugin logs a warning and runs using the same JDK that is used to run Maven. + +- **`JAVA_HOME` set for the server (`server.env`, `jvm.options`, or Maven project properties)** + + `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. + +- **Dev mode compilation** + + 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. + + **Example - Dev mode compilation using a different Maven Compiler Plugin toolchain version** + + Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-compiler-plugin` is set to use JDK 17: + + ``` + [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. + ``` + +- **Dev mode tests (Surefire/Failsafe)** + + 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. + + **Example - Dev mode tests using a different Surefire toolchain version** + + Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-surefire-plugin` is set to use JDK 17: + + ``` + [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. + ``` + + +###### Troubleshooting + +**If you see a warning indicating that no toolchain is available, verify:** +- Your `~/.m2/toolchains.xml` exists and contains a `` entry. +- The `version` (and optional `vendor`) matches your Liberty `jdkToolchain` configuration. + +**Example - Different version of toolchain JDK in toolchain.xml** + +Configured toolchain JDK 11 for Liberty Maven Plugin, but added only JDK 17 in the toolchain.xml +``` +[WARNING] CWWKM4100W: Toolchain configured for liberty server but jdkHome is not configured in .m2/toolchain.xml. +``` + +**If you see a warning that toolchain is not honored because JAVA_HOME is configured:** + +- Check `server.env` and `jvm.options` for `JAVA_HOME`. +- Check your Maven project properties for values that set `JAVA_HOME`, such as `liberty.env.JAVA_HOME` or `jvmOptions` properties. +- Remove or adjust these settings if you want the toolchain JDK to be used. + +**Example - JAVA_HOME specified in server.env** + +Added a `JAVA_HOME` variable in the server.env +``` +[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 +``` \ No newline at end of file diff --git a/liberty-maven-app-parent/pom.xml b/liberty-maven-app-parent/pom.xml index 24a1fb205..e0ee2d1c4 100644 --- a/liberty-maven-app-parent/pom.xml +++ b/liberty-maven-app-parent/pom.xml @@ -20,7 +20,7 @@ io.openliberty.tools liberty-maven - 3.11.6-SNAPSHOT + 3.12.0-SNAPSHOT liberty-maven-app-parent @@ -36,7 +36,7 @@ io.openliberty.tools liberty-maven-plugin - 3.11.6-SNAPSHOT + 3.12.0-SNAPSHOT stop-before-clean diff --git a/liberty-maven-plugin/pom.xml b/liberty-maven-plugin/pom.xml index e78a3a506..afe5c7fa5 100644 --- a/liberty-maven-plugin/pom.xml +++ b/liberty-maven-plugin/pom.xml @@ -6,7 +6,7 @@ io.openliberty.tools liberty-maven - 3.11.6-SNAPSHOT + 3.12.0-SNAPSHOT liberty-maven-plugin @@ -38,7 +38,7 @@ io.openliberty.tools liberty-ant-tasks - 1.9.18-SNAPSHOT + 1.9.18 org.apache.maven diff --git a/liberty-maven-plugin/src/it/dev-it/src/test/java/net/wasdev/wlp/test/dev/it/DevToolchainTest.java b/liberty-maven-plugin/src/it/dev-it/src/test/java/net/wasdev/wlp/test/dev/it/DevToolchainTest.java index 05c35397e..6bc7900d2 100644 --- a/liberty-maven-plugin/src/it/dev-it/src/test/java/net/wasdev/wlp/test/dev/it/DevToolchainTest.java +++ b/liberty-maven-plugin/src/it/dev-it/src/test/java/net/wasdev/wlp/test/dev/it/DevToolchainTest.java @@ -15,9 +15,9 @@ public void libertyToolchainWithoutCompilerToolchainLogsInfoAndUsesToolchainVers try { String additionalConfigMarker = ""; String additionalConfigReplacement = "\n" + - " 11\n" + - " \n" + - " "; + " 11\n" + + "\n" + + ""; replaceString(additionalConfigMarker, additionalConfigReplacement, pom); startProcess(null, true, "mvn liberty:"); @@ -68,26 +68,26 @@ public void matchingToolchainConfigurationsLogInfoMessage() throws Exception { try { String additionalConfigMarker = ""; String additionalConfigReplacement = "\n" + - " 11\n" + - " \n" + - " "; + " 11\n" + + "\n" + + ""; replaceString(additionalConfigMarker, additionalConfigReplacement, pom); String pluginsEndMarker = ""; - String compilerPluginReplacement = "\n" + - " org.apache.maven.plugins\n" + - " maven-compiler-plugin\n" + - " 3.11.0\n" + - " \n" + - " \n" + - " 11\n" + - " \n" + - " 11\n" + - " 11\n" + - " 11\n" + - " \n" + - " \n" + - " "; + String compilerPluginReplacement = " \n" + + " org.apache.maven.plugins\n" + + " maven-compiler-plugin\n" + + " 3.11.0\n" + + " \n" + + " \n" + + " 11\n" + + " \n" + + " 11\n" + + " 11\n" + + " 11\n" + + " \n" + + " \n" + + ""; replaceString(pluginsEndMarker, compilerPluginReplacement, pom); startProcess(null, true, "mvn liberty:"); @@ -104,26 +104,26 @@ public void mismatchedToolchainConfigurationsLogWarningMessage() throws Exceptio try { String additionalConfigMarker = ""; String additionalConfigReplacement = "\n" + - " 11\n" + - " \n" + - " "; + " 11\n" + + "\n" + + ""; replaceString(additionalConfigMarker, additionalConfigReplacement, pom); String pluginsEndMarker = ""; - String compilerPluginReplacement = "\n" + - " org.apache.maven.plugins\n" + - " maven-compiler-plugin\n" + - " 3.11.0\n" + - " \n" + - " \n" + - " 8\n" + - " \n" + - " 8\n" + - " 8\n" + - " 8\n" + - " \n" + - " \n" + - " "; + String compilerPluginReplacement = " \n" + + " org.apache.maven.plugins\n" + + " maven-compiler-plugin\n" + + " 3.11.0\n" + + " \n" + + " \n" + + " 8\n" + + " \n" + + " 8\n" + + " 8\n" + + " 8\n" + + " \n" + + " \n" + + " "; replaceString(pluginsEndMarker, compilerPluginReplacement, pom); startProcess(null, true, "mvn liberty:"); @@ -133,4 +133,89 @@ public void mismatchedToolchainConfigurationsLogWarningMessage() throws Exceptio cleanUpAfterClass(); } } + + @Test + public void libertyToolchainWithoutSurefireToolchainLogsInfoAndUsesToolchainVersion() throws Exception { + setUpBeforeClass(null, "../resources/basic-dev-project", true, false, null, null); + try { + String additionalConfigMarker = ""; + String additionalConfigReplacement = "\n" + + " 11\n" + + "\n" + + ""; + replaceString(additionalConfigMarker, additionalConfigReplacement, pom); + + startProcess(null, true, "mvn -X liberty:"); + + assertTrue(verifyLogMessageExists("maven-surefire-plugin is not configured with a jdkToolchain. Using Liberty Maven Plugin jdkToolchain configuration for test execution.", 120000)); + } finally { + cleanUpAfterClass(); + } + } + + @Test + public void matchingSurefireToolchainConfigurationsLogInfoMessage() throws Exception { + setUpBeforeClass(null, "../resources/basic-dev-project", true, false, null, null); + try { + String additionalConfigMarker = ""; + String additionalConfigReplacement = "\n" + + " 11\n" + + "\n" + + ""; + replaceString(additionalConfigMarker, additionalConfigReplacement, pom); + + String pluginsEndMarker = ""; + String surefirePluginReplacement = " \n" + + " org.apache.maven.plugins\n" + + " maven-surefire-plugin\n" + + " 3.0.0\n" + + " \n" + + " \n" + + " 11\n" + + " \n" + + " \n" + + " \n" + + ""; + replaceString(pluginsEndMarker, surefirePluginReplacement, pom); + + startProcess(null, true, "mvn -X liberty:"); + + assertTrue(verifyLogMessageExists("Liberty Maven Plugin jdkToolchain configuration matches the maven-surefire-plugin jdkToolchain configuration: version 11.", 120000)); + } finally { + cleanUpAfterClass(); + } + } + + @Test + public void mismatchedSurefireToolchainConfigurationsLogWarningMessage() throws Exception { + setUpBeforeClass(null, "../resources/basic-dev-project", true, false, null, null); + try { + String additionalConfigMarker = ""; + String additionalConfigReplacement = "\n" + + " 11\n" + + "\n" + + ""; + replaceString(additionalConfigMarker, additionalConfigReplacement, pom); + + String pluginsEndMarker = ""; + String surefirePluginReplacement = " \n" + + " org.apache.maven.plugins\n" + + " maven-surefire-plugin\n" + + " 3.0.0\n" + + " \n" + + " \n" + + " 8\n" + + " \n" + + " \n" + + " \n" + + ""; + replaceString(pluginsEndMarker, surefirePluginReplacement, pom); + + startProcess(null, true, "mvn -X liberty:"); + + assertTrue(verifyLogMessageExists("Liberty Maven Plugin jdkToolchain configuration (version 11) does not match the maven-surefire-plugin jdkToolchain configuration (version 8). The Liberty Maven Plugin jdkToolchain configuration will be used for test execution.", 120000)); + } finally { + cleanUpAfterClass(); + } + } } diff --git a/liberty-maven-plugin/src/main/java/io/openliberty/tools/maven/server/DevMojo.java b/liberty-maven-plugin/src/main/java/io/openliberty/tools/maven/server/DevMojo.java index cd9b14585..11dca8229 100644 --- a/liberty-maven-plugin/src/main/java/io/openliberty/tools/maven/server/DevMojo.java +++ b/liberty-maven-plugin/src/main/java/io/openliberty/tools/maven/server/DevMojo.java @@ -1,5 +1,5 @@ /** - * (C) Copyright IBM Corporation 2019, 2025. + * (C) Copyright IBM Corporation 2019, 2026. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -97,6 +97,7 @@ public class DevMojo extends LooseAppSupport { private static final String MICROSHED_HTTP_PORT = "microshed_http_port"; private static final String MICROSHED_HTTPS_PORT = "microshed_https_port"; private static final String WLP_USER_DIR_PROPERTY_NAME = "wlp.user.dir"; + private static final String TOOLCHAIN_VERSION_KEY = "version"; private static final String GEN_FEAT_LIBERTY_DEP_WARNING = "Liberty ESA feature dependencies were detected in the pom.xml file and automatic generation of features is [On]. " + "Automatic generation of features does not support Liberty ESA feature dependencies. " + "Remove any Liberty ESA feature dependencies from the pom.xml file or disable automatic generation of features by typing 'g' and press Enter."; @@ -1595,6 +1596,9 @@ private void doDevMode() throws MojoExecutionException { JavaCompilerOptions compilerOptions = getMavenCompilerOptions(project); + // Log test toolchain configuration for surefire/failsafe at dev mode startup + logTestToolchainConfiguration(project); + // collect upstream projects List upstreamProjects = new ArrayList(); if (!upstreamMavenProjects.isEmpty()) { @@ -1760,14 +1764,14 @@ private JavaCompilerOptions getMavenCompilerOptions(MavenProject currentProject) String target = getCompilerOption(configuration, "target", "maven.compiler.target", currentProject); // Fetch the toolchain version configured for the project - String jdkToolchainVersion = jdkToolchain != null ? jdkToolchain.get("version") : null; + String jdkToolchainVersion = jdkToolchain != null ? jdkToolchain.get(TOOLCHAIN_VERSION_KEY) : null; if (StringUtils.isNotEmpty(jdkToolchainVersion)) { // Fetch the toolchain version configured for the maven-compiler-plugin String compilerJdkToolchainVersion = null; if (configuration != null) { Xpp3Dom compilerJdkToolchain = configuration.getChild("jdkToolchain"); if (compilerJdkToolchain != null) { - Xpp3Dom versionChild = compilerJdkToolchain.getChild("version"); + Xpp3Dom versionChild = compilerJdkToolchain.getChild(TOOLCHAIN_VERSION_KEY); if (versionChild != null) { compilerJdkToolchainVersion = StringUtils.trimToNull(versionChild.getValue()); } @@ -1833,6 +1837,93 @@ private JavaCompilerOptions getMavenCompilerOptions(MavenProject currentProject) return compilerOptions; } + /** + * Logs the toolchain configuration for test plugins (surefire/failsafe) at dev mode startup. + */ + private void logTestToolchainConfiguration(MavenProject currentProject) { + // If no Liberty-level toolchain is configured, there is nothing to log for tests + String jdkToolchainVersion = jdkToolchain != null ? jdkToolchain.get(TOOLCHAIN_VERSION_KEY) : null; + if (StringUtils.isEmpty(jdkToolchainVersion)) { + return; + } + + // Resolve and log configuration for maven-surefire-plugin:test + try { + Plugin surefirePlugin = getPluginForProject("org.apache.maven.plugins", "maven-surefire-plugin", + currentProject); + if (surefirePlugin != null) { + Xpp3Dom surefireConfig = ExecuteMojoUtil.getPluginGoalConfig(surefirePlugin, "test", getLog()); + validateTestToolchainOptions("maven-surefire-plugin", surefireConfig); + } + } catch (Exception e) { + getLog().debug("Unable to resolve maven-surefire-plugin configuration for logging test toolchain: " + + e.getMessage()); + getLog().debug(e); + } + + // Resolve and log configuration for maven-failsafe-plugin:integration-test + try { + Plugin failsafePlugin = getPluginForProject("org.apache.maven.plugins", "maven-failsafe-plugin", + currentProject); + if (failsafePlugin != null) { + Xpp3Dom failsafeConfig = ExecuteMojoUtil.getPluginGoalConfig(failsafePlugin, "integration-test", + getLog()); + validateTestToolchainOptions("maven-failsafe-plugin", failsafeConfig); + } + } catch (Exception e) { + getLog().debug("Unable to resolve maven-failsafe-plugin configuration for logging test toolchain: " + + e.getMessage()); + getLog().debug(e); + } + } + + /** + * Validates and logs toolchain configuration for test plugins (surefire/failsafe). + * + * @param testArtifactId The test plugin artifact ID ("maven-surefire-plugin" or "maven-failsafe-plugin") + * @param testConfig The test plugin configuration to update + */ + private void validateTestToolchainOptions(String testArtifactId, Xpp3Dom testConfig) { + String jdkToolchainVersion = jdkToolchain != null ? jdkToolchain.get(TOOLCHAIN_VERSION_KEY) : null; + if (StringUtils.isEmpty(jdkToolchainVersion) || testConfig == null) { + return; + } + + String testJdkToolchainVersion = null; + Xpp3Dom testJdkToolchain = testConfig.getChild("jdkToolchain"); + if (testJdkToolchain != null) { + Xpp3Dom versionChild = testJdkToolchain.getChild(TOOLCHAIN_VERSION_KEY); + if (versionChild != null) { + testJdkToolchainVersion = StringUtils.trimToNull(versionChild.getValue()); + } + } + + if (testJdkToolchainVersion == null) { + getLog().info(testArtifactId + " is not configured with a jdkToolchain. " + + "Using Liberty Maven Plugin jdkToolchain configuration for test execution."); + } else if (jdkToolchainVersion.equals(testJdkToolchainVersion)) { + getLog().info("Liberty Maven Plugin jdkToolchain configuration matches the " + testArtifactId + " " + + "jdkToolchain configuration: version " + jdkToolchainVersion + "."); + return; + } else { + getLog().warn("Liberty Maven Plugin jdkToolchain configuration (version " + jdkToolchainVersion + + ") does not match the " + testArtifactId + " jdkToolchain configuration " + + "(version " + testJdkToolchainVersion + + "). The Liberty Maven Plugin jdkToolchain configuration will be used for test execution."); + } + + if (testJdkToolchain == null) { + testJdkToolchain = new Xpp3Dom("jdkToolchain"); + testConfig.addChild(testJdkToolchain); + } + Xpp3Dom versionChild = testJdkToolchain.getChild(TOOLCHAIN_VERSION_KEY); + if (versionChild == null) { + versionChild = new Xpp3Dom(TOOLCHAIN_VERSION_KEY); + testJdkToolchain.addChild(versionChild); + } + versionChild.setValue(jdkToolchainVersion); + } + /** * Gets a compiler option's value from CLI parameters, maven-compiler-plugin's * configuration or project properties. @@ -1899,6 +1990,10 @@ private void runTestMojo(String groupId, String artifactId, String goal, MavenPr Plugin plugin = getPluginForProject(groupId, artifactId, project); Xpp3Dom config = ExecuteMojoUtil.getPluginGoalConfig(plugin, goal, getLog()); + if (goal.equals("test") || goal.equals("integration-test")) { + validateTestToolchainOptions(artifactId, config); + } + // check if this is a project module or main module if (util.isMultiModuleProject()) { try { diff --git a/pom.xml b/pom.xml index 145d03e42..2f8d5856c 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ io.openliberty.tools liberty-maven - 3.11.6-SNAPSHOT + 3.12.0-SNAPSHOT pom Liberty Tools for Maven