coursier jvm-index

This repository hosts and manages the JVM index used by the cs java and cs java-home commands of coursier, and more generally, the JVM management capabilities of coursier.

Available JDKs

JDK	id in index
Eclipse Temurin (recommended / default)	`temurin`
GraalVM community	`graalvm-community`
Oracle JDKs	`oracle`
Azul Zulu	`zulu`
bellsoft Liberica	`liberica`
bellsoft Liberica Native Image Kit	`liberica-nik`
Amazon Corretto	`corretto`
IBM Semeru	`ibm-semeru`

Legacy JDKs

JDK	id in index
AdoptOpenJDK	`adopt`
Merge of AdoptOpenJDK and Eclipse Temurin JDKs	`adoptium`

Index structure

The index comes in 2 shapes:

a Jabba-compatible single JSON file, index.json
per-OS and CPU architecture indices, under indices/

While the former is only available on GitHub, the latter is also pushed to Maven Central, under the io.get-coursier.jvm.indices organization.

Jabba-compatible index

That index consists in 4 nested JSON objects, with the successive keys of these objects being:

the OS
- linux
- darwin (macOS)
- windows
- linux-musl (for musl libc-based systems, like Alpine Linux),
- aix
- solaris
the CPU architecture
- amd64
- arm64 (a.k.a. aarch64, Raspberry PI or Mac M1-M4 CPUs)
- x86 (32-bit)
- arm (32-bit ARM)
- ppc64
- ppc64le
- s390x
the JDK name, prefixed by jdk@, like
- jdk@temurin
- jdk@graalvm-community
- jdk@liberica
- jdk@liberica-nik
- jdk@zulu
- jdk@corretto
- jdk@java-oracle
- …
the JDK version, often prefixed with 1., like
- 1.8.0-432
- 1.17.0.13
- 1.21.0.5
- 1.23.0.1
- …

The values of the fourth nested object look like

${TYPE}+${URL}

${TYPE} being one of

tgz (for gzip-compressed tar archive JDKs, on Unixes typically)
zip (for zip-compressed JDKs, on Windows typically)

${URL} being the URL of the JDK archive, like https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_aarch64_mac_hotspot_23.0.1_11.tar.gz.

Value examples

tgz+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_aarch64_mac_hotspot_23.0.1_11.tar.gz
zip+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23%2B37/OpenJDK23U-jdk_x64_windows_hotspot_23_37.zip

Example commands to inspect the index locally:

$ cat "$(cs get https://github.com/coursier/jvm-index/raw/refs/heads/master/index.json)" |
    jq 'keys'
[
  "aix",
  "alpine-linux",
  "darwin",
  "linux",
  "linux-musl",
  "solaris",
  "windows"
]

$ cat "$(cs get https://github.com/coursier/jvm-index/raw/refs/heads/master/index.json)" |
    jq '.darwin | keys'
[
  "amd64",
  "arm64"
]

$ cat "$(cs get https://github.com/coursier/jvm-index/raw/refs/heads/master/index.json)" |
    jq '.darwin.amd64 | keys'
[
  "jdk@corretto",
  "jdk@graalvm-community",
  "jdk@graalvm-oracle",
  "jdk@java-oracle",
  "jdk@liberica",
  "jdk@temurin",
  "jdk@zulu",
  …
]

$ cat "$(cs get https://github.com/coursier/jvm-index/raw/refs/heads/master/index.json)" |
    jq '.darwin.amd64["jdk@temurin"] | keys'
[
  "1.11.0.25",
  "1.16.0.2",
  "1.17.0.13",
  "1.18.0.2.1",
  "1.19.0.2",
  "1.20.0.2",
  "1.21.0.5",
  "1.22.0.2",
  "1.23",
  "1.23.0.1",
  "1.8.0-432",
  …
]

$ cat "$(cs get https://github.com/coursier/jvm-index/raw/refs/heads/master/index.json)" |
    jq '.darwin.amd64["jdk@temurin"]["1.23.0.1"]'
"tgz+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_x64_mac_hotspot_23.0.1_11.tar.gz"

Per-OS and CPU architecture indices

These consist in 2 nested JSON objects, whose keys are:

the JDK name, like
- temurin
- graalvm-community
- liberica
- zulu
- corretto
- java-oracle
- …
the JDK version, like
- 8.0-432
- 17.0.13
- 21.0.5
- 23.0.1
- …

The values of the second nested object look like those of the Jabba-compatible index:

${TYPE}+${URL}

${TYPE} being one of

tgz (for gzip-compressed tar archive JDKs, on Unixes typically)
zip (for zip-compressed JDKs, on Windows typically)

${URL} being the URL of the JDK archive, like https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_aarch64_mac_hotspot_23.0.1_11.tar.gz.

Value examples

tgz+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_aarch64_mac_hotspot_23.0.1_11.tar.gz
zip+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23%2B37/OpenJDK23U-jdk_x64_windows_hotspot_23_37.zip

These indices live at Maven coordinates like

io.get-coursier.jvm.indices:index-${OS}-${CPU}:${INDEX_VERSION}

${OS} being one of:

linux
darwin (macOS)
windows
linux-musl (for musl libc-based systems, like Alpine Linux),
aix
solaris

${CPU} being one of:

amd64
arm64 (a.k.a. aarch64, Raspberry PI or Mac M1-M4 CPUs)
x86 (32-bit)
arm (32-bit ARM)
ppc64
ppc64le
s390x

${INDEX_VERSION} can be found from directory listings or maven-metadata.xml files on Maven Central.

Example commands to inspect such an index locally:

$ unzip -l "$(cs get https://repo1.maven.org/maven2/io/get-coursier/jvm/indices/index-darwin-arm64/0.0.4-70-51469f/index-darwin-arm64-0.0.4-70-51469f.jar)"
Archive:  ~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/io/get-coursier/jvm/indices/index-darwin-arm64/0.0.4-70-51469f/index-darwin-arm64-0.0.4-70-51469f.jar
  Length      Date    Time    Name
---------  ---------- -----   ----
      332  11-14-2024 09:51   META-INF/MANIFEST.MF
        0  11-14-2024 09:51   META-INF/
        0  11-14-2024 09:51   coursier/
        0  11-14-2024 09:51   coursier/jvm/
        0  11-14-2024 09:51   coursier/jvm/indices/
        0  11-14-2024 09:51   coursier/jvm/indices/v1/
   157254  11-14-2024 09:51   coursier/jvm/indices/v1/darwin-arm64.json
---------                     -------
   157586                     7 files

$ unzip -p "$(cs get https://repo1.maven.org/maven2/io/get-coursier/jvm/indices/index-darwin-arm64/0.0.4-70-51469f/index-darwin-arm64-0.0.4-70-51469f.jar)" coursier/jvm/indices/v1/darwin-arm64.json |
    jq keys
[
  "corretto",
  "graalvm-community",
  "graalvm-oracle",
  "ibm-semeru",
  "java-oracle",
  "liberica",
  "temurin",
  "zulu",
  …
]

$ unzip -p "$(cs get https://repo1.maven.org/maven2/io/get-coursier/jvm/indices/index-darwin-arm64/0.0.4-70-51469f/index-darwin-arm64-0.0.4-70-51469f.jar)" coursier/jvm/indices/v1/darwin-arm64.json |
    jq '.temurin | keys'
[
  "11.0.25",
  "17.0.13",
  "18.0.2.1",
  "19.0.2",
  "20.0.2",
  "21.0.5",
  "22.0.2",
  "23.0.1",
  …
]

$ unzip -p "$(cs get https://repo1.maven.org/maven2/io/get-coursier/jvm/indices/index-darwin-arm64/0.0.4-70-51469f/index-darwin-arm64-0.0.4-70-51469f.jar)" coursier/jvm/indices/v1/darwin-arm64.json |
    jq '.temurin["23.0.1"]'
"tgz+https://github.com/adoptium/temurin23-binaries/releases/download/jdk-23.0.1%2B11/OpenJDK23U-jdk_aarch64_mac_hotspot_23.0.1_11.tar.gz"

Use by coursier

API

As of writing this (coursier 2.1.18), coursier relies by default on the Jabba-compatible single JSON file index, but is able to use the per-OS and CPU index from Maven Central.

import coursier.cache.FileCache
import coursier.jvm._
val cache = FileCache()
val jvmCache = JvmCache().withDefaultIndex
val javaHomeManager = JavaHome().withCache(jvmCache)
val javaHome = javaHomeManager.get("temurin:21")
  .unsafeRun()(cache.ec)

Using the per-OS and CPU index from Maven Central:

import coursier.cache.FileCache
import coursier.jvm._
val cache = FileCache()
val jvmCache = JvmCache().withIndexChannel(
  coursier.Resolve().finalRepositories.unsafeRun()(cache.ec),
  JvmChannel.central()
)
val javaHomeManager = JavaHome().withCache(jvmCache)
val javaHome = javaHomeManager.get("temurin:21")
  .unsafeRun()(cache.ec)

CLI

The index generated here is now used by the java and java-home commands of coursier.

If you suspect one of those commands doesn't use a newer JVM version, pass --update --ttl 0 to them, like

$ cs java --env --jvm graalvm-community:23 --update --ttl 0

Use by Scala CLI

Scala CLI relies on coursier to manage JDKs. It automatically downloads JDKs if needed, based on the --jvm … option and //> jvm … directive.

Use by Mill

The Mill build tool allows its users to pick a JVM to compile / run / test code. As of writing this, this feature has just been merged via com-lihaoyi/mill#3716

How this repository works

Workflow

The update-index workflow runs daily. It lists available JVMs from various providers, and re-generates the indices. If any change is found, a PR for it is opened.

Maintainers need to pick the PR, check that it doesn't contain anything suspicious, approve it, and merge it.

Upon merge, the Jabba-compatible index is immediately up-to-date. The publish workflow runs and pushes updated per-OS and CPU architecture indices to Maven Central. Once the publish workflow ran successfully, up to a few hours are sometimes needed for the newer indices to be available on Maven Central.

Generating the index locally

Generate an index with

$ GH_TOKEN="****" ./scala-cli.sh src

or

$Env:GH_TOKEN="*****"
scala-cli src

Just ./scala-cli.sh src can work if GH_TOKEN is not set, but it usually gets rate-limited by the GitHub API. You can read more about creating a token here. Just having the public_repo scope will be enough for the access you need.

The index is written in index.json in the current directory.

About

Licensed under the Apache version 2 license.

Name		Name	Last commit message	Last commit date
Latest commit History 462 Commits
.github		.github
indices		indices
publish		publish
src/coursier/jvmindex		src/coursier/jvmindex
.gitignore		.gitignore
.scalafmt.conf		.scalafmt.conf
README.md		README.md
index.json		index.json
scala-cli.sh		scala-cli.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

coursier jvm-index

Available JDKs

Legacy JDKs

Index structure

Jabba-compatible index

Per-OS and CPU architecture indices

Use by coursier

API

CLI

Use by Scala CLI

Use by Mill

How this repository works

Workflow

Generating the index locally

About

About

Uh oh!

Releases

Packages

Uh oh!

Contributors 14

Uh oh!

Languages

coursier/jvm-index

Folders and files

Latest commit

History

Repository files navigation

coursier jvm-index

Available JDKs

Legacy JDKs

Index structure

Jabba-compatible index

Per-OS and CPU architecture indices

Use by coursier

API

CLI

Use by Scala CLI

Use by Mill

How this repository works

Workflow

Generating the index locally

About

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 14

Uh oh!

Languages

Packages