https://github.com/gradle/foojay-toolchains
Java Toolchain Resolve Plugin based on the foojay DiscoAPI
https://github.com/gradle/foojay-toolchains
gradle-bt gradle-bt-jvm
Last synced: 6 months ago
JSON representation
Java Toolchain Resolve Plugin based on the foojay DiscoAPI
- Host: GitHub
- URL: https://github.com/gradle/foojay-toolchains
- Owner: gradle
- License: apache-2.0
- Created: 2022-09-26T06:01:46.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-27T16:29:13.000Z (6 months ago)
- Last Synced: 2025-03-28T13:06:48.639Z (6 months ago)
- Topics: gradle-bt, gradle-bt-jvm
- Language: Kotlin
- Size: 313 KB
- Stars: 158
- Watchers: 23
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Foojay Toolchains Plugin
The `org.gradle.toolchains.foojay-resolver` plugin provides a [repository for downloading JVMs](https://docs.gradle.org/current/userguide/toolchains.html#sub:download_repositories).
It is based on the [foojay DiscoAPI](https://github.com/foojayio/discoapi), therefore, the [foojay API's Swagger UI](https://api.foojay.io/swagger-ui) can be used to explore what distributions are available.
See the [Matching Toolchain Specifications](#matching-toolchain-specifications) section below for how to select specific distributions.
> **TAKE HEED!**
>
> Requires Gradle **7.6 or later** to work.
>
> As opposed to most of the Gradle plugins, which are Project plugins
> and must be applied in `build.gradle[.kts]` files, this is a **SETTINGS PLUGIN** and
> must be applied in `settings.gradle[.kts]` files.
# Usage
To make use of the plugin add following to your `settings.gradle[.kts]` file.
Kotlin DSL
```kotlin
// settings.gradle.kts
plugins {
id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}
```
Groovy DSL
```groovy
// settings.gradle
plugins {
id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}
```
This is a convention plugin meant to simplify configuration.
What it does is equivalent to applying the base plugin and some extra configuration:
Kotlin DSL
```kotlin
// settings.gradle.kts
plugins {
id("org.gradle.toolchains.foojay-resolver") version "0.9.0"
}
toolchainManagement {
jvm {
javaRepositories {
repository("foojay") {
resolverClass.set(org.gradle.toolchains.foojay.FoojayToolchainResolver::class.java)
}
}
}
}
```
Groovy DSL
```groovy
// settings.gradle
plugins {
id("org.gradle.toolchains.foojay-resolver") version "0.9.0"
}
toolchainManagement {
jvm {
javaRepositories {
repository("foojay") {
resolverClass = org.gradle.toolchains.foojay.FoojayToolchainResolver
}
}
}
}
```
Feel free to use either approach.
For further information about using Toolchain Download Repositories consult the [Gradle Manual](https://docs.gradle.org/current/userguide/toolchains.html#sub:download_repositories).
# Matching Toolchain Specifications
The main thing the plugin does is to match [Gradle's toolchain specifications](https://docs.gradle.org/current/javadoc/org/gradle/jvm/toolchain/JavaToolchainSpec.html) to foojay DiscoAPI distributions and packages.
## `nativeImageCapable` criteria
When set, it is used to filter out distributions that are not capable of creating native images with GraalVM.
## Vendors
There is mostly a 1-to-1 relationship between the DiscoAPI's distributions and [Gradle vendors](https://docs.gradle.org/current/userguide/toolchains.html#sec:vendors).
The plugin works with the following mapping:
| Gradle JVM Vendor | Foojay Distribution |
|-------------------------|---------------------------|
| ADOPTIUM | Temurin |
| ADOPTOPENJDK | AOJ |
| AMAZON | Corretto |
| APPLE | - |
| AZUL | Zulu |
| BELLSOFT | Liberica |
| GRAAL_VM | Graal VM CE 8/11/16/17/19 |
| HEWLETT_PACKARD | - |
| IBM | Semeru |
| IBM_SEMERU | Semeru |
| JETBRAINS | JetBrains |
| MICROSOFT | Microsoft |
| ORACLE | Oracle OpenJDK |
| SAP | SAP Machine |
**To note:**
Not all Gradle vendors have an equivalent DiscoAPI distribution, empty cells indicate that no toolchain will be provisioned.
If no vendor is specified, distributions are iterated in the order they are provided by the DiscoAPI, and the first one that has a compatible installation package available is selected.
The exception to the Foojay ordering of distributions is that "Temurin" (ADOPTIUM) and then "AOJ" (ADOPTOPENJDK) come first, due to the history of the auto-provisioning feature in Gradle, specifically that AdoptOpenJDK/Adoptium have been the default sources for downloading JVMs.
## Implementations
When specifying toolchains Gradle distinguishes between `J9` JVMs and `VENDOR_SPECIFIC` ones (ie. any other).
What this criteria does in the plugin is to influence the Vendor-to-Distribution matching table.
`VENDOR_SPECIFICATION` doesn't change it at all, while `J9` alter it like this:
| Gradle JVM Vendor | Foojay Distribution |
|-------------------------|---------------------|
| \ | Semeru |
| ADOPTIUM | - |
| ADOPTOPENJDK | AOJ OpenJ9 |
| AMAZON | - |
| APPLE | - |
| AZUL | - |
| BELLSOFT | - |
| GRAAL_VM | - |
| HEWLETT_PACKARD | - |
| IBM | Semeru |
| IBM_SEMERU | Semeru |
| JETBRAINS | - |
| MICROSOFT | - |
| ORACLE | - |
| SAP | - |
Empty cells indicate that no toolchain will be provisioned
## Versions
Once the vendor and the implementation values of the toolchain spec have been used to select a DiscoAPI distribution, a specific package of that distribution needs to be picked by the plugin, in order for it to obtain a download link.
The inputs it uses to do this are:
* the major **Java version** number for the spec
* the **operating system** running the build that made the request
* the **CPU architecture** of the system running the build that made the request
Additional criteria used for selection:
* for each major version number only packages having the latest minor version will be considered
* only packages containing an archive of a format known to Gradle will be considered (zip, tar, tgz)
* JDKs have priority over JREs