Toolchain Resolver Plugins

In Gradle version 7.6 and above, Gradle provides a way to define Java toolchain auto-provisioning logic in plugins. This page explains how to author a toolchain resolver plugin. For details on how toolchain auto-provisioning interacts with these plugins, see Toolchains.

Provide a download URI

Toolchain resolver plugins provide logic to map a toolchain request to a download response. They do this via an implementation of JavaToolchainResolver:

JavaToolchainResolverImplementation.java

public abstract class JavaToolchainResolverImplementation
        implements JavaToolchainResolver { (1)

    public Optional<JavaToolchainDownload> resolve(JavaToolchainRequest request) { (2)
        return Optional.empty(); // custom mapping logic goes here instead
    }
}

1	This class is `abstract` because `JavaToolchainResolver` is a build service. Gradle provides dynamic implementations for certain abstract methods at runtime.
2	The mapping method returns a download response wrapped in an `Optional`. If the resolver implementation can’t provide a matching toolchain, the enclosing `Optional` contains an empty value.

Register the resolver in a plugin

Use a settings plugin (Plugin<Settings>) to register the JavaToolchainResolver implementation:

JavaToolchainResolverPlugin.java

public abstract class JavaToolchainResolverPlugin implements Plugin<Settings> { (1)
    @Inject
    protected abstract JavaToolchainResolverRegistry getToolchainResolverRegistry(); (2)

    public void apply(Settings settings) {
        settings.getPlugins().apply("jvm-toolchain-management"); (3)

        JavaToolchainResolverRegistry registry = getToolchainResolverRegistry();
        registry.register(JavaToolchainResolverImplementation.class);
    }
}

1	The plugin uses property injection, so it must be `abstract` and a settings plugin.
2	To register the resolver implementation, use property injection to access the JavaToolchainResolverRegistry Gradle service.
3	Resolver plugins must apply the `jvm-toolchain-management` base plugin. This dynamically adds the `jvm` block to `toolchainManagement`, which makes registered toolchain repositories usable from the build.