From 395273e8f42f9bde44bf1cfc8e44f4830292c4a4 Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Sun, 18 Oct 2026 16:33:22 +0800 Subject: [PATCH] docs: split the README into topic pages and add Chinese translations --- README.md | 259 +++++++-------------------- README_CN.md | 285 +++++++----------------------- docs/changes.md | 62 +++++++ docs/development.md | 132 ++++++++++++++ docs/distributions.md | 122 +++++++++++++ docs/e2e.md | 2 + docs/foojay.md | 126 +++++++++++++ docs/install-from-source.md | 72 ++++++++ docs/javafx.md | 45 +++++ docs/loongnix.md | 53 ++++++ docs/platforms.md | 71 ++++++++ docs/sdkmanrc.md | 76 ++++++++ docs/troubleshooting.md | 76 ++++++++ docs/versions.md | 120 +++++++++++++ docs/zh-CN/changes.md | 62 +++++++ docs/zh-CN/development.md | 132 ++++++++++++++ docs/zh-CN/distributions.md | 122 +++++++++++++ docs/zh-CN/e2e.md | 207 ++++++++++++++++++++++ docs/zh-CN/foojay.md | 126 +++++++++++++ docs/zh-CN/install-from-source.md | 72 ++++++++ docs/zh-CN/javafx.md | 45 +++++ docs/zh-CN/loongnix.md | 53 ++++++ docs/zh-CN/platforms.md | 71 ++++++++ docs/zh-CN/sdkmanrc.md | 76 ++++++++ docs/zh-CN/troubleshooting.md | 76 ++++++++ docs/zh-CN/versions.md | 120 +++++++++++++ hooks/available.lua | 5 +- 27 files changed, 2246 insertions(+), 422 deletions(-) create mode 100644 docs/changes.md create mode 100644 docs/development.md create mode 100644 docs/distributions.md create mode 100644 docs/foojay.md create mode 100644 docs/install-from-source.md create mode 100644 docs/javafx.md create mode 100644 docs/loongnix.md create mode 100644 docs/platforms.md create mode 100644 docs/sdkmanrc.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/versions.md create mode 100644 docs/zh-CN/changes.md create mode 100644 docs/zh-CN/development.md create mode 100644 docs/zh-CN/distributions.md create mode 100644 docs/zh-CN/e2e.md create mode 100644 docs/zh-CN/foojay.md create mode 100644 docs/zh-CN/install-from-source.md create mode 100644 docs/zh-CN/javafx.md create mode 100644 docs/zh-CN/loongnix.md create mode 100644 docs/zh-CN/platforms.md create mode 100644 docs/zh-CN/sdkmanrc.md create mode 100644 docs/zh-CN/troubleshooting.md create mode 100644 docs/zh-CN/versions.md diff --git a/README.md b/README.md index 8b39f97..099b1a9 100644 --- a/README.md +++ b/README.md @@ -2,239 +2,97 @@ [中文](README_CN.md) | [English](README.md) -> Java plugin for [vfox](https://github.com/version-fox/vfox) +Java plugin for [vfox](https://vfox.dev/). -Support for multiple JDK distributions, such as: Oracle, Graalvm, Eclipse & more. +It installs JDKs from 18 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. +## Install -# Usage +After installing [vfox](https://github.com/version-fox/vfox), install the plugin by running: -**Parameter Format**: `x.y.z-distribution` or `x.y.z-distribution-fx` (for JavaFX bundled versions) - -```shell -# add plugin for vfox +```bash vfox add java - -# install specific version (openjdk is default) -vfox install java@17.0.17 -vfox install java@17.0.17-tem # Temurin -vfox install java@17.0.17-zulu # Zulu -vfox install java@17-graal # GraalVM (latest 17.x) - -# install JavaFX bundled versions (use -fx suffix after distribution) -vfox install java@21.0.5-zulu-fx # Zulu with JavaFX -vfox install java@21.0.5-librca-fx # Liberica with JavaFX - -# view all available versions -vfox search java # view all openjdk versions -vfox search java tem # view all temurin versions -vfox search java zulu # view all zulu versions -vfox search java graal # view all graalvm versions -``` - -## Select and install a distribution - -In an interactive terminal, run `vfox search java tem` to select and install a version from the Temurin list. In a non-interactive terminal, this command only prints the versions. Replace `tem` with another distribution identifier, such as `zulu`, as needed. - -For a known version, use `vfox install java@17.0.17-tem`. Space-separated arguments to `install` identify multiple SDKs, so `vfox install java tem` does not pass `tem` as a Java distribution filter. - -## LoongArch (Linux) - -On Linux `loong64`, `vfox search java` (or `vfox search java loongnix`) lists JDKs from the [Loongnix official archive](https://ftp.loongnix.cn/Java/). Other architectures continue to use Foojay. - -Choose the ABI matching your operating system; the plugin does not guess it: - -- `lnxabi1` / `loongnix_abi1`: Linux 4.19 UAPI builds, intended for systems such as Loongnix 20 and Loongnix Server 8.4. -- `lnxabi2` / `loongnix_abi2`: Linux 5.10 UAPI builds, named `glibc2.34` upstream, intended for systems such as Debian 12 and openEuler. - -See the [upstream compatibility notes](https://www.loongnix.cn/zh/api/java/) for your system. Do not choose solely from the running kernel version. This source provides glibc builds, not musl builds. - -```shell -vfox search java lnxabi2 -vfox install java@21-lnxabi2-fx # latest matching Java 21 with JavaFX, ABI2 -vfox install java@21.0.12+8-lnxabi2-fx -``` - -Versions use the Java version and build number, not the Loongson release number. ABI and JavaFX suffixes are preserved when switching versions. Only GA LoongArch tarballs listed in the archive are supported; MIPS packages are excluded. Select `-fx` only for JavaFX builds. Bare installation requests require an explicit ABI; selecting a search result supplies it automatically. - -## JavaFX Support - -Some distributions provide JDK versions bundled with JavaFX. These versions are displayed with the `-fx` suffix after the distribution name in the version list and marked with "JavaFX" in the notes. To install a JavaFX bundled version, add `-fx` after the distribution name: - -```shell -# List versions (JavaFX versions will show -fx suffix) -vfox search java zulu -# Example output: -# 21.0.5-zulu -# 21.0.5-zulu-fx # JavaFX -# 17.0.13-zulu -# 17.0.13-zulu-fx # JavaFX - -# Install JavaFX bundled version -vfox install java@21.0.5-zulu-fx -``` - -# Supported JDK Distributions - -> Thanks [SDKMAN](https://sdkman.io/jdks)! - -## Bisheng (Huawei) -BiSheng JDK, an open-source adaptation of Huawei JDK derived from OpenJDK, is utilized across 500+ Huawei products, benefitting from the R&D team's extensive experience in addressing service-related challenges. As a downstream product of OpenJDK, it serves as a high-performance distribution for production environments, specifically addressing performance and stability issues in Huawei applications. BiSheng JDK excels in optimizing ARM architecture performance and stability, delivering enhanced results in big data scenarios. Its primary goal is to offer Java developers a stable, high-performance JDK, particularly excelling on the ARM architecture. - -```shell -$ vfox install java@x.y.z-bsg -$ vfox search java bsg -``` - -## Corretto (Amazon) -Amazon Corretto is a no-cost, multiplatform, production-ready distribution of the Open Java Development Kit (OpenJDK). Corretto comes with long-term support that will include performance enhancements and security fixes. Amazon runs Corretto internally on thousands of production services and Corretto is certified as compatible with the Java SE standard. With Corretto, you can develop and run Java applications on popular operating systems, including Linux, Windows, and macOS. - -```shell -$ vfox install java@x.y.z-amzn -$ vfox search java amzn -``` - -## Dragonwell (Alibaba) -Dragonwell, as a downstream version of OpenJDK, is the in-house OpenJDK implementation at Alibaba. It is optimized for online e-commerce, financial and logistics applications running on 100,000+ servers. Alibaba Dragonwell is the engine that runs these distributed Java applications in extreme scaling. - -```shell -$ vfox install java@x.y.z-albba -$ vfox search java albba ``` -## GraalVM (Oracle) -Oracle GraalVM is the free GraalVM distribution from Oracle, based on Oracle JDK, and includes the high-performance Graal JIT compiler. GraalVM can compile Java applications ahead of time into standalone binaries that start instantly, scale fast, and use fewer compute resources. Oracle GraalVM Native Image provides advanced features including G1 GC, SBOM, as well as performance and size optimizations. It also makes it possible to embed Python, JavaScript, Ruby, and other languages into Java applications. +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). -```shell -$ vfox install java@x.y.z-graal -$ vfox search java graal -``` - -## GraalVM (GraalVM Community) -GraalVM CE is the open source distribution of GraalVM, based on OpenJDK, and includes the high-performance Graal JIT compiler. GraalVM can compile Java applications ahead of time into standalone binaries that start instantly, scale fast, and use fewer compute resources. It also makes it possible to embed Python, JavaScript, Ruby, and other languages into Java applications. - -```shell -$ vfox install java@x.y.z-graalce -$ vfox search java graalce -``` - -## Java SE Development Kit (Oracle) -This proprietary Java Development Kit is an implementation of the Java Platform, Standard Edition released by Oracle Corporation in the form of a binary product aimed at Java developers on Linux, macOS or Windows. The JDK includes a private JVM and a few other resources to finish the development of a Java application. It is distributed under the Oracle No-Fee Terms and Conditions License - - -```shell -$ vfox install java@x.y.z-oracle -$ vfox search java oracle -``` - -## Kona (Tencent) -Tencent Kona is a free, multi-platform, and production-ready distribution of OpenJDK, featuring Long-Term Support (LTS) releases. It serves as the default JDK within Tencent for cloud computing, big data, and numerous other Java applications. - -```shell -$ vfox install java@x.y.z-kona -$ vfox search java kona -``` - -## Liberica (Bellsoft) -Liberica is a 100% open-source Java implementation. It is built from OpenJDK which BellSoft contributes to, is thoroughly tested and passed the JCK provided under the license from OpenJDK. All supported versions of Liberica also contain JavaFX. - - -```shell -$ vfox install java@x.y.z-librca -$ vfox search java librca -``` +### Example -## Liberica NIK (Bellsoft) -Liberica Native Image Kit is a utility that converts your JVM-based application into a fully compiled native executable ahead-of-time under the closed-world assumption with an almost instant startup time. Being compatible with various platforms, including lightweight musl-based Alpine Linux, it optimizes resource consumption and minimizes the static footprint. - - -```shell -$ vfox install java@x.y.z-nik -$ vfox search java nik +```bash +vfox add java +vfox install java@21-tem +vfox use --global java@21-tem ``` -## Mandrel (Red Hat) -Mandrel focuses on GraalVM's native-image component in order to provide an easy way for Quarkus users to generate native images for their applications. Developers using Quarkus should be able to go all the way from Java source code to lean, native, platform-dependent applications running on Linux. This capability is vital for deploying to containers in a cloud-native application development model. +Unreleased: release 0.6.1, the newest when this was written, installs `21+35-tem` here, and `vfox use --global java@21-tem` then fails with `java@21-tem is not installed`. Use the name that `vfox install` prints, or [install from source](docs/install-from-source.md). +You can verify this using the following command: -```shell -$ vfox install java@x.y.z-mandrel -$ vfox search java mandrel +```bash +java -version ``` +`vfox search java tem` lists the Temurin releases, and in an interactive terminal it lets you pick one and installs it. -## OpenJDK (jdk.java.net) -OpenJDK (Open Java Development Kit) is a free and open-source implementation of the Java Platform, Standard Edition (Java SE). It is the result of an effort Sun Microsystems began in 2006. The implementation is licensed under the GNU General Public License (GNU GPL) version 2 with a linking exception. Were it not for the GPL linking exception, components that linked to the Java class library would be subject to the terms of the GPL license. OpenJDK is the official reference implementation of Java SE since version 7. +Behavior that only exists on `main` and not in the latest release is marked "Unreleased" in the pages below. [docs/changes.md](docs/changes.md) lists it, and [docs/install-from-source.md](docs/install-from-source.md) gets you `main`. -```shell -$ vfox install java@x.y.z-open -$ vfox search java open -``` +## Versions and names -## OpenJDK (Microsoft) -The Microsoft Build of OpenJDK is a no-cost distribution of OpenJDK that's open source and available for free for anyone to deploy anywhere. It includes Long-Term Support (LTS) binaries for Java 11 on x64 server and desktop environments on macOS, Linux, and Windows, and AArch64/ARM64 on Linux and Windows. Microsoft also publishes Java 16 binaries for all three major Operating Systems and both x64 and AArch64 (M1/ARM64) architectures. - -```shell -$ vfox install java@x.y.z-ms -$ vfox search java ms -``` -## SapMachine (SAP) -SapMachine is a downstream version of the OpenJDK project. It is used to build and maintain a SAP supported version of OpenJDK for SAP customers and partners who wish to use OpenJDK to run their applications. SAP is committed to ensuring the continued success of the Java platform. +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. +## Distributions -```shell -$ vfox install java@x.y.z-sapmchn -$ vfox search java sapmchn -``` +| Short name | Distribution | +| --- | --- | +| `open` | OpenJDK builds from jdk.java.net, the default | +| `tem` | Temurin (Eclipse Adoptium) | +| `zulu` | Zulu (Azul) | +| `librca` | Liberica (BellSoft) | +| `amzn` | Corretto (Amazon) | +| `ms` | Microsoft Build of OpenJDK | +| `oracle` | Oracle JDK | +| `sem` | Semeru (IBM) | +| `sapmchn` | SapMachine (SAP) | +| `kona` | Kona (Tencent) | +| `albba` | Dragonwell (Alibaba) | +| `bsg` | BiSheng (Huawei) | +| `graal` | Oracle GraalVM | +| `graalce` | GraalVM Community Edition | +| `nik` | Liberica Native Image Kit (BellSoft) | +| `mandrel` | Mandrel (Red Hat) | +| `jb` | JetBrains Runtime | +| `trava` | TravaOpenJDK | +| `lnxabi1`, `lnxabi2` | Loongnix, Linux loong64 only | -## Semeru (IBM) -Semeru Runtimes use the class libraries from OpenJDK, along with the Eclipse OpenJ9 Java Virtual Machine to enable developers to build and deploy Java applications that will start quickly, deliver great performance, all while using less memory. +See [docs/distributions.md](docs/distributions.md) for what each one is, and [docs/loongnix.md](docs/loongnix.md) for the last row. -```shell -$ vfox install java@x.y.z-sem -$ vfox search java sem -``` +## Platforms -## Temurin (Eclipse) -Formerly AdoptOpenJDK, the Eclipse Adoptium Temurin™ project provides code and processes that support the building of runtime binaries and associated technologies that are high performance, enterprise-caliber, cross-platform, open-source licensed, and Java SE TCK-tested for general use across the Java ecosystem. +Not every distribution has builds for arm64, Alpine or Windows on ARM. Only Temurin, Zulu, Liberica, Microsoft and JetBrains Runtime have Windows ARM64 builds, 10 of the 18 have Alpine x64 builds and 7 have Alpine arm64. GraalVM has neither Windows ARM64 nor Alpine. See [docs/platforms.md](docs/platforms.md) for the table. -```shell -$ vfox install java@x.y.z-tem -$ vfox search java tem -``` +## JavaFX -## Trava (Trava) -TravaOpenJDK is OpenJDK for developers. It is based on dcevm and uses an integrated HotswapAgent, so allowing advanced hotswapping of classes by method and field addition or updates at runtime. +Zulu, Liberica, Liberica NIK and Corretto (Java 8 only) have builds with JavaFX bundled. Add `-fx` after the distribution, as in `java@21-zulu-fx`. See [docs/javafx.md](docs/javafx.md) for details. -```shell -$ vfox install java@x.y.z-trava -$ vfox search java trava -``` +## `.sdkmanrc` -## Zulu (Azul Systems) -Azul Zulu Builds of OpenJDK are no-cost, production-ready open-source, TCK-tested, and certified OpenJDK distributions. They are available for a wide range of hardware platforms and operating systems and are compatible with special requirements, such as stripped-down JREs and builds, including OpenJFX and Coordinated Restore at Checkpoint (CRaC). They are supported as part of Azul Platform Core, which provides stabilized security updates for rapid, assured deployment into production and solution-oriented engineering assistance. +vfox reads the `java=` line of SDKMAN's `.sdkmanrc` through this plugin and selects a JDK that is already installed. See [docs/sdkmanrc.md](docs/sdkmanrc.md) for details. -```shell -$ vfox install java@x.y.z-zulu -$ vfox search java zulu -``` +## Querying Foojay -## Jetbrains +To see which JDKs exist for your platform, ask Foojay yourself. [docs/foojay.md](docs/foojay.md) has the Swagger UI and the commands. -```shell -$ vfox install java@x.y.z-jb -$ vfox search java jb -``` +## Troubleshooting +See [docs/troubleshooting.md](docs/troubleshooting.md) for the messages the plugin prints, proxies and where the JDK is. -# Thanks +## Install from source -- [SDKMAN](https://github.com/sdkman/) -- [foojayio](https://github.com/foojayio/discoapi) +See [docs/install-from-source.md](docs/install-from-source.md) for details. -## Testing +## Development -See [docs/e2e.md](docs/e2e.md) for details. +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. ## Releasing this plugin @@ -250,3 +108,8 @@ the tag. If publication fails, re-run the original failed job to resume it. 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. + +## Thanks + +- [SDKMAN](https://github.com/sdkman/), whose identifiers the short names and `.sdkmanrc` support follow +- [Foojay](https://github.com/foojayio/discoapi), where the JDK data comes from diff --git a/README_CN.md b/README_CN.md index f0f52ad..6094d42 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,266 +2,107 @@ [中文](README_CN.md) | [English](README.md) -> Java plugin for [vfox](https://github.com/version-fox/vfox) +[vfox](https://vfox.dev/) 的 Java 插件。 -支持多种JDK发行版，如：Oracle、Graalvm、Eclipse等。 +它通过 [Foojay](https://foojay.io/) 查找并安装 18 个发行版的 JDK，包括 Temurin、Zulu、Liberica、Corretto、Microsoft、GraalVM 等。在 Linux loong64 上，则改从 Loongnix 归档安装。 -# 使用 +## 安装 -**参数格式**: `x.y.z-distribution` 或 `x.y.z-distribution-fx` (带 JavaFX 的版本) +先安装 [vfox](https://github.com/version-fox/vfox)，然后执行下面的命令安装插件： -```shell -# 添加插件 +```bash vfox add java - -# 添加运行时 -vfox install java@x.y.z # 默认使用openjdk -vfox install java@x.y.z-graal # 使用graalvm - -# 安装带 JavaFX 的版本 (在发行版名称后添加 -fx 后缀) -vfox install java@21.0.5-zulu-fx # 带 JavaFX 的 Zulu -vfox install java@21.0.5-librca-fx # 带 JavaFX 的 Liberica - -# 查看所有可用版本 -vfox search java all # 查看所有sdk版本 -vfox search java # 查看所有openjdk版本 -vfox search java graal # 查看所有graalvm版本 -``` - -## 按发行版选择并安装 - -在交互终端中运行 `vfox search java tem`，即可从 Temurin 版本列表中选择一个版本并安装；在非交互终端中，该命令只输出版本列表。也可以将 `tem` 替换为 `zulu` 等发行版标识。 - -已知版本时，使用 `vfox install java@17.0.17-tem`。`install` 的空格分隔参数用于指定多个 SDK，因此 `vfox install java tem` 不会将 `tem` 作为 Java 发行版筛选条件。 - -## 龙架构（Linux） - -在 Linux `loong64` 上，`vfox search java`（或 `vfox search java loongnix`）从 [Loongnix 官方归档](https://ftp.loongnix.cn/Java/)列出 JDK。其他架构继续使用 Foojay。 - -请按操作系统选择 ABI，插件不会自动猜测： - -- `lnxabi1` / `loongnix_abi1`：Linux 4.19 UAPI 构建，适用于 Loongnix 20、Loongnix Server 8.4 等系统。 -- `lnxabi2` / `loongnix_abi2`：Linux 5.10 UAPI 构建，上游文件名标记为 `glibc2.34`，适用于 Debian 12、openEuler 等系统。 - -请核对[上游兼容性说明](https://www.loongnix.cn/zh/api/java/)，不能仅凭当前内核版本选择 ABI。该源提供 glibc 构建，不提供 musl 构建。 - -```shell -vfox search java lnxabi2 -vfox install java@21-lnxabi2-fx # 匹配最新的 Java 21，带 JavaFX，使用 ABI2 -vfox install java@21.0.12+8-lnxabi2-fx -``` - -版本号采用 Java 版本及构建号，不是 Loongson 发行版本号。切换版本时保留 ABI 和 JavaFX 后缀。仅支持归档中的正式版 LoongArch tar 包，排除 MIPS 包；JavaFX 构建需使用 `-fx`。直接安装时必须明确 ABI，从搜索结果选择安装则会自动带上该标识。 - -## JavaFX 支持 - -部分发行版提供了捆绑 JavaFX 的 JDK 版本。这些版本在版本列表中会在发行版名称后显示 `-fx` 后缀，并在备注中标注 "JavaFX"。安装带 JavaFX 的版本时，需要在发行版名称后添加 `-fx`： - -```shell -# 查看版本列表 (带 JavaFX 的版本会显示 -fx 后缀) -vfox search java zulu -# 示例输出: -# 21.0.5-zulu -# 21.0.5-zulu-fx # JavaFX -# 17.0.13-zulu -# 17.0.13-zulu-fx # JavaFX - -# 安装带 JavaFX 的版本 -vfox install java@21.0.5-zulu-fx -``` - -# 支持的JDK发行版 - -> Thanks [SDKMAN](https://sdkman.io/jdks)! - -## Bisheng (Huawei) - -BiSheng JDK 是华为 JDK 的开源版本，源自 OpenJDK，受益于华为研发团队在解决服务相关挑战方面的丰富经验，已在 500 多款华为产品中使用。作为 -OpenJDK 的下游产品，它是面向生产环境的高性能发行版，专门解决华为应用中的性能和稳定性问题。毕升JDK在优化ARM架构性能和稳定性方面表现出色，在大数据应用场景中效果更佳。其主要目标是为 -Java 开发人员提供一个稳定、高性能的 JDK，尤其是在 ARM 架构上表现出色。 - -```shell -$ vfox install java@x.y.z-bsg -$ vfox search java bsg -``` - -## Corretto (Amazon) - -亚马逊 Corretto 是开放 Java 开发工具包（OpenJDK）的无成本、多平台、生产就绪发行版。Corretto -提供长期支持，包括性能增强和安全修复。亚马逊内部在数千个生产服务上运行 Corretto，Corretto 已通过认证，与 Java SE 标准兼容。使用 -Corretto，您可以在 Linux、Windows 和 macOS 等流行的操作系统上开发和运行 Java 应用程序。 - -```shell -$ vfox install java@x.y.z-amzn -$ vfox search java amzn -``` - -## Dragonwell (Alibaba) - -作为 OpenJDK 的下游版本，Dragonwell 是阿里巴巴内部的 OpenJDK 实现。它针对在 10 万台以上服务器上运行的在线电子商务、金融和物流应用程序进行了优化。阿里巴巴 -Dragonwell 是在极端扩展条件下运行这些分布式 Java 应用程序的引擎。 - -```shell -$ vfox install java@x.y.z-albba -$ vfox search java albba -``` - -## GraalVM (Oracle) - -Oracle GraalVM 是 Oracle 推出的免费 GraalVM 发行版，基于 Oracle JDK，包含高性能 Graal JIT 编译器。GraalVM 可将 Java -应用程序提前编译成独立的二进制文件，这些二进制文件可立即启动、快速扩展并使用更少的计算资源。Oracle GraalVM Native Image -提供的高级功能包括 G1 GC、SBOM 以及性能和大小优化。它还使在 Java 应用程序中嵌入 Python、JavaScript、Ruby 和其他语言成为可能。 - -```shell -$ vfox install java@x.y.z-graal -$ vfox search java graal -``` - -## GraalVM (GraalVM Community) - -GraalVM CE 是 GraalVM 的开源发行版，基于 OpenJDK，包含高性能 Graal JIT 编译器。GraalVM 可以将 Java -应用程序提前编译成独立的二进制文件，这些二进制文件可以立即启动、快速扩展并使用更少的计算资源。它还可以将 -Python、JavaScript、Ruby 和其他语言嵌入 Java 应用程序。 - -```shell -$ vfox install java@x.y.z-graalce -$ vfox search java graalce -``` - -## Java SE Development Kit (Oracle) - -这个专有的 Java 开发工具包是 Oracle 公司以二进制产品形式发布的 Java 平台标准版的实现，面向 Linux、macOS 或 Windows 上的 -Java 开发人员。JDK 包括一个私有 JVM 和其他一些资源，用于完成 Java 应用程序的开发。它根据 Oracle 免收费条款和条件许可证发布。 - -```shell -$ vfox install java@x.y.z-oracle -$ vfox search java oracle ``` -## Kona (Tencent) +要让 `java` 出现在 `PATH` 里，需要先把 vfox 挂载到 Shell，见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。 -Tencent Kona 是 OpenJDK 的免费、多平台和生产就绪发行版，提供长期支持（LTS）版本。它是腾讯内部默认的 JDK，用于云计算、大数据和其他众多 -Java 应用程序。 - -```shell -$ vfox install java@x.y.z-kona -$ vfox search java kona -``` +### 示例 -## Liberica (Bellsoft) - -Liberica 是 100% 的开源 Java 实现。它由 BellSoft 参与开发的 OpenJDK 构建，经过全面测试，并通过了 OpenJDK 许可提供的 -JCK。Liberica 的所有支持版本还包含 JavaFX。 - -```shell -$ vfox install java@x.y.z-librca -$ vfox search java librca +```bash +vfox add java +vfox install java@21-tem +vfox use --global java@21-tem ``` -## Liberica NIK (Bellsoft) +未发布：0.6.1（写这篇文档时最新的发布版）在这里装的是 `21+35-tem`，随后 `vfox use --global java@21-tem` 会报 `java@21-tem is not installed`。请改用 `vfox install` 打印出的名字，或者[从源码安装](docs/zh-CN/install-from-source.md)。 -Liberica Native Image Kit 是一款实用工具，可在封闭世界假设下将基于 JVM 的应用程序提前转换为完全编译的本地可执行文件，启动时间几乎为瞬间。该工具兼容各种平台，包括基于轻量级 -musl 的 Alpine Linux，可优化资源消耗并最大限度地减少静态占用空间。 +可以用下面的命令验证： -```shell -$ vfox install java@x.y.z-nik -$ vfox search java nik +```bash +java -version ``` -## Mandrel (Red Hat) +`vfox search java tem` 会列出 Temurin 的各个版本，在交互式终端里还可以直接选一个并安装。 -Mandrel 专注于 GraalVM 的本地镜像组件，目的是为 Quarkus 用户提供为其应用程序生成本地镜像的简便方法。使用 Quarkus -的开发人员应该能够从 Java 源代码一路开发到在 Linux 上运行的精益、原生、依赖平台的应用程序。这种能力对于在云原生应用程序开发模型中部署到容器中至关重要。 +只存在于 `main`、还没进入最新发布版的行为，在下面各页里标有“未发布”。完整列表见 [docs/zh-CN/changes.md](docs/zh-CN/changes.md)，想直接用上 `main`，见 [docs/zh-CN/install-from-source.md](docs/zh-CN/install-from-source.md)。 -```shell -$ vfox install java@x.y.z-mandrel -$ vfox search java mandrel -``` +## 版本与命名 -## OpenJDK (jdk.java.net) +版本写成 `<版本>-<发行版>`，例如 `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)。 -OpenJDK（开放式 Java 开发工具包）是 Java 平台标准版（Java SE）的免费开源实现。它是 Sun Microsystems 于 2006 年开始努力的成果。该实现采用 -GNU 通用公共许可证（GNU GPL）第 2 版许可，但有一个链接例外。如果没有 GPL 链接例外，链接到 Java 类库的组件将受 GPL -许可证条款的约束。OpenJDK 是 Java SE 自第 7 版起的官方参考实现。 +## 发行版 -```shell -$ vfox install java@x.y.z-open -$ vfox search java open -``` +| 简称 | 发行版 | +| --- | --- | +| `open` | jdk.java.net 上的 OpenJDK 构建，默认 | +| `tem` | Temurin（Eclipse Adoptium） | +| `zulu` | Zulu（Azul） | +| `librca` | Liberica（BellSoft） | +| `amzn` | Corretto（Amazon） | +| `ms` | Microsoft Build of OpenJDK | +| `oracle` | Oracle JDK | +| `sem` | Semeru（IBM） | +| `sapmchn` | SapMachine（SAP） | +| `kona` | Kona（腾讯） | +| `albba` | Dragonwell（阿里巴巴） | +| `bsg` | 毕昇 JDK（华为） | +| `graal` | Oracle GraalVM | +| `graalce` | GraalVM 社区版 | +| `nik` | Liberica Native Image Kit（BellSoft） | +| `mandrel` | Mandrel（Red Hat） | +| `jb` | JetBrains Runtime | +| `trava` | TravaOpenJDK | +| `lnxabi1`、`lnxabi2` | Loongnix，仅限 Linux loong64 | -## OpenJDK (Microsoft) +每个发行版是什么，见 [docs/zh-CN/distributions.md](docs/zh-CN/distributions.md)；最后一行见 [docs/zh-CN/loongnix.md](docs/zh-CN/loongnix.md)。 -OpenJDK 的 Microsoft Build 是 OpenJDK 的免费发行版，它是开源的，任何人都可以免费在任何地方部署。它包括 MacOS、Linux 和 -Windows x64 服务器和桌面环境上 Java 11 的长期支持 (LTS) 二进制文件，以及 Linux 和 Windows 上的 -AArch64/ARM64。微软还发布了适用于所有三大操作系统以及 x64 和 AArch64 (M1/ARM64) 体系结构的 Java 16 二进制文件。 +## 平台 -```shell -$ vfox install java@x.y.z-ms -$ vfox search java ms -``` +并非每个发行版都有 arm64、Alpine 或 Windows ARM 的构建。只有 Temurin、Zulu、Liberica、Microsoft 和 JetBrains Runtime 有 Windows ARM64 的构建，18 个发行版里有 10 个有 Alpine x64 的构建，7 个有 Alpine arm64 的构建。GraalVM 既没有 Windows ARM64，也没有 Alpine。完整的表格见 [docs/zh-CN/platforms.md](docs/zh-CN/platforms.md)。 -## SapMachine (SAP) +## JavaFX -SapMachine 是 OpenJDK 项目的下游版本。它用于为希望使用 OpenJDK 运行其应用程序的 SAP 客户和合作伙伴构建和维护 SAP 支持版本的 -OpenJDK。SAP 致力于确保 Java 平台的持续成功。 +Zulu、Liberica、Liberica NIK 和 Corretto（只有 Java 8）提供内置 JavaFX 的构建，在发行版后面加 `-fx` 即可，比如 `java@21-zulu-fx`。详见 [docs/zh-CN/javafx.md](docs/zh-CN/javafx.md)。 -```shell -$ vfox install java@x.y.z-sapmchn -$ vfox search java sapmchn -``` +## `.sdkmanrc` -## Semeru (IBM) +vfox 通过这个插件读取 SDKMAN 的 `.sdkmanrc` 里的 `java=` 一行，并选中已经安装的 JDK。详见 [docs/zh-CN/sdkmanrc.md](docs/zh-CN/sdkmanrc.md)。 -Semeru Runtimes 使用 OpenJDK 的类库和 Eclipse OpenJ9 Java 虚拟机，使开发人员能够构建和部署 Java -应用程序，这些应用程序启动迅速，性能卓越，同时占用内存较少。 +## 查询 Foojay -```shell -$ vfox install java@x.y.z-sem -$ vfox search java sem -``` +想知道你的平台上有哪些 JDK，可以自己去问 Foojay。[docs/zh-CN/foojay.md](docs/zh-CN/foojay.md) 里有 Swagger UI 和查询命令。 -## Temurin (Eclipse) +## 问题排查 -Eclipse Adoptium Temurin™ 项目的前身是 AdoptOpenJDK，该项目提供代码和流程，支持构建运行时二进制文件和相关技术，这些二进制文件和技术具有高性能、企业级、跨平台、开源许可和经过 -Java SE TCK 测试，可在整个 Java 生态系统中普遍使用。 +插件的各种提示、代理设置和 JDK 的位置，见 [docs/zh-CN/troubleshooting.md](docs/zh-CN/troubleshooting.md)。 -```shell -$ vfox install java@x.y.z-tem -$ vfox search java tem -``` - -## Trava (Trava) +## 从源码安装 -TravaOpenJDK 是专为开发人员设计的 OpenJDK。它基于 dcevm 并使用集成的 HotswapAgent，因此允许在运行时通过方法和字段的添加或更新对类进行高级热交换。 +详见 [docs/zh-CN/install-from-source.md](docs/zh-CN/install-from-source.md)。 -```shell -$ vfox install java@x.y.z-trava -$ vfox search java trava -``` +## 开发 -## Zulu (Azul Systems) +插件的工作方式和修改方法见 [docs/zh-CN/development.md](docs/zh-CN/development.md)，容器测试见 [docs/zh-CN/e2e.md](docs/zh-CN/e2e.md)。 -Azul Zulu Builds of OpenJDK 是无成本、生产就绪的开源、经过 TCK 测试和认证的 OpenJDK 发行版。它们适用于各种硬件平台和操作系统，并与特殊要求兼容，如精简版 -JRE 和构建，包括 OpenJFX 和 Coordinated Restore at Checkpoint (CRaC)。它们作为 Azul Platform Core 的一部分得到支持，Azul -Platform Core 可提供稳定的安全更新，以便快速、可靠地部署到生产中，并提供以解决方案为导向的工程协助。 +## 发布这个插件 -```shell -$ vfox install java@x.y.z-zulu -$ vfox search java zulu -``` - -## Jetbrains - -```shell -$ vfox install java@x.y.z-jb -$ vfox search java jb -``` +维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 前缀的稳定版插件版本号即可发布。共享工作流会更新 `metadata.lua`，创建版本提交和标签，并把 ZIP 包和 manifest 发布到本仓库；不需要在本地打标签，也不需要额外的发布令牌。PR 只运行检查，PR 标题不再触发发布。 -# 感谢 +直接推送版本标签也可以发布，前提是 `PLUGIN.version` 已经与标签一致。发布失败时，重新运行失败的那个作业即可接着发布。 -- [SDKMAN](https://github.com/sdkman/) -- [foojayio](https://github.com/foojayio/discoapi) +工作流引用的是共享的 `@v1` 发布工具，升级这个工具不会发布本插件。包的约定和首次接入的要求，见[共享工作流的文档](https://github.com/version-fox/plugin-manifest-action)。 -## 测试 +## 致谢 -详见 [docs/e2e.md](docs/e2e.md)。 \ No newline at end of file +- [SDKMAN](https://github.com/sdkman/)，简称和 `.sdkmanrc` 的支持都沿用了它的标识符 +- [Foojay](https://github.com/foojayio/discoapi)，JDK 数据的来源 diff --git a/docs/changes.md b/docs/changes.md new file mode 100644 index 0000000..06569e1 --- /dev/null +++ b/docs/changes.md @@ -0,0 +1,62 @@ +# Changes + +[中文](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.1, and `main` is ahead of it by everything under "Unreleased". [install-from-source.md](install-from-source.md) gets you those changes now. + +## Unreleased + +- `.sdkmanrc` works under vfox 1.x again. Release 0.6.1 fails with `expected 0 arguments for func() []string, got 1` under vfox 1.x (tested with 1.0.12 and 1.0.13), and vfox hides the error ([#65](https://github.com/version-fox/vfox-java/pull/65)). +- `vfox use java@21`, a bare major, works under vfox 1.0.13. Release 0.6.1 fails there with `cannot unmarshal string into plugin.PreUseHookResult` ([#65](https://github.com/version-fox/vfox-java/pull/65)). +- `.sdkmanrc` matches SDKMAN's `jbr` and JavaFX identifiers ([#78](https://github.com/version-fox/vfox-java/pull/78)), zero-padded releases ([#85](https://github.com/version-fox/vfox-java/pull/85)) and early-access identifiers ([#88](https://github.com/version-fox/vfox-java/pull/88), [#96](https://github.com/version-fox/vfox-java/pull/96)). It selects the JDK it names when several of the same major are installed ([#84](https://github.com/version-fox/vfox-java/pull/84)). See [sdkmanrc.md](sdkmanrc.md). +- A bare major installs the newest release. `java@21-tem` is `21.0.12.1+1-tem` and not `21+35-tem` ([#74](https://github.com/version-fox/vfox-java/pull/74)). `java@25-graal` installs `25.0.4.1-graal`, the newest build of the 25.0 line, where release 0.6.1 installed `25-graal` ([#101](https://github.com/version-fox/vfox-java/pull/101)). +- `vfox use java@21.0.8-tem` finds the installed `21.0.8+9-tem` ([#76](https://github.com/version-fox/vfox-java/pull/76)). The same goes for OpenJDK names with `-open` or `openjdk-` ([#77](https://github.com/version-fox/vfox-java/pull/77)) and for zero-padded releases ([#92](https://github.com/version-fox/vfox-java/pull/92)). +- `java@21.0.5+63130-jb` installs the build it names and not the newest build of the release ([#83](https://github.com/version-fox/vfox-java/pull/83)). +- `vfox search` on Windows lists releases that ship only as tar.gz ([#81](https://github.com/version-fox/vfox-java/pull/81)). +- The plugin no longer sets `GRAALVM_HOME` ([#93](https://github.com/version-fox/vfox-java/pull/93)). +- `java@tem`, a distribution without a version, asks for one instead of failing with a Lua error ([#99](https://github.com/version-fox/vfox-java/pull/99)). +- `vfox search` no longer marks GraalVM's monthly feature releases as LTS ([#100](https://github.com/version-fox/vfox-java/pull/100)). +- The repository has a container e2e suite for Linux and Windows, see [e2e.md](e2e.md) ([#65](https://github.com/version-fox/vfox-java/pull/65), [#82](https://github.com/version-fox/vfox-java/pull/82)). + +## 0.6.1 (2026-09-12) + +- On macOS the Java home is found by its `bin/java`, so archives with a vendor-named bundle or `Contents/Home` work ([#63](https://github.com/version-fox/vfox-java/pull/63)). + +## 0.6.0 (2026-09-12) + +- JDKs for Linux loong64 from the Loongnix archive, see [loongnix.md](loongnix.md) ([#62](https://github.com/version-fox/vfox-java/pull/62)). +- `vfox use` keeps the `-fx` of a JavaFX build ([#60](https://github.com/version-fox/vfox-java/pull/60)). +- JetBrains Runtime installs on Windows 11 ([#58](https://github.com/version-fox/vfox-java/pull/58)). + +## 0.5.4 (2026-06-01) + +- Early-access builds are installed as `java@26.ea.1-graal` ([#57](https://github.com/version-fox/vfox-java/pull/57)). + +## 0.5.3 (2026-01-19) + +- JavaFX builds with the `-fx` suffix ([#48](https://github.com/version-fox/vfox-java/pull/48)), see [javafx.md](javafx.md). +- Alpine and other musl systems get musl builds ([#50](https://github.com/version-fox/vfox-java/pull/50)). +- Windows x64 asks Foojay for `x64` again. 0.5.2 sent `amd64` there ([#52](https://github.com/version-fox/vfox-java/pull/52)). + +## 0.5.2 (2026-01-18) + +- arm64 asks Foojay for `aarch64`, which is what it expects ([#46](https://github.com/version-fox/vfox-java/pull/46), [#47](https://github.com/version-fox/vfox-java/pull/47)). + +## 0.5.1 (2026-01-02) + +- `vfox use java@21` is left to vfox, which matches a bare major against the installed versions. + +## 0.5.0 (2025-09-29) + +- Version strings in asdf's order work, `java@temurin-21` ([#17](https://github.com/version-fox/vfox-java/pull/17)). + +## 0.4.x (2024-04) + +- 0.4.0 reads `.sdkmanrc`. +- 0.4.3 asks Foojay for glibc builds on Linux ([#14](https://github.com/version-fox/vfox-java/pull/14)). + +## 0.1.x and 0.2.x (2024-04) + +- 0.1.0 is the first release, with 17 distributions. +- 0.1.2 adds `vfox search java all` ([#5](https://github.com/version-fox/vfox-java/pull/5)) and makes `open` the default distribution ([#6](https://github.com/version-fox/vfox-java/pull/6)). +- 0.2.1 adds Liberica Native Image Kit ([#10](https://github.com/version-fox/vfox-java/pull/10)). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..a2bc249 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,132 @@ +# Development + +[中文](zh-CN/development.md) | [English](development.md) + +## Layout + +``` +metadata.lua plugin name, version, and .sdkmanrc as a legacy file +hooks/available.lua vfox search +hooks/pre_install.lua vfox install: choose the package and name the install +hooks/post_install.lua macOS: move the Java home to the install root +hooks/env_keys.lua JAVA_HOME and PATH +hooks/pre_use.lua vfox use: map what was typed to an installed name +hooks/parse_legacy_file.lua .sdkmanrc +lib/distribution_version.lua distribution names, parsing of specs, GraalVM feature releases +lib/foojay.lua the Foojay request +lib/installed_version.lua matching against installed names +lib/loongnix.lua the Loongnix archive +tests/*_test.lua offline hook tests +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 +``` + +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. + +## What runs for a command + +| You run | Hooks | +| --- | --- | +| `vfox search java tem` | `Available` | +| `vfox install java@21-tem` | `PreInstall` returns the URL and the name. vfox downloads and unpacks, then calls `PostInstall` | +| `vfox use java@21-tem` | `PreUse` returns the installed name to select. `EnvKeys` provides the variables | +| a shell hook, `cd` into a directory with `.sdkmanrc` | `ParseLegacyFile` | +| `vfox uninstall java@21.0.8+9-tem` | none, the name has to be exact | + +A few contracts that cost time to find: + +- `PreInstall` returns `url`, `version` and `note`. `version` becomes the name of the install, which is why it carries the build number. The package's checksum is not passed on yet (`TODO: checksum` in `hooks/pre_install.lua`), and vfox prints a warning for that. +- `PreUse` returns a table or `nil`. For a bare major it returns `nil` so that vfox matches it itself. vfox 1.0.13 and later reject a bare string such as `""`. +- `ParseLegacyFile` calls `ctx.getInstalledVersions()` with no argument. vfox 1.x binds it as a Go `func() []string` and rejects the extra argument that `ctx:getInstalledVersions()` adds. vfox ignores errors from this hook, so the failure is silent. +- vfox hands over the installed versions sorted as strings, descending: `21.0.8+9-tem`, `21.0.12+8-tem`, `21.0.1+12-tem`. The first one that starts with a release is not the right one, so `lib/installed_version.lua` compares numbers one by one. +- `EnvKeys` sets no `GRAALVM_HOME`. Users point it at a GraalVM of their own. + +## Names + +Installed names are `[-][-fx]`, with no short name for OpenJDK ([versions.md](versions.md#installed-names)). `lib/distribution_version.lua` reads a spec into a version, a distribution and the JavaFX flag, in either order (`21-tem`, `tem-21`). `lib/installed_version.lua` turns a version the user typed into an installed name: the name itself first. A bare major then takes the newest installed release of it, and any other version takes the release itself or its newest build. `PreUse` stops there. `ParseLegacyFile` goes one step further and falls back to the newest installed release of the major. + +SDKMAN spells some things differently (`jbr`, `21.0.12.fx-zulu`, `21.0.12-fx+1.1-librca`, `28.0.0+ea.19-open`), and `plugin_spelling` in `hooks/parse_legacy_file.lua` rewrites them into the plugin's before parsing. `installed_version.unpad` drops the zeros SDKMAN pads releases with (`27.0.0+36` is `27+36`). The plugin's short names are SDKMAN's, except `jb`. + +## Foojay + +- A `+` in a query has to be percent-encoded. Foojay reads a bare one as a space and drops the build, so `21.0.5+63130` would match every 21.0.5 build. +- `version=21` is the GA build `21+35`. A bare major adds `latest=available` to get the newest 21.x. +- Windows asks for `zip` and `tar.gz` in one request. JetBrains Runtime ships Windows zips for its newer builds only. `PreInstall` takes the zip when a version has both. +- `Available` lists a name once where Foojay has two records for it. +- Foojay marks GraalVM's monthly feature releases (`25.1.3` and on) as LTS. `is_feature_release` in `lib/distribution_version.lua` recognises them, by the minor number, and `Available` drops the note. It is for `graal` and `graalce` only: Mandrel and Liberica NIK numbered their releases after themselves up to 24 (`mandrel` `23.1.12` is LTS) and follow the JDK from 25 on. +- For a bare major of Oracle GraalVM (`graal`) only, `PreInstall` skips the feature releases, so the 25.0 line is installed. A major that has nothing but feature releases keeps them. GraalVM Community is not filtered, because its feature releases are what it still ships. +- The CPU names are `arm64` to `aarch64`, and on Windows `amd64` to `x64`. `darwin` becomes `macos`. On Linux `ldd --version` decides between glibc and musl. + +## Tests + +The hook tests run offline under `gopher-lua`, the Lua interpreter vfox embeds: + +```bash +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_install_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua +``` + +Run them from the repository root. All five load `tests/support.lua`, which stubs `vfox.strings`, and `tests/pre_install_test.lua` and `tests/loongnix_test.lua` stub `http` and `json` themselves. `tests/pre_install_test.lua` keeps Foojay's answers in a table at the top, keyed by ` [] []`, with `windows` in front for Windows. Add the answer a new case needs there, and note the day you observed it. Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks). + +To call a single hook against the real Foojay, vfox 1.0.13 and later has `vfox plugin run`. It does not register the plugin, and `--os` and `--arch` answer for another platform: + +```bash +vfox plugin run . Available --input '{"args":["tem"]}' --json +vfox plugin run . PreInstall --input '{"version":"21-tem"}' --os windows --arch arm64 --json +vfox plugin run . ParseLegacyFile --input '{"filename":".sdkmanrc","filepath":"/tmp/p/.sdkmanrc","installedVersions":["21.0.8+9-tem"]}' --json +``` + +`vfox --debug ` shows what vfox does with a hook, which is how to find an error it swallows. + +## Adding a distribution + +1. Find its id in Foojay ([foojay.md](foojay.md)), and check that it has packages for the platforms you care about. +2. Add `[""] = ""` to `short_name` in `lib/distribution_version.lua`. Use SDKMAN's identifier when SDKMAN has the distribution. If SDKMAN spells it differently, map it in `plugin_spelling` in `hooks/parse_legacy_file.lua`. +3. If its version numbers or its LTS marks need special care, as GraalVM's do, handle that in `hooks/available.lua` and `hooks/pre_install.lua`. +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`. +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. + +## Refreshing the platform table + +[platforms.md](platforms.md) was taken from Foojay. This prints, for each platform, which distributions have a build there, in 8 requests: + +```bash +base='https://api.foojay.io/disco/v3.0/packages/jdks?directly_downloadable=true&latest=per_distro' +while read -r name query; do + printf '%-14s ' "$name" + curl -s "$base&$query" | jq -r '.result[].distribution' | sort -u | tr '\n' ' '; echo +done <<'EOF' +linux-x64 architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz +linux-arm64 architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz +alpine-x64 architecture=amd64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz +alpine-arm64 architecture=aarch64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz +macos-intel architecture=amd64&operating_system=macos&archive_type=tar.gz +macos-arm64 architecture=aarch64&operating_system=macos&archive_type=tar.gz +windows-x64 architecture=x64&operating_system=windows&archive_type=zip&archive_type=tar.gz +windows-arm64 architecture=aarch64&operating_system=windows&archive_type=zip&archive_type=tar.gz +EOF +``` + +The ids are Foojay's (`oracle_open_jdk` is `open`). The notes under "Only some releases" need one query per distribution and platform without `latest`, grouped by `major_version`. + +## Known gaps + +- Downloads are not verified, see above. +- `vfox search` lists GA releases only. Early-access builds install by name. +- Foojay distributions without a short name ([distributions.md](distributions.md#foojay-distributions-the-plugin-does-not-offer)), and JRE packages, are not offered. +- Only Linux loong64 has a source besides Foojay. + +## 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. + +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*`. + +## 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. diff --git a/docs/distributions.md b/docs/distributions.md new file mode 100644 index 0000000..e734f75 --- /dev/null +++ b/docs/distributions.md @@ -0,0 +1,122 @@ +# Distributions from Foojay + +[中文](zh-CN/distributions.md) | [English](distributions.md) + +The plugin gets the releases and download links of these 18 distributions from [Foojay](foojay.md). 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 | +| --- | --- | --- | --- | +| `open` | `openjdk` | OpenJDK builds from jdk.java.net | Oracle, for the OpenJDK project | +| `tem` | `temurin` | Temurin | Eclipse Adoptium | +| `zulu` | `zulu` | Zulu | Azul | +| `librca` | `liberica` | Liberica | BellSoft | +| `amzn` | `corretto` | Corretto | Amazon | +| `ms` | `microsoft` | Microsoft Build of OpenJDK | Microsoft | +| `oracle` | `oracle` | Oracle JDK | Oracle | +| `sem` | `semeru` | Semeru Runtimes, open edition | IBM | +| `sapmchn` | `sap_machine` | SapMachine | SAP | +| `kona` | `kona` | Tencent Kona JDK | Tencent | +| `albba` | `dragonwell` | Alibaba Dragonwell | Alibaba | +| `bsg` | `bisheng` | BiSheng JDK | Huawei | +| `graal` | `graalvm` | Oracle GraalVM | Oracle | +| `graalce` | `graalvm_community` | GraalVM Community Edition | GraalVM project | +| `nik` | `liberica_native` | Liberica Native Image Kit | BellSoft | +| `mandrel` | `mandrel` | Mandrel | Red Hat | +| `jb` | `jetbrains` | JetBrains Runtime | JetBrains | +| `trava` | `trava` | TravaOpenJDK | community | + +The long names are the distribution names Foojay takes, except `openjdk`, which Foojay lists as Oracle OpenJDK and accepts as a synonym. The short names are SDKMAN's, except `jb`, which SDKMAN calls `jbr`. A `.sdkmanrc` accepts `jbr` as well as `jb`, see [sdkmanrc.md](sdkmanrc.md). `lnxabi1` and `lnxabi2` are not in the table because they do not come from Foojay, see [loongnix.md](loongnix.md). + +Which operating systems and CPUs each distribution covers is in [platforms.md](platforms.md). `vfox search java ` lists what exists for the machine you run it on. Installed names carry the short name, except for OpenJDK, which has none (see [versions.md](versions.md)). + +## OpenJDK builds + +### OpenJDK (`open`) + +The builds on [jdk.java.net](https://jdk.java.net/), under GPLv2 with the Classpath Exception. This is what a version without a distribution means. The site carries the newest releases and the last build of older ones, which makes it a poor choice for 17 or 21, see [versions.md](versions.md#without-a-distribution). It publishes early-access builds too. + +### Temurin (`tem`) + +The builds of the [Eclipse Adoptium](https://adoptium.net/temurin/releases) project, which grew out of AdoptOpenJDK. Java 8, 11 and 16 onwards, with early-access builds. + +### Zulu (`zulu`) + +[Azul's](https://www.azul.com/downloads/?package=jdk) builds of OpenJDK. Java 6 and 7 are there as well as the current releases, and there are JavaFX builds (`-fx`). + +### Liberica (`librca`) + +[BellSoft's](https://bell-sw.com/) builds of OpenJDK, with JavaFX builds (`-fx`). It is one of five distributions with Windows on ARM64. + +### Corretto (`amzn`) + +[Amazon's](https://aws.amazon.com/corretto/) build of OpenJDK. Java 8, 11 and 15 onwards. + +### Microsoft Build of OpenJDK (`ms`) + +[Microsoft's](https://www.microsoft.com/openjdk) build. Java 11, 16, 17, 21 and 25, for Linux, macOS and Windows on x64 and arm64. + +### Oracle JDK (`oracle`) + +[Oracle's](https://www.oracle.com/java/) own JDK, from Java 17. The licence is Oracle's, not an open-source one, and its terms differ between releases. Read the ones for the release you install. + +### Semeru (`sem`) + +[IBM's](https://developer.ibm.com/languages/java/semeru-runtimes/) runtimes: the OpenJDK class library on the Eclipse OpenJ9 virtual machine instead of HotSpot. Only the open edition is offered, not Foojay's `semeru_certified`. + +### SapMachine (`sapmchn`) + +[SAP's](https://sapmachine.io/) build of OpenJDK. Java 11 onwards. + +### Kona (`kona`) + +[Tencent's](https://tencent.github.io/konajdk) build of OpenJDK. Java 8, 11, 17, 21 and 25. + +### Dragonwell (`albba`) + +[Alibaba's](https://dragonwell-jdk.io/) build of OpenJDK. Java 8, 11, 17, 21 and 25 for Linux and Windows. There is no macOS build. + +### BiSheng (`bsg`) + +[Huawei's](https://www.hikunpeng.com/developer/devkit/compilation_debugging?data=JDK) build of OpenJDK, aimed at ARM servers. Java 8, 11, 17, 21 and 25, for Linux only. + +## GraalVM family + +### 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-graal`. + +### GraalVM Community (`graalce`) + +The open-source edition of GraalVM, built on OpenJDK. + +### Liberica Native Image Kit (`nik`) + +[BellSoft's](https://bell-sw.com/) distribution for building native images, based on GraalVM. Java 21 to 25, with `-fx` builds on some platforms. + +### Mandrel (`mandrel`) + +[Red Hat's](https://github.com/graalvm/mandrel) distribution for building Quarkus native executables, which concentrates on `native-image`. + +Mandrel and Liberica NIK numbered their releases after themselves up to version 24 (Mandrel `23.1.12`), and number them after the JDK from 25 on (`25.0.4.1`). + +### 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`. Each is replaced within about a month. Foojay marks them LTS because the JDK they build on is LTS, and `vfox search` leaves the LTS note off them. Unreleased: 0.6.1 still adds the note. +- `java@25-graal` installs the newest build of the 25.0 line (`25.0.4.1-graal`), the line Oracle's own `25/latest` download follows. A feature release needs its full version: `java@25.4.4.1-graal`. Unreleased: 0.6.1 installed the GA build `25-graal`. +- 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-graalce` on 2026-10-18. Unreleased: 0.6.1 installs the GA build `25-graalce`. +- 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. Unreleased: 0.6.1 set `GRAALVM_HOME` for `graal` and `graalce`, replacing yours. +- There is no Windows ARM64 and no Alpine build, and Intel Macs get nothing after 25.0.1. See [platforms.md](platforms.md#graalvm). + +## Others + +### JetBrains Runtime (`jb`) + +The [fork of OpenJDK](https://github.com/JetBrains/JetBrainsRuntime) that JetBrains' IDEs run on. Java 11, 17, 21 and 25. On Windows some releases ship only as tar.gz. The plugin installs those, and `vfox search` lists them. Unreleased: 0.6.1 does not list them. + +### TravaOpenJDK (`trava`) + +[OpenJDK with DCEVM](https://github.com/TravaOpenJDK) and a bundled HotswapAgent, for replacing classes in a running program. Java 8 and 11. Foojay marks it as no longer maintained. It has no Apple silicon build and one for Linux arm64 (`11.0.10+6`). + +## Foojay distributions the plugin does not offer + +Foojay lists more than these 18: `aoj` and `aoj_openj9` (AdoptOpenJDK, succeeded by Temurin and Semeru), `eliya`, `gluon_graalvm`, `graalvm_ce8`, `graalvm_ce11`, `graalvm_ce16`, `graalvm_ce17`, `graalvm_ce19` (old GraalVM Community releases), `ojdk_build`, `openlogic`, `redhat` and `semeru_certified`. They have no short name here, so `vfox install java@21-openlogic` fails with `Could not extract a valid distribution`. [development.md](development.md#adding-a-distribution) describes how to add one. diff --git a/docs/e2e.md b/docs/e2e.md index 94980d5..c397c8f 100644 --- a/docs/e2e.md +++ b/docs/e2e.md @@ -1,5 +1,7 @@ # E2E +[中文](zh-CN/e2e.md) | [English](e2e.md) + The offline Lua hook tests (`tests/*_test.lua`) run in the **Test Plugin** workflow. The end-to-end suite runs in containers against real vfox on Linux and Windows; each `vfox` x `distribution` combination gets its own throwaway diff --git a/docs/foojay.md b/docs/foojay.md new file mode 100644 index 0000000..3b8f918 --- /dev/null +++ b/docs/foojay.md @@ -0,0 +1,126 @@ +# Querying Foojay + +[中文](zh-CN/foojay.md) | [English](foojay.md) + +[Foojay](https://foojay.io/) runs the Disco API, a public index of JDK builds from many vendors (source: [foojayio/discoapi](https://github.com/foojayio/discoapi)). Except on Linux loong64, the plugin gets every list of versions and every download link from it. What `vfox search` shows is Foojay's data, and Foojay is where to look when a build you expect is missing. + +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`, 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` | +| `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 | +| `lib_c_type` | `glibc` or `musl` on Linux, empty elsewhere | +| `directly_downloadable` | always `true` | +| `latest` | `available`, added only when the version is a bare major such as `21` | + +Without `latest=available`, `version=21` matches the 21 GA build only (`21+35`). With it Foojay picks the newest 21.x, which is what `java@21-tem` installs. Longer versions match as they are. + +Unreleased: release 0.6.1 sends a `+` as it is, never adds `latest=available` (so `java@21-tem` installs `21+35-tem`), and on Windows asks for `zip` only, falling back to `tar.gz` when that returns nothing. + +The answer is a list of packages. The plugin names a release after `java_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. 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). That record also holds a `checksum`. The plugin does not pass it on, so vfox prints `WARNING: Checksum is not provided, skip verify...` and does not verify the download. + +`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 (unreleased, see [distributions.md](distributions.md#behavior-of-oracle-graalvm-and-graalvm-community)). It only lists GA releases. + +## Which distributions have a build for my platform + +`latest=per_distro` returns the newest package of every distribution that has one. Do not combine it with `version`, which it ignores. + +```bash +# Windows on ARM64 +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?architecture=aarch64&operating_system=windows&archive_type=zip&archive_type=tar.gz&directly_downloadable=true&latest=per_distro' \ + | jq -r '.result[].distribution' | sort -u +``` + +``` +jetbrains +liberica +microsoft +temurin +zulu +``` + +For another platform change the three parameters that name it. Linux needs `lib_c_type=glibc` or `musl` as well: + +| Platform | Parameters | +| --- | --- | +| Linux arm64 | `architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz` | +| Alpine x64 | `architecture=amd64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz` | +| macOS Apple silicon | `architecture=aarch64&operating_system=macos&archive_type=tar.gz` | +| 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 answer includes distributions the plugin does not offer. [distributions.md](distributions.md#foojay-distributions-the-plugin-does-not-offer) lists them. + +## Which distributions have a release for my platform + +```bash +# Java 27 on Intel Macs +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?version=27&latest=available&architecture=amd64&operating_system=macos&archive_type=tar.gz&directly_downloadable=true' \ + | 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. + +## The versions of one distribution + +This is what `vfox search java tem` shows, for the machine you run it on: + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[].java_version' +``` + +``` +27+35 +26.0.2.1+1 +26.0.2+10 +... +``` + +Add `version=21.0.8` for one release, and `javafx_bundled=true` for the JavaFX builds only. A record looks like this: + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&version=21.0.8&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -c '.result[] | {java_version, distribution_version, term_of_support, javafx_bundled, archive_type, filename}' +``` + +``` +{"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`). + +## Releases and support terms + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/major_versions?ea=false&ga=true&maintained=true' \ + | jq -r '.result[] | [.major_version, .term_of_support] | @tsv' +``` + +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`. + +## 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 new file mode 100644 index 0000000..f717c9a --- /dev/null +++ b/docs/install-from-source.md @@ -0,0 +1,72 @@ +# Install from source + +[中文](zh-CN/install-from-source.md) | [English](install-from-source.md) + +`vfox add java` installs the latest release. `main` has fixes that are not in it yet ([changes.md](changes.md)), and a change you are working on is not in any release. A plugin is a `metadata.lua` plus the `hooks` and `lib` directories, and vfox adds one from a zip of them. + +## Ubuntu 26.04 + +Execute in Bash, + +```bash +sudo apt install --assume-yes git zip +git clone --depth 1 https://github.com/version-fox/vfox-java.git +cd ./vfox-java/ +zip -qr ./java.zip metadata.lua hooks lib +vfox add java --source ./java.zip +rm ./java.zip +``` + +macOS is the same, with `git` and `zip` that come with the system. + +## Windows 11 + +Assume that PowerShell 7 is already installed. Execute in PowerShell 7, + +```powershell +winget install --id Git.Git --source winget --exact +git clone --depth 1 https://github.com/version-fox/vfox-java.git +cd ./vfox-java/ +tar -a -cf ./java.zip metadata.lua hooks lib +vfox add java --source ./java.zip +Remove-Item ./java.zip +``` + +## Check it + +```bash +vfox install java@21-tem +vfox use --global java@21-tem +java -version +``` + +A build of `main` installs the newest Temurin 21 (`21.0.12.1+1-tem` on 2026-10-18). Release 0.6.1 installs `21+35-tem`, the first build of 21. + +## When java is already added + +`vfox add` refuses with `plugin named java already exists`. You can replace the plugin or add the source build next to it. + +To replace it, `vfox remove java` comes first, and it removes the JDKs installed through the plugin as well: vfox says so before it asks. Reinstall them afterwards. + +To keep both, give the new one another name: + +```bash +vfox add java --source ./java.zip --alias java-dev +vfox install java-dev@21-tem +vfox remove -y java-dev # removes only java-dev and what it installed +``` + +The alias has its own list of installed JDKs, but `JAVA_HOME` is `~/.vfox/sdks/java` for both. Select a version from only one of them per scope: for the global scope, `vfox unuse --global java` before you `vfox use --global java-dev@...`, or the other way round. With both selected, vfox relinks both on every prompt, and `JAVA_HOME` can end up at either. + +## Updating + +Pull, build the zip again and add it again. A plugin added under its own name has to be removed first, and that takes the installed JDKs with it, so the alias is the easier route when you update often: + +```bash +vfox remove -y java-dev +vfox add java --source ./java.zip --alias java-dev +``` + +`vfox update java` compares the version in `metadata.lua` with the registry's and prints `java is already the latest version` while they are equal, so it leaves a source build alone until a release newer than that version is published. + +To work on the plugin, see [development.md](development.md). diff --git a/docs/javafx.md b/docs/javafx.md new file mode 100644 index 0000000..0510464 --- /dev/null +++ b/docs/javafx.md @@ -0,0 +1,45 @@ +# JavaFX builds + +[中文](zh-CN/javafx.md) | [English](javafx.md) + +Some vendors publish JDKs with JavaFX bundled, as separate packages. Put `-fx` after the distribution to get one: + +```bash +vfox install java@21-zulu-fx +vfox install java@25.0.4-librca-fx +vfox use java@21-zulu-fx +``` + +`vfox search` lists both kinds of build, with `-fx` on the name and a JavaFX note: + +``` + - 25.0.4.1+1-zulu-fx (LTS, JavaFX) + - 25.0.4.1+1-zulu (LTS) +``` + +The installed name keeps the suffix (`25.0.4+9-librca-fx`), so a build with JavaFX and one without can sit side by side. They are never mixed up: + +- `java@21-zulu` installs a build without JavaFX, and `java@21-zulu-fx` one with it. If the distribution has only one of the two for that release, the other fails: `java@21-tem-fx` ends with `No JDK found for 21-tem-fx with JavaFX on linux/amd64`, since Temurin has no JavaFX builds. +- `vfox use java@21-zulu` never selects a `-fx` build, and the other way round. +- A `.sdkmanrc` follows the same rule, see [sdkmanrc.md](sdkmanrc.md). + +To check what you got, look for the modules: + +```bash +java --list-modules | grep javafx +``` + +A build with JavaFX lists `javafx.base` and the others, one without lists none. + +## Where JavaFX builds exist + +As of 2026-10-18 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. + +| Distribution | Linux x64 | Linux arm64 | Alpine x64 | macOS Intel | macOS Apple silicon | Windows x64 | Windows arm64 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Zulu (`zulu`) | 8, 11, 17, 21, 25 | 8, 11, 17, 21, 25 | – | 8, 11, 17, 21, 25 | 8, 11, 17, 21, 25 | 8, 11, 17, 21, 25 | – | +| Liberica (`librca`) | 8, 11, 17, 21, 25 | 11, 17, 21, 25 | 11 | 8, 11, 17, 21, 25 | 8, 11, 17, 21, 25 | 8, 11, 17, 21, 25 | 11, 17, 21, 25 | +| Corretto (`amzn`) | 8 | 8 | – | 8 | – | 8 | – | +| Liberica NIK (`nik`) | 21, 25 | – | – | 25 | 25 | 21, 25 | – | + +Nothing has JavaFX for Alpine arm64. Loongnix has JavaFX builds for LoongArch, selected the same way, see [loongnix.md](loongnix.md). To see the current picture for a platform, add `javafx_bundled=true` to a query like the ones in [foojay.md](foojay.md). diff --git a/docs/loongnix.md b/docs/loongnix.md new file mode 100644 index 0000000..b1b0d81 --- /dev/null +++ b/docs/loongnix.md @@ -0,0 +1,53 @@ +# Loongnix JDKs + +[中文](zh-CN/loongnix.md) | [English](loongnix.md) + +Foojay has no packages for LoongArch and rejects the architecture. On Linux loong64 the plugin therefore reads the JDKs from the [Loongnix archive](https://ftp.loongnix.cn/Java/) of Loongson, and does not talk to Foojay at all. It is the only JDK source of the plugin that is not Foojay. On every other platform `lnxabi1` and `lnxabi2` fail with `Loongnix JDKs require linux/loong64`, and on loong64 the distributions in [distributions.md](distributions.md) are not available: + +``` +$ vfox search java tem +Foojay does not support loong64; use vfox search java loongnix +``` + +## Choose the ABI + +The archive holds two kinds of builds, and the plugin does not guess which one fits: + +| Short name | Long name | Build | For | +| --- | --- | --- | --- | +| `lnxabi1` | `loongnix_abi1` | Linux 4.19 UAPI | Loongnix 20, Loongnix Server 8.4 | +| `lnxabi2` | `loongnix_abi2` | Linux 5.10 UAPI, `glibc2.34` in the upstream file names | Debian 12, openEuler | + +Take the choice from [Loongson's compatibility notes](https://www.loongnix.cn/zh/api/java/) for your system, and not from the kernel version alone. + +## Use + +```bash +vfox search java lnxabi2 # the ABI2 builds +vfox install java@21-lnxabi2-fx # newest Java 21 with JavaFX, ABI2 +vfox install java@21.0.12+8-lnxabi2-fx # one build +vfox use java@21.0.12+8-lnxabi2-fx +``` + +`vfox search java` without a name lists the builds of both ABIs, as `vfox search java loongnix` and `vfox search java all` do. A result looks like this: + +``` + - 26+35-lnxabi2-fx (JDK 26+35; ABI2 (Linux 5.10 UAPI, glibc 2.34); JavaFX) + - 25.0.4+7-lnxabi2-fx (JDK 25.0.4+7; ABI2 (Linux 5.10 UAPI, glibc 2.34); JavaFX) +``` + +An install needs the ABI in its name. `vfox install java@21` and `java@21-tem` end with `Choose a Loongnix ABI explicitly: run vfox search java and select lnxabi1 or lnxabi2`. Picking a result from `vfox search` in an interactive terminal supplies it. + +The version is Java's version and build number, `21.0.12+8`, and not Loongson's release number (`loongson21.12.26` in the file name). A release that Loongson published more than once is taken from the newest. `21` and `21.0.12` match by prefix and take the newest build, `21.0.1` does not match `21.0.12`. `vfox use` keeps the ABI and the `-fx` of what you type, so `21-lnxabi2-fx` selects the newest installed one and never an `lnxabi1` build. + +## JavaFX + +Most of Loongson's packages are JavaFX builds, which carry `fx-` in the upstream file name and `-fx` here. All of Java 21 and later are, and so are most of 8, 11 and 17, apart from a few early builds. Without `-fx` you only get a build that has no JavaFX, so `java@21-lnxabi2` fails with `No Loongnix JDK found for 21-lnxabi2` and `java@21-lnxabi2-fx` installs. + +## Limits + +- Only the general-availability LoongArch tarballs of the archive are offered. Early-access builds, installers, checksum files and the MIPS packages are skipped. +- The archive has glibc builds and no musl builds. +- The plugin does not verify the download. +- It reads the HTML directory listing of the archive. If Loongson changes its layout, the plugin stops with `No Loongnix JDK packages found; check the requested version and upstream directory format`. +- There is no loong64 job in the e2e suite. The hooks are tested offline against a saved copy of the archive listing, `tests/fixtures/loongnix` (see [development.md](development.md)). diff --git a/docs/platforms.md b/docs/platforms.md new file mode 100644 index 0000000..c72b4cf --- /dev/null +++ b/docs/platforms.md @@ -0,0 +1,71 @@ +# Platform support + +[中文](zh-CN/platforms.md) | [English](platforms.md) + +The plugin asks Foojay for packages of the platform it runs on: the operating system, the CPU architecture of the vfox binary and, on Linux, the C library (see [foojay.md](foojay.md) for the request). A distribution that has nothing for that platform fails in `vfox search java bsg` with `no available version`, and installing it fails too: + +``` +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. A tick means Foojay lists at least one package the plugin can install there, a dash means none. + +| Distribution | Linux x64 | Linux arm64 | Alpine x64 | Alpine arm64 | macOS Intel | macOS Apple silicon | Windows x64 | Windows arm64 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| OpenJDK (`open`) | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Temurin (`tem`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Zulu (`zulu`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Liberica (`librca`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Corretto (`amzn`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Microsoft (`ms`) | ✓ | ✓ | ✓ | – | ✓ | ✓ | ✓ | ✓ | +| Oracle JDK (`oracle`) | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Semeru (`sem`) | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| SapMachine (`sapmchn`) | ✓ | ✓ | ✓ | – | ✓ | ✓ | ✓ | – | +| Kona (`kona`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Dragonwell (`albba`) | ✓ | ✓ | ✓ | – | – | – | ✓ | – | +| BiSheng (`bsg`) | ✓ | ✓ | – | – | – | – | – | – | +| Oracle GraalVM (`graal`) | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| GraalVM Community (`graalce`) | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Liberica NIK (`nik`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Mandrel (`mandrel`) | ✓ | ✓ | – | – | – | ✓ | ✓ | – | +| JetBrains Runtime (`jb`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Trava (`trava`) | ✓ | ✓ | – | – | ✓ | – | ✓ | – | + +"Alpine" stands for Linux with the musl C library. The plugin takes it as musl when `ldd --version` mentions it, and as glibc otherwise. Loongnix has its own page, [loongnix.md](loongnix.md). + +Foojay changes, and the table with it. To get the current one, ask Foojay the way [foojay.md](foojay.md#which-distributions-have-a-build-for-my-platform) shows. + +## Only some releases + +A tick does not mean every release is there. As of the same date: + +- 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 23 to 25, and Liberica NIK 22 to 25. +- 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). + +## Which are x64 only + +Every distribution has Linux arm64 builds, and Trava has a single one (11.0.10+6). On macOS, Dragonwell and BiSheng have neither architecture, Trava has Intel only, and Mandrel has Apple silicon only. + +On Windows almost everything is x64 only. These have an arm64 build besides: Temurin, Zulu, Liberica, Microsoft and JetBrains Runtime. The others are x64 only, with BiSheng not there at all. + +## GraalVM + +Oracle GraalVM and GraalVM Community have x64 and arm64 builds for Linux and macOS, and x64 only for Windows. They have no Alpine build. For Intel Macs the newest release is 25.0.1, and the monthly feature releases since 25.1 come for Apple silicon on macOS. The e2e suite skips GraalVM Community on arm64 only because its Windows arm64 job would have nothing to install. Linux arm64 has builds. + +## Other CPUs + +vfox ships binaries for 32-bit x86 and 32-bit ARM as well as x64, arm64 and loong64. The plugin passes the architecture name of the vfox binary to Foojay (`arm64` as `aarch64`, and `amd64` as `x64` on Windows), so what you get is what Foojay lists. None of this is covered by the e2e suite. + +- 32-bit ARM Linux: Corretto, Liberica, Temurin and Zulu. +- 32-bit x86 Linux: Corretto, Liberica, Zulu and JetBrains Runtime. +- 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. + +## macOS Java home + +Some macOS archives hold the JDK in `Contents/Home` or in a vendor-named bundle. After the install the plugin moves the contents up, so `JAVA_HOME` always points at a directory with `bin/java`. The install prints `Checking Java home layout...` for it. An archive with two candidate homes, or one whose files would overwrite each other, is refused before anything is moved. diff --git a/docs/sdkmanrc.md b/docs/sdkmanrc.md new file mode 100644 index 0000000..fb9210d --- /dev/null +++ b/docs/sdkmanrc.md @@ -0,0 +1,76 @@ +# `.sdkmanrc` + +[中文](zh-CN/sdkmanrc.md) | [English](sdkmanrc.md) + +vfox can read `.sdkmanrc`, the project file of [SDKMAN](https://sdkman.io/), through this plugin (the plugin lists it in `PLUGIN.legacyFilenames`). A project that already pins its JDK for SDKMAN needs no second file for vfox: + +``` +# .sdkmanrc +java=21.0.8-tem +``` + +Only the `java=` line is read. Other lines, such as `maven=3.9.9`, are not this plugin's business. + +> Unreleased: release 0.6.1 cannot read `.sdkmanrc` under vfox 1.x. Its hook calls `ctx:getInstalledVersions()`, which every vfox 1.x rejects (tested with 1.0.12 and 1.0.13) with `expected 0 arguments for func() []string, got 1`, and vfox drops that error, so nothing happens. `main` fixes it, matches more of SDKMAN's spellings (`jbr`, JavaFX, zero padding, early access) and picks the right JDK when several of one major are installed. Try it with [install-from-source.md](install-from-source.md). The details are in [changes.md](changes.md). + +## Using it + +```bash +eval "$(vfox activate bash)" # once, in ~/.bashrc; other shells: see vfox's quick start + +vfox install java@21.0.8-tem # .sdkmanrc never installs anything +cd my-project # holds the .sdkmanrc above +java -version # Temurin 21.0.8 +``` + +vfox's shell hook reads the file when you enter the directory and selects the JDK it names. `vfox use` is not needed. The hook is vfox's own, see its [quick start](https://vfox.dev/guides/quick-start.html) for zsh, fish, PowerShell and the others. + +- The file is read from the current directory only. In a subdirectory of the project it is not found, as with SDKMAN's `sdk env`. +- A `.vfox.toml` in the same directory that names `java` wins over `.sdkmanrc`. `vfox use --project` writes one. +- In that directory the file also outranks a `vfox use` without `--project`: the next prompt switches back, while `vfox current java` still names the session's choice. +- vfox creates `.vfox/sdks/java` in that directory and does not add `.vfox/` to `.gitignore`, so `git status` lists it. Ignore it yourself. +- The JDK has to be installed already. When nothing installed matches, the file is ignored and no message is printed. `vfox list java` shows what there is. +- `vfox config legacyVersionFile.enable false` turns all legacy files off. `legacyVersionFile.strategy` has no effect on this plugin: the version in the file is what counts. + +## What an identifier selects + +The plugin matches the identifier against the JDKs that are installed, in this order: + +1. An installed name written as it is: `java=21.0.8+9-tem`, `java=28-ea+19`. +2. The release you named, with its newest installed build: `21.0.8-tem` selects `21.0.8+9-tem`. +3. Failing that, the newest installed release of the same major. `21-tem` goes straight to this step. + +Step 3 does not check that the release is at least the one named. With only `21.0.8+9-tem` installed, `java=21.0.12-tem` selects it, and so does `java=21.0.3-tem`. A build number that is not installed falls back to the newest installed build of the release (`21.0.8+7-tem` selects `21.0.8+9-tem`). If the major is not installed at all, nothing is selected. + +It never crosses to another distribution, between a JavaFX build and a plain one, or between an early-access build and a release. + +## SDKMAN's spellings + +`sdk list java` shows two generations of identifiers side by side. The plugin reads both, and its own names: + +| In `.sdkmanrc` | Selects | +| --- | --- | +| `21.0.8-tem` | Temurin 21.0.8, installed as `21.0.8+9-tem` | +| `21.0.5-jbr` | JetBrains Runtime (`jb`), which SDKMAN calls `jbr` | +| `21.0.12.fx-zulu` | Zulu with JavaFX, `21.0.12+8-zulu-fx` (older spelling) | +| `21.0.12-fx+1.1-librca` | Liberica with JavaFX (newer spelling) | +| `21.0.8+1.1-tem` | Temurin 21.0.8, see below | +| `27.0.0+36-librca`, `25.0.1.0+8-open` | `27+36-librca`, `25.0.1+8`: the zeros are dropped | +| `28.ea.19-open`, `28.0.0+ea.19-open` | the early-access build `28-ea+19` | + +The number after `+` in SDKMAN's newer identifiers (`21.0.8+1.1-tem`) counts SDKMAN's own rebuilds. It is not a build number of the vendor, so the plugin does not look for one and takes the release. Foojay, and so the installed name, has no zero padding, which is why `27.0.0` means the release `27`. A `.0` padding in `sdk list java` is common (`25.0.1.0+8-open`, `21.0.9.0+116386-jbr`), and the plugin reads it as well. + +## Not finding it + +If the JDK does not switch: + +- The shell hook is not active. `eval "$(vfox activate bash)"` has to run in the shell, not only once somewhere else. +- The shell is in a subdirectory of the one with the file. +- The JDK is not installed, or only another flavour of it is. `java=21.0.8-zulu` does not select a JavaFX build, and `java=21.0.8.fx-zulu` does not select a plain one. Install the one the file names, for example `vfox install java@21.0.8-zulu-fx`. +- A `.vfox.toml` is in the way, or `legacyVersionFile.enable` is `false`. + +`vfox --debug env -s bash` prints how the file was parsed. + +## Differences from SDKMAN + +`sdk env install` installs the JDKs a `.sdkmanrc` names. vfox only selects among what is installed, and you install with `vfox install java@`. An identifier copied from the file is not always a spec that `vfox install` takes: `21.0.8-tem` is, `21.0.12.fx-zulu` is not, and `21.0.12-zulu-fx` is. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..7420adc --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,76 @@ +# Troubleshooting + +[中文](zh-CN/troubleshooting.md) | [English](troubleshooting.md) + +## Messages from the plugin + +### `No JDK found for 21-bsg on darwin/arm64. Please check available versions with 'vfox search java'` + +Foojay has no package for that release, distribution and flavour on this platform. The platform in the message is the one the plugin asked for, `linux/amd64`, `darwin/arm64`, `windows/arm64` and so on. Check three things: + +- Whether the distribution has anything for the platform at all: [platforms.md](platforms.md). +- Whether the release exists: `vfox search java ` lists what the platform can install. +- Whether a distribution is missing from the spec. `java@17.0.17` means OpenJDK from jdk.java.net, which stops at 17.0.2. `java@17.0.17-tem` works, see [versions.md](versions.md#without-a-distribution). + +`with JavaFX` or `without JavaFX` in the message means the release exists, but not in that flavour. See [javafx.md](javafx.md). + +### `No version in tem; add one, such as 21-tem. Please check available versions with 'vfox search java tem'` + +The spec holds a distribution and no version. `java@-tem`, `java@temurin-` and `java@zulu-fx` are the same case. Unreleased: 0.6.1 stops with `attempt to index a non-table object(nil) with key 'match'` for `java@tem`, and installs the newest release for `java@-tem`. + +### `Could not extract a valid distribution: 21-foo` + +Neither part of the spec is the name of a distribution. Names are lower case and come from the table in [distributions.md](distributions.md). `java@21-openlogic` ends here too, because the plugin does not offer every distribution Foojay has. + +### `Unsupported distribution: foo` + +The same for `vfox search java foo`. + +### `Failed to fetch jdk info from foojay: ...` + +The request to Foojay failed. After `status_code =>` comes the HTTP status, otherwise the network error. See [Network](#network) below. `Failed to fetch jdk info: ...` is the same for the second request, the one for the download link. + +### `source file not found` + +The download answered 404. Vendors take old builds down while Foojay keeps their records. Early-access builds are the common case (see [versions.md](versions.md#early-access-builds)). Pick a newer build. + +### `java@21-tem is not installed` + +`vfox use` and `vfox uninstall` only know what is installed. `vfox list java` shows it, with names that carry the build number: `21.0.8+9-tem`. `vfox uninstall` needs the whole name. + +### Messages about the Java home on macOS + +`Checking Java home layout...` is printed during every macOS install. If it is followed by `Failed to normalize Java home`, the archive did not have the layout the plugin expects: `Multiple Java homes found in `, `No Java home containing bin/java found in `, or `Cannot normalize Java home: destination already exists: `. Please report it with the distribution and version. + +### Loongnix + +`Loongnix JDKs require linux/loong64`, `Foojay does not support loong64; use vfox search java loongnix`, `Choose a Loongnix ABI explicitly`, `No Loongnix JDK found for ...` and `No Loongnix JDK packages found` are explained in [loongnix.md](loongnix.md). + +## Network + +The plugin talks to Foojay for the lists, and vfox downloads the archive from the vendor's server, often GitHub Releases. The plugin has no mirror setting. + +vfox's own proxy setting covers both the Foojay requests and the download: + +```bash +vfox config proxy.enable true +vfox config proxy.url http://127.0.0.1:7890 +``` + +While `proxy.enable` is `false`, the usual `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables apply. Only `http` and `https` proxies are supported. + +## 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...` on every install.** The plugin does not pass a checksum to vfox, so the download is not verified, see [foojay.md](foojay.md#what-the-plugin-asks). +- **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. Unreleased: 0.6.1 replaced it for GraalVM. + +## Where the JDK is + +`JAVA_HOME` is a link that `vfox use` points at the JDK you chose. For `--global` it is `~/.vfox/sdks/java`, for `--project` it is `.vfox/sdks/java` in the project, and for a session it is a directory under `~/.vfox/tmp`. An IDE or a build tool that should follow your global choice can point at the first. For a fixed JDK, `vfox info java@21.0.8+9-tem` prints a directory, and the JDK is the `java-21.0.8+9-tem` directory inside it. `~/.vfox` is the default `$VFOX_HOME`. When `VFOX_HOME` is set, the JDKs (`cache/`) and the plugins live there, while the `sdks/java` link and the session directories stay in `~/.vfox`. `storage.sdkPath` moves the JDKs too, see vfox's [configuration](https://vfox.dev/guides/configuration.html). + +## Reporting a problem + +Open an issue at [version-fox/vfox-java](https://github.com/version-fox/vfox-java/issues) with the output of `vfox --version` and `vfox info java`, the operating system and CPU, the command, and everything it printed. `vfox --debug ` prints more. Data that Foojay gets wrong belongs with [Foojay](https://github.com/foojayio/discoapi). diff --git a/docs/versions.md b/docs/versions.md new file mode 100644 index 0000000..fee64bf --- /dev/null +++ b/docs/versions.md @@ -0,0 +1,120 @@ +# Versions and names + +[中文](zh-CN/versions.md) | [English](versions.md) + +The part after `java@` in `vfox install` and `vfox use` is a version and a distribution, joined with `-`: + +```bash +vfox install java@21-tem # newest Temurin 21 +vfox install java@21.0.8-tem # Temurin 21.0.8 +vfox install java@21.0.8+9-tem # that exact build +vfox install java@21-zulu-fx # Zulu 21 with JavaFX +vfox install java@temurin-21 # same as 21-tem, distribution first +vfox install java@21 # no distribution: OpenJDK from jdk.java.net +``` + +The distribution is a short name (`tem`) or a long name (`temurin`). Both lists are in [distributions.md](distributions.md). `-fx` goes last and asks for a JavaFX build, see [javafx.md](javafx.md). + +> This page describes `main`. Release 0.6.1, the newest one when this was written, differs in places marked "Unreleased", and [changes.md](changes.md) lists all of them. + +## Without a distribution + +`java@21` means OpenJDK as published on [jdk.java.net](https://jdk.java.net/), and its installed name has no suffix (`21.0.2+13`). That site carries the newest releases and the last build of older ones: 17 stops at `17.0.2`, 21 at `21.0.2`. So `vfox install java@17.0.17` fails, while `java@17.0.17-tem` works. For a release that is still maintained, name a distribution. + +## Installing + +`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. Unreleased: 0.6.1 installed the first GA build, `21+35-tem`. +- 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`. Unreleased: 0.6.1 installed the newest build of the release instead. +- A release padded with zeros, as SDKMAN writes it, is accepted: `27.0.0-librca` installs `27+36-librca`. +- Oracle GraalVM's bare major installs the newest build of its 25.0 line, not one of the monthly feature releases, which have to be named in full (`25.4.4.1-graal`). See [GraalVM](distributions.md#graalvm-family). Unreleased: 0.6.1 installed the GA build, `25-graal`. +- With `-fx` only JavaFX builds are considered, without it only builds without JavaFX. The two are never mixed. +- 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. Unreleased: 0.6.1 failed with a Lua error for `java@tem` and installed the newest release for `java@-tem`. + +An install that finds the name already present prints `java@21.0.12.1+1-tem is already installed` and downloads nothing. + +## Installed names + +The plugin names an install after the `java_version` that Foojay reports, which is also what `vfox search` prints: + +``` +[-][-fx] +``` + +| Installed name | What it is | +| --- | --- | +| `21.0.12.1+1-tem` | Temurin | +| `25.0.4+9-librca-fx` | Liberica with JavaFX | +| `25.0.2+10` | OpenJDK, no suffix | +| `17.0.12-graal` | GraalVM, which has no build number | +| `8.0.482+8-zulu` | Java 8 is `8.0.+` | +| `28-ea+19` | early-access build, see below | + +These are the names `vfox list java` shows and `vfox uninstall` needs: + +```bash +vfox uninstall java@21.0.8+9-tem +``` + +`vfox uninstall java@21.0.8-tem` answers `is not installed`. When you uninstall the version in use, vfox switches to the first entry left in `vfox list java`, which can be another major. + +## Using + +`vfox use` maps what you type to an installed name without downloading anything, so the build number and the release can be left out: + +| You type | Selects | +| --- | --- | +| `21.0.8-tem` | the newest installed build of that release, `21.0.8+9-tem` | +| `21-tem` | the newest installed Temurin 21 | +| `temurin-21.0.8` | `21.0.8+9-tem` | +| `25.0.2-open`, `openjdk-25.0.2` | `25.0.2+10`, OpenJDK has no suffix | +| `21` | vfox's own match: the highest installed 21.x, from any distribution | + +If you name a build or a release, it does not cross over to another one (`21.0.12-tem` does not select `21.0.12.1+1-tem`). It does not cross to another distribution, between JavaFX and plain, or between early-access and GA either. A name that matches nothing is reported as `java@99-tem is not installed`. + +Unreleased: 0.6.1 passed what you typed on as it was, so `vfox use java@21.0.8-tem` found nothing and needed the full name, `21.0.8+9-tem`. The same goes for the `-open` and `openjdk-` spellings and for zero-padded releases. Under vfox 1.0.13 and later, `vfox use java@21` and `java@21-open` fail outright with 0.6.1, with `cannot unmarshal string into plugin.PreUseHookResult`, because it answers a bare major with an empty string. + +Pick the scope with `vfox use`'s flags: `--global`, `--project` or `--session`, the default. In a shell without vfox's hook, Windows switches to the global scope with a warning, while Linux and macOS stop with `vfox requires hook support`. `--project` writes a `.vfox.toml` that holds the installed name (`java = "17.0.10+7-tem"`). A `.sdkmanrc` is read as well, see [sdkmanrc.md](sdkmanrc.md). + +## Early-access builds + +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.15-open # 28-ea+15 +``` + +Unreleased: 0.6.1 ignores the build number and installs the newest early-access build. + +The installed name uses Foojay's spelling, `28-ea+19`, and `vfox use java@28-ea+19` takes it as it is. `vfox search` lists GA releases only. Foojay lists early-access builds for OpenJDK, Temurin, Zulu, SapMachine, GraalVM and GraalVM Community, among others. Vendors remove old ones from their servers while Foojay keeps the record, so an old build may fail to download. + +## Searching + +```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,300 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: + +``` +$ vfox search java tem +Available versions: + - 27+35-tem + - 26.0.2.1+1-tem + ... + - 25.0.4+7-tem (LTS) + ... + - 21.0.12.1+1-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. + +`vfox install java tem` does not select Temurin: arguments separated by spaces are several SDKs. Write `java@21-tem`. + +The LTS note is Foojay's, except that GraalVM's monthly feature releases (`25.4.4.1-graal`) carry none, though Foojay marks them LTS. Unreleased: 0.6.1 still adds the note. diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md new file mode 100644 index 0000000..a94e377 --- /dev/null +++ b/docs/zh-CN/changes.md @@ -0,0 +1,62 @@ +# 变更记录 + +[中文](changes.md) | [English](../changes.md) + +按发布版本列出用户能感受到的变化。GitHub 的 Release 页面列出了对应的 PR。写这篇文档时最新的发布版是 0.6.1，`main` 比它多出“未发布”下面的所有内容。想现在就用上这些变化，见 [install-from-source.md](install-from-source.md)。 + +## 未发布 + +- `.sdkmanrc` 在 vfox 1.x 下重新可用。0.6.1 在 vfox 1.x 下会报 `expected 0 arguments for func() []string, got 1`（测试过 1.0.12 和 1.0.13），但 vfox 不会把这个错误显示出来（[#65](https://github.com/version-fox/vfox-java/pull/65)）。 +- 只写大版本号的 `vfox use java@21` 在 vfox 1.0.13 下可用。0.6.1 在那里会报 `cannot unmarshal string into plugin.PreUseHookResult`（[#65](https://github.com/version-fox/vfox-java/pull/65)）。 +- `.sdkmanrc` 能匹配 SDKMAN 的 `jbr` 和 JavaFX 标识符（[#78](https://github.com/version-fox/vfox-java/pull/78)）、补零的版本（[#85](https://github.com/version-fox/vfox-java/pull/85)）和 EA 标识符（[#88](https://github.com/version-fox/vfox-java/pull/88)、[#96](https://github.com/version-fox/vfox-java/pull/96)）。同一大版本装了多个 JDK 时，会选中文件里指明的那个（[#84](https://github.com/version-fox/vfox-java/pull/84)）。见 [sdkmanrc.md](sdkmanrc.md)。 +- 只写大版本号时，安装最新的版本。`java@21-tem` 装的是 `21.0.12.1+1-tem`，不再是 `21+35-tem`（[#74](https://github.com/version-fox/vfox-java/pull/74)）。`java@25-graal` 装的是 25.0 系列的最新构建 `25.0.4.1-graal`，0.6.1 装的是 `25-graal`（[#101](https://github.com/version-fox/vfox-java/pull/101)）。 +- `vfox use java@21.0.8-tem` 能找到已安装的 `21.0.8+9-tem`（[#76](https://github.com/version-fox/vfox-java/pull/76)）。带 `-open` 或 `openjdk-` 的 OpenJDK 名字（[#77](https://github.com/version-fox/vfox-java/pull/77)）和补零的版本（[#92](https://github.com/version-fox/vfox-java/pull/92)）同样如此。 +- `java@21.0.5+63130-jb` 装的是它指明的那个构建，不再是这个版本的最新构建（[#83](https://github.com/version-fox/vfox-java/pull/83)）。 +- Windows 上的 `vfox search` 会列出只提供 tar.gz 的版本（[#81](https://github.com/version-fox/vfox-java/pull/81)）。 +- 插件不再设置 `GRAALVM_HOME`（[#93](https://github.com/version-fox/vfox-java/pull/93)）。 +- `java@tem` 这种只写发行版的写法会提示补上版本，不再报 Lua 错误（[#99](https://github.com/version-fox/vfox-java/pull/99)）。 +- `vfox search` 不再把 GraalVM 每月发布的特性版本标成 LTS（[#100](https://github.com/version-fox/vfox-java/pull/100)）。 +- 仓库有了覆盖 Linux 和 Windows 的容器 e2e 套件，见 [e2e.md](e2e.md)（[#65](https://github.com/version-fox/vfox-java/pull/65)、[#82](https://github.com/version-fox/vfox-java/pull/82)）。 + +## 0.6.1（2026-09-12） + +- macOS 上通过 `bin/java` 的位置来确定 Java home，所以带厂商命名目录或 `Contents/Home` 的压缩包也能用（[#63](https://github.com/version-fox/vfox-java/pull/63)）。 + +## 0.6.0（2026-09-12） + +- 支持在 Linux loong64 上从 Loongnix 归档安装 JDK，见 [loongnix.md](loongnix.md)（[#62](https://github.com/version-fox/vfox-java/pull/62)）。 +- `vfox use` 切换 JavaFX 构建时保留 `-fx` 后缀（[#60](https://github.com/version-fox/vfox-java/pull/60)）。 +- JetBrains Runtime 可以在 Windows 11 上安装（[#58](https://github.com/version-fox/vfox-java/pull/58)）。 + +## 0.5.4（2026-06-01） + +- EA 构建可以这样安装：`java@26.ea.1-graal`（[#57](https://github.com/version-fox/vfox-java/pull/57)）。 + +## 0.5.3（2026-01-19） + +- 支持用 `-fx` 后缀安装带 JavaFX 的构建（[#48](https://github.com/version-fox/vfox-java/pull/48)），见 [javafx.md](javafx.md)。 +- Alpine 等 musl 系统现在装的是 musl 构建（[#50](https://github.com/version-fox/vfox-java/pull/50)）。 +- Windows x64 上重新向 Foojay 请求 `x64`，0.5.2 在那里发的是 `amd64`（[#52](https://github.com/version-fox/vfox-java/pull/52)）。 + +## 0.5.2（2026-01-18） + +- arm64 向 Foojay 请求 `aarch64`，这才是它认的名字（[#46](https://github.com/version-fox/vfox-java/pull/46)、[#47](https://github.com/version-fox/vfox-java/pull/47)）。 + +## 0.5.1（2026-01-02） + +- `vfox use java@21` 交给 vfox 处理，由它在已安装的版本里匹配只写了大版本号的输入。 + +## 0.5.0（2025-09-29） + +- 支持 asdf 风格的写法（发行版在前，版本在后），例如 `java@temurin-21`（[#17](https://github.com/version-fox/vfox-java/pull/17)）。 + +## 0.4.x（2024-04） + +- 0.4.0 开始读取 `.sdkmanrc`。 +- 0.4.3 在 Linux 上向 Foojay 请求 glibc 构建（[#14](https://github.com/version-fox/vfox-java/pull/14)）。 + +## 0.1.x 和 0.2.x（2024-04） + +- 0.1.0 是第一个发布版，支持 17 个发行版。 +- 0.1.2 增加了 `vfox search java all`（[#5](https://github.com/version-fox/vfox-java/pull/5)），并把 `open` 设为默认发行版（[#6](https://github.com/version-fox/vfox-java/pull/6)）。 +- 0.2.1 增加了 Liberica Native Image Kit（[#10](https://github.com/version-fox/vfox-java/pull/10)）。 diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md new file mode 100644 index 0000000..4246b6c --- /dev/null +++ b/docs/zh-CN/development.md @@ -0,0 +1,132 @@ +# 开发 + +[中文](development.md) | [English](../development.md) + +## 目录结构 + +``` +metadata.lua 插件名、版本，以及把 .sdkmanrc 注册为兼容版本文件 +hooks/available.lua vfox search +hooks/pre_install.lua vfox install：选择包并给安装后的版本命名 +hooks/post_install.lua macOS：把 Java home 移到安装根目录 +hooks/env_keys.lua JAVA_HOME 和 PATH +hooks/pre_use.lua vfox use：把输入映射到已安装的版本名 +hooks/parse_legacy_file.lua .sdkmanrc +lib/distribution_version.lua 发行版名称、版本写法的解析、GraalVM 特性版本的识别 +lib/foojay.lua 向 Foojay 发出的请求 +lib/installed_version.lua 与已安装的版本名做匹配 +lib/loongnix.lua Loongnix 归档 +tests/*_test.lua 离线的钩子测试 +tests/fixtures/loongnix/ Loongnix 归档目录页的一份快照 +tests/e2e/ 容器测试，见 e2e.md +Injection.lua vfox 注入对象的类型提示，不会被加载 +``` + +vfox 加载 `metadata.lua`，命令需要时调用相应的钩子，并向钩子提供全局变量 `PLUGIN` 和 `RUNTIME`（`osType`、`archType`、`version`）。`osType` 和 `archType` 就是 vfox 二进制的 Go `GOOS` 和 `GOARCH`。 + +## 一条命令会执行什么 + +| 你执行 | 调用的钩子 | +| --- | --- | +| `vfox search java tem` | `Available` | +| `vfox install java@21-tem` | `PreInstall` 返回 URL 和版本名。vfox 下载并解压，然后调用 `PostInstall` | +| `vfox use java@21-tem` | `PreUse` 返回要选中的已安装版本名，`EnvKeys` 提供环境变量 | +| 已挂载到 Shell，`cd` 进有 `.sdkmanrc` 的目录 | `ParseLegacyFile` | +| `vfox uninstall java@21.0.8+9-tem` | 无，名字必须精确 | + +几条容易踩坑的约定： + +- `PreInstall` 返回 `url`、`version` 和 `note`。`version` 会成为安装后的版本名，所以它带着构建号。包的校验和目前没有传给 vfox（`hooks/pre_install.lua` 里的 `TODO: checksum`），vfox 为此会打印警告。 +- `PreUse` 返回 Lua 表或 `nil`。只写大版本号时返回 `nil`，让 vfox 自己去匹配。vfox 1.0.13 及以后会拒绝裸字符串，比如 `""`。 +- `ParseLegacyFile` 调用 `ctx.getInstalledVersions()` 时不能带参数。vfox 1.x 把它绑定成 Go 的 `func() []string`，会拒绝 `ctx:getInstalledVersions()` 多传的那个参数。vfox 会忽略这个钩子的错误，所以出错时没有任何提示。 +- vfox 把已安装的版本按字符串降序传给钩子，例如 `21.0.8+9-tem`、`21.0.12+8-tem`、`21.0.1+12-tem`。按前缀匹配时，第一个命中的不一定是最新的，所以 `lib/installed_version.lua` 逐段比较数字。 +- `EnvKeys` 不设置 `GRAALVM_HOME`，需要的话由用户自己把它指向某个 GraalVM。 + +## 命名 + +安装后的版本名是 `[-<简称>][-fx]`，OpenJDK 没有简称（[versions.md](versions.md#安装后的版本名)）。`lib/distribution_version.lua` 把一个写法解析成版本、发行版和 JavaFX 标志，两种顺序都接受（`21-tem`、`tem-21`）。`lib/installed_version.lua` 把用户输入的版本变成已安装的版本名：先看这个名字本身。只写大版本号时，取这个大版本里已安装的最新版本；其他写法则取这个版本本身，或它的最新构建。`PreUse` 到此为止。`ParseLegacyFile` 还会再退一步，取同一大版本里已安装的最新版本。 + +SDKMAN 有些写法不同（`jbr`、`21.0.12.fx-zulu`、`21.0.12-fx+1.1-librca`、`28.0.0+ea.19-open`），`hooks/parse_legacy_file.lua` 里的 `plugin_spelling` 会在解析之前把它们改写成插件自己的写法。SDKMAN 给版本补的零由 `installed_version.unpad` 去掉（`27.0.0+36` 就是 `27+36`）。插件的简称沿用 SDKMAN 的，只有 `jb` 例外。 + +## Foojay + +- 查询里的 `+` 必须做百分号编码。Foojay 会把没编码的 `+` 当成空格并丢掉构建号，`21.0.5+63130` 就会匹配 21.0.5 的所有构建。 +- `version=21` 只是 GA 构建 `21+35`。只写大版本号时会加上 `latest=available`，才能拿到最新的 21.x。 +- Windows 在同一次请求里同时要 `zip` 和 `tar.gz`。JetBrains Runtime 只为较新的构建提供 Windows 的 zip。同一版本两种都有时，`PreInstall` 取 zip。 +- Foojay 里同一个名字有两条记录时，`Available` 只列一次。 +- Foojay 把 GraalVM 每月发布的特性版本（`25.1.3` 起）标成 LTS。`lib/distribution_version.lua` 里的 `is_feature_release` 按次版本号识别它们，`Available` 去掉它们的备注。它只适用于 `graal` 和 `graalce`：Mandrel 和 Liberica NIK 在 24 及以前按自己的版本号编号（`mandrel` 的 `23.1.12` 就是 LTS），从 25 起沿用 JDK 的编号。 +- 只有 Oracle GraalVM（`graal`）在只写大版本号时，`PreInstall` 才会跳过特性版本，所以装的是 25.0 系列。一个大版本里只有特性版本时，则保留它们。GraalVM 社区版不做这个过滤，因为特性版本就是它现在发布的全部。 +- CPU 名字：`arm64` 改成 `aarch64`，Windows 上 `amd64` 改成 `x64`；`darwin` 改成 `macos`。在 Linux 上，由 `ldd --version` 决定是 glibc 还是 musl。 + +## 测试 + +钩子测试在离线状态下用 `gopher-lua` 运行，它就是 vfox 内嵌的 Lua 解释器： + +```bash +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_install_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua +``` + +请在仓库根目录运行。五个文件都会加载 `tests/support.lua`，它模拟 `vfox.strings`；`tests/pre_install_test.lua` 和 `tests/loongnix_test.lua` 还自己模拟了 `http` 和 `json`。`tests/pre_install_test.lua` 把 Foojay 的返回结果放在文件开头的一张表里，键是 `<发行版> [<版本>] []`，Windows 的前面再加 `windows`。新增用例需要的返回结果就加在那里，并注明观察到的日期。Lint、许可证头和容器测试见 [e2e.md](e2e.md#本地检查)。 + +想对着真实的 Foojay 调用单个钩子，可以用 vfox 1.0.13 及以后版本的 `vfox plugin run`。它不会注册插件，`--os` 和 `--arch` 可以模拟其他平台： + +```bash +vfox plugin run . Available --input '{"args":["tem"]}' --json +vfox plugin run . PreInstall --input '{"version":"21-tem"}' --os windows --arch arm64 --json +vfox plugin run . ParseLegacyFile --input '{"filename":".sdkmanrc","filepath":"/tmp/p/.sdkmanrc","installedVersions":["21.0.8+9-tem"]}' --json +``` + +`vfox --debug <命令>` 会显示 vfox 对钩子做了什么，vfox 吞掉的错误可以靠它找出来。 + +## 添加发行版 + +1. 在 Foojay 里找到它的 id（见 [foojay.md](foojay.md)），并确认它在你关心的平台上有包。 +2. 在 `lib/distribution_version.lua` 的 `short_name` 里加一行 `["<简称>"] = ""`。SDKMAN 有这个发行版的话，用 SDKMAN 的标识符。SDKMAN 写法不同的话，在 `hooks/parse_legacy_file.lua` 的 `plugin_spelling` 里做映射。 +3. 如果它的版本号或 LTS 标记需要特殊处理，像 GraalVM 那样，就在 `hooks/available.lua` 和 `hooks/pre_install.lua` 里处理。 +4. 在 `tests/pre_install_test.lua` 里加一个用例。 +5. 更新 `README.md`、[distributions.md](distributions.md) 和 [platforms.md](platforms.md) 里的表，以及对应的中文版（`README_CN.md` 和 `docs/zh-CN/` 下的同名页面）。 +6. 如果引入了新的代码路径，也要加进 e2e 矩阵（[e2e.md](e2e.md)）。矩阵之外的发行版仍会运行所有检查，只是跳过 `java.vendor` 断言和 asdf 风格的 `PreUse` 写法。 + +## 更新平台表 + +[platforms.md](platforms.md) 的数据取自 Foojay。下面的命令用 8 次请求，按平台打印有构建的发行版： + +```bash +base='https://api.foojay.io/disco/v3.0/packages/jdks?directly_downloadable=true&latest=per_distro' +while read -r name query; do + printf '%-14s ' "$name" + curl -s "$base&$query" | jq -r '.result[].distribution' | sort -u | tr '\n' ' '; echo +done <<'EOF' +linux-x64 architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz +linux-arm64 architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz +alpine-x64 architecture=amd64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz +alpine-arm64 architecture=aarch64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz +macos-intel architecture=amd64&operating_system=macos&archive_type=tar.gz +macos-arm64 architecture=aarch64&operating_system=macos&archive_type=tar.gz +windows-x64 architecture=x64&operating_system=windows&archive_type=zip&archive_type=tar.gz +windows-arm64 architecture=aarch64&operating_system=windows&archive_type=zip&archive_type=tar.gz +EOF +``` + +id 是 Foojay 的（`oracle_open_jdk` 对应 `open`）。“只有部分版本”一节里的说明，需要对每个发行版、每个平台单独查询，不带 `latest`，再按 `major_version` 分组。 + +## 已知限制 + +- 下载内容没有校验，见上文。 +- `vfox search` 只列 GA 版本。EA 构建要自己写出名字来安装。 +- 插件不提供没有简称的 Foojay 发行版（[distributions.md](distributions.md#foojay-有但插件没有提供的发行版)）和 JRE 包。 +- 只有 Linux loong64 有 Foojay 以外的来源。 + +## 发布 + +维护者在默认分支上执行 **Actions → Plugin → Run workflow**，填入不带 `v` 的版本号。共享工作流具体做什么，README 里有说明。发布之后，[vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/java.json` 会显示 `vfox add java` 提供的是哪个版本。 + +文档里用“未发布”（英文是“Unreleased”）标记比最新发布版更新的内容。发布之后，把 [changes.md](changes.md) 里的这些条目移到新版本下面，并去掉这些标注，两种语言都要处理：`grep -rn -i -e unreleased -e 未发布 docs README*`。 + +## 编写文档 + +英文页面在 `docs/`，中文页面在 `docs/zh-CN/`，文件名相同；README 的中文版是根目录的 `README_CN.md`。每页开头有指向另一种语言的链接。引用 Foojay 数据的页面会写明数据取自哪一天。CI 不检查这些文档，所以你加的命令请自己跑一遍。 diff --git a/docs/zh-CN/distributions.md b/docs/zh-CN/distributions.md new file mode 100644 index 0000000..ab62573 --- /dev/null +++ b/docs/zh-CN/distributions.md @@ -0,0 +1,122 @@ +# 来自 Foojay 的发行版 + +[中文](distributions.md) | [English](../distributions.md) + +插件从 [Foojay](foojay.md) 获取下面 18 个发行版的版本列表和下载链接。凡是要写发行版的地方，简称和长名都可以：`21-tem`、`21-temurin`、`temurin-21`、`vfox search java tem`。 + +| 简称 | 长名 | 发行版 | 维护方 | +| --- | --- | --- | --- | +| `open` | `openjdk` | jdk.java.net 上的 OpenJDK 构建 | Oracle，代表 OpenJDK 项目 | +| `tem` | `temurin` | Temurin | Eclipse Adoptium | +| `zulu` | `zulu` | Zulu | Azul | +| `librca` | `liberica` | Liberica | BellSoft | +| `amzn` | `corretto` | Corretto | Amazon | +| `ms` | `microsoft` | Microsoft Build of OpenJDK | Microsoft | +| `oracle` | `oracle` | Oracle JDK | Oracle | +| `sem` | `semeru` | Semeru Runtimes 开放版 | IBM | +| `sapmchn` | `sap_machine` | SapMachine | SAP | +| `kona` | `kona` | 腾讯 Kona JDK | 腾讯 | +| `albba` | `dragonwell` | 阿里巴巴 Dragonwell | 阿里巴巴 | +| `bsg` | `bisheng` | 毕昇 JDK（BiSheng） | 华为 | +| `graal` | `graalvm` | Oracle GraalVM | Oracle | +| `graalce` | `graalvm_community` | GraalVM 社区版 | GraalVM 项目 | +| `nik` | `liberica_native` | Liberica Native Image Kit | BellSoft | +| `mandrel` | `mandrel` | Mandrel | Red Hat | +| `jb` | `jetbrains` | JetBrains Runtime | JetBrains | +| `trava` | `trava` | TravaOpenJDK | 社区 | + +长名就是 Foojay 接受的发行版名，只有 `openjdk` 例外：Foojay 里它叫 Oracle OpenJDK，`openjdk` 只是它认的同义词。简称沿用 SDKMAN 的，只有 `jb` 不同（SDKMAN 里叫 `jbr`）；`.sdkmanrc` 里 `jbr` 和 `jb` 都认，见 [sdkmanrc.md](sdkmanrc.md)。`lnxabi1` 和 `lnxabi2` 不来自 Foojay，所以不在表里，见 [loongnix.md](loongnix.md)。 + +各发行版覆盖哪些操作系统和 CPU，见 [platforms.md](platforms.md)。`vfox search java <名字>` 列出的是你这台机器上能装的版本。安装后的版本名带简称，OpenJDK 例外，它没有后缀（见 [versions.md](versions.md)）。 + +## OpenJDK 构建 + +### OpenJDK（`open`） + +[jdk.java.net](https://jdk.java.net/) 上的构建，采用 GPLv2 加 Classpath 例外条款。不写发行版时指的就是它。这个站点只提供最新的几个版本，旧版本只留最后一个构建，所以 17、21 不适合用它，见 [versions.md](versions.md#不写发行版)。它也发布 EA 构建。 + +### Temurin（`tem`） + +[Eclipse Adoptium](https://adoptium.net/temurin/releases) 项目的构建，前身是 AdoptOpenJDK。覆盖 Java 8、11，以及 16 起的所有版本，有 EA 构建。 + +### Zulu（`zulu`） + +[Azul](https://www.azul.com/downloads/?package=jdk) 的 OpenJDK 构建。除了当前版本，还有 Java 6 和 7，并提供带 JavaFX 的构建（`-fx`）。 + +### Liberica（`librca`） + +[BellSoft](https://bell-sw.com/) 的 OpenJDK 构建，提供带 JavaFX 的构建（`-fx`）。它是有 Windows ARM64 构建的 5 个发行版之一。 + +### Corretto（`amzn`） + +[Amazon](https://aws.amazon.com/corretto/) 的 OpenJDK 构建。覆盖 Java 8、11，以及 15 起的所有版本。 + +### Microsoft Build of OpenJDK（`ms`） + +[Microsoft](https://www.microsoft.com/openjdk) 的构建。覆盖 Java 11、16、17、21 和 25，支持 Linux、macOS、Windows 的 x64 和 arm64。 + +### Oracle JDK（`oracle`） + +[Oracle](https://www.oracle.com/java/) 自己的 JDK，从 Java 17 起。许可证是 Oracle 的，不是开源许可证，而且各版本的条款不同，请阅读你要安装的那个版本的条款。 + +### Semeru（`sem`） + +[IBM](https://developer.ibm.com/languages/java/semeru-runtimes/) 的运行时：OpenJDK 类库搭配 Eclipse OpenJ9 虚拟机，不是 HotSpot。只提供开放版，不提供 Foojay 里的 `semeru_certified`。 + +### SapMachine（`sapmchn`） + +[SAP](https://sapmachine.io/) 的 OpenJDK 构建。Java 11 起。 + +### Kona（`kona`） + +[腾讯](https://tencent.github.io/konajdk)的 OpenJDK 构建。覆盖 Java 8、11、17、21 和 25。 + +### Dragonwell（`albba`） + +[阿里巴巴](https://dragonwell-jdk.io/)的 OpenJDK 构建。覆盖 Java 8、11、17、21 和 25，有 Linux 和 Windows 版本，没有 macOS 版本。 + +### 毕昇 JDK（`bsg`） + +[华为](https://www.hikunpeng.com/developer/devkit/compilation_debugging?data=JDK)的 OpenJDK 构建，面向 ARM 服务器。覆盖 Java 8、11、17、21 和 25，只有 Linux 版本。 + +## GraalVM 系列 + +### Oracle GraalVM（`graal`） + +Oracle 发行的 GraalVM，基于 Oracle JDK。版本号沿用 GraalVM 自己的编号：`17.0.12-graal`、`25.0.4.1-graal`。 + +### GraalVM 社区版（`graalce`） + +GraalVM 的开源版本，基于 OpenJDK。 + +### Liberica Native Image Kit（`nik`） + +[BellSoft](https://bell-sw.com/) 用来构建原生镜像的发行版，基于 GraalVM。覆盖 Java 21 到 25，部分平台有带 `-fx` 的构建。 + +### Mandrel（`mandrel`） + +[Red Hat](https://github.com/graalvm/mandrel) 为构建 Quarkus 原生可执行文件提供的发行版，专注于 `native-image`。 + +Mandrel 和 Liberica NIK 在 24 及以前用自己的版本号体系（Mandrel 的 `23.1.12`），从 25 起沿用 JDK 的版本号（`25.0.4.1`）。 + +### 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`，每个大约一个月后就被下一个取代。它们基于的 JDK 是 LTS，所以 Foojay 也把它们标成了 LTS，而 `vfox search` 不给它们加 LTS 备注。未发布：0.6.1 仍会加上这个备注。 +- `java@25-graal` 装的是 25.0 系列的最新构建（`25.0.4.1-graal`），Oracle 官方的 `25/latest` 下载链接跟的也是这个系列。特性版本要写全版本号：`java@25.4.4.1-graal`。未发布：0.6.1 装的是 GA 构建 `25-graal`。 +- GraalVM 社区版的 25.0 系列到 `25.0.2` 为止，现在只发布特性版本。`java@25-graalce` 装其中最新的一个，截至 2026-10-18 是 `25.4.4.1-graalce`。未发布：0.6.1 装的是 GA 构建 `25-graalce`。 +- 插件只设置 `JAVA_HOME` 和 `PATH`，不设置 `GRAALVM_HOME`。你设置的、指向自己的 GraalVM 的 `GRAALVM_HOME` 保持原样；没有设置时，native-image 的构建插件会回退到 `JAVA_HOME`。未发布：0.6.1 会为 `graal` 和 `graalce` 设置 `GRAALVM_HOME`，覆盖你原来的值。 +- 没有 Windows ARM64 和 Alpine 的构建，Intel Mac 上 25.0.1 之后的版本也没有。见 [platforms.md](platforms.md#graalvm)。 + +## 其他 + +### JetBrains Runtime（`jb`） + +JetBrains 各 IDE 运行所用的 [OpenJDK 分支](https://github.com/JetBrains/JetBrainsRuntime)。覆盖 Java 11、17、21 和 25。在 Windows 上，有些版本只提供 tar.gz，插件可以安装，`vfox search` 也会列出。未发布：0.6.1 的 `vfox search` 不会列出它们。 + +### TravaOpenJDK（`trava`） + +[带 DCEVM 的 OpenJDK](https://github.com/TravaOpenJDK)，附带 HotswapAgent，用于在运行中的程序里替换类。覆盖 Java 8 和 11。Foojay 把它标为不再维护。它没有 Apple Silicon 的构建，Linux arm64 上只有一个（`11.0.10+6`）。 + +## Foojay 有但插件没有提供的发行版 + +Foojay 列出的发行版比上面这 18 个多：`aoj` 和 `aoj_openj9`（AdoptOpenJDK，已由 Temurin 和 Semeru 接替）、`eliya`、`gluon_graalvm`、`graalvm_ce8`、`graalvm_ce11`、`graalvm_ce16`、`graalvm_ce17`、`graalvm_ce19`（GraalVM 社区版的旧版本）、`ojdk_build`、`openlogic`、`redhat` 和 `semeru_certified`。它们在这里没有简称，所以 `vfox install java@21-openlogic` 会报 `Could not extract a valid distribution`。添加新发行版的方法见 [development.md](development.md#添加发行版)。 diff --git a/docs/zh-CN/e2e.md b/docs/zh-CN/e2e.md new file mode 100644 index 0000000..c85b1d8 --- /dev/null +++ b/docs/zh-CN/e2e.md @@ -0,0 +1,207 @@ +# E2E + +[中文](e2e.md) | [English](../e2e.md) + +离线的 Lua 钩子测试（`tests/*_test.lua`）在 **Test Plugin** 工作流里运行。端到端套件在容器里针对真实的 vfox 运行，覆盖 Linux 和 Windows；每个 `vfox` x `distribution` 组合都有自己的一次性容器。CI 直接在标准 runner 上运行这套测试（Docker 加 `actions/setup-go` 提供的 Go）。本地则由仓库的开发容器在 Linux 上复现这一环境；Windows 上改用 Docker Compose runner 镜像，因为开发容器无法承载 Windows 容器镜像（见下文）。 + +## 开发容器 + +`.devcontainer/` 提供一个 Linux 开发环境，在四种宿主平台上都能用： + +| 宿主 | 开发容器的运行方式 | +| --------------------- | ---------------------------------------------- | +| 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 模块缓存，第一次运行测试时就不必停下来下载。 + +用任何支持 Dev Containers 规范的工具都可以打开它：在 VS Code/Cursor 里执行 **Dev Containers: Reopen in Container**，或者用 CLI： + +```bash +devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . bash +``` + +`TESTCONTAINERS_RYUK_DISABLED=true` 是预先设好的：Ryuk 会在宿主 daemon 上发布一个端口，并等待套件回连，而 Docker-out-of-Docker 的容器做不到这一点。套件改为通过 `t.Cleanup` 显式终止每个容器；运行被强行中断后遗留的容器，名称都以 `vfox-java-e2e-` 开头，可以按这个前缀清理。使用 rootless Docker 的用户，请在打开容器之前先在宿主上 `export DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock"`。在 Windows 宿主上，把检出的代码放在 WSL 2 里（例如 `\\wsl$` 下）能让文件和 bind mount 访问保持快速；放在 Windows 文件系统上也能用。 + +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` 启动。 +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 会把没编码的 `+` 当成空格并丢掉构建号，于是会装上这个版本的最新构建。 +3. 在 `graalce` 这一行里，Oracle GraalVM 只写大版本号的 `25-graal` 应该装 25.0 系列的最新构建（`25.0.4.1-graal`），也就是 Oracle 官方 `25/latest` 下载跟的那个系列，而不是 Foojay 列在它前面的某个每月特性版本（比如 `25.4.4.1-graal`）。`vfox search java graal` 列出的 25 的各构建会先被模拟成已安装，这样 `vfox install` 报出的就是 `PreInstall` 选中的那个，而且不会下载任何东西。GA 版本 25 不放进去，因为那样 vfox 会发现 `25-graal` 已安装，根本不会去问 `PreInstall`。 +4. 固定的版本按 `PreInstall` 给它起的名字安装：请求的版本加上构建号（`21.0.8-tem` 安装为 `21.0.8+9-tem`）。`vfox search java <发行版>`（`Available` 钩子）把同一个名字列为已安装，带 JavaFX 的构建会标注 JavaFX。对 GraalVM，它还必须列出自 25.1 起每月发布的特性版本（`25.4.4.1-graalce`），这些版本都不标 LTS（Foojay 标了，因为它们基于的 JDK 是 LTS）；每个版本大约只存在一个月。在 Windows 上，列表里要包含 JetBrains Runtime 21.0.5，它在 Windows 上只有 tar.gz。 +5. 在执行任何 `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 换行写入。 +6. `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。 +7. `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） | ✓ | ✓ | +| `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`） | +| `JAVA_VERSION` | 按发行版而定 | 为每个选中的发行版安装的版本（Java 9+ 的编号方式） | +| `E2E_MAX_JOBS` | `3`（Linux），`2`（Windows） | 每台宿主并行的容器数 | +| `E2E_RETRY_ATTEMPTS` | `3` | 每个涉及网络的 exec 的尝试次数（线性退避 10 秒） | + +`JAVA_VERSION` 必须是 `java.version` 原样报告的版本（例如 `21.0.8`，而不是 Java 8 的 `1.8.0_462` 写法）。默认矩阵之外的发行版仍会运行所有检查，只是跳过 `java.vendor` 断言和 asdf 风格的 `PreUse` 写法，这两项要用到的数据只为默认的几个发行版保存（`tests/e2e/common`）。 + +## Linux（Ubuntu 26.04） + +在开发容器里，从仓库根目录执行： + +```bash +cd tests/e2e +go test -v -timeout 55m -run TestE2E ./linux +``` + +迭代时可以用环境变量缩小范围： + +```bash +VFOX_VERSION=latest DISTRIBUTION=tem E2E_MAX_JOBS=1 go test -v -timeout 55m -run TestE2E ./linux +``` + +在原生宿主上，同一条命令也能用，只需要两个前提：Docker Engine（rootful 或 rootless）和 Go 1.27.1，CI 里装的就是这两样。使用 rootless Docker 的用户要把 Docker 客户端指向自己的 socket（`export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock"`）；开发容器挂载的 socket 已经替你处理了这种情况。 + +## Windows 11 + +Windows 容器无法跨架构模拟，所以 ARM64 套件需要 ARM64 宿主（Copilot+ PC 或 `windows-11-arm` CI runner）。 + +这套测试没有开发容器，因为 Dev Containers 规范拒绝 Windows 容器镜像（见[开发容器](#开发容器)），所以它仍使用 Docker Compose runner。runner 镜像（`Dockerfile-runner`：标准的 servercore 加固定版本的 Go，它同时用来构建 vfox `main`）通过挂载的命名管道驱动宿主 daemon；对宿主的要求是 Windows 容器模式的 Docker，加上 Compose v5 插件（每台机器安装一次，见下文）。Go 从不接触宿主，所以不会与 vfox 管理的工具链冲突。 + +`windows-11-arm` runner 没有 Windows Hypervisor Platform 功能，所以无法使用 Hyper-V 隔离；进程隔离只需要 Containers 功能。 + +CI 跳过了 runner 镜像：在 `windows-11-arm` 上解压它里面的 Go 就花了两分半，而 `actions/setup-go` 已经提供了同样的 Go。CI 直接在 runner 上运行 `go test ./windows`，设置 `E2E_MAX_JOBS=3`。运行之前，`use-local-disk.ps1` 先把 Docker 的数据根目录、Go 的缓存和临时目录，从 runner 上网络挂载的 C: 盘挪到本地磁盘：`windows-latest` 用 D:，`windows-11-arm` 用未格式化的 NVMe 磁盘（脚本会先把它格式化）。镜像层和容器文件是一个个文件写入的，所以在 C: 上，光拉取 servercore 就花了五分钟。这个脚本只允许在 GitHub Actions 里运行。 + +每个组合运行时，`VFOX_HOME` 都设为带空格的路径（`C:\Users\John Doe\.vfox`），以复现 [vfox-flutter#33](https://github.com/version-fox/vfox-flutter/issues/33)。vfox 从 1.0.13 起支持这样的路径（[vfox#712](https://github.com/version-fox/vfox/pull/712)），所以 `latest` 发布版和 `main` 都在这个路径下运行。 + +### x64 + +下面所有命令都在 PowerShell 7 中运行。如果还没有安装，请先装上（这一条引导命令可以在自带的 Windows PowerShell 里运行）： + +```powershell +winget install --id Microsoft.PowerShell --source winget --exact +``` + +1. 在 PowerShell 7 中执行： + +```powershell +winget install --id Git.Git --source winget --exact +# 按需配置 Git。 + +curl.exe -fsSL ` + "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" ` + -o ./install-docker-ce.ps1 +``` + +2. 以管理员身份在 PowerShell 7 中执行： + +```powershell +./install-docker-ce.ps1 +``` + +3. 在 PowerShell 7 中执行： + +```powershell +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\cli-plugins" | Out-Null + +curl.exe -fsSL ` + "https://github.com/docker/compose/releases/download/v5.5.1/docker-compose-windows-x86_64.exe" ` + -o "$env:USERPROFILE\.docker\cli-plugins\docker-compose.exe" + +git clone git@github.com:version-fox/vfox-java.git +cd ./vfox-java/ +docker compose -f tests/e2e/windows/compose.amd64.yaml run --rm --build e2e +``` + +### arm64 + +下面所有命令都在 PowerShell 7 中运行。如果还没有安装，请先装上（这一条引导命令可以在自带的 Windows PowerShell 里运行）： + +```powershell +winget install --id Microsoft.PowerShell --source winget --exact +``` + +1. 在 PowerShell 7 中执行： + +```powershell +winget install --id Git.Git --source winget --exact +# 按需配置 Git。 +winget install --id GoLang.Go --source winget --exact +git clone git@github.com:version-fox/vfox-java.git +cd ./vfox-java/ +pwsh -NoProfile -File .\tests\e2e\windows\install-docker-arm64.ps1 +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\cli-plugins" | Out-Null + +curl.exe -fsSL ` + "https://github.com/docker/compose/releases/download/v5.5.1/docker-compose-windows-aarch64.exe" ` + -o "$env:USERPROFILE\.docker\cli-plugins\docker-compose.exe" + +docker compose -f tests/e2e/windows/compose.arm64.yaml run --rm --build e2e +``` + +在 arm64 上，构建 Docker 引擎也要用 Go，所以 `install-docker-arm64.ps1` 要在套件之前运行；之后 compose runner 镜像自带固定版本的 Go 来跑测试，宿主上的 Go 不会再被用到。这个脚本会复用它之前构建过的、版本符合的引擎；CI 从以这个脚本为键的缓存里恢复一个。想缩小运行范围，在 compose 命令前加上 `$env:VFOX_VERSION = 'latest'; $env:DISTRIBUTION = 'tem'`，和其他平台一样。 + +## 本地检查 + +在开发容器里执行，下面所有工具都已预装，版本和工作流使用的一致；也可以在宿主上装好同样的工具。 + +```bash +# Lua 和 Go 检查（.github/workflows/lint.yml）。 +cd tests/e2e +go test -short ./... +test -z "$(gofmt -l .)" +go vet ./... +cd ../.. + +stylua --check . +lua-language-server --check . --checklevel=Warning +``` + +```bash +# 离线的钩子测试（.github/workflows/test.yml）。 +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_install_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/pre_use_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/parse_legacy_file_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/loongnix_test.lua +go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/post_install_test.lua +``` + +```bash +# 许可证头（.github/workflows/license.yml）。 +license-eye header check +license-eye header fix +addlicense -check -f .license.tpl tests/e2e/windows/*.ps1 +addlicense -f .license.tpl tests/e2e/windows/*.ps1 +``` + +在只有 Docker 的宿主上，许可证检查改用容器运行（和 CI 用的镜像相同）： + +```bash +docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header check +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 +``` diff --git a/docs/zh-CN/foojay.md b/docs/zh-CN/foojay.md new file mode 100644 index 0000000..1203134 --- /dev/null +++ b/docs/zh-CN/foojay.md @@ -0,0 +1,126 @@ +# 查询 Foojay + +[中文](foojay.md) | [English](../foojay.md) + +[Foojay](https://foojay.io/) 运营着 Disco API，一个汇总了多家厂商 JDK 构建的公开索引（源码：[foojayio/discoapi](https://github.com/foojayio/discoapi)）。除了 Linux loong64，插件所有的版本列表和下载链接都来自它。`vfox search` 显示的就是 Foojay 的数据，找不到预期的构建时，应该先去 Foojay 查。 + +你可以自己在浏览器里查。这套 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` 时为空，否则是你输入内容里的版本部分。`+` 会做百分号编码，因为 Foojay 会把没编码的 `+` 当成空格，进而丢掉构建号。`28.ea.19` 会变成 `28-ea+19` | +| `architecture` | arm64 用 `aarch64`，Windows x64 用 `x64`，其他系统的 x64 用 `amd64`，其他 CPU 用 vfox 报告的名字 | +| `operating_system` | `linux`、`macos` 或 `windows` | +| `archive_type` | `tar.gz`；Windows 上是 `zip` 加 `tar.gz` | +| `lib_c_type` | Linux 上是 `glibc` 或 `musl`，其他系统为空 | +| `directly_downloadable` | 始终是 `true` | +| `latest` | `available`，仅当版本只有大版本号（如 `21`）时才加 | + +不加 `latest=available` 时，`version=21` 只匹配 21 的 GA 构建（`21+35`）；加上之后，Foojay 会挑出最新的 21.x，`java@21-tem` 装的就是它。更具体的版本则按原样匹配。 + +未发布：0.6.1 发送的 `+` 不做编码，也从不加 `latest=available`（所以 `java@21-tem` 装的是 `21+35-tem`），在 Windows 上只请求 `zip`，没有结果时才退回 `tar.gz`。 + +返回的是一个包列表。插件用 `java_version` 给版本命名；`javafx_bundled` 为真时加上 `-fx`；`term_of_support` 是 `lts` 时标注 LTS；在 Windows 上，同一版本既有 `zip` 又有 `tar.gz` 时优先用 `zip`。安装时，插件再取这个包的 `links.pkg_info_uri`，并从其中的 `direct_download_uri` 下载，那是厂商自己的服务器（Temurin 是 GitHub Releases）。这条记录里还有 `checksum`，但插件没有把它交给 vfox，所以 vfox 会打印 `WARNING: Checksum is not provided, skip verify...`，下载内容不做校验。 + +`vfox search` 与原始列表有几处不同：Foojay 里同一个名字有两条记录时，它只列一次；不给 GraalVM 的特性版本加 LTS 备注（未发布：见 [distributions.md](distributions.md#oracle-graalvm-与-graalvm-社区版的行为)）；只列 GA 版本。 + +## 我的平台上有哪些发行版 + +`latest=per_distro` 为每个有包的发行版返回最新的一个包。不要和 `version` 一起用，`version` 会被忽略。 + +```bash +# Windows ARM64 +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?architecture=aarch64&operating_system=windows&archive_type=zip&archive_type=tar.gz&directly_downloadable=true&latest=per_distro' \ + | jq -r '.result[].distribution' | sort -u +``` + +``` +jetbrains +liberica +microsoft +temurin +zulu +``` + +换成别的平台，改动指明平台的那三个参数即可。Linux 还要加上 `lib_c_type=glibc` 或 `musl`： + +| 平台 | 参数 | +| --- | --- | +| Linux arm64 | `architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz` | +| Alpine x64 | `architecture=amd64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz` | +| macOS Apple Silicon | `architecture=aarch64&operating_system=macos&archive_type=tar.gz` | +| 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#foojay-有但插件没有提供的发行版)。 + +## 我的平台上哪些发行版有某个版本 + +```bash +# Intel Mac 上的 Java 27 +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?version=27&latest=available&architecture=amd64&operating_system=macos&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[].distribution' | sort -u +``` + +2026-10-18 运行这条命令，打印的是 `corretto liberica oracle semeru zulu`。Temurin 和 OpenJDK 不在其中：它们在 Intel Mac 上停在了 26。只写大版本号时像插件一样加上 `latest=available`，写更具体的版本时就不要加。 + +## 某个发行版的所有版本 + +这就是 `vfox search java tem` 在你这台机器上显示的内容： + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -r '.result[].java_version' +``` + +``` +27+35 +26.0.2.1+1 +26.0.2+10 +... +``` + +加上 `version=21.0.8` 只看某个版本，加上 `javafx_bundled=true` 只看带 JavaFX 的构建。一条记录长这样： + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&version=21.0.8&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \ + | jq -c '.result[] | {java_version, distribution_version, term_of_support, javafx_bundled, archive_type, filename}' +``` + +``` +{"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`）。 + +## 版本与支持期限 + +```bash +curl -s 'https://api.foojay.io/disco/v3.0/major_versions?ea=false&ga=true&maintained=true' \ + | jq -r '.result[] | [.major_version, .term_of_support] | @tsv' +``` + +列出仍在维护的各个大版本，以及每个是 LTS 还是 STS。EA 构建要用 `release_status=ea`，或者像 `version=28-ea` 这样明确写出版本。 + +## 补充说明 + +- 有些 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 new file mode 100644 index 0000000..4307c8e --- /dev/null +++ b/docs/zh-CN/install-from-source.md @@ -0,0 +1,72 @@ +# 从源码安装 + +[中文](install-from-source.md) | [English](../install-from-source.md) + +`vfox add java` 安装的是最新的发布版。`main` 上有尚未发布的修复（[changes.md](changes.md)），你正在改的代码也不在任何发布版里。插件就是一个 `metadata.lua` 加上 `hooks` 和 `lib` 两个目录，vfox 可以从它们的 zip 包添加插件。 + +## Ubuntu 26.04 + +在 Bash 中执行： + +```bash +sudo apt install --assume-yes git zip +git clone --depth 1 https://github.com/version-fox/vfox-java.git +cd ./vfox-java/ +zip -qr ./java.zip metadata.lua hooks lib +vfox add java --source ./java.zip +rm ./java.zip +``` + +macOS 的步骤相同，系统自带 `git` 和 `zip`。 + +## Windows 11 + +这里默认已装好 PowerShell 7，在 PowerShell 7 中执行： + +```powershell +winget install --id Git.Git --source winget --exact +git clone --depth 1 https://github.com/version-fox/vfox-java.git +cd ./vfox-java/ +tar -a -cf ./java.zip metadata.lua hooks lib +vfox add java --source ./java.zip +Remove-Item ./java.zip +``` + +## 验证 + +```bash +vfox install java@21-tem +vfox use --global java@21-tem +java -version +``` + +用 `main` 构建出的插件装的是最新的 Temurin 21（截至 2026-10-18 是 `21.0.12.1+1-tem`）；0.6.1 装的是 `21+35-tem`，也就是 21 的第一个构建。 + +## 已经添加过 java 时 + +`vfox add` 会报错 `plugin named java already exists`。你可以替换原有的插件，也可以给源码构建的版本另起一个名字，与原插件并存。 + +替换要先执行 `vfox remove java`，它会连同通过这个插件装的 JDK 一起删掉，vfox 会在确认之前先告诉你这一点。之后需要重新安装这些 JDK。 + +想两个都留着，就给新的起个别名： + +```bash +vfox add java --source ./java.zip --alias java-dev +vfox install java-dev@21-tem +vfox remove -y java-dev # 只删除 java-dev 和它装的东西 +``` + +别名有它自己的已安装列表，但两者的 `JAVA_HOME` 都是 `~/.vfox/sdks/java`。在每个作用域里，只从其中一个选版本：全局作用域下，先执行 `vfox unuse --global java`，再 `vfox use --global java-dev@...`，反过来也一样。两个都选了的话，vfox 在每个提示符都会重新建立两者的链接，`JAVA_HOME` 最后指向哪一个说不准。 + +## 更新 + +拉取代码，重新打 zip 包，再添加一次。以原名添加的插件必须先删除，这会连已安装的 JDK 一起删掉，所以经常更新时用别名更省事： + +```bash +vfox remove -y java-dev +vfox add java --source ./java.zip --alias java-dev +``` + +`vfox update java` 会拿 `metadata.lua` 里的版本号和插件注册表里的比较，两者相同时只会打印 `java is already the latest version`，所以在发布出比它更新的版本之前，不会动源码构建的版本。 + +开发插件请看 [development.md](development.md)。 diff --git a/docs/zh-CN/javafx.md b/docs/zh-CN/javafx.md new file mode 100644 index 0000000..47a3fc6 --- /dev/null +++ b/docs/zh-CN/javafx.md @@ -0,0 +1,45 @@ +# JavaFX 构建 + +[中文](javafx.md) | [English](../javafx.md) + +有些厂商会把 JavaFX 打包进 JDK，作为单独的包发布。在发行版后面加 `-fx` 就能装上这种包： + +```bash +vfox install java@21-zulu-fx +vfox install java@25.0.4-librca-fx +vfox use java@21-zulu-fx +``` + +`vfox search` 会同时列出两种构建，带 JavaFX 的名字以 `-fx` 结尾，并有 JavaFX 备注： + +``` + - 25.0.4.1+1-zulu-fx (LTS, JavaFX) + - 25.0.4.1+1-zulu (LTS) +``` + +安装后的版本名保留这个后缀（`25.0.4+9-librca-fx`），所以带 JavaFX 和不带的构建可以并存，两者不会串用： + +- `java@21-zulu` 装不带 JavaFX 的构建，`java@21-zulu-fx` 装带的。如果发行版对某个版本只提供其中一种，另一种就会失败：`java@21-tem-fx` 会报 `No JDK found for 21-tem-fx with JavaFX on linux/amd64`，因为 Temurin 没有带 JavaFX 的构建。 +- `vfox use java@21-zulu` 不会选中 `-fx` 构建，反过来也一样。 +- `.sdkmanrc` 遵循同样的规则，见 [sdkmanrc.md](sdkmanrc.md)。 + +想确认装到的是哪种，看模块列表： + +```bash +java --list-modules | grep javafx +``` + +带 JavaFX 的构建会列出 `javafx.base` 等模块，不带的什么也列不出。 + +## 哪些平台有 JavaFX 构建 + +截至 2026-10-18，提供 JavaFX 构建的发行版有四个，而且并非每个平台都有。下表列出有 JavaFX 构建的 LTS 版本，中间的非 LTS 版本也有一些，但有缺口。 + +| 发行版 | Linux x64 | Linux arm64 | Alpine x64 | macOS Intel | macOS Apple Silicon | Windows x64 | Windows arm64 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Zulu（`zulu`） | 8、11、17、21、25 | 8、11、17、21、25 | – | 8、11、17、21、25 | 8、11、17、21、25 | 8、11、17、21、25 | – | +| Liberica（`librca`） | 8、11、17、21、25 | 11、17、21、25 | 11 | 8、11、17、21、25 | 8、11、17、21、25 | 8、11、17、21、25 | 11、17、21、25 | +| Corretto（`amzn`） | 8 | 8 | – | 8 | – | 8 | – | +| Liberica NIK（`nik`） | 21、25 | – | – | 25 | 25 | 21、25 | – | + +Alpine arm64 上没有任何发行版提供 JavaFX。Loongnix 为龙架构提供带 JavaFX 的构建，选择方式相同，见 [loongnix.md](loongnix.md)。想看某个平台当前的情况，在 [foojay.md](foojay.md) 的查询里加上 `javafx_bundled=true` 即可。 diff --git a/docs/zh-CN/loongnix.md b/docs/zh-CN/loongnix.md new file mode 100644 index 0000000..1bfbe8b --- /dev/null +++ b/docs/zh-CN/loongnix.md @@ -0,0 +1,53 @@ +# Loongnix JDK + +[中文](loongnix.md) | [English](../loongnix.md) + +Foojay 没有龙架构（LoongArch）的包，并且会拒绝这个架构名。所以在 Linux loong64 上，插件改从龙芯的 [Loongnix 归档](https://ftp.loongnix.cn/Java/)读取 JDK，完全不访问 Foojay。这是插件在 Foojay 之外唯一的 JDK 来源。在其他平台上，`lnxabi1` 和 `lnxabi2` 会报 `Loongnix JDKs require linux/loong64`；在 loong64 上，[distributions.md](distributions.md) 里的发行版都用不了： + +``` +$ vfox search java tem +Foojay does not support loong64; use vfox search java loongnix +``` + +## 选择 ABI + +归档里有两种构建，插件不会替你猜该用哪一种： + +| 简称 | 长名 | 构建 | 适用于 | +| --- | --- | --- | --- | +| `lnxabi1` | `loongnix_abi1` | Linux 4.19 UAPI | Loongnix 20、Loongnix Server 8.4 | +| `lnxabi2` | `loongnix_abi2` | Linux 5.10 UAPI，上游文件名里是 `glibc2.34` | Debian 12、openEuler | + +请对照[龙芯的兼容性说明](https://www.loongnix.cn/zh/api/java/)，按你的系统来选，不要只看内核版本。 + +## 使用 + +```bash +vfox search java lnxabi2 # ABI2 的构建 +vfox install java@21-lnxabi2-fx # Java 21 的最新版，带 JavaFX，ABI2 +vfox install java@21.0.12+8-lnxabi2-fx # 指定构建 +vfox use java@21.0.12+8-lnxabi2-fx +``` + +不带名字的 `vfox search java` 会列出两种 ABI 的构建，`vfox search java loongnix` 和 `vfox search java all` 也一样。一条结果长这样： + +``` + - 26+35-lnxabi2-fx (JDK 26+35; ABI2 (Linux 5.10 UAPI, glibc 2.34); JavaFX) + - 25.0.4+7-lnxabi2-fx (JDK 25.0.4+7; ABI2 (Linux 5.10 UAPI, glibc 2.34); JavaFX) +``` + +安装时名字里必须带 ABI。`vfox install java@21` 和 `java@21-tem` 都会报 `Choose a Loongnix ABI explicitly: run vfox search java and select lnxabi1 or lnxabi2`。在交互式终端里从 `vfox search` 的结果中选择，会自动带上 ABI。 + +版本号是 Java 的版本和构建号，即 `21.0.12+8`，不是龙芯自己的发行号（文件名里的 `loongson21.12.26`）。同一个版本龙芯发布过多次的，取最新的一次。`21` 和 `21.0.12` 按前缀匹配，取最新的构建，`21.0.1` 不会匹配 `21.0.12`。`vfox use` 会保留你输入的 ABI 和 `-fx`，所以 `21-lnxabi2-fx` 选中的是已安装的最新版本，不会选到 `lnxabi1` 的构建。 + +## JavaFX + +龙芯的包大多是带 JavaFX 的构建，上游文件名里有 `fx-`，在插件里写作 `-fx`。Java 21 及以后的全部带 JavaFX，8、11、17 的大部分也带，只有少数早期构建不带。不写 `-fx` 就只会得到不带 JavaFX 的构建，所以 `java@21-lnxabi2` 会失败，报 `No Loongnix JDK found for 21-lnxabi2`，而 `java@21-lnxabi2-fx` 可以装上。 + +## 限制 + +- 只提供归档里 GA 版本的龙架构 tar 包。EA 构建、安装程序、校验文件以及 MIPS 包都会跳过。 +- 归档里只有 glibc 构建，没有 musl 构建。 +- 插件不校验下载内容。 +- 插件读取的是归档的 HTML 目录页。龙芯如果改了目录格式，插件会报错 `No Loongnix JDK packages found; check the requested version and upstream directory format` 并停止。 +- e2e 套件里没有 loong64 作业。钩子的离线测试用的是 `tests/fixtures/loongnix` 里保存的一份归档目录页（见 [development.md](development.md)）。 diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md new file mode 100644 index 0000000..97d58de --- /dev/null +++ b/docs/zh-CN/platforms.md @@ -0,0 +1,71 @@ +# 平台支持 + +[中文](platforms.md) | [English](../platforms.md) + +插件向 Foojay 请求的是当前平台的包：操作系统、vfox 二进制所属的 CPU 架构，在 Linux 上还有 C 库（请求的具体内容见 [foojay.md](foojay.md)）。某个发行版在这个平台上没有包，`vfox search java bsg` 就会报 `no available version`，安装也会失败： + +``` +No JDK found for 21-bsg on darwin/arm64. Please check available versions with 'vfox search java' +``` + +下表列出各发行版有哪些平台的包，数据取自 2026-10-18 的 Foojay。打勾表示 Foojay 在这个平台上至少列有一个插件能安装的包，短横线表示一个也没有。 + +| 发行版 | Linux x64 | Linux arm64 | Alpine x64 | Alpine arm64 | macOS Intel | macOS Apple Silicon | Windows x64 | Windows arm64 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| OpenJDK（`open`） | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Temurin（`tem`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Zulu（`zulu`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Liberica（`librca`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Corretto（`amzn`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Microsoft（`ms`） | ✓ | ✓ | ✓ | – | ✓ | ✓ | ✓ | ✓ | +| Oracle JDK（`oracle`） | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Semeru（`sem`） | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| SapMachine（`sapmchn`） | ✓ | ✓ | ✓ | – | ✓ | ✓ | ✓ | – | +| Kona（`kona`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Dragonwell（`albba`） | ✓ | ✓ | ✓ | – | – | – | ✓ | – | +| 毕昇 JDK（`bsg`） | ✓ | ✓ | – | – | – | – | – | – | +| Oracle GraalVM（`graal`） | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| GraalVM 社区版（`graalce`） | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | – | +| Liberica NIK（`nik`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | – | +| Mandrel（`mandrel`） | ✓ | ✓ | – | – | – | ✓ | ✓ | – | +| JetBrains Runtime（`jb`） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Trava（`trava`） | ✓ | ✓ | – | – | ✓ | – | ✓ | – | + +“Alpine”指使用 musl C 库的 Linux。`ldd --version` 的输出里提到 musl，插件就当作 musl，否则当作 glibc。Loongnix 另有单独的页面：[loongnix.md](loongnix.md)。 + +Foojay 的数据会变，这张表也会过时。想看当前的情况，按 [foojay.md](foojay.md#我的平台上有哪些发行版) 里的方法去问 Foojay。 + +## 只有部分版本 + +打勾不代表所有版本都有。以下同样截至 2026-10-18： + +- 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 到 25，Liberica NIK 有 22 到 25。 +- 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-构建)。 + +## 哪些只有 x64 + +每个发行版在 Linux 上都有 arm64 构建，Trava 只有一个（11.0.10+6）。macOS 上，Dragonwell 和毕昇两种架构都没有，Trava 只有 Intel，Mandrel 只有 Apple Silicon。 + +Windows 上几乎都只有 x64。另外有 arm64 构建的是 Temurin、Zulu、Liberica、Microsoft 和 JetBrains Runtime。其余都只有 x64，其中毕昇在 Windows 上根本没有。 + +## GraalVM + +Oracle GraalVM 和 GraalVM 社区版在 Linux 和 macOS 上有 x64 和 arm64 构建，在 Windows 上只有 x64。它们没有 Alpine 的构建。Intel Mac 上最新的是 25.0.1，25.1 之后每月发布的特性版本在 macOS 上只有 Apple Silicon 版本。e2e 套件在 arm64 上不测 GraalVM 社区版，只是因为它的 Windows arm64 作业没有可装的包。Linux arm64 是有构建的。 + +## 其他 CPU + +vfox 除了 x64、arm64 和 loong64，还发布 32 位 x86 和 32 位 ARM 的二进制。插件会把 vfox 二进制的架构名传给 Foojay（`arm64` 改成 `aarch64`，Windows 上 `amd64` 改成 `x64`），所以能装到什么，取决于 Foojay 列出什么。e2e 套件没有覆盖这些情况。 + +- 32 位 ARM Linux：Corretto、Liberica、Temurin 和 Zulu。 +- 32 位 x86 Linux：Corretto、Liberica、Zulu 和 JetBrains Runtime。 +- 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。 + +## macOS 上的 Java home + +有些 macOS 压缩包把 JDK 放在 `Contents/Home` 里，或放在以厂商命名的目录中。安装之后插件会把内容上移一层，这样 `JAVA_HOME` 总是指向含有 `bin/java` 的目录。安装时会打印 `Checking Java home layout...`。压缩包里有两个候选的 Java home，或者移动时文件会互相覆盖，插件会在移动任何文件之前报错并中止。 diff --git a/docs/zh-CN/sdkmanrc.md b/docs/zh-CN/sdkmanrc.md new file mode 100644 index 0000000..dcf3d4c --- /dev/null +++ b/docs/zh-CN/sdkmanrc.md @@ -0,0 +1,76 @@ +# `.sdkmanrc` + +[中文](sdkmanrc.md) | [English](../sdkmanrc.md) + +vfox 可以通过这个插件，把 [SDKMAN](https://sdkman.io/) 的项目文件 `.sdkmanrc` 当作兼容版本文件来读取（插件在 `PLUGIN.legacyFilenames` 里声明了它）。已经为 SDKMAN 固定了 JDK 版本的项目，不需要再为 vfox 另写一个文件： + +``` +# .sdkmanrc +java=21.0.8-tem +``` + +只读取 `java=` 这一行。其他行，例如 `maven=3.9.9`，与这个插件无关。 + +> 未发布：0.6.1 在 vfox 1.x 下读不了 `.sdkmanrc`。它的钩子调用了 `ctx:getInstalledVersions()`，所有 vfox 1.x 都会拒绝这种调用（测试过 1.0.12 和 1.0.13），报 `expected 0 arguments for func() []string, got 1`，而 vfox 又不会显示这个错误，所以看上去什么都没发生。`main` 已修复，并且支持 SDKMAN 更多的写法（`jbr`、JavaFX、补零、EA），也能在同一大版本装了多个 JDK 时选对。可以用 [install-from-source.md](install-from-source.md) 先试用，详情见 [changes.md](changes.md)。 + +## 使用方法 + +```bash +eval "$(vfox activate bash)" # 只需配置一次，写进 ~/.bashrc；其他 Shell 见 vfox 的快速入门 + +vfox install java@21.0.8-tem # .sdkmanrc 不会帮你安装任何东西 +cd my-project # 里面有上面那个 .sdkmanrc +java -version # Temurin 21.0.8 +``` + +vfox 挂载到 Shell 之后，进入目录时会读取这个文件，并选中其中指定的 JDK，不需要 `vfox use`。zsh、fish、PowerShell 等其他 Shell 的挂载方式见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。 + +- 只读取当前目录下的文件。进入项目的子目录就找不到它了，SDKMAN 的 `sdk env` 也是这样。 +- 同一目录里的 `.vfox.toml` 如果写了 `java`，优先于 `.sdkmanrc`。`vfox use --project` 会写出这个文件。 +- 在这个目录里，这个文件还优先于不带 `--project` 的 `vfox use`：下一个提示符就会切回来，而 `vfox current java` 仍然显示会话里选的那个。 +- vfox 会在这个目录里创建 `.vfox/sdks/java`，并且不会把 `.vfox/` 加进 `.gitignore`，所以 `git status` 会列出它，需要你自己忽略。 +- JDK 必须已经安装。没有任何已安装的版本匹配时，这个文件会被忽略，也不会有任何提示。`vfox list java` 可以看到已有哪些。 +- `vfox config legacyVersionFile.enable false` 会关闭所有兼容版本文件。`legacyVersionFile.strategy` 对这个插件没有作用：以文件里写的版本为准。 + +## 标识符会选中什么 + +插件把标识符与已安装的 JDK 按下面的顺序匹配： + +1. 原样写出的已安装版本名：`java=21.0.8+9-tem`、`java=28-ea+19`。 +2. 你写的那个版本，取它已安装的最新构建：`21.0.8-tem` 选中 `21.0.8+9-tem`。 +3. 不行的话，取同一大版本里已安装的最新版本。`21-tem` 直接走这一步。 + +第 3 步不检查已装的版本是否低于你写的版本。只装了 `21.0.8+9-tem` 时，`java=21.0.12-tem` 会选中它，`java=21.0.3-tem` 也一样。写了没装的构建号，会退到这个版本已安装的最新构建（`21.0.8+7-tem` 选中 `21.0.8+9-tem`）。如果这个大版本根本没装，就什么也不选。 + +它不会跨发行版，不会在带 JavaFX 和不带 JavaFX 的构建之间串用，也不会在 EA 构建和 GA 版本之间串用。 + +## SDKMAN 的写法 + +`sdk list java` 里同时存在两代标识符。插件两种都认，也认自己的写法： + +| `.sdkmanrc` 里写 | 选中 | +| --- | --- | +| `21.0.8-tem` | Temurin 21.0.8，安装后叫 `21.0.8+9-tem` | +| `21.0.5-jbr` | JetBrains Runtime（`jb`），SDKMAN 叫它 `jbr` | +| `21.0.12.fx-zulu` | 带 JavaFX 的 Zulu，`21.0.12+8-zulu-fx`（较旧的写法） | +| `21.0.12-fx+1.1-librca` | 带 JavaFX 的 Liberica（较新的写法） | +| `21.0.8+1.1-tem` | Temurin 21.0.8，见下文 | +| `27.0.0+36-librca`、`25.0.1.0+8-open` | `27+36-librca`、`25.0.1+8`：补的零会被去掉 | +| `28.ea.19-open`、`28.0.0+ea.19-open` | EA 构建 `28-ea+19` | + +SDKMAN 新写法里 `+` 后面的数字（`21.0.8+1.1-tem`）是 SDKMAN 自己重新构建的次数，不是厂商的构建号，所以插件不会去找这个构建，而是按版本匹配。Foojay 和安装后的版本名都不补零，所以 `27.0.0` 指的就是 `27`。`sdk list java` 里补一个 `.0` 很常见（`25.0.1.0+8-open`、`21.0.9.0+116386-jbr`），插件同样能读。 + +## 没有生效怎么办 + +JDK 没有切换时，依次检查： + +- vfox 没有挂载到当前的 Shell。`eval "$(vfox activate bash)"` 要在当前 Shell 里执行过，只在别处执行过不算。 +- 当前目录是 `.sdkmanrc` 所在目录的子目录。 +- JDK 没有安装，或者只装了另一种构建（带或不带 JavaFX）。`java=21.0.8-zulu` 不会选中带 JavaFX 的构建，`java=21.0.8.fx-zulu` 也不会选中不带的。请安装文件里指明的那种，比如 `vfox install java@21.0.8-zulu-fx`。 +- 被 `.vfox.toml` 挡住了，或者 `legacyVersionFile.enable` 是 `false`。 + +`vfox --debug env -s bash` 会打印文件的解析过程。 + +## 与 SDKMAN 的区别 + +`sdk env install` 会安装 `.sdkmanrc` 里指明的 JDK。vfox 只在已安装的版本里选择，安装要用 `vfox install java@<版本>`。从文件里复制的标识符不一定能直接给 `vfox install` 用：`21.0.8-tem` 可以，`21.0.12.fx-zulu` 不行，`21.0.12-zulu-fx` 可以。 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md new file mode 100644 index 0000000..cb38422 --- /dev/null +++ b/docs/zh-CN/troubleshooting.md @@ -0,0 +1,76 @@ +# 问题排查 + +[中文](troubleshooting.md) | [English](../troubleshooting.md) + +## 插件给出的提示 + +### `No JDK found for 21-bsg on darwin/arm64. Please check available versions with 'vfox search java'` + +Foojay 在这个平台上没有对应的包：版本、发行版、带不带 JavaFX，三者要同时对上。提示里的平台是插件实际请求的平台，比如 `linux/amd64`、`darwin/arm64`、`windows/arm64`。检查这三点： + +- 这个发行版在这个平台上有没有包，见 [platforms.md](platforms.md)。 +- 这个版本是否存在：`vfox search java <发行版>` 列出的是这个平台能装的版本。 +- 是不是漏写了发行版。`java@17.0.17` 指的是 jdk.java.net 上的 OpenJDK，它停在 17.0.2。`java@17.0.17-tem` 可以装，见 [versions.md](versions.md#不写发行版)。 + +提示里出现 `with JavaFX` 或 `without JavaFX`，说明这个版本是有的，只是没有对应的构建（带或不带 JavaFX），见 [javafx.md](javafx.md)。 + +### `No version in tem; add one, such as 21-tem. Please check available versions with 'vfox search java tem'` + +`java@` 后面只有发行版，没有版本。`java@-tem`、`java@temurin-` 和 `java@zulu-fx` 都属于这种情况。未发布：0.6.1 对 `java@tem` 会报 `attempt to index a non-table object(nil) with key 'match'`，对 `java@-tem` 则会装上最新版本。 + +### `Could not extract a valid distribution: 21-foo` + +`-` 前后两部分都不是发行版名。名字都是小写，取自 [distributions.md](distributions.md) 里的表。`java@21-openlogic` 也会报这个错，因为插件没有提供 Foojay 里的所有发行版。 + +### `Unsupported distribution: foo` + +`vfox search java foo` 报的是这一条。 + +### `Failed to fetch jdk info from foojay: ...` + +向 Foojay 的请求失败了。`status_code =>` 后面是 HTTP 状态码；没有这一段时，后面是网络错误。见下面的[网络](#网络)。第二次请求（取下载链接）失败时，报的是 `Failed to fetch jdk info: ...`。 + +### `source file not found` + +下载时服务器返回 404。厂商会下线旧的构建，而 Foojay 仍保留它们的记录。最常见的是 EA 构建（见 [versions.md](versions.md#早期访问ea构建)）。换一个较新的构建。 + +### `java@21-tem is not installed` + +`vfox use` 和 `vfox uninstall` 只认已安装的版本。`vfox list java` 能看到它们，名字里带构建号：`21.0.8+9-tem`。`vfox uninstall` 需要写完整的名字。 + +### macOS 上关于 Java home 的提示 + +每次在 macOS 上安装都会打印 `Checking Java home layout...`。如果后面跟着 `Failed to normalize Java home`，说明压缩包的目录结构不是插件预期的：`Multiple Java homes found in `、`No Java home containing bin/java found in `，或者 `Cannot normalize Java home: destination already exists: `。请带上发行版和版本号来报告。 + +### Loongnix + +`Loongnix JDKs require linux/loong64`、`Foojay does not support loong64; use vfox search java loongnix`、`Choose a Loongnix ABI explicitly`、`No Loongnix JDK found for ...` 和 `No Loongnix JDK packages found` 的含义见 [loongnix.md](loongnix.md)。 + +## 网络 + +插件向 Foojay 取版本列表，压缩包则由 vfox 从厂商的服务器下载，常常是 GitHub Releases。插件没有镜像设置。 + +vfox 自己的代理设置对 Foojay 请求和下载都有效： + +```bash +vfox config proxy.enable true +vfox config proxy.url http://127.0.0.1:7890 +``` + +`proxy.enable` 为 `false` 时，通常的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量依然有效。只支持 `http` 和 `https` 代理。 + +## 看起来不对，其实没问题 + +- **`vfox search` 里没有你预期的版本。** vfox 会缓存搜索结果 12 小时。`vfox config cache.availableHookDuration 0` 可以关闭缓存。也可能是 Foojay 那边还没有这个版本。 +- **每次安装都有 `WARNING: Checksum is not provided, skip verify...`。** 插件没有把校验和交给 vfox，所以下载内容没有校验，见 [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`。未发布：0.6.1 对 GraalVM 会把它替换掉。 + +## JDK 在哪里 + +`JAVA_HOME` 是一个链接，由 `vfox use` 指向你选的 JDK：`--global` 时是 `~/.vfox/sdks/java`，`--project` 时是项目里的 `.vfox/sdks/java`，会话作用域下是 `~/.vfox/tmp` 下的一个目录。想让 IDE 或构建工具跟随全局选择，可以直接指向 `~/.vfox/sdks/java`。要固定指向某个 JDK，`vfox info java@21.0.8+9-tem` 会打印一个目录，JDK 就在其中的 `java-21.0.8+9-tem` 目录里。`~/.vfox` 是 `$VFOX_HOME` 的默认值。设置了 `VFOX_HOME` 之后，JDK（`cache/`）和插件放在那里，`sdks/java` 链接和会话目录仍留在 `~/.vfox`。`storage.sdkPath` 同样可以改变 JDK 的存放位置，见 vfox 的[配置文档](https://vfox.dev/zh-hans/guides/configuration.html)。 + +## 报告问题 + +请到 [version-fox/vfox-java](https://github.com/version-fox/vfox-java/issues) 提 issue，附上 `vfox --version` 和 `vfox info java` 的输出、操作系统和 CPU、你执行的命令以及它打印的全部内容。`vfox --debug <命令>` 会打印更多信息。Foojay 数据本身的错误请向 [Foojay](https://github.com/foojayio/discoapi) 反馈。 diff --git a/docs/zh-CN/versions.md b/docs/zh-CN/versions.md new file mode 100644 index 0000000..47bb759 --- /dev/null +++ b/docs/zh-CN/versions.md @@ -0,0 +1,120 @@ +# 版本与命名 + +[中文](versions.md) | [English](../versions.md) + +`vfox install` 和 `vfox use` 在 `java@` 后面写版本和发行版，用 `-` 连接： + +```bash +vfox install java@21-tem # Temurin 21 的最新版 +vfox install java@21.0.8-tem # Temurin 21.0.8 +vfox install java@21.0.8+9-tem # 精确到某个构建 +vfox install java@21-zulu-fx # 带 JavaFX 的 Zulu 21 +vfox install java@temurin-21 # 等同于 21-tem，发行版写在前面 +vfox install java@21 # 不写发行版：jdk.java.net 上的 OpenJDK +``` + +发行版可以写简称（`tem`）或长名（`temurin`），两份名单都在 [distributions.md](distributions.md)。`-fx` 放在最后，表示要带 JavaFX 的构建，见 [javafx.md](javafx.md)。 + +> 本页描述的是 `main`。写这篇文档时最新的发布版是 0.6.1，它在下文标有“未发布”的地方与本页不同，完整列表见 [changes.md](changes.md)。 + +## 不写发行版 + +`java@21` 指 [jdk.java.net](https://jdk.java.net/) 上发布的 OpenJDK，安装后的版本名不带后缀（`21.0.2+13`）。这个站点只提供最新的几个版本，旧版本只留最后一个构建：17 停在 `17.0.2`，21 停在 `21.0.2`。所以 `vfox install java@17.0.17` 会失败，`java@17.0.17-tem` 才能装上。要用仍在维护的版本，请指定发行版。 + +## 安装 + +`vfox install` 先问插件该装哪个包，再由 vfox 下载并解压。 + +- 只写大版本号（`21`、`21-tem`）时，安装这个发行版列出的、这个大版本下最新的版本，例如截至 2026-10-18 是 `21.0.12.1+1-tem`。未发布：0.6.1 装的是第一个 GA 构建 `21+35-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`。未发布：0.6.1 会改装这个版本的最新构建。 +- SDKMAN 写法里补了零的版本也能识别：`27.0.0-librca` 装的是 `27+36-librca`。 +- Oracle GraalVM 只写大版本号时，装 25.0 系列的最新构建，不装每月发布的特性版本（feature release）。特性版本要写全版本号（`25.4.4.1-graal`）。见 [GraalVM](distributions.md#graalvm-系列)。未发布：0.6.1 装的是 GA 构建 `25-graal`。 +- 写了 `-fx` 就只考虑带 JavaFX 的构建，没写就只考虑不带的，两者不会混用。 +- 在 Windows 上，同一版本既有 zip 又有 tar.gz 时，装 zip。 +- 只写发行版不写版本（`java@tem`、`java@-tem`、`java@zulu-fx`）会被拒绝，并提示补上版本。未发布：0.6.1 对 `java@tem` 报 Lua 错误，对 `java@-tem` 则装上最新版本。 + +如果这个版本名已经装过，会提示 `java@21.0.12.1+1-tem is already installed`，不会重新下载。 + +## 安装后的版本名 + +安装后的版本名取自 Foojay 返回的 `java_version`，`vfox search` 里显示的也是它： + +``` +[-<简称>][-fx] +``` + +| 安装后的版本名 | 含义 | +| --- | --- | +| `21.0.12.1+1-tem` | Temurin | +| `25.0.4+9-librca-fx` | 带 JavaFX 的 Liberica | +| `25.0.2+10` | OpenJDK，没有后缀 | +| `17.0.12-graal` | GraalVM，没有构建号 | +| `8.0.482+8-zulu` | Java 8 写成 `8.0.<更新号>+<构建号>` | +| `28-ea+19` | EA 构建，见下文 | + +`vfox list java` 显示的、`vfox uninstall` 需要的都是这种名字： + +```bash +vfox uninstall java@21.0.8+9-tem +``` + +`vfox uninstall java@21.0.8-tem` 会提示 `is not installed`。卸载当前正在使用的版本时，vfox 会切到 `vfox list java` 里剩下的第一项，那可能是另一个大版本。 + +## 使用 + +`vfox use` 会把你输入的内容映射到已安装的版本名，不会下载任何东西，所以构建号和小版本都可以省略： + +| 输入 | 选中 | +| --- | --- | +| `21.0.8-tem` | 这个版本已安装的最新构建 `21.0.8+9-tem` | +| `21-tem` | 已安装的最新 Temurin 21 | +| `temurin-21.0.8` | `21.0.8+9-tem` | +| `25.0.2-open`、`openjdk-25.0.2` | `25.0.2+10`，OpenJDK 没有后缀 | +| `21` | 由 vfox 自己匹配：已安装的最高 21.x，不限发行版 | + +写明了构建或版本时，不会跳到别的构建或版本（`21.0.12-tem` 不会选中 `21.0.12.1+1-tem`）。也不会跨发行版，不会在带 JavaFX 和不带 JavaFX 的构建之间串用，不会在 EA 和 GA 之间串用。什么都匹配不上时，报 `java@99-tem is not installed`。 + +未发布：0.6.1 把输入原样交给 vfox，所以 `vfox use java@21.0.8-tem` 找不到，必须写完整名字 `21.0.8+9-tem`。`-open`、`openjdk-` 写法和补零的版本同理。在 vfox 1.0.13 及以后，0.6.1 上的 `vfox use java@21` 和 `java@21-open` 会直接报错 `cannot unmarshal string into plugin.PreUseHookResult`，因为它对只写大版本号的输入返回了空字符串。 + +作用域用 `vfox use` 的参数选择：`--global`、`--project` 或 `--session`，默认是会话作用域。如果 Shell 没有挂载 vfox，Windows 会警告并切到全局作用域，Linux 和 macOS 则报 `vfox requires hook support` 后退出。`--project` 会写出 `.vfox.toml`，里面记录的是安装后的版本名（`java = "17.0.10+7-tem"`）。`.sdkmanrc` 也会被读取，见 [sdkmanrc.md](sdkmanrc.md)。 + +## 早期访问（EA）构建 + +写成 `<大版本>.ea[.<构建号>]`： + +```bash +vfox install java@28.ea-open # 最新的 EA 构建，截至 2026-10-18 是 28-ea+19 +vfox install java@28.ea.15-open # 28-ea+15 +``` + +未发布：0.6.1 会忽略构建号，装的总是最新的 EA 构建。 + +安装后的版本名沿用 Foojay 的写法 `28-ea+19`，`vfox use java@28-ea+19` 按原样识别。`vfox search` 只列 GA 版本。Foojay 列有 EA 构建的发行版包括 OpenJDK、Temurin、Zulu、SapMachine、GraalVM 和 GraalVM 社区版等。厂商会把旧的 EA 构建从服务器上撤掉，而 Foojay 仍保留记录，所以较旧的构建可能下载失败。 + +## 搜索 + +```bash +vfox search java # 默认的 OpenJDK +vfox search java tem # 指定一个发行版，简称或长名都行 +vfox search java all # 所有发行版，在 Linux x64 上约 2300 行 +``` + +每一行都是可以接在 `java@` 后面的名字，新的在前，带 LTS、JavaFX（见 [javafx.md](javafx.md)）备注，已安装的会有标记： + +``` +$ vfox search java tem +Available versions: + - 27+35-tem + - 26.0.2.1+1-tem + ... + - 25.0.4+7-tem (LTS) + ... + - 21.0.12.1+1-tem (LTS) (installed) +``` + +列表是按你运行命令的这台机器来的，只含它能装的版本，见 [platforms.md](platforms.md)。在交互式终端里，`vfox search java tem` 可以直接选一个版本安装；在其他环境下只打印列表。vfox 会缓存搜索结果 12 小时（`vfox config cache.availableHookDuration`），所以刚发布的版本可能暂时看不到。 + +`vfox install java tem` 选的不是 Temurin：用空格分隔的参数表示多个 SDK。请写 `java@21-tem`。 + +LTS 备注来自 Foojay，唯独 GraalVM 每月发布的特性版本（`25.4.4.1-graal`）不带这个备注，尽管 Foojay 把它们标成了 LTS。未发布：0.6.1 仍会给它们加上 LTS 备注。 diff --git a/hooks/available.lua b/hooks/available.lua index 4f4d2d4..99515cc 100644 --- a/hooks/available.lua +++ b/hooks/available.lua @@ -16,8 +16,9 @@ local foojay = require("foojay") local loongnix = require("loongnix") local distribution_version_parser = require("distribution_version") --- is_feature_release reads GraalVM's numbering only: Liberica NIK and Mandrel --- number every release after themselves (Mandrel 23.1.12 is LTS). +-- is_feature_release reads GraalVM's numbering only. Liberica NIK and Mandrel +-- numbered their releases after themselves up to 24 (Mandrel 23.1.12 is LTS) and +-- follow the JDK from 25 on, so they stay out of it. local graalvm = { graal = true, graalce = true } --- Return all available versions provided by this plugin