From b3de2ebde27501f64c5449e5204c989b8d83fa13 Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 3 Nov 2026 12:20:10 +0800 Subject: [PATCH] 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 After the release: - `docs/changes.md` and its translation: "Unreleased" becomes 0.6.4 (2026-11-03), and the sentence about `main` being ahead of the latest release goes. - `docs/troubleshooting.md` and its translation: the three "Unreleased: release 0.6.3 ..." remarks about checksums go. - `docs/development.md` and its translation: "Releasing" now holds what the README said about the shared workflow, and "After a release" lists the steps (changes.md, the previous release number, the quoted data). Reading order: - `README.md` and `README_CN.md` start with install and usage, then versions and short names, then the topics, "Coming from SDKMAN" (shorter, in two paragraphs) and a "Documentation" list that names every page, grouped by what a reader wants. The pointer-only sections and the maintainers' "Releasing this plugin" are gone from the README. The table of short names is unchanged, as the notes of `vfox add java` link to it. - `docs/native-image.md` and its translation are new. They hold the section that was at the end of the GraalVM family in `distributions.md`, in the same words, under headings for Ubuntu, other systems, GraalVM CE 8 to 19 and what was checked. `distributions.md` now lists the GraalVM distributions first and the explanations of their numbers after them. - `docs/foojay.md` puts the queries a reader can run before what the plugin asks and how it checks downloads. `docs/e2e.md` puts how to run the suite before the list of what it verifies. The headings are the same, so links to them still work. - `docs/platforms.md` has one list of notes with one date instead of two. Data: the platform table, the JavaFX table, the places Foojay links each distribution to, the number of distributions and SDKMAN's short names were compared with Foojay and SDKMAN on 2026-11-03 and are unchanged. What changed and is updated: Zulu has Java 27 for Windows ARM64, `java@21-tem` is `21.0.13+9-tem`, `java@28.ea-open` is `28-ea+21`, `java@25-graal` is `25.0.5.0.3-graal`, and `vfox search java all` lists about 2,600 lines. The dev container also carries vfox now, which `docs/e2e.md` did not say. The sections of `foojay.md`, `e2e.md` and `distributions.md` were moved by a script that checks that no line is lost, and the relative links and anchors of all 33 pages resolve. --- README.md | 97 ++++---- README_CN.md | 90 +++---- docs/changes.md | 4 +- docs/development.md | 18 +- docs/distributions.md | 44 +--- docs/e2e.md | 386 +++++++++++++++--------------- docs/foojay.md | 180 +++++++------- docs/install-from-source.md | 2 +- docs/javafx.md | 2 +- docs/mirror.md | 2 +- docs/native-image.md | 34 +++ docs/platforms.md | 22 +- docs/sdkman.md | 4 +- docs/troubleshooting.md | 10 +- docs/versions.md | 12 +- docs/zh-CN/changes.md | 4 +- docs/zh-CN/development.md | 18 +- docs/zh-CN/distributions.md | 44 +--- docs/zh-CN/e2e.md | 92 +++---- docs/zh-CN/foojay.md | 180 +++++++------- docs/zh-CN/install-from-source.md | 2 +- docs/zh-CN/javafx.md | 2 +- docs/zh-CN/mirror.md | 2 +- docs/zh-CN/native-image.md | 34 +++ docs/zh-CN/platforms.md | 22 +- docs/zh-CN/sdkman.md | 4 +- docs/zh-CN/troubleshooting.md | 10 +- docs/zh-CN/versions.md | 12 +- 28 files changed, 690 insertions(+), 643 deletions(-) create mode 100644 docs/native-image.md create mode 100644 docs/zh-CN/native-image.md diff --git a/README.md b/README.md index 4076618..455d705 100644 --- a/README.md +++ b/README.md @@ -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 `-`, 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 `-`, 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 @@ -80,7 +65,13 @@ A version is `-`, 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 @@ -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` @@ -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 diff --git a/README_CN.md b/README_CN.md index d534886..f491386 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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)。 ## 发行版 @@ -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)。 ## 平台 @@ -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` @@ -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)：容器测试 ## 致谢 diff --git a/docs/changes.md b/docs/changes.md index 566081a..fdd24bd 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -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). diff --git a/docs/development.md b/docs/development.md index bf54c31..a03f51f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -23,6 +23,8 @@ tests/post_install_layouts.lua the macOS layouts PostInstall handles, with its tests/fixtures/loongnix/ a saved copy of the Loongnix archive listing tests/e2e/ container tests, see e2e.md Injection.lua type hints for what vfox injects, never loaded +README.md, docs/ the documentation; README_CN.md and docs/zh-CN/ are the Chinese version +opencode.jsonc lets OpenCode agent sessions in this repository run git push, gh pr create and gh pr comment without asking ``` vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGIN` and `RUNTIME` (`osType`, `archType`, `version`) in scope. `osType` and `archType` are Go's `GOOS` and `GOARCH` of the vfox binary. @@ -107,7 +109,7 @@ vfox plugin run . ParseLegacyFile --input '{"filename":".sdkmanrc","filepath":"/ 2. Add `[""] = ""` to `short_name` in `lib/distribution_version.lua`. Use SDKMAN's identifier when SDKMAN has or had the distribution. Otherwise make one the way SDKMAN does: keep a short vendor name whole, and cut a longer one down, mostly by dropping vowels (`opnlgc`). If SDKMAN spells it differently, map it in `plugin_spelling` in `hooks/parse_legacy_file.lua`, and add the difference to [distributions.md](distributions.md#short-names-and-sdkman). 3. If its version numbers need special care, as those of GraalVM and Mandrel do, handle them where `lib/foojay.lua` reads Foojay's answer (`graalvm_packages`, `own_numbers`), and its LTS marks or the pick for a bare major in `hooks/available.lua` and `hooks/pre_install.lua`. If it ships no tar.gz outside Windows, add its archive type to `other_archive_type` in `lib/foojay.lua`, and if Foojay lists packages of it that do not install as they are, add a fix to `fixes` there. 4. Add a case to `tests/pre_install_test.lua`. -5. Update the tables in `README.md`, [distributions.md](distributions.md) and [platforms.md](platforms.md), and their translations in `README_CN.md` and `docs/zh-CN`. +5. Update the tables in `README.md`, [distributions.md](distributions.md) and [platforms.md](platforms.md), the number of distributions that `README.md` and distributions.md give, and the translations of all of them in `README_CN.md` and `docs/zh-CN`. 6. For a new code path, also add it to the e2e matrix ([e2e.md](e2e.md)). Distributions outside the matrix still run every check except the `java.vendor` assertion and the asdf-style `PreUse` spelling. One that only brings a name goes into `nameOnly` in `tests/e2e/common/common.go` instead, with the runner platforms Foojay has it for. ## Refreshing the platform table @@ -148,10 +150,18 @@ The ids are Foojay's (`oracle_open_jdk` is `open`). It prints `redhat` for Linux ## Releasing -A maintainer runs **Actions → Plugin → Run workflow** on the default branch with the version, without `v`. The README describes what the shared workflow does. Afterwards `plugins/java.json` in [vfox-plugins](https://github.com/version-fox/vfox-plugins) shows the version that `vfox add java` serves. +A maintainer publishes from **Actions → Plugin → Run workflow** on the default branch, entering a stable plugin version without the `v` prefix. The shared workflow, [plugin-manifest-action](https://github.com/version-fox/plugin-manifest-action), updates `metadata.lua`, creates the version commit and the tag, and publishes the ZIP and the manifest in this repository. No local tag or extra release token is needed. Pull requests run the checks only. -The documentation marks what is newer than the last release with "Unreleased" ("未发布" in Chinese). After a release, move those entries in [changes.md](changes.md) under the new version and take the remarks out, in both languages: `grep -rn -i -e unreleased -e 未发布 docs README*`. Also search for the number of the previous release: a few sentences compare against it without saying "Unreleased". +Pushing a version tag publishes too, when `PLUGIN.version` already matches the tag. If publication fails, re-run the failed job to resume it. The workflow follows the shared `@v1` release tool, and updating the tool does not release this plugin. The shared workflow's documentation has the package contract and the requirements of a first rollout. Afterwards `plugins/java.json` in [vfox-plugins](https://github.com/version-fox/vfox-plugins) shows the version that `vfox add java` serves. + +### After a release + +The documentation marks what is newer than the last release with "Unreleased" ("未发布" in Chinese). Once the release is out: + +1. Move those entries in [changes.md](changes.md) under the new version, with the date of the release, and take the remarks out, in both languages: `grep -rn -i -e unreleased -e 未发布 docs README*`. +2. Search for the number of the previous release: a few sentences compare against it without saying "Unreleased". +3. Pages that quote Foojay give the day the data was taken. Bring up to date the quotes that name the newest release of something (`21.0.13+9-tem` on 2026-11-03), and check the tables against Foojay again, see [Refreshing the platform table](#refreshing-the-platform-table). ## Writing the docs -English pages are in `docs/`, the Chinese ones in `docs/zh-CN/` under the same names (the Chinese README is `README_CN.md`), and each page starts with a link to the other language. Pages that quote Foojay give the day the data was taken. Nothing in CI checks them, so run the commands you add. +English pages are in `docs/`, the Chinese ones in `docs/zh-CN/` under the same names (the Chinese README is `README_CN.md`), and each page starts with a link to the other language. A new page goes into the Documentation list of both READMEs. The notes that `vfox add java` prints link to `README.md` (`PLUGIN.notes` in `metadata.lua`, checked by the e2e suite), so the README keeps the list of short names and the way to search a distribution. Pages that quote Foojay give the day the data was taken. Nothing in CI checks them, so run the commands you add. diff --git a/docs/distributions.md b/docs/distributions.md index bd379bc..9b5e383 100644 --- a/docs/distributions.md +++ b/docs/distributions.md @@ -2,7 +2,7 @@ [中文](zh-CN/distributions.md) | [English](distributions.md) -The plugin gets the releases and download links of these 31 distributions from [Foojay](foojay.md), all that Foojay listed on 2026-10-20. The short name or the long name goes wherever a distribution does: `21-tem`, `21-temurin`, `temurin-21`, `vfox search java tem`. +The plugin gets the releases and download links of these 31 distributions from [Foojay](foojay.md), all that Foojay lists on 2026-11-03. The short name or the long name goes wherever a distribution does: `21-tem`, `21-temurin`, `temurin-21`, `vfox search java tem`. | Short name | Long name | Distribution | Maintained by | | --- | --- | --- | --- | @@ -44,7 +44,7 @@ Which operating systems and CPUs each distribution covers is in [platforms.md](p ## Short names and SDKMAN -The short names follow the identifiers of [SDKMAN](https://sdkman.io/), where Temurin 21.0.8 is `21.0.8-tem` too. These are the differences, against SDKMAN's list of 2026-10-20: +The short names follow the identifiers of [SDKMAN](https://sdkman.io/), where Temurin 21.0.8 is `21.0.8-tem` too. These are the differences, against SDKMAN's list of 2026-11-03: - JetBrains Runtime is `jb`, which SDKMAN calls `jbr`, and BiSheng is `bsg`, which SDKMAN calls `bisheng`, the plugin's long name for it. A `.sdkmanrc` takes SDKMAN's spellings, see [sdkmanrc.md](sdkmanrc.md). - SDKMAN no longer lists Dragonwell, TravaOpenJDK, AdoptOpenJDK, Gluon GraalVM or the GraalVM CE builds numbered after GraalVM. It called the last three `adpt`, `gln` and `grl`, and wrote the virtual machine or the JDK into the version: `11.0.10.hs-adpt` with HotSpot, `11.0.10.j9-adpt` with OpenJ9, `22.3.3.r17-grl` on JDK 17. Here each Foojay distribution has a name of its own, so that part moved into the name: `11.0.10-adpt`, `11.0.10-adptj9`, `22.3.3-grl17`. A `.sdkmanrc` with SDKMAN's spelling selects them. @@ -126,6 +126,8 @@ IBM Semeru Runtime Certified Edition: Semeru's OpenJ9 runtimes, certified agains ## GraalVM family +Many of these carry GraalVM's own version numbers and not Java's. How they are named and what a bare major installs is explained after the list, for [Oracle GraalVM and GraalVM Community](#behavior-of-oracle-graalvm-and-graalvm-community), for [Mandrel and Liberica NIK](#behavior-of-mandrel-and-liberica-nik) and for [the older ones](#versions-numbered-after-graalvm). To build native executables with them, see [native-image.md](native-image.md). + ### Oracle GraalVM (`graal`) Oracle's distribution of GraalVM, built on Oracle JDK. Releases carry GraalVM's numbers: `17.0.12-graal`, `25.0.4.1.1-graal`, `25.4.4.1.1-graal`. @@ -142,13 +144,6 @@ The open-source edition of GraalVM, built on OpenJDK. [Red Hat's](https://github.com/graalvm/mandrel) distribution for building Quarkus native executables, which concentrates on `native-image`. Releases 20.3 to 25, which run Java 11, 17 and 20 to 25. -### Behavior of Mandrel and Liberica NIK - -- Both carry the version of the GraalVM they are built from, and their installs are named after it: `23.1.12.1-mandrel`, `23.1.8-nik`. Up to 24 that is not the Java version. 23.1 runs Java 21, 24.0 Java 22, 24.1 Java 23 and 24.2 Java 24, and older releases run Java 11, 17 or 20. From 25 on the two agree (`25.0.4.1`). -- A bare major is GraalVM's as well: `java@23-mandrel` installs the newest 23.x, `23.1.12.1-mandrel`, which runs Java 21, and `java@21-mandrel` installs `21.3.6-mandrel`, which runs Java 17. A longer version installs the release it names: `java@23.1.12-mandrel` is 23.1.12, not 23.1.12.1, and `java@23.1-mandrel` is the first 23.1 release, 23.1.0. A build number finds nothing (`java@23.1.8+1-nik`). -- The releases ending in `.0.0` are listed under the bare major (`24-mandrel` is Mandrel 24.0.0) and install with a longer version, `java@24.0.0-mandrel`. Once one is installed, vfox finds `java@24-mandrel` by that name, for `vfox install` and `vfox use` alike. -- Some releases come for several Java versions under one number, such as Mandrel 21.3.6 for Java 11 and 17. The plugin installs the build for the newest Java, which for Mandrel 23.0.1.2 and Liberica NIK 23.0.1 is Java 20, not 17. Liberica NIK built a few releases twice for the same Java (`25.0.3`), and the later build installs. The name shows neither the Java version nor BellSoft's build, so the other builds cannot be installed. - ### GraalVM CE 8 to 19 (`grl8`, `grl11`, `grl16`, `grl17`, `grl19`) GraalVM Community Edition up to 22.3, from before it numbered its releases after the JDK. Foojay has one distribution per JDK: `grl8` (GraalVM 19.3 to 21.3.1), `grl11` (19.3 to 22.3.3), `grl16` (21.1 and 21.2), `grl17` (21.3 to 22.3.3) and `grl19` (22.3 and 22.3.1). GraalVM Community (`graalce`) followed them. @@ -157,39 +152,26 @@ GraalVM Community Edition up to 22.3, from before it numbered its releases after [Gluon's](https://docs.gluonhq.com/#_graalvm) build of GraalVM, for compiling JavaFX applications into native images. 21.1 and 21.2 run on JDK 11. The 22.x releases, 22 to 22.1.0.1, come for JDK 11 and for JDK 17 under one version, and the plugin installs the JDK 17 build. 23+25 is a development build on JDK 23. Linux x64, macOS and Windows x64, with Apple silicon from 22.1.0.1. -### Versions numbered after GraalVM - -GraalVM CE 8 to 19, Gluon GraalVM before 23, and Mandrel and Liberica NIK before 25 carry GraalVM's version numbers, not Java's: `22.3.3-grl17` is GraalVM 22.3.3 and runs Java 17.0.8, `21.3.1-grl11` runs Java 11, and `23.1.12.1-mandrel` runs Java 21. For a bare major vfox takes the highest installed version that starts with it, from any distribution, so with `21.3.1-grl11` and `21.0.12.1+1-tem` installed, `vfox use java@21` selects `21.3.1-grl11`. Name the distribution, as in `java@21-tem`. - ### Behavior of Oracle GraalVM and GraalVM Community - Since 25.1 (June 2026) GraalVM puts out a feature release every month next to its 25.0 line: `25.1.3`, `25.2.4`, `25.3.4.1`, `25.4.4.1.1`. Each is replaced within about a month. Foojay marks Oracle GraalVM's STS, but GraalVM Community's LTS where it lists them the old way round (see below), as the JDK they build on is LTS. `vfox search` leaves the LTS note off them all. - Releases are named after GraalVM's own version, which Foojay gives as `distribution_version`. Foojay's `java_version` is the JDK's version, which a feature release shares with the 25.0 line: `25.4.4.1.1-graal`, `25.3.4.1-graal`, `25.0.4.1.1-graal` and `25.0.4.1-graal` all have the `java_version` 25.0.4.1. - Foojay lists GraalVM Community's feature releases under GraalVM's version too, as it did before October 2026, with downloads from GitHub. So `java@25.4.4.1-graalce`, the name release 0.6.2 gives the 25.4.4.1.1 build, still installs it from GitHub, while `java@25.4.4.1.1-graalce` gets the same file from Oracle's GraalVM Download Service. -- `java@25-graal` installs the newest build of the 25.0 line (`25.0.5-graal` on 2026-10-20), the line Oracle's own `25/latest` download follows. A feature release needs its full version: `java@25.4.4.1.1-graal`. `vfox use java@25-graal` and `java=25-graal` in a `.sdkmanrc` select the newest installed build of that line too, and a feature release only where nothing else of 25 is installed. -- GraalVM Community's 25.0 line ended with `25.0.2`, and the feature releases are all it still ships. `java@25-graalce` installs the newest of them, `25.4.4.1.1-graalce` on 2026-10-20. +- `java@25-graal` installs the newest build of the 25.0 line (`25.0.5.0.3-graal` on 2026-11-03), the line Oracle's own `25/latest` download follows. A feature release needs its full version: `java@25.4.4.1.1-graal`. `vfox use java@25-graal` and `java=25-graal` in a `.sdkmanrc` select the newest installed build of that line too, and a feature release only where nothing else of 25 is installed. +- GraalVM Community's 25.0 line ended with `25.0.2`, and the feature releases are all it still ships. `java@25-graalce` installs the newest of them, `25.4.4.1.1-graalce` on 2026-11-03. - The plugin sets `JAVA_HOME` and `PATH`, and no `GRAALVM_HOME`. A `GRAALVM_HOME` that points at a GraalVM of your own stays as it is, and the native-image build plugins fall back to `JAVA_HOME` when it is unset. - There is no Windows ARM64 and no Alpine build, and Intel Macs get nothing after 25.0.1. See [platforms.md](platforms.md#graalvm). -### Native Image and the C toolchain - -A GraalVM installs and runs like any other JDK. After `vfox install java@25.0.2-graalce` and `vfox use`, `java` and `javac` work on a system with no compiler and no zlib headers. `sudo apt install --assume-yes build-essential zlib1g-dev` is for `native-image` alone, the tool that compiles a program into a native executable. It links the executable with the system's `gcc` against the C library and zlib, so it needs them, and so does whatever calls it, such as the Maven and Gradle plugins for Native Image. The plugin installs the JDK and nothing else. - -On Ubuntu 26.04, execute in Bash, - -```bash -sudo apt install --assume-yes build-essential zlib1g-dev -``` +### Behavior of Mandrel and Liberica NIK -- `native-image` is in the `bin` directory of Oracle GraalVM, GraalVM Community, Liberica NIK, Mandrel and Gluon GraalVM. GraalVM CE 8 to 19 are the exception, see below. -- Without `gcc` the build stops within seconds with `Error: Default native-compiler executable 'gcc' not found via environment variable PATH`, and `zlib1g-dev` alone does not change that. -- With `gcc` but without `zlib1g-dev`, which is what `build-essential` alone gives, the build goes through the analysis and the compilation first, which took between 20 seconds and two minutes for a hello world, and fails when it links: `There was an error linking the native image: Linker command exited with 1`, GraalVM's hint `It appears as though libz:.a is missing. Please install it.`, and `cannot find -lz: No such file or directory`. -- `gcc`, `libc6-dev` and `zlib1g-dev` were enough to build a hello world, without `g++` and `make`. `build-essential` brings both, and is what GraalVM's documentation lists. -- Other systems need other packages. GraalVM's [prerequisites](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites) list `sudo dnf install gcc glibc-devel zlib-devel libstdc++-static` for Fedora and the other systems that use dnf, `xcode-select --install` for macOS, and the Visual Studio Build Tools with the Windows SDK for Windows. On Fedora 44, `gcc`, `glibc-devel` and `zlib-devel` built a hello world without `libstdc++-static`. +- Both carry the version of the GraalVM they are built from, and their installs are named after it: `23.1.12.1-mandrel`, `23.1.8-nik`. Up to 24 that is not the Java version. 23.1 runs Java 21, 24.0 Java 22, 24.1 Java 23 and 24.2 Java 24, and older releases run Java 11, 17 or 20. From 25 on the two agree (`25.0.4.1`). +- A bare major is GraalVM's as well: `java@23-mandrel` installs the newest 23.x, `23.1.12.1-mandrel`, which runs Java 21, and `java@21-mandrel` installs `21.3.6-mandrel`, which runs Java 17. A longer version installs the release it names: `java@23.1.12-mandrel` is 23.1.12, not 23.1.12.1, and `java@23.1-mandrel` is the first 23.1 release, 23.1.0. A build number finds nothing (`java@23.1.8+1-nik`). +- The releases ending in `.0.0` are listed under the bare major (`24-mandrel` is Mandrel 24.0.0) and install with a longer version, `java@24.0.0-mandrel`. Once one is installed, vfox finds `java@24-mandrel` by that name, for `vfox install` and `vfox use` alike. +- Some releases come for several Java versions under one number, such as Mandrel 21.3.6 for Java 11 and 17. The plugin installs the build for the newest Java, which for Mandrel 23.0.1.2 and Liberica NIK 23.0.1 is Java 20, not 17. Liberica NIK built a few releases twice for the same Java (`25.0.3`), and the later build installs. The name shows neither the Java version nor BellSoft's build, so the other builds cannot be installed. -GraalVM CE 8 to 19 (`grl8`, `grl11`, `grl16`, `grl17`, `grl19`) come without `native-image`. Their `bin` directory holds `gu`, the GraalVM Updater, and `native-image` is `command not found` until `gu install native-image` has added it from GitHub. That worked for `22.3.3-grl11`, `21.2-grl16`, `22.3.3-grl17` and `22.3.1-grl19` on 2026-11-02, and the packages above are needed after it as before. It failed for `21.3.1-grl8` with `Internal error occurred: A JSONObject text must begin with '{'`, because the release index that this `gu` downloads, `https://oca.opensource.oracle.com/gds/meta-data.json`, is a web page now. For that release, download `native-image-installable-svm-java8-linux-amd64-21.3.1.jar` from the [`vm-21.3.1` release](https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.1) and run `gu -L install` on the file. +### Versions numbered after GraalVM -Checked on 2026-11-02 with vfox 1.0.13 in Ubuntu 26.04 container images (x64) that had no compiler. GraalVM Community 25.0.2 and 25.4.4.1.1, Oracle GraalVM 25.0.5, Mandrel 25.0.5, Liberica NIK 25.0.4.1 and Gluon GraalVM 22.1.0.1 stopped as described without the packages, and with them built a hello world that ran. So did `22.3.3-grl17` after `gu install native-image`, and GraalVM Community 25.0.2 in a Fedora 44 image. +GraalVM CE 8 to 19, Gluon GraalVM before 23, and Mandrel and Liberica NIK before 25 carry GraalVM's version numbers, not Java's: `22.3.3-grl17` is GraalVM 22.3.3 and runs Java 17.0.8, `21.3.1-grl11` runs Java 11, and `23.1.12.1-mandrel` runs Java 21. For a bare major vfox takes the highest installed version that starts with it, from any distribution, so with `21.3.1-grl11` and `21.0.12.1+1-tem` installed, `vfox use java@21` selects `21.3.1-grl11`. Name the distribution, as in `java@21-tem`. ## Others diff --git a/docs/e2e.md b/docs/e2e.md index 62184c7..a014b1f 100644 --- a/docs/e2e.md +++ b/docs/e2e.md @@ -11,6 +11,9 @@ from `actions/setup-go`). Locally, the repository dev container reproduces that on Linux; on Windows a Docker Compose runner image does, since dev containers cannot host Windows container images (see below). +The sections below say how to run the suite. The list of every check is at +the end, under [What the suite verifies](#what-the-suite-verifies). + ## Dev container `.devcontainer/` opens a Linux development environment that works on all four @@ -22,12 +25,13 @@ host platforms: | Windows amd64 / arm64 | Docker Desktop in Linux-container mode (WSL 2) | It carries Go 1.27.1 (the version CI installs), the Docker CLI, stylua, -lua-language-server, and the license tools — all pinned to the versions in -`.github/workflows/lint.yml` and `license.yml` — and mounts the host Docker -daemon socket. The suites then run testcontainers against that daemon -(Docker-out-of-Docker), spawning the same target containers a native CI -runner spawns; this is deliberately not Docker-in-Docker, so image cache and -networking stay the host's. The image needs no workspace files, so the build +lua-language-server, the license tools and vfox, which runs the offline hook +tests — all pinned to the versions in `.github/workflows/lint.yml`, +`license.yml` and `test.yml` — and mounts the host Docker daemon socket. The +suites then run testcontainers against that daemon (Docker-out-of-Docker), +spawning the same target containers a native CI runner spawns; this is +deliberately not Docker-in-Docker, so image cache and networking stay the +host's. The image needs no workspace files, so the build context stays at `.devcontainer/`; `postCreateCommand` warms the Go module cache for `tests/e2e` so the first test run does not stop to download. @@ -55,196 +59,12 @@ container: the Dev Containers spec does not support Windows container images and Windows containers only run on a Windows daemon. That suite keeps its Docker Compose runner on a Windows host; see [Windows 11](#windows-11) below. -## What the suite verifies - -Every combination runs the same flow (one long-lived container per combo, -driven from Go through `docker exec`-style calls); the target images carry no -JDK, so `java` can only come from what vfox installs: - -1. vfox is installed from the requested channel — the latest release - (`latest`) or built from source (`main`) — and the local `java` plugin is - registered from this checkout. On Windows, the runner builds `main` once, - while the `latest` combinations run, and the `main` containers start from - the e2e image plus that `vfox.exe`. Then the notes printed by - `vfox info java` must link to the README, which lists the short names - and shows how to search a distribution. They used to give five short - names but not how to list their versions - ([vfox#390](https://github.com/version-fox/vfox/issues/390)). -2. A distribution without a version, alone or after an empty one - (`java@tem`, `java@-tem`), fails both `vfox install` and `vfox use` with - an error asking for one. The hooks stopped with a Lua error on the first, - while `PreInstall` sent the empty version to Foojay, which lists every - release, and installed the newest one. - A release no distribution has published (`.0.99`) fails to install, - with `PreInstall` naming the platform it searched (`linux/amd64`, - `windows/arm64`, ...), so the Foojay lookup is checked to target the - runner. So does a build of the pinned release that was never published - (`+99`, e.g. `21.0.8+99-tem`), proving the lookup keeps the - build number: Foojay reads an unencoded `+` as a space and drops the - build, and the release's newest build would install instead. - - On the Temurin rows an install through a mirror that does not exist must - fail too. With `VFOX_JAVA_GITHUB_MIRROR=https://invalid.example.invalid` - the mirror goes in front of Temurin's GitHub URL, so `vfox install` fails on - the download, and its error must name the URL it asked for: the mirror, a - slash and the GitHub URL. Before the plugin read the variable, it downloaded - the JDK from github.com and the install succeeded. Nothing is downloaded, - and no mirror that works is run. -3. On the GraalVM Community rows, Oracle GraalVM's bare major `25-graal` - installs the newest build of its 25.0 line (`25.0.5-graal` on - 2026-10-20), the line Oracle's own `25/latest` download follows, not one - of the monthly feature releases listed before it (`25.4.4.1.1-graal`). - `vfox search java graal` must list those under GraalVM's own version, - and mark the other releases of 25 alike, as in item 5. The plugin used to - name them after the JDK version Foojay has given them since October 2026, - which they share with the 25.0 line: the search then listed no feature - release, and `25.0.4.1-graal` had no LTS note and installed 25.4.4.1.1. - The builds of 25 that the search lists are faked as installed first, so - `vfox install` names the one `PreInstall` picked and nothing downloads. - GA 25 is left out, as vfox would find `25-graal` itself installed without - asking `PreInstall`. On Linux the install must also ask Foojay what the - search asked, as at the end of item 4. - - With those builds installed, `vfox use java@25-graal` and a `.sdkmanrc` - holding `java=25-graal` must select the build `vfox install` names. - `PreUse` and `ParseLegacyFile` took the newest installed release of 25, - which is a feature release as soon as one is installed - ([#110](https://github.com/version-fox/vfox-java/issues/110)). Each faked - build holds a stand-in `java` that only prints its name, as in item 6. - Once the 25.0 line is removed, `vfox use` and the `.sdkmanrc` must both - select the newest feature release. -4. On the Temurin rows, which run on every runner, the distributions the - suite checks by name only (`adpt` to `semcrt`, `nameOnly` in - `tests/e2e/common`) go by their short names where Foojay has packages of - them for the runner: `vfox search java ` lists each, and once the - newest version it lists is faked as installed, - `vfox install java@-` (`22-grl17`) reports that version as - already installed, so nothing downloads. Before they had short names, the - two failed with `Unsupported distribution` and `Could not extract a valid - distribution`. - - On the same rows Mandrel and Liberica NIK go by the GraalVM version they - carry (`ownNumbers` in `tests/e2e/common`; Windows arm64 has neither): - `vfox search java mandrel` lists `23.1.12-mandrel` (`23.1.8-nik` for - Liberica NIK), and with it and the newest 23.x the search lists faked as - installed, `vfox install java@mandrel-23.1.12` and - `vfox install java@23-mandrel` report those two as already installed. - Before the plugin read `distribution_version`, where Foojay moved that - version in October 2026, the search listed one name per Java major, - `23.1.12-mandrel` was not found, and `java@23-mandrel` installed Mandrel - 24.1.2, built for Java 23. - - On Linux these rows, and the GraalVM Community rows of item 3, reach - Foojay through a stand-in for api.foojay.io, built from - `tests/e2e/linux/front`, which logs what the plugin asks. Each install - above must ask what the search before it asked (`AsksAsSearch` in - `tests/e2e/common`). Foojay's answers are cached per question, so for half - an hour after a release another question can take a build that the search - does not list yet, which would download and fail the check - ([foojay.md](foojay.md#what-the-plugin-asks)). Before - [#113](https://github.com/version-fox/vfox-java/issues/113) a bare major - asked for `latest=available`, and Mandrel and Liberica NIK by - `distribution_version`. -5. The pinned release installs under the name `PreInstall` gives it: the - requested version plus the build number (`21.0.8-tem` installs as - `21.0.8+9-tem`). `vfox search java ` (the `Available` hook) - lists that same name as installed, noting JavaFX on `-fx` builds. For - GraalVM it must also list the feature releases GraalVM ships every month - since 25.1 (`25.4.4.1.1-graalce`), none of them noted LTS, though Foojay - marks some of them LTS, as the JDK they build on is; each lasts about a - month. Every other release of a major must carry the same note. The - plugin used to list the feature release 25.4.4.1.1 as `25.0.4.1-graalce`, - without the LTS note `25.0.2-graalce` has. - On Windows the list includes JetBrains Runtime 21.0.5, which ships only as - tar.gz there. - - The install itself must also have verified the download. Foojay lists a - checksum for the pinned release of every default distribution on every - runner (2026-11-02), and `vfox install` must print `Verifying checksum - ...` with a digest of a length vfox supports, not `WARNING: - Checksum is not provided, skip verify...`, which every install ended with - until the plugin passed Foojay's checksums on. The digests come in four - forms, so each way the plugin reads them runs: SHA-256 and SHA-1 in - Foojay's record (Temurin, Liberica), SHA-256 in a file that holds the - digest alone (OpenJDK, GraalVM Community) and SHA-512 in a file that adds - the name (JetBrains). vfox compares the digest with the hash of the file it - downloaded and fails the install if they differ, so the install succeeding - proves the digest is the file's. A release chosen with `JAVA_VERSION` is - not checked, as Foojay may list no checksum for it. -6. Before any `vfox use`, a `.sdkmanrc` holding the SDKMAN identifier - without the build number selects the JDK through `ParseLegacyFile`: - `java=21.0.8-tem`, `java=21.0.5-jbr` (SDKMAN's name for JetBrains) or - `java=25.0.4.fx-librca` (its spelling of JavaFX builds). So does one - padding the release with a zero, as `sdk list java` shows many: - `java=21.0.8.0+9-tem`, `java=25.0.4.0-fx+9-librca` (Foojay, and so the - installed name, has no such zero). So does one holding the installed - version (`java=21.0.8+9-tem`). All run next to an empty install of - another release whose version starts with the pinned one - (`21.0.80+1-tem`): vfox sorts installed versions as strings, descending, - so `vfox list java` must show it first. `ParseLegacyFile` used to take it - as the first one starting with the release, and, for the padded release, - as the newest release of the major. Then SDKMAN's identifier of an - early-access build of the pinned major, spelled as `sdk list java` shows - OpenJDK's (`28.0.0.0+ea.20-open`), must select that build: - `java=21.0.0.0+ea.1-tem` selects `21-ea+1-tem`, not the release, which - `ParseLegacyFile` took while it understood only SDKMAN's older - `21.ea.1-tem`. So must the installed name itself (`java=21-ea+1-tem`), - for which `ParseLegacyFile`, unable to parse it, selected nothing, while - `vfox use` selects it. jdk.java.net removes each early-access build within - weeks, so that install is faked: its `bin` holds a stand-in `java` that - only prints the name. On Windows the file is written with CRLF line - endings. - - On the Temurin rows, a `.sdkmanrc` holding one of SDKMAN's identifiers of - Mandrel and Liberica NIK with the JDK after `.r` must then select the - release it names: `java=25.0.4.r25-nik` selects `25.0.4-nik`, not - `25.0.4.1-nik`, which `ParseLegacyFile` took while it read `25.0.4.r25` as - the release. `java=22.1.r11-mandrel` must select nothing, as the plugin - installs only the JDK 17 build of Mandrel 22.1 (`OwnNumberIdentifiers` in - `tests/e2e/common`). The releases they name and a newer one of each major - are faked the same way. -7. After `vfox use --global`, the JDK on `PATH` reports the requested - `java.version`, the runner's `os.arch` (`amd64` / `aarch64`, which also - catches an x64 JDK emulated on Windows ARM64) and the distribution's - `java.vendor`. `JAVA_HOME` holds that same JDK, `javac` compiles a - program that `java` then runs, the module list carries JavaFX exactly for - `-fx` builds, and `vfox current java` reports the installed version. A - `GRAALVM_HOME` set beforehand keeps its value, as users point it at a - GraalVM of their own; for GraalVM, the plugin used to replace it with - the JDK in use. -8. `PreUse` maps the spellings users type to the installed version without - another download: the bare major (`java@21`, left to vfox core's fuzzy - matching), the spec the JDK was installed with (`java@21.0.8-tem`, whose - build number `PreUse` finds among the installed versions) and the - asdf-style `-[-fx]` (`java@temurin-21.0.8+9`, - rewritten to `21.0.8+9-tem`; `java@openjdk-25.0.2+10` to `25.0.2+10`). - So does the release padded with a zero, as SDKMAN writes releases - (`java@21.0.8.0-tem`, `java@21.0.8.0+9-tem`), which `vfox install` must - first find already installed: `PreInstall` passes the zero on to Foojay, - which leaves it out, while `PreUse` looked for an installed version - starting with the padded release and reported it not installed. - -The default matrix runs every distribution against both vfox channels -(`latest`, `main`): - -| Distribution | Release | Covers | amd64 | arm64 | -| ------------ | ------- | --------------------------------------------------------------------------------------------------------- | ----- | ----- | -| `open` | 25.0.2 | the default distribution, versions without a suffix | ✓ | | -| `tem` | 21.0.8 | the common path (tar.gz on Linux, zip on Windows); the mirror, name and number checks of items 2, 4 and 6 | ✓ | ✓ | -| `librca-fx` | 25.0.4 | JavaFX bundled builds (`-fx`) | ✓ | ✓ | -| `jb` | 21.0.5 | the tar.gz path on Windows, which has no zip for it | ✓ | ✓ | -| `graalce` | 25.0.2 | a `GRAALVM_HOME` set beforehand keeps its value; Oracle GraalVM's `25-graal` | ✓ | | - -Every pinned release is published through Foojay for each platform its row -runs on. OpenJDK and GraalVM Community ship no `windows-aarch64` build, so -arm64 runs the other three on both Linux and Windows. - ## Environment knobs | Variable | Default | Meaning | | -------------------- | -------------------------- | ----------------------------------------------------------------------- | | `VFOX_VERSION` | `latest main` | Space-separated vfox channels (`latest`, `main`) | -| `DISTRIBUTION` | see matrix above | Space-separated plugin distributions, `-fx` for JavaFX (`tem zulu-fx`) | +| `DISTRIBUTION` | see matrix below | Space-separated plugin distributions, `-fx` for JavaFX (`tem zulu-fx`) | | `JAVA_VERSION` | per distribution | Release installed for every selected distribution (Java 9+ numbering) | | `E2E_MAX_JOBS` | `3` (Linux), `2` (Windows) | Parallel containers per host | | `E2E_RETRY_ATTEMPTS` | `3` | Attempts per network-touching exec (linear 10s backoff) | @@ -428,3 +248,187 @@ docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header fix docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -check -f .license.tpl tests/e2e/windows/*.ps1 docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -f .license.tpl tests/e2e/windows/*.ps1 ``` + +## What the suite verifies + +Every combination runs the same flow (one long-lived container per combo, +driven from Go through `docker exec`-style calls); the target images carry no +JDK, so `java` can only come from what vfox installs: + +1. vfox is installed from the requested channel — the latest release + (`latest`) or built from source (`main`) — and the local `java` plugin is + registered from this checkout. On Windows, the runner builds `main` once, + while the `latest` combinations run, and the `main` containers start from + the e2e image plus that `vfox.exe`. Then the notes printed by + `vfox info java` must link to the README, which lists the short names + and shows how to search a distribution. They used to give five short + names but not how to list their versions + ([vfox#390](https://github.com/version-fox/vfox/issues/390)). +2. A distribution without a version, alone or after an empty one + (`java@tem`, `java@-tem`), fails both `vfox install` and `vfox use` with + an error asking for one. The hooks stopped with a Lua error on the first, + while `PreInstall` sent the empty version to Foojay, which lists every + release, and installed the newest one. + A release no distribution has published (`.0.99`) fails to install, + with `PreInstall` naming the platform it searched (`linux/amd64`, + `windows/arm64`, ...), so the Foojay lookup is checked to target the + runner. So does a build of the pinned release that was never published + (`+99`, e.g. `21.0.8+99-tem`), proving the lookup keeps the + build number: Foojay reads an unencoded `+` as a space and drops the + build, and the release's newest build would install instead. + + On the Temurin rows an install through a mirror that does not exist must + fail too. With `VFOX_JAVA_GITHUB_MIRROR=https://invalid.example.invalid` + the mirror goes in front of Temurin's GitHub URL, so `vfox install` fails on + the download, and its error must name the URL it asked for: the mirror, a + slash and the GitHub URL. Before the plugin read the variable, it downloaded + the JDK from github.com and the install succeeded. Nothing is downloaded, + and no mirror that works is run. +3. On the GraalVM Community rows, Oracle GraalVM's bare major `25-graal` + installs the newest build of its 25.0 line (`25.0.5.0.3-graal` on + 2026-11-03), the line Oracle's own `25/latest` download follows, not one + of the monthly feature releases listed before it (`25.4.4.1.1-graal`). + `vfox search java graal` must list those under GraalVM's own version, + and mark the other releases of 25 alike, as in item 5. The plugin used to + name them after the JDK version Foojay has given them since October 2026, + which they share with the 25.0 line: the search then listed no feature + release, and `25.0.4.1-graal` had no LTS note and installed 25.4.4.1.1. + The builds of 25 that the search lists are faked as installed first, so + `vfox install` names the one `PreInstall` picked and nothing downloads. + GA 25 is left out, as vfox would find `25-graal` itself installed without + asking `PreInstall`. On Linux the install must also ask Foojay what the + search asked, as at the end of item 4. + + With those builds installed, `vfox use java@25-graal` and a `.sdkmanrc` + holding `java=25-graal` must select the build `vfox install` names. + `PreUse` and `ParseLegacyFile` took the newest installed release of 25, + which is a feature release as soon as one is installed + ([#110](https://github.com/version-fox/vfox-java/issues/110)). Each faked + build holds a stand-in `java` that only prints its name, as in item 6. + Once the 25.0 line is removed, `vfox use` and the `.sdkmanrc` must both + select the newest feature release. +4. On the Temurin rows, which run on every runner, the distributions the + suite checks by name only (`adpt` to `semcrt`, `nameOnly` in + `tests/e2e/common`) go by their short names where Foojay has packages of + them for the runner: `vfox search java ` lists each, and once the + newest version it lists is faked as installed, + `vfox install java@-` (`22-grl17`) reports that version as + already installed, so nothing downloads. Before they had short names, the + two failed with `Unsupported distribution` and `Could not extract a valid + distribution`. + + On the same rows Mandrel and Liberica NIK go by the GraalVM version they + carry (`ownNumbers` in `tests/e2e/common`; Windows arm64 has neither): + `vfox search java mandrel` lists `23.1.12-mandrel` (`23.1.8-nik` for + Liberica NIK), and with it and the newest 23.x the search lists faked as + installed, `vfox install java@mandrel-23.1.12` and + `vfox install java@23-mandrel` report those two as already installed. + Before the plugin read `distribution_version`, where Foojay moved that + version in October 2026, the search listed one name per Java major, + `23.1.12-mandrel` was not found, and `java@23-mandrel` installed Mandrel + 24.1.2, built for Java 23. + + On Linux these rows, and the GraalVM Community rows of item 3, reach + Foojay through a stand-in for api.foojay.io, built from + `tests/e2e/linux/front`, which logs what the plugin asks. Each install + above must ask what the search before it asked (`AsksAsSearch` in + `tests/e2e/common`). Foojay's answers are cached per question, so for half + an hour after a release another question can take a build that the search + does not list yet, which would download and fail the check + ([foojay.md](foojay.md#what-the-plugin-asks)). Before + [#113](https://github.com/version-fox/vfox-java/issues/113) a bare major + asked for `latest=available`, and Mandrel and Liberica NIK by + `distribution_version`. +5. The pinned release installs under the name `PreInstall` gives it: the + requested version plus the build number (`21.0.8-tem` installs as + `21.0.8+9-tem`). `vfox search java ` (the `Available` hook) + lists that same name as installed, noting JavaFX on `-fx` builds. For + GraalVM it must also list the feature releases GraalVM ships every month + since 25.1 (`25.4.4.1.1-graalce`), none of them noted LTS, though Foojay + marks some of them LTS, as the JDK they build on is; each lasts about a + month. Every other release of a major must carry the same note. The + plugin used to list the feature release 25.4.4.1.1 as `25.0.4.1-graalce`, + without the LTS note `25.0.2-graalce` has. + On Windows the list includes JetBrains Runtime 21.0.5, which ships only as + tar.gz there. + + The install itself must also have verified the download. Foojay lists a + checksum for the pinned release of every default distribution on every + runner (2026-11-02), and `vfox install` must print `Verifying checksum + ...` with a digest of a length vfox supports, not `WARNING: + Checksum is not provided, skip verify...`, which every install ended with + until the plugin passed Foojay's checksums on. The digests come in four + forms, so each way the plugin reads them runs: SHA-256 and SHA-1 in + Foojay's record (Temurin, Liberica), SHA-256 in a file that holds the + digest alone (OpenJDK, GraalVM Community) and SHA-512 in a file that adds + the name (JetBrains). vfox compares the digest with the hash of the file it + downloaded and fails the install if they differ, so the install succeeding + proves the digest is the file's. A release chosen with `JAVA_VERSION` is + not checked, as Foojay may list no checksum for it. +6. Before any `vfox use`, a `.sdkmanrc` holding the SDKMAN identifier + without the build number selects the JDK through `ParseLegacyFile`: + `java=21.0.8-tem`, `java=21.0.5-jbr` (SDKMAN's name for JetBrains) or + `java=25.0.4.fx-librca` (its spelling of JavaFX builds). So does one + padding the release with a zero, as `sdk list java` shows many: + `java=21.0.8.0+9-tem`, `java=25.0.4.0-fx+9-librca` (Foojay, and so the + installed name, has no such zero). So does one holding the installed + version (`java=21.0.8+9-tem`). All run next to an empty install of + another release whose version starts with the pinned one + (`21.0.80+1-tem`): vfox sorts installed versions as strings, descending, + so `vfox list java` must show it first. `ParseLegacyFile` used to take it + as the first one starting with the release, and, for the padded release, + as the newest release of the major. Then SDKMAN's identifier of an + early-access build of the pinned major, spelled as `sdk list java` shows + OpenJDK's (`28.0.0.0+ea.20-open`), must select that build: + `java=21.0.0.0+ea.1-tem` selects `21-ea+1-tem`, not the release, which + `ParseLegacyFile` took while it understood only SDKMAN's older + `21.ea.1-tem`. So must the installed name itself (`java=21-ea+1-tem`), + for which `ParseLegacyFile`, unable to parse it, selected nothing, while + `vfox use` selects it. jdk.java.net removes each early-access build within + weeks, so that install is faked: its `bin` holds a stand-in `java` that + only prints the name. On Windows the file is written with CRLF line + endings. + + On the Temurin rows, a `.sdkmanrc` holding one of SDKMAN's identifiers of + Mandrel and Liberica NIK with the JDK after `.r` must then select the + release it names: `java=25.0.4.r25-nik` selects `25.0.4-nik`, not + `25.0.4.1-nik`, which `ParseLegacyFile` took while it read `25.0.4.r25` as + the release. `java=22.1.r11-mandrel` must select nothing, as the plugin + installs only the JDK 17 build of Mandrel 22.1 (`OwnNumberIdentifiers` in + `tests/e2e/common`). The releases they name and a newer one of each major + are faked the same way. +7. After `vfox use --global`, the JDK on `PATH` reports the requested + `java.version`, the runner's `os.arch` (`amd64` / `aarch64`, which also + catches an x64 JDK emulated on Windows ARM64) and the distribution's + `java.vendor`. `JAVA_HOME` holds that same JDK, `javac` compiles a + program that `java` then runs, the module list carries JavaFX exactly for + `-fx` builds, and `vfox current java` reports the installed version. A + `GRAALVM_HOME` set beforehand keeps its value, as users point it at a + GraalVM of their own; for GraalVM, the plugin used to replace it with + the JDK in use. +8. `PreUse` maps the spellings users type to the installed version without + another download: the bare major (`java@21`, left to vfox core's fuzzy + matching), the spec the JDK was installed with (`java@21.0.8-tem`, whose + build number `PreUse` finds among the installed versions) and the + asdf-style `-[-fx]` (`java@temurin-21.0.8+9`, + rewritten to `21.0.8+9-tem`; `java@openjdk-25.0.2+10` to `25.0.2+10`). + So does the release padded with a zero, as SDKMAN writes releases + (`java@21.0.8.0-tem`, `java@21.0.8.0+9-tem`), which `vfox install` must + first find already installed: `PreInstall` passes the zero on to Foojay, + which leaves it out, while `PreUse` looked for an installed version + starting with the padded release and reported it not installed. + +The default matrix runs every distribution against both vfox channels +(`latest`, `main`): + +| Distribution | Release | Covers | amd64 | arm64 | +| ------------ | ------- | --------------------------------------------------------------------------------------------------------- | ----- | ----- | +| `open` | 25.0.2 | the default distribution, versions without a suffix | ✓ | | +| `tem` | 21.0.8 | the common path (tar.gz on Linux, zip on Windows); the mirror, name and number checks of items 2, 4 and 6 | ✓ | ✓ | +| `librca-fx` | 25.0.4 | JavaFX bundled builds (`-fx`) | ✓ | ✓ | +| `jb` | 21.0.5 | the tar.gz path on Windows, which has no zip for it | ✓ | ✓ | +| `graalce` | 25.0.2 | a `GRAALVM_HOME` set beforehand keeps its value; Oracle GraalVM's `25-graal` | ✓ | | + +Every pinned release is published through Foojay for each platform its row +runs on. OpenJDK and GraalVM Community ship no `windows-aarch64` build, so +arm64 runs the other three on both Linux and Windows. diff --git a/docs/foojay.md b/docs/foojay.md index 52bf8a9..82c1683 100644 --- a/docs/foojay.md +++ b/docs/foojay.md @@ -6,91 +6,7 @@ You can ask it yourself in the browser. The [Swagger UI](https://api.foojay.io/swagger-ui) of the API has the endpoints, and its spec is [foojay-discoapi-3.0.yml](https://api.foojay.io/swagger/foojay-discoapi-3.0.yml). Open `GET /disco/v3.0/packages/jdks`, press "Try it out", fill in the parameters and press "Execute". The page shows the `curl` command it ran and the JSON that came back. -## What the plugin asks - -`vfox install java@21.0.8-tem` on Linux x64 sends: - -``` -https://api.foojay.io/disco/v3.0/packages/jdks - ?version=21.0.8 - &distribution=temurin - &architecture=amd64 - &archive_type=tar.gz - &operating_system=linux - &lib_c_type=glibc - &directly_downloadable=true -``` - -| Parameter | Value | -| --- | --- | -| `distribution` | the long name, see [distributions.md](distributions.md) | -| `version` | empty for `vfox search` and for a bare major such as `21`, else the version part of what you typed. A `+` is percent-encoded, because Foojay reads a bare one as a space and drops the build. `28.ea.19` becomes `28-ea+19`. Always empty for Mandrel and Liberica NIK, and for the GA releases of Oracle GraalVM and GraalVM Community | -| `architecture` | `aarch64` for arm64, `x64` on Windows x64, `amd64` for x64 elsewhere, and the name vfox reports for other CPUs | -| `operating_system` | `linux`, `macos` or `windows` | -| `archive_type` | `tar.gz`, and `zip` plus `tar.gz` on Windows. Elsewhere `tar.xz` comes in for Red Hat, and `zip` for OJDKBuild, OpenLogic and Gluon GraalVM | -| `lib_c_type` | `glibc` or `musl` on Linux, empty elsewhere | -| `directly_downloadable` | always `true` | - -For a bare major such as `21` the answer lists every release, and the plugin takes the newest 21.x itself, which is what `java@21-tem` installs: `version=21` would match the 21 GA build only (`21+35`). Longer versions match as they are. - -A bare major asks what searching asks so that installing sees the builds `vfox search` lists. Foojay's answers are cached per question, and two questions can get answers of different ages: half an hour after Oracle GraalVM 25.0.5 reached Foojay on 2026-10-20, GitHub's runners got it from a lookup with `distribution_version=25` but not from a search, and `vfox install java@25-graal` took a build that `vfox search java graal` did not list ([#113](https://github.com/version-fox/vfox-java/issues/113)). - -The answer is a list of packages. The plugin names a release after `java_version` (Mandrel and Liberica NIK after `distribution_version`, Oracle GraalVM and GraalVM Community after GraalVM's own version), adds `-fx` where `javafx_bundled` is true, marks it LTS where `term_of_support` is `lts`, and prefers a `zip` over a `tar.gz` of the same version on Windows. It leaves out the JREs, installer bundles and RHEL 6 builds that Foojay lists among OJDKBuild's Windows JDKs, and the JDK 11 builds of Gluon GraalVM's 22.x releases, see [distributions.md](distributions.md). For the install it then fetches the package's `links.pkg_info_uri` and downloads its `direct_download_uri`, which is a vendor's own server (GitHub Releases for Temurin). The same record says how to check the download, see [Checksums](#checksums). A download from GitHub can go through a mirror, see [mirror.md](mirror.md). - -`vfox search` differs from the raw list in a few ways. It lists a name once where Foojay has two records for it, and it leaves the LTS note off GraalVM's feature releases (see [distributions.md](distributions.md#behavior-of-oracle-graalvm-and-graalvm-community)). It only lists GA releases. - -### Mandrel and Liberica NIK - -Foojay gives the GraalVM version these two carry as `distribution_version`, and the Java version as `java_version`, for Mandrel the major only (2026-10-20): - -```bash -curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=mandrel&distribution_version=23.1.12&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ - | jq -r '.result[] | [.java_version, .distribution_version, .filename] | @tsv' -``` - -``` -21 23.1.12.1 mandrel-java21-linux-amd64-23.1.12.1-Final.tar.gz -21 23.1.12 mandrel-java21-linux-amd64-23.1.12.0-Final.tar.gz -``` - -So the plugin asks for every package of these two, as `vfox search` does, and picks the release by `distribution_version` itself: the one named, or for a bare major the newest of the major. Foojay's own matching does neither: `distribution_version=23.1.12` lists 23.1.12.1 as well, as above, and with `distribution_version=23`, `latest=available` answered with 23.1.8 and two builds of 23.0.1.2, although 23.1.12.1 was out. Where a release comes for several Java versions the plugin takes the build for the newest, and of two Liberica NIK builds for the same Java the later one, which only the file name tells apart (`...-25.0.3+2-linux-amd64.tar.gz`). Searching sorts them by `distribution_version`, newest first. - -## Checksums - -The record that `links.pkg_info_uri` points to also says how to check the download. `checksum_type` is the algorithm, and the digest is in the record as `checksum`, or in a file of the vendor that `checksum_uri` points to. GraalVM Community 25.0.2 has the file only (2026-11-02): - -```bash -curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=graalvm_community&version=25.0.2&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ - | jq -r '.result[0].links.pkg_info_uri' | xargs curl -s | jq -c '.result[0] | {checksum_type, checksum, checksum_uri}' -``` - -``` -{"checksum_type":"sha256","checksum":"","checksum_uri":"https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-25.0.2/graalvm-community-jdk-25.0.2_linux-x64_bin.tar.gz.sha256"} -``` - -Temurin's record holds the digest itself (`f2dc5418...9219` for 21.0.8 on Linux x64), next to the address of the vendor's file. - -The plugin hands vfox the digest under the name of its algorithm (`sha256 = "..."` in what `PreInstall` returns). vfox hashes the file it downloaded and compares the two before it unpacks anything. It prints `Verifying checksum e0be791c...` and goes on, or stops with `Checksum error`, see [troubleshooting.md](troubleshooting.md#checksum-error). vfox verifies `sha256`, `sha512`, `sha1` and `md5`, and the packages use all four. Foojay names others too (`sha3_256`), which vfox cannot verify. - -The digest in Foojay's record goes first. It comes from Foojay and not from the vendor's download site, which may be a mirror, and it costs no request. The plugin fetches the file only where the record has no digest, from GitHub through the mirror ([mirror.md](mirror.md)) like the download. These files do not all write a digest the same way, and the plugin reads three forms: - -- the digest alone (GraalVM Community, OpenJDK, Oracle), -- `sha256sum`'s ` `, with a `*` before the name for a binary file (Microsoft, JetBrains, Semeru, SAP Machine), -- BSD's `MD5 () = ` (Tencent Kona). - -A file that lists several packages gives the line of the one being installed. One that lists others only gives none: Microsoft's file for its EA build of 11.0.14 for macOS names the GA build, and that digest would fail an install that is fine. - -Which packages come with a checksum varies by release, and Foojay holds none for some distributions. For the newest releases (2026-11-02): - -| Foojay lists | Short names | -| --- | --- | -| the digest in the record | `tem`, `zulu`, `librca`, `nik`, `eliya`, `rdht`, `mandrel` from 25, the newest `graal` and `graalce` | -| a file of the vendor | `open`, `oracle`, `ms`, `sapmchn`, `sem`, `semcrt`, `jb`, `kona`, `ojdkbld`, `grl8`, `grl11`, `grl16`, `grl17`, `grl19`, the older `graal` and `graalce`, and Corretto 8 (`amzn`) | -| no checksum | `albba`, `bsg`, `trava`, `adpt`, `adptj9`, `gln`, `opnlgc`, `amzn` other than Corretto 8, and the older releases of several of the others | - -For a package with none, vfox prints `WARNING: Checksum is not provided, skip verify...` and trusts the download. - -Where Foojay lists a checksum that the plugin cannot use, the install goes on without it, as it did before the plugin read checksums, and the plugin says why: `Cannot verify the download: https://example.org/x.tar.gz.sha256 has no digest for x.tar.gz`. The file may not answer, it may hold no digest for the package, or the algorithm may be one vfox does not verify. A checksum that cannot be had stops nothing. A download that does not match one does. Foojay gives the link and the checksum alike, so the check catches a damaged or substituted file, not a wrong record. +The examples below use `curl` and `jq`, which you may have to install. Any JSON tool will do. Some HTTP clients get `403` from Foojay with their default User-Agent. Python's `urllib` does. `curl` does not, and neither does vfox. What the plugin itself asks is under [What the plugin asks](#what-the-plugin-asks), and how it verifies a download under [Checksums](#checksums). ## Which distributions have a build for my platform @@ -120,7 +36,7 @@ For another platform change the three parameters that name it. Linux needs `lib_ | macOS Intel | `architecture=amd64&operating_system=macos&archive_type=tar.gz` | | Windows x64 | `architecture=x64&operating_system=windows&archive_type=zip&archive_type=tar.gz` | -The names in the answer are the long names in [distributions.md](distributions.md), except `oracle_open_jdk`, which the plugin calls `openjdk` (`open`). With `archive_type=tar.gz` alone the answer misses Red Hat and OJDKBuild on Linux, and OpenLogic on macOS, which ship tar.xz or zip there. The plugin asks for those types for them, see the table above. +The names in the answer are the long names in [distributions.md](distributions.md), except `oracle_open_jdk`, which the plugin calls `openjdk` (`open`). With `archive_type=tar.gz` alone the answer misses Red Hat and OJDKBuild on Linux, and OpenLogic on macOS, which ship tar.xz or zip there. The plugin asks for those types for them, see [What the plugin asks](#what-the-plugin-asks). ## Which distributions have a release for my platform @@ -130,7 +46,7 @@ curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?version=27&latest=availa | jq -r '.result[].distribution' | sort -u ``` -On 2026-10-18 this printed `corretto liberica oracle semeru zulu`. Temurin and OpenJDK were not among them: they stopped at 26 there. Use `latest=available` for a bare major, as the plugin does, and leave it out for a longer version. +On 2026-11-03 this printed `corretto liberica oracle semeru zulu`. Temurin and OpenJDK were not among them: they stopped at 26 there. Use `latest=available` for a bare major, as the plugin does, and leave it out for a longer version. ## The versions of one distribution @@ -159,7 +75,7 @@ curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&ver {"java_version":"21.0.8+9","distribution_version":"21.0.8","term_of_support":"lts","javafx_bundled":false,"archive_type":"tar.gz","filename":"OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz"} ``` -`java_version` is Java's version and the one the plugin uses. `distribution_version` is the vendor's own (Zulu's `27.28.101` for Java `27+35`), which the plugin uses for Mandrel and Liberica NIK, see [above](#mandrel-and-liberica-nik), and for Oracle GraalVM and GraalVM Community. +`java_version` is Java's version and the one the plugin uses. `distribution_version` is the vendor's own (Zulu's `27.28.101` for Java `27+35`), which the plugin uses for Mandrel and Liberica NIK, see [below](#mandrel-and-liberica-nik), and for Oracle GraalVM and GraalVM Community. For Oracle GraalVM and GraalVM Community, since October 2026, `distribution_version` is GraalVM's own version and `java_version` the JDK's, which a monthly feature release shares with a build of the 25.0 line: @@ -186,9 +102,93 @@ curl -s 'https://api.foojay.io/disco/v3.0/major_versions?ea=false&ga=true&mainta lists the feature releases that are still maintained and whether each is LTS or STS. Early-access builds need `release_status=ea` or an explicit version such as `version=28-ea`. +## What the plugin asks + +`vfox install java@21.0.8-tem` on Linux x64 sends: + +``` +https://api.foojay.io/disco/v3.0/packages/jdks + ?version=21.0.8 + &distribution=temurin + &architecture=amd64 + &archive_type=tar.gz + &operating_system=linux + &lib_c_type=glibc + &directly_downloadable=true +``` + +| Parameter | Value | +| --- | --- | +| `distribution` | the long name, see [distributions.md](distributions.md) | +| `version` | empty for `vfox search` and for a bare major such as `21`, else the version part of what you typed. A `+` is percent-encoded, because Foojay reads a bare one as a space and drops the build. `28.ea.19` becomes `28-ea+19`. Always empty for Mandrel and Liberica NIK, and for the GA releases of Oracle GraalVM and GraalVM Community | +| `architecture` | `aarch64` for arm64, `x64` on Windows x64, `amd64` for x64 elsewhere, and the name vfox reports for other CPUs | +| `operating_system` | `linux`, `macos` or `windows` | +| `archive_type` | `tar.gz`, and `zip` plus `tar.gz` on Windows. Elsewhere `tar.xz` comes in for Red Hat, and `zip` for OJDKBuild, OpenLogic and Gluon GraalVM | +| `lib_c_type` | `glibc` or `musl` on Linux, empty elsewhere | +| `directly_downloadable` | always `true` | + +For a bare major such as `21` the answer lists every release, and the plugin takes the newest 21.x itself, which is what `java@21-tem` installs: `version=21` would match the 21 GA build only (`21+35`). Longer versions match as they are. + +A bare major asks what searching asks so that installing sees the builds `vfox search` lists. Foojay's answers are cached per question, and two questions can get answers of different ages: half an hour after Oracle GraalVM 25.0.5 reached Foojay on 2026-10-20, GitHub's runners got it from a lookup with `distribution_version=25` but not from a search, and `vfox install java@25-graal` took a build that `vfox search java graal` did not list ([#113](https://github.com/version-fox/vfox-java/issues/113)). + +The answer is a list of packages. The plugin names a release after `java_version` (Mandrel and Liberica NIK after `distribution_version`, Oracle GraalVM and GraalVM Community after GraalVM's own version), adds `-fx` where `javafx_bundled` is true, marks it LTS where `term_of_support` is `lts`, and prefers a `zip` over a `tar.gz` of the same version on Windows. It leaves out the JREs, installer bundles and RHEL 6 builds that Foojay lists among OJDKBuild's Windows JDKs, and the JDK 11 builds of Gluon GraalVM's 22.x releases, see [distributions.md](distributions.md). For the install it then fetches the package's `links.pkg_info_uri` and downloads its `direct_download_uri`, which is a vendor's own server (GitHub Releases for Temurin). The same record says how to check the download, see [Checksums](#checksums). A download from GitHub can go through a mirror, see [mirror.md](mirror.md). + +`vfox search` differs from the raw list in a few ways. It lists a name once where Foojay has two records for it, and it leaves the LTS note off GraalVM's feature releases (see [distributions.md](distributions.md#behavior-of-oracle-graalvm-and-graalvm-community)). It only lists GA releases. + +### Mandrel and Liberica NIK + +Foojay gives the GraalVM version these two carry as `distribution_version`, and the Java version as `java_version`, for Mandrel the major only (2026-10-20): + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=mandrel&distribution_version=23.1.12&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[] | [.java_version, .distribution_version, .filename] | @tsv' +``` + +``` +21 23.1.12.1 mandrel-java21-linux-amd64-23.1.12.1-Final.tar.gz +21 23.1.12 mandrel-java21-linux-amd64-23.1.12.0-Final.tar.gz +``` + +So the plugin asks for every package of these two, as `vfox search` does, and picks the release by `distribution_version` itself: the one named, or for a bare major the newest of the major. Foojay's own matching does neither: `distribution_version=23.1.12` lists 23.1.12.1 as well, as above, and with `distribution_version=23`, `latest=available` answered with 23.1.8 and two builds of 23.0.1.2, although 23.1.12.1 was out. Where a release comes for several Java versions the plugin takes the build for the newest, and of two Liberica NIK builds for the same Java the later one, which only the file name tells apart (`...-25.0.3+2-linux-amd64.tar.gz`). Searching sorts them by `distribution_version`, newest first. + +## Checksums + +The record that `links.pkg_info_uri` points to also says how to check the download. `checksum_type` is the algorithm, and the digest is in the record as `checksum`, or in a file of the vendor that `checksum_uri` points to. GraalVM Community 25.0.2 has the file only (2026-11-02): + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=graalvm_community&version=25.0.2&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[0].links.pkg_info_uri' | xargs curl -s | jq -c '.result[0] | {checksum_type, checksum, checksum_uri}' +``` + +``` +{"checksum_type":"sha256","checksum":"","checksum_uri":"https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-25.0.2/graalvm-community-jdk-25.0.2_linux-x64_bin.tar.gz.sha256"} +``` + +Temurin's record holds the digest itself (`f2dc5418...9219` for 21.0.8 on Linux x64), next to the address of the vendor's file. + +The plugin hands vfox the digest under the name of its algorithm (`sha256 = "..."` in what `PreInstall` returns). vfox hashes the file it downloaded and compares the two before it unpacks anything. It prints `Verifying checksum e0be791c...` and goes on, or stops with `Checksum error`, see [troubleshooting.md](troubleshooting.md#checksum-error). vfox verifies `sha256`, `sha512`, `sha1` and `md5`, and the packages use all four. Foojay names others too (`sha3_256`), which vfox cannot verify. + +The digest in Foojay's record goes first. It comes from Foojay and not from the vendor's download site, which may be a mirror, and it costs no request. The plugin fetches the file only where the record has no digest, from GitHub through the mirror ([mirror.md](mirror.md)) like the download. These files do not all write a digest the same way, and the plugin reads three forms: + +- the digest alone (GraalVM Community, OpenJDK, Oracle), +- `sha256sum`'s ` `, with a `*` before the name for a binary file (Microsoft, JetBrains, Semeru, SAP Machine), +- BSD's `MD5 () = ` (Tencent Kona). + +A file that lists several packages gives the line of the one being installed. One that lists others only gives none: Microsoft's file for its EA build of 11.0.14 for macOS names the GA build, and that digest would fail an install that is fine. + +Which packages come with a checksum varies by release, and Foojay holds none for some distributions. For the newest releases (2026-11-02): + +| Foojay lists | Short names | +| --- | --- | +| the digest in the record | `tem`, `zulu`, `librca`, `nik`, `eliya`, `rdht`, `mandrel` from 25, the newest `graal` and `graalce` | +| a file of the vendor | `open`, `oracle`, `ms`, `sapmchn`, `sem`, `semcrt`, `jb`, `kona`, `ojdkbld`, `grl8`, `grl11`, `grl16`, `grl17`, `grl19`, the older `graal` and `graalce`, and Corretto 8 (`amzn`) | +| no checksum | `albba`, `bsg`, `trava`, `adpt`, `adptj9`, `gln`, `opnlgc`, `amzn` other than Corretto 8, and the older releases of several of the others | + +For a package with none, vfox prints `WARNING: Checksum is not provided, skip verify...` and trusts the download. + +Where Foojay lists a checksum that the plugin cannot use, the install goes on without it, as it did before the plugin read checksums, and the plugin says why: `Cannot verify the download: https://example.org/x.tar.gz.sha256 has no digest for x.tar.gz`. The file may not answer, it may hold no digest for the package, or the algorithm may be one vfox does not verify. A checksum that cannot be had stops nothing. A download that does not match one does. Foojay gives the link and the checksum alike, so the check catches a damaged or substituted file, not a wrong record. + ## Notes -- Some HTTP clients get `403` from Foojay with their default User-Agent. Python's `urllib` does. `curl` does not, and neither does vfox. -- The examples use `jq`, which you may have to install. Any JSON tool will do. - vfox keeps the result of `vfox search` for 12 hours, so a change in Foojay may take that long to show up. - Data problems, such as a missing or wrongly marked build, belong to Foojay: [foojayio/discoapi](https://github.com/foojayio/discoapi). Problems with how this plugin reads the data belong in this repository. diff --git a/docs/install-from-source.md b/docs/install-from-source.md index a60fe69..7623e92 100644 --- a/docs/install-from-source.md +++ b/docs/install-from-source.md @@ -40,7 +40,7 @@ vfox use --global java@21-tem java -version ``` -`vfox install java@21-tem` installs the newest Temurin 21, `21.0.12.1+1-tem` on 2026-10-18. +`vfox install java@21-tem` installs the newest Temurin 21, `21.0.13+9-tem` on 2026-11-03. ## When java is already added diff --git a/docs/javafx.md b/docs/javafx.md index 067b853..45d5ebb 100644 --- a/docs/javafx.md +++ b/docs/javafx.md @@ -33,7 +33,7 @@ A build with JavaFX lists `javafx.base` and the others, one without lists none. ## Where JavaFX builds exist -As of 2026-10-20 four distributions have them, and not for every platform. The table lists the LTS releases that have a JavaFX build. The releases in between have some too, with gaps. For Liberica NIK it gives the Java version, not the GraalVM version in its names (see [distributions.md](distributions.md#behavior-of-mandrel-and-liberica-nik)): its JavaFX builds for Java 21 are `23.1.x-nik-fx`. +As of 2026-11-03 four distributions have them, and not for every platform. The table lists the LTS releases that have a JavaFX build. The releases in between have some too, with gaps. For Liberica NIK it gives the Java version, not the GraalVM version in its names (see [distributions.md](distributions.md#behavior-of-mandrel-and-liberica-nik)): its JavaFX builds for Java 21 are `23.1.x-nik-fx`. | Distribution | Linux x64 | Linux arm64 | Alpine x64 | macOS Intel | macOS Apple silicon | Windows x64 | Windows arm64 | | --- | --- | --- | --- | --- | --- | --- | --- | diff --git a/docs/mirror.md b/docs/mirror.md index cdca040..97355d8 100644 --- a/docs/mirror.md +++ b/docs/mirror.md @@ -39,7 +39,7 @@ Then install as usual, `vfox install java@21-tem`. To go back to github.com, uns Only requests for `https://github.com/`: the downloads, and the checksum files on GitHub that the plugin reads for them (see [Notes](#notes)). A JDK on any other host downloads from there as before, and the requests to Foojay do not change. -Where Foojay links each distribution (2026-10-21): +Where Foojay links each distribution (2026-11-03): | Short names | Download from | | --- | --- | diff --git a/docs/native-image.md b/docs/native-image.md new file mode 100644 index 0000000..febebc1 --- /dev/null +++ b/docs/native-image.md @@ -0,0 +1,34 @@ +# Native Image and the C toolchain + +[中文](zh-CN/native-image.md) | [English](native-image.md) + +A GraalVM installs and runs like any other JDK. After `vfox install java@25.0.2-graalce` and `vfox use`, `java` and `javac` work on a system with no compiler and no zlib headers. Only `native-image` needs more. It is the tool that compiles a program into a native executable, and it links the executable with the system's `gcc` against the C library and zlib. So it needs them, and so does whatever calls it, such as the Maven and Gradle plugins for Native Image. The plugin installs the JDK and nothing else, and a minimal Ubuntu, such as its container image, has neither a compiler nor zlib's headers. + +`native-image` is in the `bin` directory of Oracle GraalVM, GraalVM Community, Liberica NIK, Mandrel and Gluon GraalVM. GraalVM CE 8 to 19 are the exception, see [below](#graalvm-ce-8-to-19). + +## Ubuntu + +On Ubuntu 26.04, execute in Bash once, before the first native build, + +```bash +sudo apt install --assume-yes build-essential zlib1g-dev +``` + +Without them: + +- Without `gcc` the build stops within seconds with `Error: Default native-compiler executable 'gcc' not found via environment variable PATH`, and `zlib1g-dev` alone does not change that. +- With `gcc` but without `zlib1g-dev`, which is what `build-essential` alone gives, the build goes through the analysis and the compilation first, which took between 20 seconds and two minutes for a hello world, and fails when it links: `There was an error linking the native image: Linker command exited with 1`, GraalVM's hint `It appears as though libz:.a is missing. Please install it.`, and `cannot find -lz: No such file or directory`. + +`gcc`, `libc6-dev` and `zlib1g-dev` were enough to build a hello world, without `g++` and `make`. `build-essential` brings both, and is what GraalVM's documentation lists. + +## Other systems + +Other systems need other packages. GraalVM's [prerequisites](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites) list `sudo dnf install gcc glibc-devel zlib-devel libstdc++-static` for Fedora and the other systems that use dnf, `xcode-select --install` for macOS, and the Visual Studio Build Tools with the Windows SDK for Windows. On Fedora 44, `gcc`, `glibc-devel` and `zlib-devel` built a hello world without `libstdc++-static`. + +## GraalVM CE 8 to 19 + +GraalVM CE 8 to 19 (`grl8`, `grl11`, `grl16`, `grl17`, `grl19`) come without `native-image`. Their `bin` directory holds `gu`, the GraalVM Updater, and `native-image` is `command not found` until `gu install native-image` has added it from GitHub. That worked for `22.3.3-grl11`, `21.2-grl16`, `22.3.3-grl17` and `22.3.1-grl19` on 2026-11-02, and the packages above are needed after it as before. It failed for `21.3.1-grl8` with `Internal error occurred: A JSONObject text must begin with '{'`, because the release index that this `gu` downloads, `https://oca.opensource.oracle.com/gds/meta-data.json`, is a web page now. For that release, download `native-image-installable-svm-java8-linux-amd64-21.3.1.jar` from the [`vm-21.3.1` release](https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.1) and run `gu -L install` on the file. + +## What was checked + +Checked on 2026-11-02 with vfox 1.0.13 in Ubuntu 26.04 container images (x64) that had no compiler. GraalVM Community 25.0.2 and 25.4.4.1.1, Oracle GraalVM 25.0.5, Mandrel 25.0.5, Liberica NIK 25.0.4.1 and Gluon GraalVM 22.1.0.1 stopped as described without the packages, and with them built a hello world that ran. So did `22.3.3-grl17` after `gu install native-image`, and GraalVM Community 25.0.2 in a Fedora 44 image. diff --git a/docs/platforms.md b/docs/platforms.md index 302b6f5..281b33c 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -8,7 +8,7 @@ The plugin asks Foojay for packages of the platform it runs on: the operating sy No JDK found for 21-bsg on darwin/arm64. Please check available versions with 'vfox search java' ``` -The table shows which platforms each distribution has packages for. It was taken from Foojay on 2026-10-18, and the rows from AdoptOpenJDK on were added on 2026-10-20. ✅ means Foojay lists at least one package the plugin can install there, ❌ means none. +The table shows which platforms each distribution has packages for, as Foojay lists them on 2026-11-03. ✅ means Foojay lists at least one package the plugin can install there, ❌ means none. | Distribution | Linux x64 | Linux arm64 | Alpine x64 | Alpine arm64 | macOS Intel | macOS Apple silicon | Windows x64 | Windows arm64 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | @@ -50,21 +50,15 @@ Foojay changes, and the table with it. To get the current one, ask Foojay the wa ## Only some releases -A ✅ does not mean every release is there. As of the same date: +A ✅ does not mean every release is there. As of 2026-11-03: -- Windows on ARM64 has no Java 8 from anyone. Temurin has 21 and 23 there, Zulu 16 to 19, 21 and 25, Liberica 11 and 16 to 27, Microsoft 11, 16, 17, 21 and 25, and JetBrains Runtime 17, 21 and 25. -- On Apple silicon Java 8 comes from Zulu, Liberica, Corretto and Kona. Temurin and Semeru have 11 and 17 to 27 there, and OpenJDK 17 to 27. Mandrel has releases 23.1 to 25, for Java 21 to 25, and Liberica NIK 22.2 to 25, for Java 11, 17 and 20 to 25 (see [their numbers](distributions.md#behavior-of-mandrel-and-liberica-nik)). +- Windows on ARM64 has no Java 8 from anyone. Temurin has 21 and 23 there, Zulu 16 to 19, 21, 25 and 27, Liberica 11 and 16 to 27, Microsoft 11, 16, 17, 21 and 25, and JetBrains Runtime 17, 21 and 25. +- On Apple silicon Java 8 comes from Zulu, Liberica, Corretto and Kona. Temurin and Semeru have 11 and 17 to 27 there, and OpenJDK 17 to 27. Mandrel has releases 23.1 to 25, for Java 21 to 25, and Liberica NIK 22.2 to 25, for Java 11, 17 and 20 to 25 (see [their numbers](distributions.md#behavior-of-mandrel-and-liberica-nik)). Gluon GraalVM has 22.1.0.1 and 23+25, GraalVM CE 11 and 17 have GraalVM 22.1 to 22.3.1, and GraalVM CE 19 has 22.3 and 22.3.1. - Intel Macs get new releases later or not at all. OpenJDK and Temurin stop at 26 where Linux has 27, SapMachine stops at 24, and Oracle GraalVM and GraalVM Community stop at 25.0.1. Mandrel has no Intel Mac build. -- On Alpine, Temurin has arm64 builds from 21 only. For x64, Microsoft has 11 and 17, SapMachine 17 and 20 to 27, Kona 8 and 21, Dragonwell 11, 17, 21 and 25, and JetBrains Runtime 17. Kona has Java 8 for arm64, and JetBrains Runtime 17 for both. -- Trava has a single build for Linux arm64, 11.0.10+6. -- JavaFX builds exist for fewer platforms than plain ones, see [javafx.md](javafx.md#where-javafx-builds-exist). - -For the rows added on 2026-10-20, as of that date: - -- AdoptOpenJDK's Alpine x64 builds are Java 16 with HotSpot, and its OpenJ9 builds for Linux arm64 are 8, 11, 15 and 16. -- OJDKBuild has Java 8 and 11 for Linux. +- On Alpine, Temurin has arm64 builds from 21 only. For x64, Microsoft has 11 and 17, SapMachine 17 and 20 to 27, Kona 8 and 21, Dragonwell 11, 17, 21 and 25, and JetBrains Runtime 17. Kona has Java 8 for arm64, and JetBrains Runtime 17 for both. AdoptOpenJDK's Alpine x64 builds are Java 16 with HotSpot. +- Trava has a single build for Linux arm64, 11.0.10+6. AdoptOpenJDK's OpenJ9 builds for Linux arm64 are 8, 11, 15 and 16, and OJDKBuild has Java 8 and 11 for Linux. - Red Hat's builds download for Linux x64 only, its one ✅ in the table. Foojay also lists a few for Linux arm64 and one for Windows, which `vfox search` shows, but their downloads answer 404. -- On Apple silicon Gluon GraalVM has 22.1.0.1 and 23+25, GraalVM CE 11 and 17 have GraalVM 22.1 to 22.3.1, and GraalVM CE 19 has 22.3 and 22.3.1. +- JavaFX builds exist for fewer platforms than plain ones, see [javafx.md](javafx.md#where-javafx-builds-exist). ## Which are x64 only @@ -86,7 +80,7 @@ vfox ships binaries for 32-bit x86 and 32-bit ARM as well as x64, arm64 and loon - 32-bit x86 Linux: Corretto, Liberica, Zulu and JetBrains Runtime, and OpenLogic's Java 8. - loong64 is unknown to Foojay, and Linux loong64 uses Loongnix instead, see [loongnix.md](loongnix.md). -If you build vfox for riscv64, ppc64le or s390x, Foojay lists riscv64 packages for Dragonwell, Liberica and Temurin, ppc64le for Liberica, SapMachine, Semeru and Temurin, and s390x for Semeru and Temurin. Of the distributions added on 2026-10-20, AdoptOpenJDK, with HotSpot and with OpenJ9, and Semeru certified have ppc64le and s390x packages. Red Hat's ppc64le records answer 404. +If you build vfox for riscv64, ppc64le or s390x, Foojay lists riscv64 packages for Dragonwell, Liberica and Temurin, ppc64le for AdoptOpenJDK (with HotSpot and with OpenJ9), Liberica, SapMachine, Semeru, Semeru certified and Temurin, and s390x for AdoptOpenJDK (both), Semeru, Semeru certified and Temurin. Red Hat has ppc64le records too, but their downloads answer 404. ## macOS Java home diff --git a/docs/sdkman.md b/docs/sdkman.md index 2f7810c..ba0ee7f 100644 --- a/docs/sdkman.md +++ b/docs/sdkman.md @@ -39,8 +39,8 @@ The scopes of `vfox use` correspond to SDKMAN's: `--session`, the default, to `s ## What differs - **Identifiers.** SDKMAN's `21.0.8-tem` goes after `java@` as it is, and the short names are SDKMAN's, with a few exceptions such as `jb`, which SDKMAN calls `jbr`, see [distributions.md](distributions.md#short-names-and-sdkman). A release padded with a zero, as in SDKMAN's current identifiers (`25.0.5.0+8-tem`), is accepted. JavaFX is `-fx` at the end, `21.0.12-zulu-fx`. SDKMAN's `21.0.12.fx-zulu` is not a spec that `vfox install` takes, though a `.sdkmanrc` can hold it, see [sdkmanrc.md](sdkmanrc.md#sdkmans-spellings). -- **A bare major.** `vfox install java@21-tem` installs the newest Temurin 21, `21.0.13+9-tem` on 2026-11-02. SDKMAN's `21-tem` is one release, the GA build `21+35`. -- **No default JDK.** `sdk install java` installs SDKMAN's default, a Temurin LTS release (`25.0.5.0+8-tem` on 2026-11-02). `vfox install java` has none: in a terminal it asks you to pick a version, in a script it fails. A version without a distribution (`java@21`) is OpenJDK from jdk.java.net, which has nothing newer than 21.0.2 for 21. Write `java@21-tem`, see [versions.md](versions.md#without-a-distribution). +- **A bare major.** `vfox install java@21-tem` installs the newest Temurin 21, `21.0.13+9-tem` on 2026-11-03. SDKMAN's `21-tem` is one release, the GA build `21+35`. +- **No default JDK.** `sdk install java` installs SDKMAN's default, a Temurin LTS release (`25.0.5.0+8-tem` on 2026-11-03). `vfox install java` has none: in a terminal it asks you to pick a version, in a script it fails. A version without a distribution (`java@21`) is OpenJDK from jdk.java.net, which has nothing newer than 21.0.2 for 21. Write `java@21-tem`, see [versions.md](versions.md#without-a-distribution). - **Installing does not select.** After `sdk install`, SDKMAN asks whether the JDK becomes the default. `vfox install` only installs, and `vfox use` selects. - **Two lists.** `sdk list java` shows every vendor's JDKs. `vfox search java` lists OpenJDK only, so name a distribution (`vfox search java tem`) or write `all`. `vfox list java` shows what is installed. The versions come from [Foojay](foojay.md). - **Installed names carry the build number.** `vfox list java` shows `21.0.8+9-tem`, which `vfox uninstall` and `vfox info` need in full, while `vfox use java@21.0.8-tem` finds it without the build, see [versions.md](versions.md#installed-names). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 892dfed..ecc809e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -36,11 +36,11 @@ The download answered 404. Vendors take old builds down while Foojay keeps their ### `Checksum error` -vfox printed `Checksum error, file: `, then `failed to install java` and `checksum error`, and stopped before it unpacked anything, so nothing is installed. The download does not match the checksum that Foojay lists for it, see [foojay.md](foojay.md#checksums). A download cut short or damaged on the way is the usual cause: try again. If it keeps happening through a mirror ([mirror.md](mirror.md)), the mirror may serve another file, so unset `VFOX_JAVA_GITHUB_MIRROR`. If it happens without one, the vendor may have replaced the file after Foojay recorded its checksum: report it to [Foojay](https://github.com/foojayio/discoapi) with the distribution and version. Unreleased: release 0.6.3 gives vfox no checksum, so it never stops here. +vfox printed `Checksum error, file: `, then `failed to install java` and `checksum error`, and stopped before it unpacked anything, so nothing is installed. The download does not match the checksum that Foojay lists for it, see [foojay.md](foojay.md#checksums). A download cut short or damaged on the way is the usual cause: try again. If it keeps happening through a mirror ([mirror.md](mirror.md)), the mirror may serve another file, so unset `VFOX_JAVA_GITHUB_MIRROR`. If it happens without one, the vendor may have replaced the file after Foojay recorded its checksum: report it to [Foojay](https://github.com/foojayio/discoapi) with the distribution and version. ### `Cannot verify the download: ...` -Foojay lists a checksum for the package that the plugin could not use, so the install goes on without verifying the download, and vfox prints `WARNING: Checksum is not provided, skip verify...` after it. After the colon comes why: `failed to fetch
: ...` when the file that holds the checksum did not answer (see [Network](#network)), `
has no digest` when the file holds none (a page that a firewall or a portal answered with, say), `
has no digest for ` when it lists other packages only, or `vfox cannot verify a sha3_256 checksum` for an algorithm vfox does not know. Trying again fixes the first. Please report the others with the distribution and version, as the plugin or Foojay's record needs a fix. Unreleased: release 0.6.3 never reads checksums. +Foojay lists a checksum for the package that the plugin could not use, so the install goes on without verifying the download, and vfox prints `WARNING: Checksum is not provided, skip verify...` after it. After the colon comes why: `failed to fetch
: ...` when the file that holds the checksum did not answer (see [Network](#network)), `
has no digest` when the file holds none (a page that a firewall or a portal answered with, say), `
has no digest for ` when it lists other packages only, or `vfox cannot verify a sha3_256 checksum` for an algorithm vfox does not know. Trying again fixes the first. Please report the others with the distribution and version, as the plugin or Foojay's record needs a fix. ### `VFOX_JAVA_GITHUB_MIRROR must start with http:// or https://, such as https://gh-proxy.org/, but is gh-proxy.org` @@ -74,14 +74,14 @@ While `proxy.enable` is `false`, the usual `HTTP_PROXY`, `HTTPS_PROXY` and `NO_P ## Things that look wrong and are not - **A release you expect is missing from `vfox search`.** vfox keeps the result for 12 hours. `vfox config cache.availableHookDuration 0` turns the cache off. Foojay itself may not have the release yet either. -- **`WARNING: Checksum is not provided, skip verify...` when a JDK installs.** Foojay lists no checksum for that package (Dragonwell, Bisheng, Trava, AdoptOpenJDK, OpenLogic, Gluon GraalVM, Corretto after 8, and older releases of several others), so vfox has nothing to verify the download against and trusts it. Where Foojay lists one, vfox prints `Verifying checksum ...` instead, see [foojay.md](foojay.md#checksums). Unreleased: release 0.6.3 gives vfox no checksum at all, so every install ends with the warning. +- **`WARNING: Checksum is not provided, skip verify...` when a JDK installs.** Foojay lists no checksum for that package (Dragonwell, Bisheng, Trava, AdoptOpenJDK, OpenLogic, Gluon GraalVM, Corretto after 8, and older releases of several others), so vfox has nothing to verify the download against and trusts it. Where Foojay lists one, vfox prints `Verifying checksum ...` instead, see [foojay.md](foojay.md#checksums). - **The installed name has a build number you did not type.** `java@21.0.8-tem` installs `21.0.8+9-tem`. The build is part of the name, see [versions.md](versions.md#installed-names). - **`vfox install java@21-tem` and `vfox install java tem` do different things.** The second one is two SDKs, `java` and `tem`. - **A `GRAALVM_HOME` you set is left alone.** The plugin sets `JAVA_HOME` and `PATH` only. - **`vfox use java@21` selects `21.3.1-grl11`, which runs Java 11.** GraalVM CE 8 to 19, Gluon GraalVM before 23, and Mandrel and Liberica NIK before 25 carry GraalVM's version numbers, and vfox matches a bare major against those, see [distributions.md](distributions.md#versions-numbered-after-graalvm). Write `java@21-tem`. - **`java@21-mandrel` installs a Mandrel that runs Java 17.** Mandrel's and Liberica NIK's majors are GraalVM's: `21.3.6-mandrel` is the newest Mandrel 21.x. Their releases for Java 21 are 23.1.x, so write `java@23-mandrel`, see [distributions.md](distributions.md#behavior-of-mandrel-and-liberica-nik). -- **`native-image` stops with `Default native-compiler executable 'gcc' not found via environment variable PATH`, or at its last step with `cannot find -lz`.** The plugin installs the JDK and nothing else, and `native-image` needs the system's C toolchain and zlib. On Ubuntu, `sudo apt install --assume-yes build-essential zlib1g-dev` installs them, see [distributions.md](distributions.md#native-image-and-the-c-toolchain). -- **`native-image: command not found` with a GraalVM CE 8 to 19, such as `22.3.3-grl17`.** These come without `native-image`, and `gu install native-image` adds it. It fails for `21.3.1-grl8`, see [distributions.md](distributions.md#native-image-and-the-c-toolchain). +- **`native-image` stops with `Default native-compiler executable 'gcc' not found via environment variable PATH`, or at its last step with `cannot find -lz`.** The plugin installs the JDK and nothing else, and `native-image` needs the system's C toolchain and zlib. On Ubuntu, `sudo apt install --assume-yes build-essential zlib1g-dev` installs them, see [native-image.md](native-image.md#ubuntu). +- **`native-image: command not found` with a GraalVM CE 8 to 19, such as `22.3.3-grl17`.** These come without `native-image`, and `gu install native-image` adds it. It fails for `21.3.1-grl8`, see [native-image.md](native-image.md#graalvm-ce-8-to-19). ## Where the JDK is diff --git a/docs/versions.md b/docs/versions.md index 8aa22ff..e17904e 100644 --- a/docs/versions.md +++ b/docs/versions.md @@ -23,7 +23,7 @@ The distribution is a short name (`tem`) or a long name (`temurin`). Both lists `vfox install` asks the plugin which package matches, then vfox downloads and unpacks it. -- A bare major (`21`, `21-tem`) installs the newest release of that major the distribution lists, for example `21.0.12.1+1-tem` on 2026-10-18. +- A bare major (`21`, `21-tem`) installs the newest release of that major the distribution lists, for example `21.0.13+9-tem` on 2026-11-03. - A longer version must match a release the distribution lists. `21.0.8-tem` installs `21.0.8+9-tem`, the newest build of 21.0.8. A release nobody published fails with `No JDK found for 21.0.99-tem on linux/amd64`. - A build number selects that build: `21.0.5+63130-jb`. - A release padded with zeros, as SDKMAN writes it, is accepted: `27.0.0-librca` installs `27+36-librca`. @@ -33,7 +33,7 @@ The distribution is a short name (`tem`) or a long name (`temurin`). Both lists - On Windows a release shipped as zip and as tar.gz installs from the zip. - A distribution without a version (`java@tem`, `java@-tem`, `java@zulu-fx`) is rejected with a message that asks for one. -An install that finds the name already present prints `java@21.0.12.1+1-tem is already installed` and downloads nothing. +An install that finds the name already present prints `java@21.0.13+9-tem is already installed` and downloads nothing. ## Installed names @@ -87,7 +87,7 @@ Pick the scope with `vfox use`'s flags: `--global`, `--project` or `--session`, Spell the build as `.ea[.]`: ```bash -vfox install java@28.ea-open # newest early-access build, 28-ea+19 on 2026-10-18 +vfox install java@28.ea-open # newest early-access build, 28-ea+21 on 2026-11-03 vfox install java@28.ea.15-open # 28-ea+15 ``` @@ -98,7 +98,7 @@ The installed name uses Foojay's spelling, `28-ea+19`, and `vfox use java@28-ea+ ```bash vfox search java # OpenJDK, the default vfox search java tem # one distribution, short or long name -vfox search java all # every distribution, about 2,500 lines on Linux x64 +vfox search java all # every distribution, about 2,600 lines on Linux x64 ``` Each line is a name that can follow `java@`, newest first, with notes for LTS and JavaFX (see [javafx.md](javafx.md)) and a mark for versions that are installed: @@ -109,9 +109,9 @@ Available versions: - 27+35-tem - 26.0.2.1+1-tem ... - - 25.0.4+7-tem (LTS) + - 25.0.5+8-tem (LTS) ... - - 21.0.12.1+1-tem (LTS) (installed) + - 21.0.13+9-tem (LTS) (installed) ``` The list holds what exists for the machine you run it on, see [platforms.md](platforms.md). In an interactive terminal `vfox search java tem` lets you pick a version and installs it, elsewhere it only prints. vfox caches the result for 12 hours (`vfox config cache.availableHookDuration`), so a release published a minute ago may be missing. diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index a354c56..3c4d97d 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -2,9 +2,9 @@ [中文](changes.md) | [English](../changes.md) -按发布版本列出用户能感受到的变化。GitHub 的 Release 页面列出了对应的 PR。写这篇文档时最新的发布版是 0.6.3，`main` 比它多出“未发布”下面的所有内容。想现在就用上这些变化，见 [install-from-source.md](install-from-source.md)。 +按发布版本列出用户能感受到的变化。GitHub 的 Release 页面列出了对应的 PR。 -## 未发布 +## 0.6.4（2026-11-03） - vfox 会按 Foojay 给出的校验和校验下载的文件。0.6.3 不给 vfox 任何校验和，所以每次安装最后都有 `WARNING: Checksum is not provided, skip verify...`，下载的内容照单全收，尽管 Foojay 给大多数发行版都列了校验和。现在 `vfox install java@25.0.2-graalce` 会打印 `Verifying checksum e0be791c...`，下载的文件对不上校验和时以 `Checksum error` 终止，什么也不会装上。Dragonwell、Bisheng、Trava、AdoptOpenJDK、OpenLogic、Gluon GraalVM、8 以后的 Corretto，以及其余发行版里较旧的版本，Foojay 没有校验和，vfox 对这些仍然会警告。GitHub 上的校验和文件和下载一样经过 `VFOX_JAVA_GITHUB_MIRROR`。Foojay 给了校验和而插件用不上时，插件会打印原因（`Cannot verify the download: ...`），安装照旧。见 [foojay.md](foojay.md#校验和)。 diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index a618e64..fde5aac 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -23,6 +23,8 @@ tests/post_install_layouts.lua PostInstall 处理的 macOS 目录结构，会 tests/fixtures/loongnix/ Loongnix 归档目录页的一份快照 tests/e2e/ 容器测试，见 e2e.md Injection.lua vfox 注入对象的类型提示，不会被加载 +README.md, docs/ 文档；README_CN.md 和 docs/zh-CN/ 是中文版 +opencode.jsonc 让本仓库里的 OpenCode 智能体会话不必确认就能执行 git push、gh pr create 和 gh pr comment ``` vfox 加载 `metadata.lua`，命令需要时调用相应的钩子，并向钩子提供全局变量 `PLUGIN` 和 `RUNTIME`（`osType`、`archType`、`version`）。`osType` 和 `archType` 就是 vfox 二进制的 Go `GOOS` 和 `GOARCH`。 @@ -107,7 +109,7 @@ vfox plugin run . ParseLegacyFile --input '{"filename":".sdkmanrc","filepath":"/ 2. 在 `lib/distribution_version.lua` 的 `short_name` 里加一行 `["<简称>"] = ""`。SDKMAN 现在或以前有这个发行版的话，用 SDKMAN 的标识符；没有的话，照 SDKMAN 的习惯起一个：短的厂商名保持原样，长的要缩短，多半是去掉元音（`opnlgc`）。SDKMAN 写法不同的话，在 `hooks/parse_legacy_file.lua` 的 `plugin_spelling` 里做映射，并把这个差别补进 [distributions.md](distributions.md#简称与-sdkman-的不同)。 3. 如果它的版本号需要特殊处理，像 GraalVM 和 Mandrel 那样，就在 `lib/foojay.lua` 读 Foojay 返回结果的地方处理（`graalvm_packages`、`own_numbers`）；LTS 标记或只写大版本号时选哪个，在 `hooks/available.lua` 和 `hooks/pre_install.lua` 里处理。如果它在 Windows 以外的系统上没有 tar.gz，就把它的格式加进 `lib/foojay.lua` 的 `other_archive_type`；如果 Foojay 给它列的包有的不能照原样安装，就在同一文件的 `fixes` 里加一条修正。 4. 在 `tests/pre_install_test.lua` 里加一个用例。 -5. 更新 `README.md`、[distributions.md](distributions.md) 和 [platforms.md](platforms.md) 里的表，以及对应的中文版（`README_CN.md` 和 `docs/zh-CN/` 下的同名页面）。 +5. 更新 `README.md`、[distributions.md](distributions.md) 和 [platforms.md](platforms.md) 里的表，以及 `README.md` 和 distributions.md 里写的发行版数量，再同步对应的中文版（`README_CN.md` 和 `docs/zh-CN/` 下的同名页面）。 6. 如果引入了新的代码路径，也要加进 e2e 矩阵（[e2e.md](e2e.md)）。矩阵之外的发行版仍会运行所有检查，只是跳过 `java.vendor` 断言和 asdf 风格的 `PreUse` 写法。只新增名字、没有新代码路径的发行版，则改加进 `tests/e2e/common/common.go` 的 `nameOnly`，并写上 Foojay 有它的那些 runner 平台。 ## 更新平台表 @@ -148,10 +150,18 @@ id 是 Foojay 的（`oracle_open_jdk` 对应 `open`）。这段命令在 Linux a ## 发布 -维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 的版本号。共享工作流具体做什么，README 里有说明。发布之后，[vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/java.json` 会显示 `vfox add java` 提供的是哪个版本。 +维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 前缀的稳定版插件版本号即可发布。共享工作流 [plugin-manifest-action](https://github.com/version-fox/plugin-manifest-action) 会更新 `metadata.lua`，创建版本提交和标签，并把 ZIP 包和 manifest 发布到本仓库；不需要在本地打标签，也不需要额外的发布令牌。PR 只运行检查。 -文档里用“未发布”（英文是“Unreleased”）标记比最新发布版更新的内容。发布之后，把 [changes.md](changes.md) 里的这些条目移到新版本下面，并去掉这些标注，两种语言都要处理：`grep -rn -i -e unreleased -e 未发布 docs README*`。上一个发布版的版本号也要搜一遍：有几句话是拿它做对比的，没有写“未发布”。 +直接推送版本标签也可以发布，前提是 `PLUGIN.version` 已经与标签一致。发布失败时，重新运行失败的那个作业即可接着发布。工作流引用的是共享的 `@v1` 发布工具，升级这个工具不会发布本插件。包的约定和首次接入的要求，见共享工作流的文档。发布之后，[vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/java.json` 会显示 `vfox add java` 提供的是哪个版本。 + +### 发布之后 + +文档里用“未发布”（英文是“Unreleased”）标记比最新发布版更新的内容。发布完成后： + +1. 把 [changes.md](changes.md) 里的这些条目移到新版本下面，写上发布日期，并去掉这些标注，两种语言都要处理：`grep -rn -i -e unreleased -e 未发布 docs README*`。 +2. 上一个发布版的版本号也要搜一遍：有几句话是拿它做对比的，没有写“未发布”。 +3. 引用 Foojay 数据的页面会写明数据取自哪一天。把那些写着“某个东西的最新版本”的引用（2026-11-03 的 `21.0.13+9-tem`）更新一遍，并重新对照 Foojay 检查各张表，见[更新平台表](#更新平台表)。 ## 编写文档 -英文页面在 `docs/`，中文页面在 `docs/zh-CN/`，文件名相同；README 的中文版是根目录的 `README_CN.md`。每页开头有指向另一种语言的链接。引用 Foojay 数据的页面会写明数据取自哪一天。CI 不检查这些文档，所以你加的命令请自己跑一遍。 +英文页面在 `docs/`，中文页面在 `docs/zh-CN/`，文件名相同；README 的中文版是根目录的 `README_CN.md`。每页开头有指向另一种语言的链接。新增的页面要加进两份 README 的“文档”列表。`vfox add java` 打印的 Notes 链接到 `README.md`（`metadata.lua` 里的 `PLUGIN.notes`，e2e 套件会检查），所以 README 要一直保留简称列表和搜索某个发行版的写法。引用 Foojay 数据的页面会写明数据取自哪一天。CI 不检查这些文档，所以你加的命令请自己跑一遍。 diff --git a/docs/zh-CN/distributions.md b/docs/zh-CN/distributions.md index 4d40763..9a2b6fa 100644 --- a/docs/zh-CN/distributions.md +++ b/docs/zh-CN/distributions.md @@ -2,7 +2,7 @@ [中文](distributions.md) | [English](../distributions.md) -插件从 [Foojay](foojay.md) 获取下面 31 个发行版的版本列表和下载链接，2026-10-20 时 Foojay 列出的发行版全在这里。凡是要写发行版的地方，简称和长名都可以：`21-tem`、`21-temurin`、`temurin-21`、`vfox search java tem`。 +插件从 [Foojay](foojay.md) 获取下面 31 个发行版的版本列表和下载链接，2026-11-03 时 Foojay 列出的发行版全在这里。凡是要写发行版的地方，简称和长名都可以：`21-tem`、`21-temurin`、`temurin-21`、`vfox search java tem`。 | 简称 | 长名 | 发行版 | 维护方 | | --- | --- | --- | --- | @@ -44,7 +44,7 @@ ## 简称与 SDKMAN 的不同 -简称沿用 [SDKMAN](https://sdkman.io/) 的标识符，Temurin 21.0.8 在两边都写作 `21.0.8-tem`。下面是与 SDKMAN 不同的地方，对照的是 2026-10-20 的 SDKMAN 列表： +简称沿用 [SDKMAN](https://sdkman.io/) 的标识符，Temurin 21.0.8 在两边都写作 `21.0.8-tem`。下面是与 SDKMAN 不同的地方，对照的是 2026-11-03 的 SDKMAN 列表： - JetBrains Runtime 叫 `jb`，SDKMAN 里叫 `jbr`；毕昇 JDK 叫 `bsg`，SDKMAN 里叫 `bisheng`，也就是插件给它的长名。`.sdkmanrc` 里写 SDKMAN 的叫法也认，见 [sdkmanrc.md](sdkmanrc.md)。 - Dragonwell、TravaOpenJDK、AdoptOpenJDK、Gluon GraalVM 和按 GraalVM 自身编号的 GraalVM CE，SDKMAN 都已经不再提供。后三个在 SDKMAN 里曾叫 `adpt`、`gln` 和 `grl`，当时把虚拟机或 JDK 版本写进版本号：HotSpot 版是 `11.0.10.hs-adpt`，OpenJ9 版是 `11.0.10.j9-adpt`，基于 JDK 17 的是 `22.3.3.r17-grl`。插件给 Foojay 的每个发行版各起一个名字，所以这部分挪进了简称：`11.0.10-adpt`、`11.0.10-adptj9`、`22.3.3-grl17`。`.sdkmanrc` 里用 SDKMAN 的旧写法也能选中它们。 @@ -126,6 +126,8 @@ IBM Semeru Runtime Certified Edition：Semeru 的 OpenJ9 运行时，通过了 J ## GraalVM 系列 +这些发行版里，不少沿用 GraalVM 自己的版本号，而不是 Java 的。版本怎样命名、只写大版本号时装什么，在列表之后说明：[Oracle GraalVM 与 GraalVM 社区版](#oracle-graalvm-与-graalvm-社区版的行为)、[Mandrel 与 Liberica NIK](#mandrel-与-liberica-nik-的行为)，以及[更早的那些](#按-graalvm-编号的版本)。想用它们构建原生可执行文件，见 [native-image.md](native-image.md)。 + ### Oracle GraalVM（`graal`） Oracle 发行的 GraalVM，基于 Oracle JDK。版本号沿用 GraalVM 自己的编号：`17.0.12-graal`、`25.0.4.1.1-graal`、`25.4.4.1.1-graal`。 @@ -142,13 +144,6 @@ GraalVM 的开源版本，基于 OpenJDK。 [Red Hat](https://github.com/graalvm/mandrel) 为构建 Quarkus 原生可执行文件提供的发行版，专注于 `native-image`。版本号从 20.3 到 25，运行的是 Java 11、17 和 20 到 25。 -### Mandrel 与 Liberica NIK 的行为 - -- 两者都沿用所基于的 GraalVM 的版本号，安装后的版本名用的也是它：`23.1.12.1-mandrel`、`23.1.8-nik`。到 24 为止，这个版本号和 Java 的版本号对不上：23.1 运行的是 Java 21，24.0 是 Java 22，24.1 是 Java 23，24.2 是 Java 24，更早的版本运行 Java 11、17 或 20。从 25 起两者一致（`25.0.4.1`）。 -- 只写大版本号时，这个大版本号同样是 GraalVM 的：`java@23-mandrel` 装最新的 23.x，即 `23.1.12.1-mandrel`，运行的是 Java 21；`java@21-mandrel` 装的是 `21.3.6-mandrel`，运行的是 Java 17。写得更具体的版本只装它指定的那一个：`java@23.1.12-mandrel` 装的是 23.1.12，不是 23.1.12.1；`java@23.1-mandrel` 装的是 23.1 系列的第一个版本 23.1.0。写了构建号则什么也找不到（`java@23.1.8+1-nik`）。 -- 以 `.0.0` 结尾的版本在列表里显示为只有大版本号的名字（`24-mandrel` 是 Mandrel 24.0.0），要写全版本号才能装：`java@24.0.0-mandrel`。装上之后，vfox 会按这个名字找到 `java@24-mandrel`，`vfox install` 和 `vfox use` 都一样。 -- 有些版本号下有几个构建，分别对应不同的 Java，比如 Mandrel 21.3.6 有 Java 11 和 Java 17 两个构建，插件装 Java 最新的那个；对 Mandrel 23.0.1.2 和 Liberica NIK 23.0.1 来说，那是 Java 20，不是 17。Liberica NIK 有几个版本为同一个 Java 构建了两次（`25.0.3`），装的是后一次的构建。版本名里既看不出 Java 版本，也看不出 BellSoft 的构建号，所以其他构建装不了。 - ### GraalVM CE 8 到 19（`grl8`、`grl11`、`grl16`、`grl17`、`grl19`） 22.3 及以前的 GraalVM 社区版，那时它还没有改用 JDK 的版本号。Foojay 按 JDK 分成了几个发行版：`grl8`（GraalVM 19.3 到 21.3.1）、`grl11`（19.3 到 22.3.3）、`grl16`（21.1 和 21.2）、`grl17`（21.3 到 22.3.3）和 `grl19`（22.3 和 22.3.1）。之后接替它们的是 GraalVM 社区版（`graalce`）。 @@ -157,39 +152,26 @@ GraalVM 的开源版本，基于 OpenJDK。 [Gluon](https://docs.gluonhq.com/#_graalvm) 的 GraalVM 构建，用来把 JavaFX 应用编译成原生镜像。21.1 和 21.2 基于 JDK 11。22.x（22 到 22.1.0.1）同一个版本号下有 JDK 11 和 JDK 17 两个构建，插件装的是 JDK 17 的。23+25 是基于 JDK 23 的开发构建。有 Linux x64、macOS 和 Windows x64 的版本，Apple Silicon 从 22.1.0.1 起才有。 -### 按 GraalVM 编号的版本 - -GraalVM CE 8 到 19、23 以前的 Gluon GraalVM，以及 25 以前的 Mandrel 和 Liberica NIK，版本号是 GraalVM 自己的，不是 Java 的：`22.3.3-grl17` 是 GraalVM 22.3.3，运行的是 Java 17.0.8；`21.3.1-grl11` 运行的是 Java 11；`23.1.12.1-mandrel` 运行的是 Java 21。对只写大版本号的写法，vfox 只按版本号匹配，不分发行版，取以它开头的最高已安装版本，所以同时装了 `21.3.1-grl11` 和 `21.0.12.1+1-tem` 时，`vfox use java@21` 选中的是 `21.3.1-grl11`。请写上发行版，比如 `java@21-tem`。 - ### Oracle GraalVM 与 GraalVM 社区版的行为 - 从 25.1（2026 年 6 月）起，GraalVM 在 25.0 系列之外每月发布一个特性版本（feature release）：`25.1.3`、`25.2.4`、`25.3.4.1`、`25.4.4.1.1`，每个大约一个月后就被下一个取代。Foojay 把 Oracle GraalVM 的特性版本标成 STS；GraalVM 社区版按老办法列的那些（见下文），则因为基于的 JDK 是 LTS，也被标成了 LTS。`vfox search` 一律不给它们加 LTS 备注。 - 版本名用的是 GraalVM 自己的版本号，也就是 Foojay 的 `distribution_version`。Foojay 的 `java_version` 是 JDK 的版本号，特性版本会和 25.0 系列的某个构建共用同一个值：`25.4.4.1.1-graal`、`25.3.4.1-graal`、`25.0.4.1.1-graal` 和 `25.0.4.1-graal` 的 `java_version` 都是 25.0.4.1。 - GraalVM 社区版的特性版本，Foojay 还像 2026 年 10 月以前那样，按 GraalVM 的版本号另列了一份，下载地址在 GitHub。所以 0.6.2 给 25.4.4.1.1 构建起的名字 `java@25.4.4.1-graalce` 仍然能从 GitHub 装上这个构建，而 `java@25.4.4.1.1-graalce` 是从 Oracle 的 GraalVM Download Service 下载同一个文件。 -- `java@25-graal` 装的是 25.0 系列的最新构建（2026-10-20 是 `25.0.5-graal`），Oracle 官方的 `25/latest` 下载链接跟的也是这个系列。特性版本要写全版本号：`java@25.4.4.1.1-graal`。`vfox use java@25-graal` 和 `.sdkmanrc` 里的 `java=25-graal` 选中的也是这个系列里已安装的最新构建，只有 25 里没有装别的版本时才会选特性版本。 -- GraalVM 社区版的 25.0 系列到 `25.0.2` 为止，现在只发布特性版本。`java@25-graalce` 装其中最新的一个，截至 2026-10-20 是 `25.4.4.1.1-graalce`。 +- `java@25-graal` 装的是 25.0 系列的最新构建（2026-11-03 是 `25.0.5.0.3-graal`），Oracle 官方的 `25/latest` 下载链接跟的也是这个系列。特性版本要写全版本号：`java@25.4.4.1.1-graal`。`vfox use java@25-graal` 和 `.sdkmanrc` 里的 `java=25-graal` 选中的也是这个系列里已安装的最新构建，只有 25 里没有装别的版本时才会选特性版本。 +- GraalVM 社区版的 25.0 系列到 `25.0.2` 为止，现在只发布特性版本。`java@25-graalce` 装其中最新的一个，截至 2026-11-03 是 `25.4.4.1.1-graalce`。 - 插件只设置 `JAVA_HOME` 和 `PATH`，不设置 `GRAALVM_HOME`。你设置的、指向自己的 GraalVM 的 `GRAALVM_HOME` 保持原样；没有设置时，native-image 的构建插件会回退到 `JAVA_HOME`。 - 没有 Windows ARM64 和 Alpine 的构建，Intel Mac 上 25.0.1 之后的版本也没有。见 [platforms.md](platforms.md#graalvm)。 -### Native Image 与 C 工具链 - -GraalVM 的安装和使用与别的 JDK 没有两样：`vfox install java@25.0.2-graalce` 和 `vfox use` 之后，`java` 和 `javac` 在没有编译器、也没有 zlib 头文件的系统上照常工作。`sudo apt install --assume-yes build-essential zlib1g-dev` 只为 `native-image` 而装，它是把程序编译成原生可执行文件的工具。它用系统的 `gcc` 把可执行文件与 C 库和 zlib 链接起来，所以需要它们；调用它的程序同样需要，比如 Native Image 的 Maven 和 Gradle 插件。插件只安装 JDK，不装别的。 - -在 Ubuntu 26.04 的 Bash 中执行： - -```bash -sudo apt install --assume-yes build-essential zlib1g-dev -``` +### Mandrel 与 Liberica NIK 的行为 -- `native-image` 在 Oracle GraalVM、GraalVM 社区版、Liberica NIK、Mandrel 和 Gluon GraalVM 的 `bin` 目录里。GraalVM CE 8 到 19 是例外，见下文。 -- 没有 `gcc` 时，构建几秒内就停下，报 `Error: Default native-compiler executable 'gcc' not found via environment variable PATH`，只装 `zlib1g-dev` 也没用。 -- 有 `gcc` 却没有 `zlib1g-dev` 时（只装了 `build-essential` 也是这种情况），构建会先走完分析和编译（hello world 用了 20 秒到两分钟），到链接时才失败：`There was an error linking the native image: Linker command exited with 1`，GraalVM 自己的提示 `It appears as though libz:.a is missing. Please install it.`，以及 `cannot find -lz: No such file or directory`。 -- 构建一个 hello world，`gcc`、`libc6-dev` 和 `zlib1g-dev` 就够了，用不着 `g++` 和 `make`。`build-essential` 把这两个也装上，GraalVM 的文档列出的正是它。 -- 其他系统需要的包不一样。GraalVM 的[前置条件](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites)里，Fedora 和其他使用 dnf 的系统是 `sudo dnf install gcc glibc-devel zlib-devel libstdc++-static`，macOS 是 `xcode-select --install`，Windows 是带 Windows SDK 的 Visual Studio Build Tools。在 Fedora 44 上，只装 `gcc`、`glibc-devel` 和 `zlib-devel`、不装 `libstdc++-static`，也构建出了 hello world。 +- 两者都沿用所基于的 GraalVM 的版本号，安装后的版本名用的也是它：`23.1.12.1-mandrel`、`23.1.8-nik`。到 24 为止，这个版本号和 Java 的版本号对不上：23.1 运行的是 Java 21，24.0 是 Java 22，24.1 是 Java 23，24.2 是 Java 24，更早的版本运行 Java 11、17 或 20。从 25 起两者一致（`25.0.4.1`）。 +- 只写大版本号时，这个大版本号同样是 GraalVM 的：`java@23-mandrel` 装最新的 23.x，即 `23.1.12.1-mandrel`，运行的是 Java 21；`java@21-mandrel` 装的是 `21.3.6-mandrel`，运行的是 Java 17。写得更具体的版本只装它指定的那一个：`java@23.1.12-mandrel` 装的是 23.1.12，不是 23.1.12.1；`java@23.1-mandrel` 装的是 23.1 系列的第一个版本 23.1.0。写了构建号则什么也找不到（`java@23.1.8+1-nik`）。 +- 以 `.0.0` 结尾的版本在列表里显示为只有大版本号的名字（`24-mandrel` 是 Mandrel 24.0.0），要写全版本号才能装：`java@24.0.0-mandrel`。装上之后，vfox 会按这个名字找到 `java@24-mandrel`，`vfox install` 和 `vfox use` 都一样。 +- 有些版本号下有几个构建，分别对应不同的 Java，比如 Mandrel 21.3.6 有 Java 11 和 Java 17 两个构建，插件装 Java 最新的那个；对 Mandrel 23.0.1.2 和 Liberica NIK 23.0.1 来说，那是 Java 20，不是 17。Liberica NIK 有几个版本为同一个 Java 构建了两次（`25.0.3`），装的是后一次的构建。版本名里既看不出 Java 版本，也看不出 BellSoft 的构建号，所以其他构建装不了。 -GraalVM CE 8 到 19（`grl8`、`grl11`、`grl16`、`grl17`、`grl19`）不带 `native-image`。它们的 `bin` 目录里只有 GraalVM 更新器 `gu`，`native-image` 会报 `command not found`，要先用 `gu install native-image` 从 GitHub 添加。2026-11-02 这在 `22.3.3-grl11`、`21.2-grl16`、`22.3.3-grl17` 和 `22.3.1-grl19` 上成功了，添加之后仍然需要上面的包。`21.3.1-grl8` 上失败了，报 `Internal error occurred: A JSONObject text must begin with '{'`：这个 `gu` 下载的版本索引 `https://oca.opensource.oracle.com/gds/meta-data.json` 现在返回的是一个网页。对这个版本，请从 [`vm-21.3.1` 发布页](https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.1)下载 `native-image-installable-svm-java8-linux-amd64-21.3.1.jar`，再对这个文件执行 `gu -L install`。 +### 按 GraalVM 编号的版本 -2026-11-02 用 vfox 1.0.13 在没有编译器的 Ubuntu 26.04 容器镜像（x64）里检查过：GraalVM 社区版 25.0.2 和 25.4.4.1.1、Oracle GraalVM 25.0.5、Mandrel 25.0.5、Liberica NIK 25.0.4.1 和 Gluon GraalVM 22.1.0.1，没有这些包时都如上所述停下，装上之后都构建出了能运行的 hello world。`22.3.3-grl17` 在执行 `gu install native-image` 之后也是如此，GraalVM 社区版 25.0.2 在 Fedora 44 的镜像里也一样。 +GraalVM CE 8 到 19、23 以前的 Gluon GraalVM，以及 25 以前的 Mandrel 和 Liberica NIK，版本号是 GraalVM 自己的，不是 Java 的：`22.3.3-grl17` 是 GraalVM 22.3.3，运行的是 Java 17.0.8；`21.3.1-grl11` 运行的是 Java 11；`23.1.12.1-mandrel` 运行的是 Java 21。对只写大版本号的写法，vfox 只按版本号匹配，不分发行版，取以它开头的最高已安装版本，所以同时装了 `21.3.1-grl11` 和 `21.0.12.1+1-tem` 时，`vfox use java@21` 选中的是 `21.3.1-grl11`。请写上发行版，比如 `java@21-tem`。 ## 其他 diff --git a/docs/zh-CN/e2e.md b/docs/zh-CN/e2e.md index d083eca..f37386b 100644 --- a/docs/zh-CN/e2e.md +++ b/docs/zh-CN/e2e.md @@ -4,6 +4,8 @@ 离线的 Lua 钩子测试（`tests/*_test.lua` 由 `vfox plugin test` 运行，`tests/post_install_layouts.lua` 由 `glua` 运行）在 **Test Plugin** 工作流里运行。端到端套件在容器里针对真实的 vfox 运行，覆盖 Linux 和 Windows；每个 `vfox` x `distribution` 组合都有自己的一次性容器。CI 直接在标准 runner 上运行这套测试（Docker 加 `actions/setup-go` 提供的 Go）。本地则由仓库的开发容器在 Linux 上复现这一环境；Windows 上改用 Docker Compose runner 镜像，因为开发容器无法承载 Windows 容器镜像（见下文）。 +下面的章节说明怎样运行这套测试，页末的[套件验证什么](#套件验证什么)列出它检查的全部内容。 + ## 开发容器 `.devcontainer/` 提供一个 Linux 开发环境，在四种宿主平台上都能用： @@ -13,7 +15,7 @@ | Linux amd64 / arm64 | 原生运行 | | Windows amd64 / arm64 | Docker Desktop 的 Linux 容器模式（WSL 2） | -它带有 Go 1.27.1（CI 安装的版本）、Docker CLI、stylua、lua-language-server 和许可证工具，版本都与 `.github/workflows/lint.yml` 和 `license.yml` 里固定的一致，并挂载宿主的 Docker daemon socket。套件随后通过 testcontainers 连接这个 daemon（Docker-out-of-Docker），启动的目标容器和原生 CI runner 启动的完全相同；这里刻意不用 Docker-in-Docker，这样镜像缓存和网络都还是宿主的。镜像不需要工作区里的文件，所以构建上下文保持在 `.devcontainer/`；`postCreateCommand` 会预热 `tests/e2e` 的 Go 模块缓存，第一次运行测试时就不必停下来下载。 +它带有 Go 1.27.1（CI 安装的版本）、Docker CLI、stylua、lua-language-server、许可证工具，以及运行离线钩子测试的 vfox，版本都与 `.github/workflows/lint.yml`、`license.yml` 和 `test.yml` 里固定的一致，并挂载宿主的 Docker daemon socket。套件随后通过 testcontainers 连接这个 daemon（Docker-out-of-Docker），启动的目标容器和原生 CI runner 启动的完全相同；这里刻意不用 Docker-in-Docker，这样镜像缓存和网络都还是宿主的。镜像不需要工作区里的文件，所以构建上下文保持在 `.devcontainer/`；`postCreateCommand` 会预热 `tests/e2e` 的 Go 模块缓存，第一次运行测试时就不必停下来下载。 用任何支持 Dev Containers 规范的工具都可以打开它：在 VS Code/Cursor 里执行 **Dev Containers: Reopen in Container**，或者用 CLI： @@ -26,55 +28,12 @@ devcontainer exec --workspace-folder . bash Windows 容器的覆盖（`tests/e2e/windows`）无法在开发容器里运行：Dev Containers 规范不支持 Windows 容器镜像（[vscode-remote-release#445](https://github.com/microsoft/vscode-remote-release/issues/445)），而且 Windows 容器只能跑在 Windows daemon 上。这套测试仍然使用 Windows 宿主上的 Docker Compose runner，见下面的 [Windows 11](#windows-11)。 -## 套件验证什么 - -每个组合都运行同样的流程（每个组合一个长期存活的容器，由 Go 通过类似 `docker exec` 的调用来驱动）；目标镜像里没有 JDK，所以 `java` 只能来自 vfox 安装的东西： - -1. 从指定的渠道安装 vfox，要么是最新发布版（`latest`），要么从源码构建（`main`），然后从当前检出的代码注册本地的 `java` 插件。在 Windows 上，runner 会在 `latest` 组合运行期间把 `main` 构建一次，`main` 的容器由 e2e 镜像加上这个 `vfox.exe` 启动。接着，`vfox info java` 打印的 Notes 要链接到 README，README 里列了各个简称，也写了怎样搜索某个发行版。以前的 Notes 只给了五个简称，没说怎样列出它们的版本（[vfox#390](https://github.com/version-fox/vfox/issues/390)）。 -2. 只写发行版不写版本，无论单独写还是跟在空版本后面（`java@tem`、`java@-tem`），`vfox install` 和 `vfox use` 都应失败，并提示补上版本。以前，`java@tem` 会让钩子报 Lua 错误；`java@-tem` 则让 `PreInstall` 把空版本发给 Foojay，Foojay 列出所有版本，结果装上了最新的。没有任何发行版发布过的版本（`<大版本>.0.99`）应该安装失败，并且 `PreInstall` 要指出它搜索的平台（`linux/amd64`、`windows/arm64` 等），以此确认向 Foojay 查询的就是 runner 所在的平台。已固定版本里从未发布过的构建（`<版本>+99`，例如 `21.0.8+99-tem`）也一样，这证明查询保留了构建号：Foojay 会把没编码的 `+` 当成空格并丢掉构建号，于是会装上这个版本的最新构建。 - - 在 `tem` 这几行里，经过一个不存在的镜像安装也必须失败。设成 `VFOX_JAVA_GITHUB_MIRROR=https://invalid.example.invalid` 后，镜像会加在 Temurin 的 GitHub 地址前面，所以 `vfox install` 在下载时失败，错误信息里必须出现 vfox 请求的那个地址：镜像、一个斜杠，再加 GitHub 地址。以前插件不读这个变量，会从 github.com 下载 JDK，安装成功。这一步不下载任何东西，也不运行能正常工作的镜像。 -3. 在 `graalce` 这一行里，Oracle GraalVM 只写大版本号的 `25-graal` 应该装 25.0 系列的最新构建（2026-10-20 是 `25.0.5-graal`），也就是 Oracle 官方 `25/latest` 下载跟的那个系列，而不是列在它前面的某个每月特性版本（比如 `25.4.4.1.1-graal`）。`vfox search java graal` 必须按 GraalVM 自己的版本号列出这些特性版本，25 的其他版本备注要一致，同第 5 条。从 2026 年 10 月起，Foojay 给特性版本标的是 JDK 的版本号，和 25.0 系列共用。插件以前按这个版本号命名，结果搜索里一个特性版本都没有，`25.0.4.1-graal` 也没有 LTS 备注，装上的却是 25.4.4.1.1。搜索列出的 25 的各构建会先被模拟成已安装，这样 `vfox install` 报出的就是 `PreInstall` 选中的那个，而且不会下载任何东西。GA 版本 25 不放进去，因为那样 vfox 会发现 `25-graal` 已安装，根本不会去问 `PreInstall`。在 Linux 上，安装向 Foojay 发的请求还必须和搜索的相同，同第 4 条末尾。 - - 装着这些构建时，`vfox use java@25-graal` 和写着 `java=25-graal` 的 `.sdkmanrc` 必须选中 `vfox install` 报出的那个构建。`PreUse` 和 `ParseLegacyFile` 以前选的是 25 里已安装的最新版本，所以一旦装了特性版本，选中的就是它（[#110](https://github.com/version-fox/vfox-java/issues/110)）。模拟出的每个构建里都放着一个只打印名字的替身 `java`，同第 6 条。把 25.0 系列的构建删掉之后，`vfox use` 和 `.sdkmanrc` 都必须选中最新的特性版本。 -4. 在 `tem` 这几行里（这几行在每个 runner 上都会运行），只按名字检查的发行版（`adpt` 到 `semcrt`，即 `tests/e2e/common` 里的 `nameOnly`），只要 Foojay 在这个 runner 上有它的包，都要能用简称找到：`vfox search java <简称>` 能列出它；把它列出的最新版本模拟成已安装后，`vfox install java@<大版本>-<简称>`（`22-grl17`）要报告这个版本已经安装，所以不会下载任何东西。以前没有这些简称时，这两条命令分别报 `Unsupported distribution` 和 `Could not extract a valid distribution`。 - - 同样在这几行里，Mandrel 和 Liberica NIK 要按它们沿用的 GraalVM 版本号来（`tests/e2e/common` 里的 `ownNumbers`；Windows arm64 上两者都没有）：`vfox search java mandrel` 要列出 `23.1.12-mandrel`（Liberica NIK 是 `23.1.8-nik`）；把它和搜索结果里最新的 23.x 模拟成已安装后，`vfox install java@mandrel-23.1.12` 和 `vfox install java@23-mandrel` 要报告这两个版本已经安装。2026 年 10 月 Foojay 把这个版本号挪到了 `distribution_version`，插件改读它之前，搜索结果每个 Java 大版本只列一个名字，找不到 `23.1.12-mandrel`，`java@23-mandrel` 装上的是为 Java 23 构建的 Mandrel 24.1.2。 - - 在 Linux 上，这几行和第 3 条的 `graalce` 行经由一个冒充 api.foojay.io 的替身访问 Foojay（由 `tests/e2e/linux/front` 构建），替身记下插件发出的每个请求。上面每次安装发的请求都必须和它前面那次搜索的相同（`tests/e2e/common` 里的 `AsksAsSearch`）。Foojay 的结果按请求分别缓存，新版本发布后的半小时里，换一个请求就可能装上搜索还没列出的构建，于是真的下载，检查失败（见 [foojay.md](foojay.md#插件发出的请求)）。[#113](https://github.com/version-fox/vfox-java/issues/113) 之前，只写大版本号时查的是 `latest=available`，Mandrel 和 Liberica NIK 则按 `distribution_version` 查。 -5. 固定的版本按 `PreInstall` 给它起的名字安装：请求的版本加上构建号（`21.0.8-tem` 安装为 `21.0.8+9-tem`）。`vfox search java <发行版>`（`Available` 钩子）把同一个名字列为已安装，带 JavaFX 的构建会标注 JavaFX。对 GraalVM，它还必须列出自 25.1 起每月发布的特性版本（`25.4.4.1.1-graalce`），这些版本都不标 LTS（Foojay 给其中一些标了，因为它们基于的 JDK 是 LTS）；每个版本大约只存在一个月。同一个大版本里的其他版本，备注必须一致。插件以前把特性版本 25.4.4.1.1 列成 `25.0.4.1-graalce`，没有 `25.0.2-graalce` 那样的 LTS 备注。在 Windows 上，列表里要包含 JetBrains Runtime 21.0.5，它在 Windows 上只有 tar.gz。 - - 安装本身还必须校验了下载的文件。每个默认发行版固定的版本，Foojay 在每个 runner 上都给出了校验和（2026-11-02），`vfox install` 必须打印 `Verifying checksum <摘要>...`，摘要的长度是 vfox 支持的，并且不能出现 `WARNING: Checksum is not provided, skip verify...`——在插件把 Foojay 的校验和交给 vfox 之前，每次安装最后都有这条警告。摘要有四种形式，所以插件读取它们的每种方式都会跑到：Foojay 记录里的 SHA-256 和 SHA-1（Temurin、Liberica），只有摘要的文件里的 SHA-256（OpenJDK、GraalVM 社区版），以及带着文件名的文件里的 SHA-512（JetBrains）。vfox 把摘要和下载文件的哈希值比较，对不上就让安装失败，所以安装成功就证明摘要确实是这个文件的。用 `JAVA_VERSION` 指定的版本不检查这一项，因为 Foojay 可能没有它的校验和。 -6. 在执行任何 `vfox use` 之前，`.sdkmanrc` 要能通过 `ParseLegacyFile` 选中 JDK。测试时，`vfox list java` 里排在最前面的是另一个版本的空安装（`21.0.80+1-tem`，它的版本号以固定的版本开头；vfox 按字符串降序给已安装版本排序）。以前 `ParseLegacyFile` 会把它当成第一个以该版本开头的版本，对补零的版本（见下面第二条），则当成该大版本里最新的版本。要覆盖的写法有： - - 不含构建号的 SDKMAN 标识符：`java=21.0.8-tem`、`java=21.0.5-jbr`（SDKMAN 对 JetBrains 的叫法）、`java=25.0.4.fx-librca`（它对 JavaFX 构建的写法）。 - - 补零的标识符，`sdk list java` 里有很多这样的：`java=21.0.8.0+9-tem`、`java=25.0.4.0-fx+9-librca`（Foojay 以及安装后的版本名里没有这个零）。 - - 安装后的版本名：`java=21.0.8+9-tem`。 - - EA 构建的标识符。固定大版本的 EA 构建，如果按 `sdk list java` 里 OpenJDK 的写法来写（`28.0.0.0+ea.20-open`），必须选中那个 EA 构建：`java=21.0.0.0+ea.1-tem` 要选中 `21-ea+1-tem`，不能选中 GA 版本。`ParseLegacyFile` 只认 SDKMAN 较旧的 `21.ea.1-tem` 写法时，选中的正是 GA 版本。安装后的版本名本身（`java=21-ea+1-tem`）也要能选中：`ParseLegacyFile` 以前解析不了它，什么也没选中，而 `vfox use` 是能选中的。 - - jdk.java.net 会在几周内撤掉每个 EA 构建，所以这个安装是模拟出来的：它的 `bin` 里放着一个只打印名字的替身 `java`。在 Windows 上，文件用 CRLF 换行写入。 - - 接着，在 `tem` 这几行里，`.sdkmanrc` 里写的是 SDKMAN 给 Mandrel 和 Liberica NIK 的、`.r` 后面带 JDK 版本的标识符时，要选中标识符指明的版本：`java=25.0.4.r25-nik` 选中 `25.0.4-nik`，而不是 `25.0.4.1-nik`。`ParseLegacyFile` 以前把 `25.0.4.r25` 当成版本号，选中的正是后者。`java=22.1.r11-mandrel` 则什么都不能选中，因为插件只装 Mandrel 22.1 的 JDK 17 构建（`tests/e2e/common` 里的 `OwnNumberIdentifiers`）。标识符指明的版本，以及同一大版本里更新的一个版本，也是这样模拟安装的。 -7. `vfox use --global` 之后，`PATH` 上的 JDK 要报告请求的 `java.version`、runner 的 `os.arch`（`amd64` / `aarch64`，这也能抓出在 Windows ARM64 上模拟运行的 x64 JDK）和这个发行版的 `java.vendor`。`JAVA_HOME` 指向同一个 JDK，`javac` 能编译一个程序，`java` 能运行它，模块列表恰好在 `-fx` 构建里含有 JavaFX，`vfox current java` 报告已安装的版本。事先设置的 `GRAALVM_HOME` 保持原值，因为用户会把它指向自己的 GraalVM；对 GraalVM，插件以前会把它替换成正在使用的 JDK。 -8. `PreUse` 把用户输入的各种写法映射到已安装的版本，不需要再次下载：只写大版本号（`java@21`，交给 vfox 核心做模糊匹配）、安装时用的写法（`java@21.0.8-tem`，`PreUse` 会在已安装的版本里找到它的构建号），以及 asdf 风格的 `<长名>-<版本>[-fx]`（`java@temurin-21.0.8+9` 改写成 `21.0.8+9-tem`；`java@openjdk-25.0.2+10` 改写成 `25.0.2+10`）。SDKMAN 那样补零的版本也一样（`java@21.0.8.0-tem`、`java@21.0.8.0+9-tem`），`vfox install` 必须先发现它们已经安装：`PreInstall` 把零原样交给了 Foojay，Foojay 会去掉它，而 `PreUse` 以前去找以补零版本开头的已安装版本，报告说没有安装。 - -默认矩阵对每个发行版都跑两个 vfox 渠道（`latest`、`main`）： - -| 发行版 | 版本 | 覆盖内容 | amd64 | arm64 | -| ------------ | ------- | ---------------------------------------------------------------------------- | ----- | ----- | -| `open` | 25.0.2 | 默认发行版，版本不带后缀 | ✓ | | -| `tem` | 21.0.8 | 常规路径（Linux 上是 tar.gz，Windows 上是 zip）；第 2、4、6 条里的镜像检查、按名字和按版本号的检查 | ✓ | ✓ | -| `librca-fx` | 25.0.4 | 带 JavaFX 的构建（`-fx`） | ✓ | ✓ | -| `jb` | 21.0.5 | Windows 上走 tar.gz 的路径，那里没有 zip | ✓ | ✓ | -| `graalce` | 25.0.2 | 事先设置的 `GRAALVM_HOME` 保持原值；Oracle GraalVM 的 `25-graal` | ✓ | | - -表里每一行固定的版本，在这一行要跑的每个平台上，Foojay 都有对应的包。OpenJDK 和 GraalVM 社区版没有 `windows-aarch64` 构建，所以 arm64 不管在 Linux 还是 Windows 上，都只跑另外三个。 - ## 环境变量 | 变量 | 默认值 | 含义 | | -------------------- | -------------------------- | ----------------------------------------------------------------------- | | `VFOX_VERSION` | `latest main` | 用空格分隔的 vfox 渠道（`latest`、`main`） | -| `DISTRIBUTION` | 见上面的矩阵 | 用空格分隔的插件发行版，JavaFX 加 `-fx`（`tem zulu-fx`） | +| `DISTRIBUTION` | 见下面的矩阵 | 用空格分隔的插件发行版，JavaFX 加 `-fx`（`tem zulu-fx`） | | `JAVA_VERSION` | 按发行版而定 | 为每个选中的发行版安装的版本（Java 9+ 的编号方式） | | `E2E_MAX_JOBS` | `3`（Linux），`2`（Windows） | 每台宿主并行的容器数 | | `E2E_RETRY_ATTEMPTS` | `3` | 每个涉及网络的 exec 的尝试次数（线性退避 10 秒） | @@ -215,3 +174,46 @@ docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header fix docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -check -f .license.tpl tests/e2e/windows/*.ps1 docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -f .license.tpl tests/e2e/windows/*.ps1 ``` + +## 套件验证什么 + +每个组合都运行同样的流程（每个组合一个长期存活的容器，由 Go 通过类似 `docker exec` 的调用来驱动）；目标镜像里没有 JDK，所以 `java` 只能来自 vfox 安装的东西： + +1. 从指定的渠道安装 vfox，要么是最新发布版（`latest`），要么从源码构建（`main`），然后从当前检出的代码注册本地的 `java` 插件。在 Windows 上，runner 会在 `latest` 组合运行期间把 `main` 构建一次，`main` 的容器由 e2e 镜像加上这个 `vfox.exe` 启动。接着，`vfox info java` 打印的 Notes 要链接到 README，README 里列了各个简称，也写了怎样搜索某个发行版。以前的 Notes 只给了五个简称，没说怎样列出它们的版本（[vfox#390](https://github.com/version-fox/vfox/issues/390)）。 +2. 只写发行版不写版本，无论单独写还是跟在空版本后面（`java@tem`、`java@-tem`），`vfox install` 和 `vfox use` 都应失败，并提示补上版本。以前，`java@tem` 会让钩子报 Lua 错误；`java@-tem` 则让 `PreInstall` 把空版本发给 Foojay，Foojay 列出所有版本，结果装上了最新的。没有任何发行版发布过的版本（`<大版本>.0.99`）应该安装失败，并且 `PreInstall` 要指出它搜索的平台（`linux/amd64`、`windows/arm64` 等），以此确认向 Foojay 查询的就是 runner 所在的平台。已固定版本里从未发布过的构建（`<版本>+99`，例如 `21.0.8+99-tem`）也一样，这证明查询保留了构建号：Foojay 会把没编码的 `+` 当成空格并丢掉构建号，于是会装上这个版本的最新构建。 + + 在 `tem` 这几行里，经过一个不存在的镜像安装也必须失败。设成 `VFOX_JAVA_GITHUB_MIRROR=https://invalid.example.invalid` 后，镜像会加在 Temurin 的 GitHub 地址前面，所以 `vfox install` 在下载时失败，错误信息里必须出现 vfox 请求的那个地址：镜像、一个斜杠，再加 GitHub 地址。以前插件不读这个变量，会从 github.com 下载 JDK，安装成功。这一步不下载任何东西，也不运行能正常工作的镜像。 +3. 在 `graalce` 这一行里，Oracle GraalVM 只写大版本号的 `25-graal` 应该装 25.0 系列的最新构建（2026-11-03 是 `25.0.5.0.3-graal`），也就是 Oracle 官方 `25/latest` 下载跟的那个系列，而不是列在它前面的某个每月特性版本（比如 `25.4.4.1.1-graal`）。`vfox search java graal` 必须按 GraalVM 自己的版本号列出这些特性版本，25 的其他版本备注要一致，同第 5 条。从 2026 年 10 月起，Foojay 给特性版本标的是 JDK 的版本号，和 25.0 系列共用。插件以前按这个版本号命名，结果搜索里一个特性版本都没有，`25.0.4.1-graal` 也没有 LTS 备注，装上的却是 25.4.4.1.1。搜索列出的 25 的各构建会先被模拟成已安装，这样 `vfox install` 报出的就是 `PreInstall` 选中的那个，而且不会下载任何东西。GA 版本 25 不放进去，因为那样 vfox 会发现 `25-graal` 已安装，根本不会去问 `PreInstall`。在 Linux 上，安装向 Foojay 发的请求还必须和搜索的相同，同第 4 条末尾。 + + 装着这些构建时，`vfox use java@25-graal` 和写着 `java=25-graal` 的 `.sdkmanrc` 必须选中 `vfox install` 报出的那个构建。`PreUse` 和 `ParseLegacyFile` 以前选的是 25 里已安装的最新版本，所以一旦装了特性版本，选中的就是它（[#110](https://github.com/version-fox/vfox-java/issues/110)）。模拟出的每个构建里都放着一个只打印名字的替身 `java`，同第 6 条。把 25.0 系列的构建删掉之后，`vfox use` 和 `.sdkmanrc` 都必须选中最新的特性版本。 +4. 在 `tem` 这几行里（这几行在每个 runner 上都会运行），只按名字检查的发行版（`adpt` 到 `semcrt`，即 `tests/e2e/common` 里的 `nameOnly`），只要 Foojay 在这个 runner 上有它的包，都要能用简称找到：`vfox search java <简称>` 能列出它；把它列出的最新版本模拟成已安装后，`vfox install java@<大版本>-<简称>`（`22-grl17`）要报告这个版本已经安装，所以不会下载任何东西。以前没有这些简称时，这两条命令分别报 `Unsupported distribution` 和 `Could not extract a valid distribution`。 + + 同样在这几行里，Mandrel 和 Liberica NIK 要按它们沿用的 GraalVM 版本号来（`tests/e2e/common` 里的 `ownNumbers`；Windows arm64 上两者都没有）：`vfox search java mandrel` 要列出 `23.1.12-mandrel`（Liberica NIK 是 `23.1.8-nik`）；把它和搜索结果里最新的 23.x 模拟成已安装后，`vfox install java@mandrel-23.1.12` 和 `vfox install java@23-mandrel` 要报告这两个版本已经安装。2026 年 10 月 Foojay 把这个版本号挪到了 `distribution_version`，插件改读它之前，搜索结果每个 Java 大版本只列一个名字，找不到 `23.1.12-mandrel`，`java@23-mandrel` 装上的是为 Java 23 构建的 Mandrel 24.1.2。 + + 在 Linux 上，这几行和第 3 条的 `graalce` 行经由一个冒充 api.foojay.io 的替身访问 Foojay（由 `tests/e2e/linux/front` 构建），替身记下插件发出的每个请求。上面每次安装发的请求都必须和它前面那次搜索的相同（`tests/e2e/common` 里的 `AsksAsSearch`）。Foojay 的结果按请求分别缓存，新版本发布后的半小时里，换一个请求就可能装上搜索还没列出的构建，于是真的下载，检查失败（见 [foojay.md](foojay.md#插件发出的请求)）。[#113](https://github.com/version-fox/vfox-java/issues/113) 之前，只写大版本号时查的是 `latest=available`，Mandrel 和 Liberica NIK 则按 `distribution_version` 查。 +5. 固定的版本按 `PreInstall` 给它起的名字安装：请求的版本加上构建号（`21.0.8-tem` 安装为 `21.0.8+9-tem`）。`vfox search java <发行版>`（`Available` 钩子）把同一个名字列为已安装，带 JavaFX 的构建会标注 JavaFX。对 GraalVM，它还必须列出自 25.1 起每月发布的特性版本（`25.4.4.1.1-graalce`），这些版本都不标 LTS（Foojay 给其中一些标了，因为它们基于的 JDK 是 LTS）；每个版本大约只存在一个月。同一个大版本里的其他版本，备注必须一致。插件以前把特性版本 25.4.4.1.1 列成 `25.0.4.1-graalce`，没有 `25.0.2-graalce` 那样的 LTS 备注。在 Windows 上，列表里要包含 JetBrains Runtime 21.0.5，它在 Windows 上只有 tar.gz。 + + 安装本身还必须校验了下载的文件。每个默认发行版固定的版本，Foojay 在每个 runner 上都给出了校验和（2026-11-02），`vfox install` 必须打印 `Verifying checksum <摘要>...`，摘要的长度是 vfox 支持的，并且不能出现 `WARNING: Checksum is not provided, skip verify...`——在插件把 Foojay 的校验和交给 vfox 之前，每次安装最后都有这条警告。摘要有四种形式，所以插件读取它们的每种方式都会跑到：Foojay 记录里的 SHA-256 和 SHA-1（Temurin、Liberica），只有摘要的文件里的 SHA-256（OpenJDK、GraalVM 社区版），以及带着文件名的文件里的 SHA-512（JetBrains）。vfox 把摘要和下载文件的哈希值比较，对不上就让安装失败，所以安装成功就证明摘要确实是这个文件的。用 `JAVA_VERSION` 指定的版本不检查这一项，因为 Foojay 可能没有它的校验和。 +6. 在执行任何 `vfox use` 之前，`.sdkmanrc` 要能通过 `ParseLegacyFile` 选中 JDK。测试时，`vfox list java` 里排在最前面的是另一个版本的空安装（`21.0.80+1-tem`，它的版本号以固定的版本开头；vfox 按字符串降序给已安装版本排序）。以前 `ParseLegacyFile` 会把它当成第一个以该版本开头的版本，对补零的版本（见下面第二条），则当成该大版本里最新的版本。要覆盖的写法有： + - 不含构建号的 SDKMAN 标识符：`java=21.0.8-tem`、`java=21.0.5-jbr`（SDKMAN 对 JetBrains 的叫法）、`java=25.0.4.fx-librca`（它对 JavaFX 构建的写法）。 + - 补零的标识符，`sdk list java` 里有很多这样的：`java=21.0.8.0+9-tem`、`java=25.0.4.0-fx+9-librca`（Foojay 以及安装后的版本名里没有这个零）。 + - 安装后的版本名：`java=21.0.8+9-tem`。 + - EA 构建的标识符。固定大版本的 EA 构建，如果按 `sdk list java` 里 OpenJDK 的写法来写（`28.0.0.0+ea.20-open`），必须选中那个 EA 构建：`java=21.0.0.0+ea.1-tem` 要选中 `21-ea+1-tem`，不能选中 GA 版本。`ParseLegacyFile` 只认 SDKMAN 较旧的 `21.ea.1-tem` 写法时，选中的正是 GA 版本。安装后的版本名本身（`java=21-ea+1-tem`）也要能选中：`ParseLegacyFile` 以前解析不了它，什么也没选中，而 `vfox use` 是能选中的。 + + jdk.java.net 会在几周内撤掉每个 EA 构建，所以这个安装是模拟出来的：它的 `bin` 里放着一个只打印名字的替身 `java`。在 Windows 上，文件用 CRLF 换行写入。 + + 接着，在 `tem` 这几行里，`.sdkmanrc` 里写的是 SDKMAN 给 Mandrel 和 Liberica NIK 的、`.r` 后面带 JDK 版本的标识符时，要选中标识符指明的版本：`java=25.0.4.r25-nik` 选中 `25.0.4-nik`，而不是 `25.0.4.1-nik`。`ParseLegacyFile` 以前把 `25.0.4.r25` 当成版本号，选中的正是后者。`java=22.1.r11-mandrel` 则什么都不能选中，因为插件只装 Mandrel 22.1 的 JDK 17 构建（`tests/e2e/common` 里的 `OwnNumberIdentifiers`）。标识符指明的版本，以及同一大版本里更新的一个版本，也是这样模拟安装的。 +7. `vfox use --global` 之后，`PATH` 上的 JDK 要报告请求的 `java.version`、runner 的 `os.arch`（`amd64` / `aarch64`，这也能抓出在 Windows ARM64 上模拟运行的 x64 JDK）和这个发行版的 `java.vendor`。`JAVA_HOME` 指向同一个 JDK，`javac` 能编译一个程序，`java` 能运行它，模块列表恰好在 `-fx` 构建里含有 JavaFX，`vfox current java` 报告已安装的版本。事先设置的 `GRAALVM_HOME` 保持原值，因为用户会把它指向自己的 GraalVM；对 GraalVM，插件以前会把它替换成正在使用的 JDK。 +8. `PreUse` 把用户输入的各种写法映射到已安装的版本，不需要再次下载：只写大版本号（`java@21`，交给 vfox 核心做模糊匹配）、安装时用的写法（`java@21.0.8-tem`，`PreUse` 会在已安装的版本里找到它的构建号），以及 asdf 风格的 `<长名>-<版本>[-fx]`（`java@temurin-21.0.8+9` 改写成 `21.0.8+9-tem`；`java@openjdk-25.0.2+10` 改写成 `25.0.2+10`）。SDKMAN 那样补零的版本也一样（`java@21.0.8.0-tem`、`java@21.0.8.0+9-tem`），`vfox install` 必须先发现它们已经安装：`PreInstall` 把零原样交给了 Foojay，Foojay 会去掉它，而 `PreUse` 以前去找以补零版本开头的已安装版本，报告说没有安装。 + +默认矩阵对每个发行版都跑两个 vfox 渠道（`latest`、`main`）： + +| 发行版 | 版本 | 覆盖内容 | amd64 | arm64 | +| ------------ | ------- | ---------------------------------------------------------------------------- | ----- | ----- | +| `open` | 25.0.2 | 默认发行版，版本不带后缀 | ✓ | | +| `tem` | 21.0.8 | 常规路径（Linux 上是 tar.gz，Windows 上是 zip）；第 2、4、6 条里的镜像检查、按名字和按版本号的检查 | ✓ | ✓ | +| `librca-fx` | 25.0.4 | 带 JavaFX 的构建（`-fx`） | ✓ | ✓ | +| `jb` | 21.0.5 | Windows 上走 tar.gz 的路径，那里没有 zip | ✓ | ✓ | +| `graalce` | 25.0.2 | 事先设置的 `GRAALVM_HOME` 保持原值；Oracle GraalVM 的 `25-graal` | ✓ | | + +表里每一行固定的版本，在这一行要跑的每个平台上，Foojay 都有对应的包。OpenJDK 和 GraalVM 社区版没有 `windows-aarch64` 构建，所以 arm64 不管在 Linux 还是 Windows 上，都只跑另外三个。 diff --git a/docs/zh-CN/foojay.md b/docs/zh-CN/foojay.md index 033341d..f77dcc1 100644 --- a/docs/zh-CN/foojay.md +++ b/docs/zh-CN/foojay.md @@ -6,91 +6,7 @@ 你可以自己在浏览器里查。这套 API 的 [Swagger UI](https://api.foojay.io/swagger-ui) 列出了所有接口，规范文件是 [foojay-discoapi-3.0.yml](https://api.foojay.io/swagger/foojay-discoapi-3.0.yml)。打开 `GET /disco/v3.0/packages/jdks`，点“Try it out”，填好参数再点“Execute”，页面会给出实际执行的 `curl` 命令和返回的 JSON。 -## 插件发出的请求 - -在 Linux x64 上执行 `vfox install java@21.0.8-tem`，发出的请求是： - -``` -https://api.foojay.io/disco/v3.0/packages/jdks - ?version=21.0.8 - &distribution=temurin - &architecture=amd64 - &archive_type=tar.gz - &operating_system=linux - &lib_c_type=glibc - &directly_downloadable=true -``` - -| 参数 | 取值 | -| --- | --- | -| `distribution` | 发行版的长名，见 [distributions.md](distributions.md) | -| `version` | `vfox search` 时和只写大版本号（如 `21`）时为空，否则是你输入内容里的版本部分。`+` 会做百分号编码，因为 Foojay 会把没编码的 `+` 当成空格，进而丢掉构建号。`28.ea.19` 会变成 `28-ea+19`。查 Mandrel、Liberica NIK，以及 Oracle GraalVM 和 GraalVM 社区版的 GA 版本时始终为空 | -| `architecture` | arm64 用 `aarch64`，Windows x64 用 `x64`，其他系统的 x64 用 `amd64`，其他 CPU 用 vfox 报告的名字 | -| `operating_system` | `linux`、`macos` 或 `windows` | -| `archive_type` | `tar.gz`；Windows 上是 `zip` 加 `tar.gz`。其他系统上，Red Hat 还要 `tar.xz`，OJDKBuild、OpenLogic 和 Gluon GraalVM 还要 `zip` | -| `lib_c_type` | Linux 上是 `glibc` 或 `musl`，其他系统为空 | -| `directly_downloadable` | 始终是 `true` | - -只写大版本号（如 `21`）时，返回结果里有全部版本，由插件自己挑出最新的 21.x，`java@21-tem` 装的就是它：`version=21` 只会匹配 21 的 GA 构建（`21+35`）。更具体的版本则按原样匹配。 - -只写大版本号时和搜索发同一个请求，这样安装时看到的构建和 `vfox search` 列出的才一致。Foojay 的结果按请求分别缓存，不同的请求拿到的结果可能新旧不一：2026-10-20 Oracle GraalVM 25.0.5 上了 Foojay 半小时后，GitHub 的 runner 用 `distribution_version=25` 查已经有它，搜索的结果里却还没有，`vfox install java@25-graal` 装上了 `vfox search java graal` 没有列出的构建（[#113](https://github.com/version-fox/vfox-java/issues/113)）。 - -返回的是一个包列表。插件用 `java_version` 给版本命名（Mandrel 和 Liberica NIK 用 `distribution_version`，Oracle GraalVM 和 GraalVM 社区版用 GraalVM 自己的版本号）；`javafx_bundled` 为真时加上 `-fx`；`term_of_support` 是 `lts` 时标注 LTS；在 Windows 上，同一版本既有 `zip` 又有 `tar.gz` 时优先用 `zip`。Foojay 混在 OJDKBuild 的 Windows JDK 里的 JRE、installer bundle 包和 RHEL 6 构建，以及 Gluon GraalVM 22.x 的 JDK 11 构建，插件都会略过，见 [distributions.md](distributions.md)。安装时，插件再取这个包的 `links.pkg_info_uri`，并从其中的 `direct_download_uri` 下载，那是厂商自己的服务器（Temurin 是 GitHub Releases）。同一条记录还说明了怎么校验下载的文件，见[校验和](#校验和)。从 GitHub 下载时可以经过镜像，见 [mirror.md](mirror.md)。 - -`vfox search` 与原始列表有几处不同：Foojay 里同一个名字有两条记录时，它只列一次；不给 GraalVM 的特性版本加 LTS 备注（见 [distributions.md](distributions.md#oracle-graalvm-与-graalvm-社区版的行为)）；只列 GA 版本。 - -### Mandrel 与 Liberica NIK - -截至 2026-10-20，这两个发行版沿用的 GraalVM 版本号，Foojay 放在 `distribution_version` 里，Java 的版本号放在 `java_version` 里，其中 Mandrel 的 `java_version` 只有大版本号： - -```bash -curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=mandrel&distribution_version=23.1.12&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ - | jq -r '.result[] | [.java_version, .distribution_version, .filename] | @tsv' -``` - -``` -21 23.1.12.1 mandrel-java21-linux-amd64-23.1.12.1-Final.tar.gz -21 23.1.12 mandrel-java21-linux-amd64-23.1.12.0-Final.tar.gz -``` - -所以插件像 `vfox search` 那样查出这两个发行版的全部包，再按 `distribution_version` 自己挑：写得具体时挑指定的那个版本，只写大版本号时挑这个大版本里最新的。Foojay 自己的匹配两样都做不到：如上所示，查 `distribution_version=23.1.12` 也会返回 23.1.12.1；查 `distribution_version=23` 并加上 `latest=available` 时，返回的是 23.1.8 和 23.0.1.2 的两个构建，而 23.1.12.1 已经发布。同一个版本有几个 Java 版本的构建时，插件取 Java 最新的那个；Liberica NIK 为同一个 Java 构建了两次时，取后一次的，两次构建只能从文件名里区分（`...-25.0.3+2-linux-amd64.tar.gz`）。搜索时按 `distribution_version` 从新到旧排列。 - -## 校验和 - -`links.pkg_info_uri` 指向的那条记录还说明了怎么校验下载的文件。`checksum_type` 是算法，摘要要么就在记录里（`checksum`），要么在厂商的一个文件里，由 `checksum_uri` 指向。GraalVM 社区版 25.0.2 只有这个文件（2026-11-02）： - -```bash -curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=graalvm_community&version=25.0.2&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ - | jq -r '.result[0].links.pkg_info_uri' | xargs curl -s | jq -c '.result[0] | {checksum_type, checksum, checksum_uri}' -``` - -``` -{"checksum_type":"sha256","checksum":"","checksum_uri":"https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-25.0.2/graalvm-community-jdk-25.0.2_linux-x64_bin.tar.gz.sha256"} -``` - -Temurin 的记录里直接带着摘要（Linux x64 上的 21.0.8 是 `f2dc5418...9219`），旁边还有厂商那个文件的地址。 - -插件把摘要以算法的名字交给 vfox（`PreInstall` 返回的表里写成 `sha256 = "..."`）。vfox 在解压任何东西之前，先算出下载文件的摘要，再和它比较：打印 `Verifying checksum e0be791c...` 然后继续，或者以 `Checksum error` 终止，见 [troubleshooting.md](troubleshooting.md#checksum-error)。vfox 校验 `sha256`、`sha512`、`sha1` 和 `md5`，这四种在包里都有。Foojay 还写过别的算法（`sha3_256`），vfox 不能校验它们。 - -记录里自带的摘要优先。它来自 Foojay，而不是厂商的下载站（那可能是个镜像），也不需要再发请求。只有记录里没有摘要时，插件才去取那个文件，GitHub 上的文件和下载一样经过镜像（[mirror.md](mirror.md)）。这些文件写摘要的格式并不统一，插件能读三种： - -- 只有摘要（GraalVM 社区版、OpenJDK、Oracle）， -- `sha256sum` 的 `<摘要> <文件名>`，二进制文件的文件名前有个 `*`（Microsoft、JetBrains、Semeru、SAP Machine）， -- BSD 的 `MD5 (<文件名>) = <摘要>`（腾讯 Kona）。 - -文件里列了好几个包时，取正在安装的那个包的那一行。只列了别的包的文件不给出摘要：Microsoft 为 macOS 上 11.0.14 的 EA 构建发布的文件，里面写的是 GA 构建，那个摘要会让本来没问题的安装失败。 - -哪些包带校验和因版本而异，有些发行版 Foojay 根本没有。各发行版最新的版本（2026-11-02）： - -| Foojay 给出的 | 简称 | -| --- | --- | -| 记录里的摘要 | `tem`、`zulu`、`librca`、`nik`、`eliya`、`rdht`、25 起的 `mandrel`、最新的 `graal` 和 `graalce` | -| 厂商的一个文件 | `open`、`oracle`、`ms`、`sapmchn`、`sem`、`semcrt`、`jb`、`kona`、`ojdkbld`、`grl8`、`grl11`、`grl16`、`grl17`、`grl19`、较旧的 `graal` 和 `graalce`，以及 Corretto 8（`amzn`） | -| 没有校验和 | `albba`、`bsg`、`trava`、`adpt`、`adptj9`、`gln`、`opnlgc`、Corretto 8 以外的 `amzn`，以及其余发行版里较旧的版本 | - -没有校验和的包，vfox 会打印 `WARNING: Checksum is not provided, skip verify...`，下载内容照单全收。 - -Foojay 给出的校验和插件用不上时，安装照常进行，只是不校验，和插件还不读校验和的时候一样，并且会说明原因：`Cannot verify the download: https://example.org/x.tar.gz.sha256 has no digest for x.tar.gz`。可能是文件打不开，可能是里面没有这个包的摘要，也可能是 vfox 不校验的算法。拿不到校验和，不会拦下安装；下载的文件和校验和对不上，则会。链接和校验和都是 Foojay 给的，所以这个检查能发现损坏或被替换的文件，发现不了记录本身有误。 +下面的示例用了 `curl` 和 `jq`，你可能需要自己安装，任何 JSON 工具都可以。有些 HTTP 客户端用默认 User-Agent 访问 Foojay 会得到 `403`，比如 Python 的 `urllib`。`curl` 不会，vfox 也不会。插件自己向 Foojay 问了什么，见[插件发出的请求](#插件发出的请求)，怎样校验下载的文件，见[校验和](#校验和)。 ## 我的平台上有哪些发行版 @@ -120,7 +36,7 @@ zulu | macOS Intel | `architecture=amd64&operating_system=macos&archive_type=tar.gz` | | Windows x64 | `architecture=x64&operating_system=windows&archive_type=zip&archive_type=tar.gz` | -返回结果里的名字就是 [distributions.md](distributions.md) 里的长名，只有 `oracle_open_jdk` 例外，插件里叫它 `openjdk`（`open`）。只写 `archive_type=tar.gz` 时，结果里会缺 Linux 上的 Red Hat 和 OJDKBuild、macOS 上的 OpenLogic，因为它们在那里提供的是 tar.xz 或 zip 包。插件会为它们额外请求这些格式，见上面的表。 +返回结果里的名字就是 [distributions.md](distributions.md) 里的长名，只有 `oracle_open_jdk` 例外，插件里叫它 `openjdk`（`open`）。只写 `archive_type=tar.gz` 时，结果里会缺 Linux 上的 Red Hat 和 OJDKBuild、macOS 上的 OpenLogic，因为它们在那里提供的是 tar.xz 或 zip 包。插件会为它们额外请求这些格式，见[插件发出的请求](#插件发出的请求)。 ## 我的平台上哪些发行版有某个版本 @@ -130,7 +46,7 @@ curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?version=27&latest=availa | jq -r '.result[].distribution' | sort -u ``` -2026-10-18 运行这条命令，打印的是 `corretto liberica oracle semeru zulu`。Temurin 和 OpenJDK 不在其中：它们在 Intel Mac 上停在了 26。只写大版本号时像插件一样加上 `latest=available`，写更具体的版本时就不要加。 +2026-11-03 运行这条命令，打印的是 `corretto liberica oracle semeru zulu`。Temurin 和 OpenJDK 不在其中：它们在 Intel Mac 上停在了 26。只写大版本号时像插件一样加上 `latest=available`，写更具体的版本时就不要加。 ## 某个发行版的所有版本 @@ -159,7 +75,7 @@ curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&ver {"java_version":"21.0.8+9","distribution_version":"21.0.8","term_of_support":"lts","javafx_bundled":false,"archive_type":"tar.gz","filename":"OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz"} ``` -`java_version` 是 Java 的版本号，插件用的就是它。`distribution_version` 是厂商自己的版本号（Java `27+35` 对应 Zulu 的 `27.28.101`），插件对 Mandrel 和 Liberica NIK 用它（见[上文](#mandrel-与-liberica-nik)），对 Oracle GraalVM 和 GraalVM 社区版也用它。 +`java_version` 是 Java 的版本号，插件用的就是它。`distribution_version` 是厂商自己的版本号（Java `27+35` 对应 Zulu 的 `27.28.101`），插件对 Mandrel 和 Liberica NIK 用它（见[下文](#mandrel-与-liberica-nik)），对 Oracle GraalVM 和 GraalVM 社区版也用它。 从 2026 年 10 月起，Oracle GraalVM 和 GraalVM 社区版的 `distribution_version` 是 GraalVM 自己的版本号，`java_version` 则是 JDK 的版本号，而每月的特性版本和 25.0 系列的某个构建会共用同一个 JDK 版本号： @@ -186,9 +102,93 @@ curl -s 'https://api.foojay.io/disco/v3.0/major_versions?ea=false&ga=true&mainta 列出仍在维护的各个大版本，以及每个是 LTS 还是 STS。EA 构建要用 `release_status=ea`，或者像 `version=28-ea` 这样明确写出版本。 +## 插件发出的请求 + +在 Linux x64 上执行 `vfox install java@21.0.8-tem`，发出的请求是： + +``` +https://api.foojay.io/disco/v3.0/packages/jdks + ?version=21.0.8 + &distribution=temurin + &architecture=amd64 + &archive_type=tar.gz + &operating_system=linux + &lib_c_type=glibc + &directly_downloadable=true +``` + +| 参数 | 取值 | +| --- | --- | +| `distribution` | 发行版的长名，见 [distributions.md](distributions.md) | +| `version` | `vfox search` 时和只写大版本号（如 `21`）时为空，否则是你输入内容里的版本部分。`+` 会做百分号编码，因为 Foojay 会把没编码的 `+` 当成空格，进而丢掉构建号。`28.ea.19` 会变成 `28-ea+19`。查 Mandrel、Liberica NIK，以及 Oracle GraalVM 和 GraalVM 社区版的 GA 版本时始终为空 | +| `architecture` | arm64 用 `aarch64`，Windows x64 用 `x64`，其他系统的 x64 用 `amd64`，其他 CPU 用 vfox 报告的名字 | +| `operating_system` | `linux`、`macos` 或 `windows` | +| `archive_type` | `tar.gz`；Windows 上是 `zip` 加 `tar.gz`。其他系统上，Red Hat 还要 `tar.xz`，OJDKBuild、OpenLogic 和 Gluon GraalVM 还要 `zip` | +| `lib_c_type` | Linux 上是 `glibc` 或 `musl`，其他系统为空 | +| `directly_downloadable` | 始终是 `true` | + +只写大版本号（如 `21`）时，返回结果里有全部版本，由插件自己挑出最新的 21.x，`java@21-tem` 装的就是它：`version=21` 只会匹配 21 的 GA 构建（`21+35`）。更具体的版本则按原样匹配。 + +只写大版本号时和搜索发同一个请求，这样安装时看到的构建和 `vfox search` 列出的才一致。Foojay 的结果按请求分别缓存，不同的请求拿到的结果可能新旧不一：2026-10-20 Oracle GraalVM 25.0.5 上了 Foojay 半小时后，GitHub 的 runner 用 `distribution_version=25` 查已经有它，搜索的结果里却还没有，`vfox install java@25-graal` 装上了 `vfox search java graal` 没有列出的构建（[#113](https://github.com/version-fox/vfox-java/issues/113)）。 + +返回的是一个包列表。插件用 `java_version` 给版本命名（Mandrel 和 Liberica NIK 用 `distribution_version`，Oracle GraalVM 和 GraalVM 社区版用 GraalVM 自己的版本号）；`javafx_bundled` 为真时加上 `-fx`；`term_of_support` 是 `lts` 时标注 LTS；在 Windows 上，同一版本既有 `zip` 又有 `tar.gz` 时优先用 `zip`。Foojay 混在 OJDKBuild 的 Windows JDK 里的 JRE、installer bundle 包和 RHEL 6 构建，以及 Gluon GraalVM 22.x 的 JDK 11 构建，插件都会略过，见 [distributions.md](distributions.md)。安装时，插件再取这个包的 `links.pkg_info_uri`，并从其中的 `direct_download_uri` 下载，那是厂商自己的服务器（Temurin 是 GitHub Releases）。同一条记录还说明了怎么校验下载的文件，见[校验和](#校验和)。从 GitHub 下载时可以经过镜像，见 [mirror.md](mirror.md)。 + +`vfox search` 与原始列表有几处不同：Foojay 里同一个名字有两条记录时，它只列一次；不给 GraalVM 的特性版本加 LTS 备注（见 [distributions.md](distributions.md#oracle-graalvm-与-graalvm-社区版的行为)）；只列 GA 版本。 + +### Mandrel 与 Liberica NIK + +截至 2026-10-20，这两个发行版沿用的 GraalVM 版本号，Foojay 放在 `distribution_version` 里，Java 的版本号放在 `java_version` 里，其中 Mandrel 的 `java_version` 只有大版本号： + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=mandrel&distribution_version=23.1.12&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[] | [.java_version, .distribution_version, .filename] | @tsv' +``` + +``` +21 23.1.12.1 mandrel-java21-linux-amd64-23.1.12.1-Final.tar.gz +21 23.1.12 mandrel-java21-linux-amd64-23.1.12.0-Final.tar.gz +``` + +所以插件像 `vfox search` 那样查出这两个发行版的全部包，再按 `distribution_version` 自己挑：写得具体时挑指定的那个版本，只写大版本号时挑这个大版本里最新的。Foojay 自己的匹配两样都做不到：如上所示，查 `distribution_version=23.1.12` 也会返回 23.1.12.1；查 `distribution_version=23` 并加上 `latest=available` 时，返回的是 23.1.8 和 23.0.1.2 的两个构建，而 23.1.12.1 已经发布。同一个版本有几个 Java 版本的构建时，插件取 Java 最新的那个；Liberica NIK 为同一个 Java 构建了两次时，取后一次的，两次构建只能从文件名里区分（`...-25.0.3+2-linux-amd64.tar.gz`）。搜索时按 `distribution_version` 从新到旧排列。 + +## 校验和 + +`links.pkg_info_uri` 指向的那条记录还说明了怎么校验下载的文件。`checksum_type` 是算法，摘要要么就在记录里（`checksum`），要么在厂商的一个文件里，由 `checksum_uri` 指向。GraalVM 社区版 25.0.2 只有这个文件（2026-11-02）： + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=graalvm_community&version=25.0.2&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[0].links.pkg_info_uri' | xargs curl -s | jq -c '.result[0] | {checksum_type, checksum, checksum_uri}' +``` + +``` +{"checksum_type":"sha256","checksum":"","checksum_uri":"https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-25.0.2/graalvm-community-jdk-25.0.2_linux-x64_bin.tar.gz.sha256"} +``` + +Temurin 的记录里直接带着摘要（Linux x64 上的 21.0.8 是 `f2dc5418...9219`），旁边还有厂商那个文件的地址。 + +插件把摘要以算法的名字交给 vfox（`PreInstall` 返回的表里写成 `sha256 = "..."`）。vfox 在解压任何东西之前，先算出下载文件的摘要，再和它比较：打印 `Verifying checksum e0be791c...` 然后继续，或者以 `Checksum error` 终止，见 [troubleshooting.md](troubleshooting.md#checksum-error)。vfox 校验 `sha256`、`sha512`、`sha1` 和 `md5`，这四种在包里都有。Foojay 还写过别的算法（`sha3_256`），vfox 不能校验它们。 + +记录里自带的摘要优先。它来自 Foojay，而不是厂商的下载站（那可能是个镜像），也不需要再发请求。只有记录里没有摘要时，插件才去取那个文件，GitHub 上的文件和下载一样经过镜像（[mirror.md](mirror.md)）。这些文件写摘要的格式并不统一，插件能读三种： + +- 只有摘要（GraalVM 社区版、OpenJDK、Oracle）， +- `sha256sum` 的 `<摘要> <文件名>`，二进制文件的文件名前有个 `*`（Microsoft、JetBrains、Semeru、SAP Machine）， +- BSD 的 `MD5 (<文件名>) = <摘要>`（腾讯 Kona）。 + +文件里列了好几个包时，取正在安装的那个包的那一行。只列了别的包的文件不给出摘要：Microsoft 为 macOS 上 11.0.14 的 EA 构建发布的文件，里面写的是 GA 构建，那个摘要会让本来没问题的安装失败。 + +哪些包带校验和因版本而异，有些发行版 Foojay 根本没有。各发行版最新的版本（2026-11-02）： + +| Foojay 给出的 | 简称 | +| --- | --- | +| 记录里的摘要 | `tem`、`zulu`、`librca`、`nik`、`eliya`、`rdht`、25 起的 `mandrel`、最新的 `graal` 和 `graalce` | +| 厂商的一个文件 | `open`、`oracle`、`ms`、`sapmchn`、`sem`、`semcrt`、`jb`、`kona`、`ojdkbld`、`grl8`、`grl11`、`grl16`、`grl17`、`grl19`、较旧的 `graal` 和 `graalce`，以及 Corretto 8（`amzn`） | +| 没有校验和 | `albba`、`bsg`、`trava`、`adpt`、`adptj9`、`gln`、`opnlgc`、Corretto 8 以外的 `amzn`，以及其余发行版里较旧的版本 | + +没有校验和的包，vfox 会打印 `WARNING: Checksum is not provided, skip verify...`，下载内容照单全收。 + +Foojay 给出的校验和插件用不上时，安装照常进行，只是不校验，和插件还不读校验和的时候一样，并且会说明原因：`Cannot verify the download: https://example.org/x.tar.gz.sha256 has no digest for x.tar.gz`。可能是文件打不开，可能是里面没有这个包的摘要，也可能是 vfox 不校验的算法。拿不到校验和，不会拦下安装；下载的文件和校验和对不上，则会。链接和校验和都是 Foojay 给的，所以这个检查能发现损坏或被替换的文件，发现不了记录本身有误。 + ## 补充说明 -- 有些 HTTP 客户端用默认 User-Agent 访问 Foojay 会得到 `403`，比如 Python 的 `urllib`。`curl` 不会，vfox 也不会。 -- 示例里用了 `jq`，你可能需要自己安装。任何 JSON 工具都可以。 - vfox 会缓存 `vfox search` 的结果 12 小时，所以 Foojay 上的变化最多要隔这么久才会出现。 - 数据本身的问题，比如缺少某个构建或标记有误，请向 [Foojay](https://github.com/foojayio/discoapi) 反馈。插件读取数据的方式有问题，请在本仓库提 issue。 diff --git a/docs/zh-CN/install-from-source.md b/docs/zh-CN/install-from-source.md index eee1e6c..64d3908 100644 --- a/docs/zh-CN/install-from-source.md +++ b/docs/zh-CN/install-from-source.md @@ -40,7 +40,7 @@ vfox use --global java@21-tem java -version ``` -`vfox install java@21-tem` 装的是最新的 Temurin 21，截至 2026-10-18 是 `21.0.12.1+1-tem`。 +`vfox install java@21-tem` 装的是最新的 Temurin 21，截至 2026-11-03 是 `21.0.13+9-tem`。 ## 已经添加过 java 时 diff --git a/docs/zh-CN/javafx.md b/docs/zh-CN/javafx.md index 9f9a60a..3f0f7f1 100644 --- a/docs/zh-CN/javafx.md +++ b/docs/zh-CN/javafx.md @@ -33,7 +33,7 @@ java --list-modules | grep javafx ## 哪些平台有 JavaFX 构建 -截至 2026-10-20，提供 JavaFX 构建的发行版有四个，而且并非每个平台都有。下表列出有 JavaFX 构建的 LTS 版本，中间的非 LTS 版本也有一些，但有缺口。Liberica NIK 一行写的是 Java 版本，不是它名字里的 GraalVM 版本号（见 [distributions.md](distributions.md#mandrel-与-liberica-nik-的行为)）：它为 Java 21 提供的 JavaFX 构建是 `23.1.x-nik-fx`。 +截至 2026-11-03，提供 JavaFX 构建的发行版有四个，而且并非每个平台都有。下表列出有 JavaFX 构建的 LTS 版本，中间的非 LTS 版本也有一些，但有缺口。Liberica NIK 一行写的是 Java 版本，不是它名字里的 GraalVM 版本号（见 [distributions.md](distributions.md#mandrel-与-liberica-nik-的行为)）：它为 Java 21 提供的 JavaFX 构建是 `23.1.x-nik-fx`。 | 发行版 | Linux x64 | Linux arm64 | Alpine x64 | macOS Intel | macOS Apple Silicon | Windows x64 | Windows arm64 | | --- | --- | --- | --- | --- | --- | --- | --- | diff --git a/docs/zh-CN/mirror.md b/docs/zh-CN/mirror.md index 93c8009..19b6bb0 100644 --- a/docs/zh-CN/mirror.md +++ b/docs/zh-CN/mirror.md @@ -39,7 +39,7 @@ $env:VFOX_JAVA_GITHUB_MIRROR = "https://gh-proxy.org/" 只有以 `https://github.com/` 开头的请求：下载，以及插件为这些下载去读的 GitHub 上的校验和文件（见[补充说明](#补充说明)）。其他主机上的 JDK 照旧从那里下载，向 Foojay 发的请求也不变。 -Foojay 给各发行版的链接（2026-10-21）： +Foojay 给各发行版的链接（2026-11-03）： | 简称 | 下载来源 | | --- | --- | diff --git a/docs/zh-CN/native-image.md b/docs/zh-CN/native-image.md new file mode 100644 index 0000000..32cad04 --- /dev/null +++ b/docs/zh-CN/native-image.md @@ -0,0 +1,34 @@ +# Native Image 与 C 工具链 + +[中文](native-image.md) | [English](../native-image.md) + +GraalVM 的安装和使用与别的 JDK 没有两样：`vfox install java@25.0.2-graalce` 和 `vfox use` 之后，`java` 和 `javac` 在没有编译器、也没有 zlib 头文件的系统上照常工作。只有 `native-image` 还需要更多的东西。它是把程序编译成原生可执行文件的工具，会用系统的 `gcc` 把可执行文件与 C 库和 zlib 链接起来，所以需要它们；调用它的程序同样需要，比如 Native Image 的 Maven 和 Gradle 插件。插件只安装 JDK，不装别的，而最小化的 Ubuntu（比如它的容器镜像）既没有编译器，也没有 zlib 的头文件。 + +`native-image` 在 Oracle GraalVM、GraalVM 社区版、Liberica NIK、Mandrel 和 Gluon GraalVM 的 `bin` 目录里。GraalVM CE 8 到 19 是例外，见[下文](#graalvm-ce-8-到-19)。 + +## Ubuntu + +在 Ubuntu 26.04 的 Bash 中执行，第一次构建原生镜像之前装一次即可： + +```bash +sudo apt install --assume-yes build-essential zlib1g-dev +``` + +没有这些包时： + +- 没有 `gcc` 时，构建几秒内就停下，报 `Error: Default native-compiler executable 'gcc' not found via environment variable PATH`，只装 `zlib1g-dev` 也没用。 +- 有 `gcc` 却没有 `zlib1g-dev` 时（只装了 `build-essential` 也是这种情况），构建会先走完分析和编译（hello world 用了 20 秒到两分钟），到链接时才失败：`There was an error linking the native image: Linker command exited with 1`，GraalVM 自己的提示 `It appears as though libz:.a is missing. Please install it.`，以及 `cannot find -lz: No such file or directory`。 + +构建一个 hello world，`gcc`、`libc6-dev` 和 `zlib1g-dev` 就够了，用不着 `g++` 和 `make`。`build-essential` 把这两个也装上，GraalVM 的文档列出的正是它。 + +## 其他系统 + +其他系统需要的包不一样。GraalVM 的[前置条件](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites)里，Fedora 和其他使用 dnf 的系统是 `sudo dnf install gcc glibc-devel zlib-devel libstdc++-static`，macOS 是 `xcode-select --install`，Windows 是带 Windows SDK 的 Visual Studio Build Tools。在 Fedora 44 上，只装 `gcc`、`glibc-devel` 和 `zlib-devel`、不装 `libstdc++-static`，也构建出了 hello world。 + +## GraalVM CE 8 到 19 + +GraalVM CE 8 到 19（`grl8`、`grl11`、`grl16`、`grl17`、`grl19`）不带 `native-image`。它们的 `bin` 目录里只有 GraalVM 更新器 `gu`，`native-image` 会报 `command not found`，要先用 `gu install native-image` 从 GitHub 添加。2026-11-02 这在 `22.3.3-grl11`、`21.2-grl16`、`22.3.3-grl17` 和 `22.3.1-grl19` 上成功了，添加之后仍然需要上面的包。`21.3.1-grl8` 上失败了，报 `Internal error occurred: A JSONObject text must begin with '{'`：这个 `gu` 下载的版本索引 `https://oca.opensource.oracle.com/gds/meta-data.json` 现在返回的是一个网页。对这个版本，请从 [`vm-21.3.1` 发布页](https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.1)下载 `native-image-installable-svm-java8-linux-amd64-21.3.1.jar`，再对这个文件执行 `gu -L install`。 + +## 检查过的环境 + +2026-11-02 用 vfox 1.0.13 在没有编译器的 Ubuntu 26.04 容器镜像（x64）里检查过：GraalVM 社区版 25.0.2 和 25.4.4.1.1、Oracle GraalVM 25.0.5、Mandrel 25.0.5、Liberica NIK 25.0.4.1 和 Gluon GraalVM 22.1.0.1，没有这些包时都如上所述停下，装上之后都构建出了能运行的 hello world。`22.3.3-grl17` 在执行 `gu install native-image` 之后也是如此，GraalVM 社区版 25.0.2 在 Fedora 44 的镜像里也一样。 diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md index 899f2de..f3e3577 100644 --- a/docs/zh-CN/platforms.md +++ b/docs/zh-CN/platforms.md @@ -8,7 +8,7 @@ No JDK found for 21-bsg on darwin/arm64. Please check available versions with 'vfox search java' ``` -下表列出各发行版有哪些平台的包，数据取自 2026-10-18 的 Foojay，从 AdoptOpenJDK 起的各行是 2026-10-20 补上的。✅ 表示 Foojay 在这个平台上至少列有一个插件能安装的包，❌ 表示一个也没有。 +下表列出各发行版有哪些平台的包，数据取自 2026-11-03 的 Foojay。✅ 表示 Foojay 在这个平台上至少列有一个插件能安装的包，❌ 表示一个也没有。 | 发行版 | Linux x64 | Linux arm64 | Alpine x64 | Alpine arm64 | macOS Intel | macOS Apple Silicon | Windows x64 | Windows arm64 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | @@ -50,21 +50,15 @@ Foojay 的数据会变，这张表也会过时。想看当前的情况，按 [fo ## 只有部分版本 -标了 ✅ 也不代表所有版本都有。以下同样截至 2026-10-18： +标了 ✅ 也不代表所有版本都有。以下截至 2026-11-03： -- Windows ARM64 上，没有任何发行版提供 Java 8。Temurin 有 21 和 23，Zulu 有 16 到 19、21 和 25，Liberica 有 11 和 16 到 27，Microsoft 有 11、16、17、21 和 25，JetBrains Runtime 有 17、21 和 25。 -- Apple Silicon 上，Java 8 来自 Zulu、Liberica、Corretto 和 Kona。Temurin 和 Semeru 在那里有 11 和 17 到 27，OpenJDK 有 17 到 27。Mandrel 有 23.1 到 25 的版本，运行 Java 21 到 25；Liberica NIK 有 22.2 到 25 的版本，运行 Java 11、17 和 20 到 25（见[它们的版本号](distributions.md#mandrel-与-liberica-nik-的行为)）。 +- Windows ARM64 上，没有任何发行版提供 Java 8。Temurin 有 21 和 23，Zulu 有 16 到 19、21、25 和 27，Liberica 有 11 和 16 到 27，Microsoft 有 11、16、17、21 和 25，JetBrains Runtime 有 17、21 和 25。 +- Apple Silicon 上，Java 8 来自 Zulu、Liberica、Corretto 和 Kona。Temurin 和 Semeru 在那里有 11 和 17 到 27，OpenJDK 有 17 到 27。Mandrel 有 23.1 到 25 的版本，运行 Java 21 到 25；Liberica NIK 有 22.2 到 25 的版本，运行 Java 11、17 和 20 到 25（见[它们的版本号](distributions.md#mandrel-与-liberica-nik-的行为)）。Gluon GraalVM 有 22.1.0.1 和 23+25，GraalVM CE 11 和 17 有 GraalVM 22.1 到 22.3.1，GraalVM CE 19 有 22.3 和 22.3.1。 - Intel Mac 上的新版本来得更晚，有的干脆没有。OpenJDK 和 Temurin 停在 26，而 Linux 上已有 27；SapMachine 停在 24；Oracle GraalVM 和 GraalVM 社区版停在 25.0.1。Mandrel 没有 Intel Mac 的构建。 -- 在 Alpine 上，Temurin 的 arm64 构建只有 21 及以后。x64 方面，Microsoft 只有 11 和 17，SapMachine 有 17 和 20 到 27，Kona 有 8 和 21，Dragonwell 有 11、17、21 和 25，JetBrains Runtime 只有 17。arm64 方面，Kona 有 Java 8，JetBrains Runtime 有 17（x64 也有）。 -- Trava 在 Linux arm64 上只有一个构建，11.0.10+6。 -- 带 JavaFX 的构建覆盖的平台比不带的少，见 [javafx.md](javafx.md#哪些平台有-javafx-构建)。 - -2026-10-20 补上的那些行，截至当天： - -- AdoptOpenJDK 的 Alpine x64 构建只有 HotSpot 版的 Java 16，OpenJ9 版在 Linux arm64 上只有 8、11、15 和 16。 -- OJDKBuild 在 Linux 上只有 Java 8 和 11。 +- 在 Alpine 上，Temurin 的 arm64 构建只有 21 及以后。x64 方面，Microsoft 只有 11 和 17，SapMachine 有 17 和 20 到 27，Kona 有 8 和 21，Dragonwell 有 11、17、21 和 25，JetBrains Runtime 只有 17。arm64 方面，Kona 有 Java 8，JetBrains Runtime 有 17（x64 也有）。AdoptOpenJDK 的 Alpine x64 构建只有 HotSpot 版的 Java 16。 +- Trava 在 Linux arm64 上只有一个构建，11.0.10+6。AdoptOpenJDK 的 OpenJ9 版在 Linux arm64 上只有 8、11、15 和 16，OJDKBuild 在 Linux 上只有 Java 8 和 11。 - Red Hat 的构建只有 Linux x64 能下载，也就是表里它唯一的 ✅。Foojay 还列了几个 Linux arm64 的和一个 Windows 的，`vfox search` 也会列出来，但下载都返回 404。 -- Apple Silicon 上，Gluon GraalVM 有 22.1.0.1 和 23+25，GraalVM CE 11 和 17 有 GraalVM 22.1 到 22.3.1，GraalVM CE 19 有 22.3 和 22.3.1。 +- 带 JavaFX 的构建覆盖的平台比不带的少，见 [javafx.md](javafx.md#哪些平台有-javafx-构建)。 ## 哪些只有 x64 @@ -86,7 +80,7 @@ vfox 除了 x64、arm64 和 loong64，还发布 32 位 x86 和 32 位 ARM 的二 - 32 位 x86 Linux：Corretto、Liberica、Zulu 和 JetBrains Runtime，以及 OpenLogic 的 Java 8。 - Foojay 不认识 loong64，Linux loong64 改用 Loongnix，见 [loongnix.md](loongnix.md)。 -如果你自己为 riscv64、ppc64le 或 s390x 编译 vfox：Foojay 列有 riscv64 包的是 Dragonwell、Liberica 和 Temurin，ppc64le 的是 Liberica、SapMachine、Semeru 和 Temurin，s390x 的是 Semeru 和 Temurin。2026-10-20 补上的发行版里，AdoptOpenJDK（HotSpot 版和 OpenJ9 版都有）和 Semeru 认证版有 ppc64le 和 s390x 的包，Red Hat 的 ppc64le 记录下载返回 404。 +如果你自己为 riscv64、ppc64le 或 s390x 编译 vfox：Foojay 列有 riscv64 包的是 Dragonwell、Liberica 和 Temurin，ppc64le 的是 AdoptOpenJDK（HotSpot 版和 OpenJ9 版）、Liberica、SapMachine、Semeru、Semeru 认证版和 Temurin，s390x 的是 AdoptOpenJDK（两个版本）、Semeru、Semeru 认证版和 Temurin。Red Hat 也有 ppc64le 的记录，但下载返回 404。 ## macOS 上的 Java home diff --git a/docs/zh-CN/sdkman.md b/docs/zh-CN/sdkman.md index 55eac5c..e505976 100644 --- a/docs/zh-CN/sdkman.md +++ b/docs/zh-CN/sdkman.md @@ -39,8 +39,8 @@ ## 差别 - **标识符。** SDKMAN 的 `21.0.8-tem` 原样写在 `java@` 后面，简称也沿用 SDKMAN 的，只有少数例外，比如 JetBrains Runtime 在 SDKMAN 里叫 `jbr`，这里是 `jb`，见 [distributions.md](distributions.md#简称与-sdkman-的不同)。SDKMAN 现在的标识符会给版本补一个零（`25.0.5.0+8-tem`），这样的写法也能识别。JavaFX 是放在最后的 `-fx`，即 `21.0.12-zulu-fx`。SDKMAN 的 `21.0.12.fx-zulu` 不是 `vfox install` 接受的写法，不过 `.sdkmanrc` 里可以写，见 [sdkmanrc.md](sdkmanrc.md#sdkman-的写法)。 -- **只写大版本号。** `vfox install java@21-tem` 装的是最新的 Temurin 21，2026-11-02 是 `21.0.13+9-tem`。SDKMAN 的 `21-tem` 只是一个版本，即 GA 构建 `21+35`。 -- **没有默认 JDK。** `sdk install java` 装的是 SDKMAN 的默认版本，一个 Temurin 的 LTS 版本（2026-11-02 是 `25.0.5.0+8-tem`）。`vfox install java` 没有默认值：在终端里它会让你选一个版本，在脚本里则直接失败。只写版本不写发行版（`java@21`）指的是 jdk.java.net 上的 OpenJDK，它的 21 只到 21.0.2。请写 `java@21-tem`，见 [versions.md](versions.md#不写发行版)。 +- **只写大版本号。** `vfox install java@21-tem` 装的是最新的 Temurin 21，2026-11-03 是 `21.0.13+9-tem`。SDKMAN 的 `21-tem` 只是一个版本，即 GA 构建 `21+35`。 +- **没有默认 JDK。** `sdk install java` 装的是 SDKMAN 的默认版本，一个 Temurin 的 LTS 版本（2026-11-03 是 `25.0.5.0+8-tem`）。`vfox install java` 没有默认值：在终端里它会让你选一个版本，在脚本里则直接失败。只写版本不写发行版（`java@21`）指的是 jdk.java.net 上的 OpenJDK，它的 21 只到 21.0.2。请写 `java@21-tem`，见 [versions.md](versions.md#不写发行版)。 - **安装不等于选中。** `sdk install` 之后，SDKMAN 会问要不要把这个 JDK 设为默认。`vfox install` 只负责安装，选中要用 `vfox use`。 - **两份列表。** `sdk list java` 列出所有厂商的 JDK。`vfox search java` 只列 OpenJDK，所以要写上发行版（`vfox search java tem`）或 `all`。已安装的看 `vfox list java`。版本数据来自 [Foojay](foojay.md)。 - **安装后的版本名带构建号。** `vfox list java` 显示 `21.0.8+9-tem`，`vfox uninstall` 和 `vfox info` 都要写全，而 `vfox use java@21.0.8-tem` 不写构建号也能找到它，见 [versions.md](versions.md#安装后的版本名)。 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 9d35440..5d8f87c 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -36,11 +36,11 @@ Foojay 在这个平台上没有对应的包：版本、发行版、带不带 Jav ### `Checksum error` -vfox 打印了 `Checksum error, file: <路径>`，接着是 `failed to install java` 和 `checksum error`，并在解压任何东西之前就停了下来，所以什么也没有装上。下载的文件和 Foojay 给它的校验和对不上，见 [foojay.md](foojay.md#校验和)。最常见的原因是下载中途被截断或损坏：再试一次。如果经过镜像（[mirror.md](mirror.md)）总是出现，可能是镜像给了别的文件，取消设置 `VFOX_JAVA_GITHUB_MIRROR`。没有镜像也出现，则可能是 Foojay 记下校验和之后，厂商换掉了文件：带上发行版和版本，向 [Foojay](https://github.com/foojayio/discoapi) 报告。未发布：0.6.3 不给 vfox 任何校验和，所以不会停在这里。 +vfox 打印了 `Checksum error, file: <路径>`，接着是 `failed to install java` 和 `checksum error`，并在解压任何东西之前就停了下来，所以什么也没有装上。下载的文件和 Foojay 给它的校验和对不上，见 [foojay.md](foojay.md#校验和)。最常见的原因是下载中途被截断或损坏：再试一次。如果经过镜像（[mirror.md](mirror.md)）总是出现，可能是镜像给了别的文件，取消设置 `VFOX_JAVA_GITHUB_MIRROR`。没有镜像也出现，则可能是 Foojay 记下校验和之后，厂商换掉了文件：带上发行版和版本，向 [Foojay](https://github.com/foojayio/discoapi) 报告。 ### `Cannot verify the download: ...` -Foojay 给这个包列出了校验和，但插件用不上，所以安装照常进行、下载的文件没有校验，下载完成后 vfox 会打印 `WARNING: Checksum is not provided, skip verify...`。冒号后面是原因：存放校验和的文件打不开时是 `failed to fetch <地址>: ...`（见[网络](#网络)），文件里根本没有摘要时是 `<地址> has no digest`（比如防火墙或认证页面返回了一个网页），文件里只列了别的包时是 `<地址> has no digest for <文件>`，算法是 vfox 不认识的则是 `vfox cannot verify a sha3_256 checksum`。第一种再试一次就行。其余两种请带上发行版和版本报告，因为需要修插件，或者 Foojay 的记录有误。未发布：0.6.3 从不读校验和。 +Foojay 给这个包列出了校验和，但插件用不上，所以安装照常进行、下载的文件没有校验，下载完成后 vfox 会打印 `WARNING: Checksum is not provided, skip verify...`。冒号后面是原因：存放校验和的文件打不开时是 `failed to fetch <地址>: ...`（见[网络](#网络)），文件里根本没有摘要时是 `<地址> has no digest`（比如防火墙或认证页面返回了一个网页），文件里只列了别的包时是 `<地址> has no digest for <文件>`，算法是 vfox 不认识的则是 `vfox cannot verify a sha3_256 checksum`。第一种再试一次就行。其余两种请带上发行版和版本报告，因为需要修插件，或者 Foojay 的记录有误。 ### `VFOX_JAVA_GITHUB_MIRROR must start with http:// or https://, such as https://gh-proxy.org/, but is gh-proxy.org` @@ -74,14 +74,14 @@ vfox config proxy.url http://127.0.0.1:7890 ## 看起来不对，其实没问题 - **`vfox search` 里没有你预期的版本。** vfox 会缓存搜索结果 12 小时。`vfox config cache.availableHookDuration 0` 可以关闭缓存。也可能是 Foojay 那边还没有这个版本。 -- **装某个 JDK 时出现 `WARNING: Checksum is not provided, skip verify...`。** Foojay 没有给这个包列出校验和（Dragonwell、Bisheng、Trava、AdoptOpenJDK、OpenLogic、Gluon GraalVM、8 以后的 Corretto，以及其余发行版里较旧的版本），vfox 没有可以拿来比对的东西，只能信任下载的内容。Foojay 给了校验和的包，vfox 会打印 `Verifying checksum <摘要>...`，见 [foojay.md](foojay.md#校验和)。未发布：0.6.3 根本不给 vfox 校验和，所以每次安装最后都有这条警告。 +- **装某个 JDK 时出现 `WARNING: Checksum is not provided, skip verify...`。** Foojay 没有给这个包列出校验和（Dragonwell、Bisheng、Trava、AdoptOpenJDK、OpenLogic、Gluon GraalVM、8 以后的 Corretto，以及其余发行版里较旧的版本），vfox 没有可以拿来比对的东西，只能信任下载的内容。Foojay 给了校验和的包，vfox 会打印 `Verifying checksum <摘要>...`，见 [foojay.md](foojay.md#校验和)。 - **安装后的版本名里多了一个你没写的构建号。** `java@21.0.8-tem` 装出来是 `21.0.8+9-tem`。构建号是版本名的一部分，见 [versions.md](versions.md#安装后的版本名)。 - **`vfox install java@21-tem` 和 `vfox install java tem` 做的是不同的事。** 后者是两个 SDK，`java` 和 `tem`。 - **你设置的 `GRAALVM_HOME` 不会被改动。** 插件只设置 `JAVA_HOME` 和 `PATH`。 - **`vfox use java@21` 选中了 `21.3.1-grl11`，而它运行的是 Java 11。** GraalVM CE 8 到 19、23 以前的 Gluon GraalVM，以及 25 以前的 Mandrel 和 Liberica NIK，用的都是 GraalVM 的版本号；对只写大版本号的写法，vfox 只按版本号匹配，不分发行版，见 [distributions.md](distributions.md#按-graalvm-编号的版本)。请写成 `java@21-tem`。 - **`java@21-mandrel` 装上的 Mandrel 运行的是 Java 17。** Mandrel 和 Liberica NIK 的大版本号是 GraalVM 的：`21.3.6-mandrel` 是最新的 Mandrel 21.x。它们为 Java 21 发布的是 23.1.x，所以要写 `java@23-mandrel`，见 [distributions.md](distributions.md#mandrel-与-liberica-nik-的行为)。 -- **`native-image` 停在 `Default native-compiler executable 'gcc' not found via environment variable PATH`，或者在最后一步报 `cannot find -lz`。** 插件只安装 JDK，而 `native-image` 需要系统里的 C 工具链和 zlib。Ubuntu 上执行 `sudo apt install --assume-yes build-essential zlib1g-dev` 即可装上，见 [distributions.md](distributions.md#native-image-与-c-工具链)。 -- **GraalVM CE 8 到 19（比如 `22.3.3-grl17`）里 `native-image: command not found`。** 这些版本不带 `native-image`，用 `gu install native-image` 添加。`21.3.1-grl8` 上这条命令会失败，见 [distributions.md](distributions.md#native-image-与-c-工具链)。 +- **`native-image` 停在 `Default native-compiler executable 'gcc' not found via environment variable PATH`，或者在最后一步报 `cannot find -lz`。** 插件只安装 JDK，而 `native-image` 需要系统里的 C 工具链和 zlib。Ubuntu 上执行 `sudo apt install --assume-yes build-essential zlib1g-dev` 即可装上，见 [native-image.md](native-image.md#ubuntu)。 +- **GraalVM CE 8 到 19（比如 `22.3.3-grl17`）里 `native-image: command not found`。** 这些版本不带 `native-image`，用 `gu install native-image` 添加。`21.3.1-grl8` 上这条命令会失败，见 [native-image.md](native-image.md#graalvm-ce-8-到-19)。 ## JDK 在哪里 diff --git a/docs/zh-CN/versions.md b/docs/zh-CN/versions.md index 68dd8ca..0843a7b 100644 --- a/docs/zh-CN/versions.md +++ b/docs/zh-CN/versions.md @@ -23,7 +23,7 @@ vfox install java@21 # 不写发行版：jdk.java.net 上的 Open `vfox install` 先问插件该装哪个包，再由 vfox 下载并解压。 -- 只写大版本号（`21`、`21-tem`）时，安装这个发行版列出的、这个大版本下最新的版本，例如截至 2026-10-18 是 `21.0.12.1+1-tem`。 +- 只写大版本号（`21`、`21-tem`）时，安装这个发行版列出的、这个大版本下最新的版本，例如截至 2026-11-03 是 `21.0.13+9-tem`。 - 写得更具体时，必须是这个发行版列出的版本。`21.0.8-tem` 装的是 21.0.8 的最新构建 `21.0.8+9-tem`。根本不存在的版本会失败，报 `No JDK found for 21.0.99-tem on linux/amd64`。 - 写了构建号就装那个构建：`21.0.5+63130-jb`。 - SDKMAN 写法里补了零的版本也能识别：`27.0.0-librca` 装的是 `27+36-librca`。 @@ -33,7 +33,7 @@ vfox install java@21 # 不写发行版：jdk.java.net 上的 Open - 在 Windows 上，同一版本既有 zip 又有 tar.gz 时，装 zip。 - 只写发行版不写版本（`java@tem`、`java@-tem`、`java@zulu-fx`）会被拒绝，并提示补上版本。 -如果这个版本名已经装过，会提示 `java@21.0.12.1+1-tem is already installed`，不会重新下载。 +如果这个版本名已经装过，会提示 `java@21.0.13+9-tem is already installed`，不会重新下载。 ## 安装后的版本名 @@ -87,7 +87,7 @@ vfox 自己匹配 `21` 时只看版本号，所以 GraalVM CE 8 到 19、Gluon G 写成 `<大版本>.ea[.<构建号>]`： ```bash -vfox install java@28.ea-open # 最新的 EA 构建，截至 2026-10-18 是 28-ea+19 +vfox install java@28.ea-open # 最新的 EA 构建，截至 2026-11-03 是 28-ea+21 vfox install java@28.ea.15-open # 28-ea+15 ``` @@ -98,7 +98,7 @@ vfox install java@28.ea.15-open # 28-ea+15 ```bash vfox search java # 默认的 OpenJDK vfox search java tem # 指定一个发行版，简称或长名都行 -vfox search java all # 所有发行版，在 Linux x64 上约 2500 行 +vfox search java all # 所有发行版，在 Linux x64 上约 2600 行 ``` 每一行都是可以接在 `java@` 后面的名字，新的在前，带 LTS、JavaFX（见 [javafx.md](javafx.md)）备注，已安装的会有标记： @@ -109,9 +109,9 @@ Available versions: - 27+35-tem - 26.0.2.1+1-tem ... - - 25.0.4+7-tem (LTS) + - 25.0.5+8-tem (LTS) ... - - 21.0.12.1+1-tem (LTS) (installed) + - 21.0.13+9-tem (LTS) (installed) ``` 列表是按你运行命令的这台机器来的，只含它能装的版本，见 [platforms.md](platforms.md)。在交互式终端里，`vfox search java tem` 可以直接选一个版本安装；在其他环境下只打印列表。vfox 会缓存搜索结果 12 小时（`vfox config cache.availableHookDuration`），所以刚发布的版本可能暂时看不到。