Skip to content

docs: move the unreleased changes under 0.6.4, restructure the README and the longer pages, and bring the data they quote up to date #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linghengqian merged 1 commit into from
Nov 3, 2026
Merged

docs: move the unreleased changes under 0.6.4, restructure the README and the longer pages, and bring the data they quote up to date #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 47 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,32 @@ Java plugin for [vfox](https://vfox.dev/).

It installs JDKs from 31 distributions, among them Temurin, Zulu, Liberica, Corretto, Microsoft and GraalVM, looked up through [Foojay](https://foojay.io/). On Linux loong64 it installs from the Loongnix archive instead.

## Use cases

The plugin installs several JDKs side by side and switches between them for one shell, for a project or for every new shell, which is what [SDKMAN](https://sdkman.io/) does. It also works where SDKMAN does not. SDKMAN is a set of bash scripts, so on Windows it needs WSL or Git Bash and cannot be used in PowerShell, not even in the Windows PowerShell 5.1 that comes with Windows, while vfox is a native program with a hook for PowerShell. There the plugin takes SDKMAN's place. It follows SDKMAN's short names and reads `.sdkmanrc`, so SDKMAN users and vfox users can share a project. The commands side by side:

| | SDKMAN | vfox |
| --- | --- | --- |
| Install | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
| Use in the current shell only | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
| Use in every new shell | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |

See [docs/sdkman.md](docs/sdkman.md) for when to use the plugin, the other commands and what differs.

## Install

After installing [vfox](https://github.com/version-fox/vfox), install the plugin by running:

```bash
vfox add java
```

vfox has to be hooked into your shell for `java` to be on the `PATH`, see its [quick start](https://vfox.dev/guides/quick-start.html).

### Example
After installing [vfox](https://github.com/version-fox/vfox), install the plugin and a JDK, and select the JDK:

```bash
vfox add java
vfox install java@21-tem
vfox use --global java@21-tem
```

You can verify this using the following command:

```bash
java -version
```

`java -version` shows the JDK that is selected. For `java` to be on the `PATH`, vfox has to be hooked into your shell, see its [quick start](https://vfox.dev/guides/quick-start.html).

`vfox search java tem` lists the Temurin releases, and in an interactive terminal it lets you pick one and installs it.

## Versions and names

A version is `<version>-<distribution>`, such as `21.0.8-tem`, with `-fx` after it for JavaFX. Without a distribution you get OpenJDK from jdk.java.net, which has nothing newer than 17.0.2 for 17 and 21.0.2 for 21. See [docs/versions.md](docs/versions.md) for details.
A version is `<version>-<distribution>`, such as `21.0.8-tem`, with `-fx` after it for JavaFX:

```bash
vfox install java@21-tem # newest Temurin 21
vfox install java@21.0.8-tem # Temurin 21.0.8
vfox install java@21-zulu-fx # Zulu 21 with JavaFX
```

Without a distribution you get OpenJDK from jdk.java.net, which has nothing newer than 17.0.2 for 17 and 21.0.2 for 21, so name a distribution. See [docs/versions.md](docs/versions.md) for installing, using, searching and early-access builds.

## Distributions

Expand Down Expand Up @@ -80,7 +65,13 @@ A version is `<version>-<distribution>`, such as `21.0.8-tem`, with `-fx` after
| `grl8`, `grl11`, `grl16`, `grl17`, `grl19` | GraalVM CE for JDK 8 to 19 |
| `lnxabi1`, `lnxabi2` | Loongnix, Linux loong64 only |

The short names follow SDKMAN's identifiers, with a few differences: SDKMAN calls JetBrains Runtime `jbr`, and it wrote the virtual machine or JDK of AdoptOpenJDK and GraalVM CE into the version (`11.0.10.j9-adpt`, `22.3.3.r17-grl`), where the plugin has a name for each (`adptj9`, `grl17`). Eliya, OJDKBuild, OpenLogic, Red Hat and Semeru certified have no SDKMAN identifier, so their short names are the plugin's own. See [docs/distributions.md](docs/distributions.md) for all the differences and for what each distribution is, and [docs/loongnix.md](docs/loongnix.md) for the last row.
The short names follow the identifiers of [SDKMAN](https://sdkman.io/), with these differences:

- JetBrains Runtime is `jb` and BiSheng is `bsg`, which SDKMAN calls `jbr` and `bisheng`.
- SDKMAN wrote the virtual machine or JDK of AdoptOpenJDK and GraalVM CE into the version (`11.0.10.j9-adpt`, `22.3.3.r17-grl`). The plugin has a name for each (`adptj9`, `grl17`).
- Eliya, OJDKBuild, OpenLogic, Red Hat and Semeru certified have no SDKMAN identifier, so their short names are the plugin's own.

See [docs/distributions.md](docs/distributions.md) for all the differences and for what each distribution is, and [docs/loongnix.md](docs/loongnix.md) for the last row.

## Platforms

Expand All @@ -98,7 +89,7 @@ A GraalVM installs and runs like any other JDK. Only `native-image`, which build
sudo apt install --assume-yes build-essential zlib1g-dev
```

GraalVM CE 8 to 19 come without `native-image` and need it added first. See [docs/distributions.md](docs/distributions.md#native-image-and-the-c-toolchain) for what `native-image` prints without these packages, for other systems, and for adding it.
GraalVM CE 8 to 19 come without `native-image` and need it added first. See [docs/native-image.md](docs/native-image.md) for what `native-image` prints without these packages, for other systems, and for adding it.

## `.sdkmanrc`

Expand All @@ -108,36 +99,42 @@ vfox reads the `java=` line of SDKMAN's `.sdkmanrc` through this plugin and sele

Most distributions download from GitHub. If that is slow where you are, `export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/` sends these downloads through a mirror. See [docs/mirror.md](docs/mirror.md) for details.

## Querying Foojay
## Coming from SDKMAN

To see which JDKs exist for your platform, ask Foojay yourself. [docs/foojay.md](docs/foojay.md) has the Swagger UI and the commands.
[SDKMAN](https://sdkman.io/) installs several JDKs side by side and switches between them for one shell, for a project or for every new shell. So does this plugin, with SDKMAN's short names, and it reads `.sdkmanrc`, so SDKMAN users and vfox users can share a project.

## Troubleshooting
It also works where SDKMAN does not. SDKMAN is a set of bash scripts, so on Windows it needs WSL or Git Bash and cannot be used in PowerShell, not even in the Windows PowerShell 5.1 that comes with Windows. vfox is a native program with a hook for PowerShell, and there the plugin takes SDKMAN's place. The commands side by side:

See [docs/troubleshooting.md](docs/troubleshooting.md) for the messages the plugin and `native-image` print, proxies and where the JDK is.

## Install from source

See [docs/install-from-source.md](docs/install-from-source.md) for details.
| | SDKMAN | vfox |
| --- | --- | --- |
| Install | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
| Use in the current shell only | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
| Use in every new shell | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |

## Development
See [docs/sdkman.md](docs/sdkman.md) for when to use the plugin, the other commands and what differs.

See [docs/development.md](docs/development.md) for how the plugin works and how to change it, and [docs/e2e.md](docs/e2e.md) for the container tests.
## Documentation

## Releasing this plugin
**Using the plugin**

Maintainers can publish from **Actions → Plugin → Run workflow** on the default
branch by entering a stable plugin version without the `v` prefix. The shared
workflow updates `metadata.lua`, creates the version commit and tag, and publishes
the ZIP and manifest in this repository. No local tag or extra release token is
needed. Pull requests run checks only; PR titles no longer trigger publication.
- [Versions and names](docs/versions.md): how to write a version, and installing, using, searching and early-access builds
- [Distributions](docs/distributions.md): what each distribution is, its long name, and how GraalVM, Mandrel and Liberica NIK are numbered
- [Platforms](docs/platforms.md): which distribution has builds for which operating system and CPU
- [Querying Foojay](docs/foojay.md): asking Foojay yourself which JDKs exist for your platform, what the plugin asks it, and how downloads are verified
- [JavaFX](docs/javafx.md): the `-fx` builds and where they exist
- [Native Image](docs/native-image.md): the C compiler and zlib that `native-image` needs
- [`.sdkmanrc`](docs/sdkmanrc.md): which JDK a SDKMAN project file selects
- [SDKMAN and vfox](docs/sdkman.md): when to use the plugin, the commands side by side, what differs
- [GitHub mirror](docs/mirror.md): downloading through a mirror when github.com is slow
- [Loongnix](docs/loongnix.md): JDKs for Linux loong64
- [Troubleshooting](docs/troubleshooting.md): the messages the plugin and `native-image` print, proxies and where the JDK is
- [Changes](docs/changes.md): what each release changed

Existing version-tag pushes are supported when `PLUGIN.version` already matches
the tag. If publication fails, re-run the original failed job to resume it.
**Working on the plugin**

The workflow follows the shared `@v1` release-tool version. Updating the tool does
not release this plugin. See the [shared workflow documentation](https://github.com/version-fox/plugin-manifest-action)
for the package contract and first-rollout requirements.
- [Install from source](docs/install-from-source.md): trying `main` before the next release
- [Development](docs/development.md): how the plugin works, how to change it and how to release it
- [E2E tests](docs/e2e.md): the container tests

## Thanks

Expand Down
90 changes: 47 additions & 43 deletions README_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,32 @@

它通过 [Foojay](https://foojay.io/) 查找并安装 31 个发行版的 JDK，包括 Temurin、Zulu、Liberica、Corretto、Microsoft、GraalVM 等。在 Linux loong64 上，则改从 Loongnix 归档安装。

## 适用场景

这个插件可以同时装好几个 JDK，并按单个 Shell、按项目，或为之后新开的所有 Shell 切换，[SDKMAN](https://sdkman.io/) 做的就是这件事。它还能用在 SDKMAN 用不了的地方：SDKMAN 是一组 bash 脚本，在 Windows 上要借助 WSL 或 Git Bash，不能在 PowerShell 里使用，Windows 自带的 Windows PowerShell 5.1 也不行；vfox 是原生的 Windows 程序，能挂载到 PowerShell，在那里这个插件就取代了 SDKMAN。插件沿用 SDKMAN 的简称，也读取 `.sdkmanrc`，所以 SDKMAN 用户和 vfox 用户可以共用同一个项目。两边的命令对照如下：

| | SDKMAN | vfox |
| --- | --- | --- |
| 安装 | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
| 只在当前 Shell 里使用 | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
| 在之后新开的所有 Shell 里使用 | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |

什么时候该用这个插件、其余的命令以及它们的差别，见 [docs/zh-CN/sdkman.md](docs/zh-CN/sdkman.md)。

## 安装

先安装 [vfox](https://github.com/version-fox/vfox)，然后执行下面的命令安装插件：

```bash
vfox add java
```

要让 `java` 出现在 `PATH` 里，需要先把 vfox 挂载到 Shell，见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。

### 示例
先安装 [vfox](https://github.com/version-fox/vfox)，然后安装插件和 JDK，并选中这个 JDK：

```bash
vfox add java
vfox install java@21-tem
vfox use --global java@21-tem
```

可以用下面的命令验证：

```bash
java -version
```

`java -version` 会显示当前选中的 JDK。要让 `java` 出现在 `PATH` 里，需要先把 vfox 挂载到 Shell，见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。

`vfox search java tem` 会列出 Temurin 的各个版本，在交互式终端里还可以直接选一个并安装。

## 版本与命名

版本写成 `<版本>-<发行版>`，例如 `21.0.8-tem`，后面加 `-fx` 表示带 JavaFX。不写发行版时得到的是 jdk.java.net 上的 OpenJDK，它的 17 只到 17.0.2，21 只到 21.0.2。详见 [docs/zh-CN/versions.md](docs/zh-CN/versions.md)。
版本写成 `<版本>-<发行版>`，例如 `21.0.8-tem`，后面加 `-fx` 表示带 JavaFX：

```bash
vfox install java@21-tem # Temurin 21 的最新版
vfox install java@21.0.8-tem # Temurin 21.0.8
vfox install java@21-zulu-fx # 带 JavaFX 的 Zulu 21
```

不写发行版时得到的是 jdk.java.net 上的 OpenJDK，它的 17 只到 17.0.2，21 只到 21.0.2，所以请指定发行版。安装、使用、搜索和 EA 构建的细节见 [docs/zh-CN/versions.md](docs/zh-CN/versions.md)。

## 发行版

Expand Down Expand Up @@ -80,7 +65,13 @@ java -version
| `grl8`、`grl11`、`grl16`、`grl17`、`grl19` | 基于 JDK 8 到 19 的 GraalVM CE |
| `lnxabi1`、`lnxabi2` | Loongnix，仅限 Linux loong64 |

简称沿用 SDKMAN 的标识符，有几处不同：JetBrains Runtime 在 SDKMAN 里叫 `jbr`；AdoptOpenJDK 和 GraalVM CE 的虚拟机或 JDK 版本，SDKMAN 当时写在版本号里（`11.0.10.j9-adpt`、`22.3.3.r17-grl`），插件则给每种各起一个简称（`adptj9`、`grl17`）。Eliya、OJDKBuild、OpenLogic、Red Hat 和 Semeru 认证版在 SDKMAN 里没有标识符，简称是插件自己起的。全部差别以及每个发行版是什么，见 [docs/zh-CN/distributions.md](docs/zh-CN/distributions.md)；最后一行见 [docs/zh-CN/loongnix.md](docs/zh-CN/loongnix.md)。
简称沿用 [SDKMAN](https://sdkman.io/) 的标识符，有这几处不同：

- JetBrains Runtime 是 `jb`，毕昇是 `bsg`，它们在 SDKMAN 里叫 `jbr` 和 `bisheng`。
- AdoptOpenJDK 和 GraalVM CE 的虚拟机或 JDK 版本，SDKMAN 当时写在版本号里（`11.0.10.j9-adpt`、`22.3.3.r17-grl`），插件则给每种各起一个简称（`adptj9`、`grl17`）。
- Eliya、OJDKBuild、OpenLogic、Red Hat 和 Semeru 认证版在 SDKMAN 里没有标识符，简称是插件自己起的。

全部差别以及每个发行版是什么，见 [docs/zh-CN/distributions.md](docs/zh-CN/distributions.md)；最后一行见 [docs/zh-CN/loongnix.md](docs/zh-CN/loongnix.md)。

## 平台

Expand All @@ -98,7 +89,7 @@ GraalVM 的安装和使用与别的 JDK 没有两样。只有用来构建原生
sudo apt install --assume-yes build-essential zlib1g-dev
```

GraalVM CE 8 到 19 不带 `native-image`，要先添加。没有这些包时 `native-image` 的报错、其他系统的做法以及怎样添加，见 [docs/zh-CN/distributions.md](docs/zh-CN/distributions.md#native-image-与-c-工具链)。
GraalVM CE 8 到 19 不带 `native-image`，要先添加。没有这些包时 `native-image` 的报错、其他系统的做法以及怎样添加，见 [docs/zh-CN/native-image.md](docs/zh-CN/native-image.md)。

## `.sdkmanrc`

Expand All @@ -108,29 +99,42 @@ vfox 通过这个插件读取 SDKMAN 的 `.sdkmanrc` 里的 `java=` 一行，并

大多数发行版从 GitHub 下载。如果你那里下载很慢，执行 `export VFOX_JAVA_GITHUB_MIRROR=https://gh-proxy.org/`，这些下载就会经过镜像。详见 [docs/zh-CN/mirror.md](docs/zh-CN/mirror.md)。

## 查询 Foojay
## SDKMAN 用户

想知道你的平台上有哪些 JDK，可以自己去问 Foojay。[docs/zh-CN/foojay.md](docs/zh-CN/foojay.md) 里有 Swagger UI 和查询命令。
[SDKMAN](https://sdkman.io/) 可以同时装好几个 JDK，并按单个 Shell、按项目，或为之后新开的所有 Shell 切换。这个插件也一样，沿用 SDKMAN 的简称，也读取 `.sdkmanrc`，所以 SDKMAN 用户和 vfox 用户可以共用同一个项目。

## 问题排查
它还能用在 SDKMAN 用不了的地方。SDKMAN 是一组 bash 脚本，在 Windows 上要借助 WSL 或 Git Bash，不能在 PowerShell 里使用，Windows 自带的 Windows PowerShell 5.1 也不行。vfox 是原生的 Windows 程序，能挂载到 PowerShell，在那里这个插件就取代了 SDKMAN。两边的命令对照如下：

插件和 `native-image` 的各种提示、代理设置和 JDK 的位置，见 [docs/zh-CN/troubleshooting.md](docs/zh-CN/troubleshooting.md)。

## 从源码安装

详见 [docs/zh-CN/install-from-source.md](docs/zh-CN/install-from-source.md)。
| | SDKMAN | vfox |
| --- | --- | --- |
| 安装 | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
| 只在当前 Shell 里使用 | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
| 在之后新开的所有 Shell 里使用 | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |

## 开发
什么时候该用这个插件、其余的命令以及它们的差别，见 [docs/zh-CN/sdkman.md](docs/zh-CN/sdkman.md)。

插件的工作方式和修改方法见 [docs/zh-CN/development.md](docs/zh-CN/development.md)，容器测试见 [docs/zh-CN/e2e.md](docs/zh-CN/e2e.md)。
## 文档

## 发布这个插件
**使用插件**

维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 前缀的稳定版插件版本号即可发布。共享工作流会更新 `metadata.lua`，创建版本提交和标签，并把 ZIP 包和 manifest 发布到本仓库；不需要在本地打标签，也不需要额外的发布令牌。PR 只运行检查，PR 标题不再触发发布。
- [版本与命名](docs/zh-CN/versions.md)：怎样写版本，以及安装、使用、搜索和 EA 构建
- [发行版](docs/zh-CN/distributions.md)：每个发行版是什么、它的长名，以及 GraalVM、Mandrel 和 Liberica NIK 怎样编号
- [平台](docs/zh-CN/platforms.md)：各发行版在哪些操作系统和 CPU 上有构建
- [查询 Foojay](docs/zh-CN/foojay.md)：自己去问 Foojay 你的平台上有哪些 JDK、插件向它问了什么，以及怎样校验下载的文件
- [JavaFX](docs/zh-CN/javafx.md)：`-fx` 构建以及哪些平台有
- [Native Image](docs/zh-CN/native-image.md)：`native-image` 需要的 C 编译器和 zlib
- [`.sdkmanrc`](docs/zh-CN/sdkmanrc.md)：SDKMAN 的项目文件会选中哪个 JDK
- [SDKMAN 与 vfox](docs/zh-CN/sdkman.md)：什么时候该用这个插件、命令对照以及差别
- [GitHub 镜像](docs/zh-CN/mirror.md)：github.com 很慢时让下载经过镜像
- [Loongnix](docs/zh-CN/loongnix.md)：Linux loong64 上的 JDK
- [问题排查](docs/zh-CN/troubleshooting.md)：插件和 `native-image` 的各种提示、代理设置和 JDK 的位置
- [变更记录](docs/zh-CN/changes.md)：每个版本改了什么

直接推送版本标签也可以发布，前提是 `PLUGIN.version` 已经与标签一致。发布失败时，重新运行失败的那个作业即可接着发布。
**参与开发**

工作流引用的是共享的 `@v1` 发布工具，升级这个工具不会发布本插件。包的约定和首次接入的要求，见[共享工作流的文档](https://github.com/version-fox/plugin-manifest-action)。
- [从源码安装](docs/zh-CN/install-from-source.md)：在下一个版本发布之前用上 `main`
- [开发](docs/zh-CN/development.md)：插件的工作方式、修改方法和发布流程
- [E2E 测试](docs/zh-CN/e2e.md)：容器测试

## 致谢

Expand Down
4 changes: 2 additions & 2 deletions docs/changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

[中文](zh-CN/changes.md) | [English](changes.md)

What changed in each release, as a user notices it. GitHub's release pages list the pull requests. The newest release at the time of writing is 0.6.3, and `main` is ahead of it by everything under "Unreleased". [install-from-source.md](install-from-source.md) gets you those changes now.
What changed in each release, as a user notices it. GitHub's release pages list the pull requests.

## Unreleased
## 0.6.4 (2026-11-03)

- vfox verifies a download against the checksum Foojay lists for it. Release 0.6.3 gives vfox no checksum, so every install ends with `WARNING: Checksum is not provided, skip verify...` and trusts the download, though Foojay lists a checksum for most distributions. Now `vfox install java@25.0.2-graalce` prints `Verifying checksum e0be791c...` instead, and a download that does not match stops with `Checksum error` and installs nothing. Foojay lists none for Dragonwell, Bisheng, Trava, AdoptOpenJDK, OpenLogic, Gluon GraalVM, Corretto after 8 and the older releases of several others, and vfox still warns about those. A checksum file on GitHub goes through `VFOX_JAVA_GITHUB_MIRROR` like the download. Where the plugin cannot use a checksum that Foojay lists, it prints why (`Cannot verify the download: ...`) and installs as before. See [foojay.md](foojay.md#checksums).

Expand Down
Loading
Loading