Document which toolchains must be listed in `~/.m2/toolchains.xml` to build locally

[msridhar]

On a Mac when I run mvn clean verify on the latest master branch I get an error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-toolchains-plugin:3.2.0:toolchain (default) on project error_prone_parent: Cannot find matching toolchain definitions for the following toolchain types:
[ERROR] jdk [ version='25' ]
[ERROR] Please make sure you define the required toolchains in your ~/.m2/toolchains.xml file.

I tried changing the value in pom.xml to 23 or 21 (both of which I have installed) but I got a similar error. I also ran mvn toolchains:generate-jdk-toolchains-xml -Dtoolchain.file=~/.m2/toolchains.xml to try to generate the toolchains.xml file but still got the same error.

Are there docs somewhere on steps required to build locally and properly specify the toolchains? Thanks!

[msridhar]

Update: I created the following ~/.m2/toolchains.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
            xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>21</version>
        </provides>
        <configuration>
            <jdkHome>/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home</jdkHome>
        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>25</version>
        </provides>
        <configuration>
            <jdkHome>/Library/Java/JavaVirtualMachines/jdk-25.jdk/Contents/Home</jdkHome>
        </configuration>
    </toolchain>
</toolchains>

Here is my JDK 25 version:

$ java -version
openjdk version "25-ea" 2025-09-16
OpenJDK Runtime Environment (build 25-ea+9-963)
OpenJDK 64-Bit Server VM (build 25-ea+9-963, mixed mode, sharing)

With the above, if I run mvn clean compile, I get further, but the build still fails, this time with a compile error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project error_prone_check_api: Compilation failure
[ERROR] /Users/msridhar/git-repos/error-prone/check_api/src/main/java/com/google/errorprone/util/ErrorProneSignatureGenerator.java:[31,4] error: an enclosing instance that contains Types.SignatureGenerator is required
[ERROR]

If I edit the top-level pom.xml file as follows:

diff --git a/pom.xml b/pom.xml
index ac716fb30..c500f45b4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -302,7 +302,7 @@
         <configuration>
           <toolchains>
             <jdk>
-              <version>25</version>
+              <version>21</version>
             </jdk>
           </toolchains>
         </configuration>

Then, mvn clean verify succeeds. This is with running mvn itself on JDK 21.

[msridhar]

Ok, I figured it out I think. If I also add a Java 17 JDK to the toolchains.xml then everything compiles out of the box. Based on these lines in ci.yml I think the minimum set of toolchains required to be specified in toolchains.xml to build and test Error Prone locally is 17, 23, and 25. Is there a good place to document this?

[cushon]

Sorry you had to figure this out the hard way, we should definitely document it somewhere.

Maybe the wiki, perhaps in https://github.com/google/error-prone/wiki/For-Developers ?

If you want to propose something I will add it there, or I will try to find time to write it up.

[commonquail]

A possible source of confusion is how m-toolchains-p matches versions. For example, I have

$ mvn toolchains:display-discovered-jdk-toolchains
...
[INFO] --- toolchains:3.2.0:display-discovered-jdk-toolchains (default-cli) @ error_prone_parent ---
...
[INFO]   - /usr/lib64/jvm/java-23-openjdk-23
[INFO]     provides:
[INFO]       version: 23.0.1
[INFO]       current: true
...

which does not satisfy the constraint

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <jdkToolchain>
            <version>${java.specification.version}</version>
          </jdkToolchain>

when java.specification.version=23. But the java.specification.version value is a prefix of the java.version value so a somewhat silly looking variant constraint

          <jdkToolchain>
            <version>[${java.specification.version},${java.version}]</version>
          </jdkToolchain>

would be satisfied (there are other constraints in other locations).

It would not save a user from having to maintain a ~/.m2/toolchains.xml file but it would more easily match the output of toolchains:generate-jdk-toolchains-xml.

It would seem like plain <version>${java.version}</version> could also work but that would fail to match a toolchains file entry where <version> has been explicitly set to 23.

(Of course, the toolchains file is static whereas users will probably tend to have transparently updating implementations, so <version> will tend towards lying anyway)

[msridhar]

@cushon I wrote up some instructions here:

https://github.com/msridhar/error-prone-wiki/commit/607ab1038e84e05f83e76fae6f61117ecd1a2855

It would be cool if we could re-configure the pom.xml version constraints with ranges as @commonquail suggested, to allow the output of toolchains:generate-jdk-toolchains-xml to work. I think we would need ranges as the setup-java GitHub action just uses versions like 23 when generating the xml.

[cushon]

Thanks @msridhar! I added that to the wiki.

Adjusting the versions constraints to be more compatible with generate-jdk-toolchains-xml also sounds like a good thing to consider.