diff --git a/README.md b/README.md index ce82b23..0a82709 100644 --- a/README.md +++ b/README.md @@ -188,8 +188,8 @@ uv-build downloads can go through `VFOX_PYTHON_UV_BUILD_MIRROR`. See ## Thanks -- [pyenv](https://github.com/pyenv/pyenv), whose version list and `python-build` - the default Linux and macOS installs use +- [pyenv](https://github.com/pyenv/pyenv), whose `python-build` makes the Linux and + macOS source builds, and whose version list `vfox search python` shows there - [uv](https://github.com/astral-sh/uv), for the prebuilt Python archives and the `.python-version` convention - [python.org](https://www.python.org/), for the releases and Windows installers diff --git a/README_CN.md b/README_CN.md index 2ee2f45..6847611 100644 --- a/README_CN.md +++ b/README_CN.md @@ -164,7 +164,7 @@ uv-build 的下载可以走 `VFOX_PYTHON_UV_BUILD_MIRROR`。两个变量和镜 ## 致谢 -- [pyenv](https://github.com/pyenv/pyenv),Linux 和 macOS 的默认安装沿用它的版本列表和 `python-build` +- [pyenv](https://github.com/pyenv/pyenv),Linux 和 macOS 的源码构建用它的 `python-build`,`vfox search python` 列出的版本名也来自它 - [uv](https://github.com/astral-sh/uv),提供预编译 Python 包和 `.python-version` 约定 - [python.org](https://www.python.org/),提供各版本和 Windows 安装包 - [Oracle GraalPy](https://github.com/oracle/graalpython),提供 GraalPy 各版本 diff --git a/docs/changes.md b/docs/changes.md index 0fad1fa..74063e9 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -2,7 +2,7 @@ [中文](zh-CN/changes.md) | [English](changes.md) -## Unreleased +## 0.6.4 - Index requests to the uv-build and pyenv indexes are sent again on a network error, HTTP 429, a 5xx, or a 200 response that is not the index: up to three attempts in @@ -52,6 +52,9 @@ read from the cabinet inside the installer with `expand.exe`, which ships with Windows, and the `bin/` directory is gone. Antivirus software has no WiX tools to quarantine. The same MSI packages are installed as before. +- CI: a docs check in `lint.yml` compares the Chinese pages with the English ones. The + Linux E2E suite installs CPython from uv-build with the default settings in a bare + Ubuntu 24.04 container, and the Windows test job checks that index retries wait. ## 0.6.3 diff --git a/docs/development.md b/docs/development.md index 6b4a4ad..b4f9a74 100644 --- a/docs/development.md +++ b/docs/development.md @@ -272,10 +272,11 @@ installs CPython from source (`VFOX_PYTHON_USE_UV_BUILD=0`), through the mirror, and also runs `vfox link --detect` and a project `.python-version` on the runner. The Windows package installs CPython and uv-build, installs GraalPy with PEP 514 registration, and checks `.python-version`. Both packages also -run GraalPy checks in Docker containers: the Linux package through -testcontainers-go, the Windows package through the `docker` CLI, because -testcontainers-go creates a bridge network for every container and a Windows -engine has no bridge driver. +run container checks. The Linux package starts a bare Ubuntu 24.04 container, +installs CPython from uv-build with the default settings and checks GraalPy there, through +testcontainers-go. The Windows package checks GraalPy in a Server Core container through the +`docker` CLI, because testcontainers-go creates a bridge network for every container and a +Windows engine has no bridge driver. See [E2E](e2e.md) for the layout and the local commands. Local commands: @@ -365,7 +366,7 @@ updating that tool does not release this plugin. | `VFOX_PYTHON_UV_LIBC` | Available, PreInstall | `gnu` or `musl` override | | `VFOX_PYTHON_UV_BUILD_MIRROR` | PreInstall | HTTPS mirror for uv-build archives | | `VFOX_PYTHON_REGISTER_PY_LAUNCHER` | PostInstall, PreUninstall | register Windows installs under `HKCU\Software\Python\VersionFox`; on by default, `0`, `false`, `no` or `off` disables | -| `GITHUB_TOKEN`, `GH_TOKEN` | Available | raise the GitHub API limit for the Windows GraalPy release list | +| `GITHUB_TOKEN`, `GH_TOKEN` | Available, PreInstall | authenticate the GitHub API requests for GraalPy release lookups, which raises the rate limit | | `UV_PYTHON_INSTALL_DIR` | Detect | uv's Python directory | | `PYENV_ROOT` | Detect | pyenv root | | `ASDF_DATA_DIR` | Detect | asdf data directory | diff --git a/docs/e2e.md b/docs/e2e.md index 3def196..91de1ac 100644 --- a/docs/e2e.md +++ b/docs/e2e.md @@ -14,7 +14,7 @@ in Docker containers. `.github/workflows/e2e.yml` only installs Go and runs | `common/` | builds the plugin zip, installs vfox 1.1.0, runs host commands, reads the uv-build index, asserts | | `linux/e2e_test.go` | `TestNativeE2E`: source build, mirror, uv-build, GraalPy, `vfox link --detect`, `.python-version` | | `linux/container_test.go` | `TestContainerE2E`: a bare Ubuntu 24.04 container for the default install, and one for each GraalPy release | -| `linux/Dockerfile` | Ubuntu 24.04 with `ca-certificates`, `curl`, `tar`, `xz-utils` and `zip`; no compiler and no `-dev` packages | +| `linux/Dockerfile` | Ubuntu 24.04 with `ca-certificates`, `curl`, `tar`, `xz-utils` and `zip`, plus vfox 1.1.0 at `/usr/local/bin/vfox`; no compiler and no `-dev` packages | | `windows/e2e_test.go` | `TestNativeE2E`: python.org EXE installer, mirror, uv-build, GraalPy with launcher registration, `.python-version` | | `windows/container_test.go` | `TestContainerE2E`: a Server Core container, driven by the docker CLI, with PowerShell 7, the Visual C++ runtime and vfox, GraalPy | | `windows/Dockerfile`, `windows/bootstrap-tools.ps1` | provision the Server Core image: PowerShell 7, the Visual C++ runtime and vfox | diff --git a/docs/install-from-source.md b/docs/install-from-source.md index 819ba3c..50fe9f9 100644 --- a/docs/install-from-source.md +++ b/docs/install-from-source.md @@ -7,7 +7,7 @@ Try `main` before the next release: ```bash git clone https://github.com/version-fox/vfox-python.git cd vfox-python -zip -qr /tmp/vfox-python.zip metadata.lua hooks lib bin +zip -qr /tmp/vfox-python.zip metadata.lua hooks lib vfox add --source /tmp/vfox-python.zip ``` diff --git a/docs/uv.md b/docs/uv.md index f77ca79..9801d60 100644 --- a/docs/uv.md +++ b/docs/uv.md @@ -58,10 +58,10 @@ asked to wait. An HTTP-date `Retry-After` is not read. Other statuses, such as 4 are not retried. If the index still cannot be read, the install fails and names `VFOX_PYTHON_USE_UV_BUILD=0`, so it never starts a source build without saying so. -If the index has no archive for this version on this platform, such as an +In the default mode, if the index has no archive for this version on this platform, such as an architecture it does not cover, the install builds from source and prints a line -saying so. On Linux, if the libc cannot be detected, the install builds from source; -set `VFOX_PYTHON_UV_LIBC` to use uv-build. +saying so. On Linux, if the libc cannot be detected, the default mode builds from source +too; set `VFOX_PYTHON_UV_LIBC` to use uv-build. The plugin asks `https://vault.vfox.dev/python/uv-build` for the builds of the running platform, architecture and libc, then hands vfox the archive URL and its @@ -105,8 +105,9 @@ The request carries `os`, `arch` and, on Linux, `libc`: | `VFOX_PYTHON_UV_BUILD_MIRROR` | downloads the archives through a mirror | Linux libc detection runs `ldd --version`, looks for the musl loader, then asks -`getconf GNU_LIBC_VERSION`; if all of that fails it prints a warning and uses -`gnu`. Set the variable when detection is wrong. +`getconf GNU_LIBC_VERSION`. When all of that fails, `VFOX_PYTHON_USE_UV_BUILD=1` prints a +warning and uses `gnu`; the default mode builds from source instead. Set the variable +when detection is wrong. The mirror must be an HTTPS URL and must mirror GitHub release downloads at `//`. The default GitHub URL becomes diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index 034c406..73aefc1 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -2,7 +2,7 @@ [中文](changes.md) | [English](../changes.md) -## 未发布 +## 0.6.4 - uv-build 和 pyenv 索引的请求遇到网络错误、HTTP 429、5xx,或 200 响应不是索引时会重发:总共最多三次。等待时间跟随服务器的 `Retry-After`(秒数,不超过 10 秒),否则依次为 1 秒和 2 秒。持续失败仍会使安装失败;默认模式不会因此改为源码构建。 - uv-build 索引和 pyenv 版本列表现在用同一个比较函数从新到旧排序。过去 `VFOX_PYTHON_USE_UV_BUILD=1` @@ -28,6 +28,8 @@ 没有 CPython 安装时,回退仍然选已安装的任意名字。要选中自由线程、预发布版或 GraalPy,请写完整名字。 - Windows 上的 EXE 安装不再携带或运行 WiX 工具。插件用 Windows 自带的 `expand.exe` 从安装包里解出 MSI, `bin/` 目录已移除。杀毒软件因此没有 WiX 工具可以隔离。安装的 MSI 与以前相同。 +- CI:`lint.yml` 里的文档检查会比较中文页与英文页的结构。Linux 的 E2E 套件在没有构建包的 + Ubuntu 24.04 容器里,用默认设置从 uv-build 安装 CPython;Windows 测试任务会检查索引重试是否真的等待。 ## 0.6.3 diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index b55e514..8ea5773 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -211,9 +211,10 @@ local versions = plugin:Available({}) E2E 套件在 `tests/e2e` 里,使用 Go 编写。Linux 包在 runner 上安装 CPython 源码构建(`VFOX_PYTHON_USE_UV_BUILD=0`)、镜像构建、uv-build 和 GraalPy,还会运行 `vfox link --detect` 和项目 的 `.python-version`。Windows 包安装 CPython 和 uv-build,安装带 PEP 514 注册的 -GraalPy,并检查 `.python-version`。两个包也在 Docker 容器里跑 GraalPy 检查:Linux 包通过 -testcontainers-go,Windows 包直接调用 `docker` 命令行,因为 testcontainers-go 会为每个容器 -创建 bridge 网络,而 Windows 引擎没有 bridge 驱动。目录结构和本地命令见 +GraalPy,并检查 `.python-version`。两个包也在 Docker 容器里做检查。Linux 包通过 testcontainers-go 启动一个没有构建包的 +Ubuntu 24.04 容器,用默认设置从 uv-build 安装 CPython,并在里面检查 GraalPy;Windows 包直接调用 +`docker` 命令行,在 Server Core 容器里检查 GraalPy,因为 testcontainers-go 会为每个容器创建 bridge 网络, +而 Windows 引擎没有 bridge 驱动。目录结构和本地命令见 [端到端测试](e2e.md)。 本地命令: @@ -290,7 +291,7 @@ vfox 的全局变量,只关闭 `duplicate-set-field`(测试会有意替换 ` | `VFOX_PYTHON_UV_LIBC` | Available、PreInstall | 覆盖 `gnu` / `musl` 识别 | | `VFOX_PYTHON_UV_BUILD_MIRROR` | PreInstall | uv-build 包的 HTTPS 镜像 | | `VFOX_PYTHON_REGISTER_PY_LAUNCHER` | PostInstall、PreUninstall | 把 Windows 安装注册到 `HKCU\Software\Python\VersionFox`;默认开启,`0`、`false`、`no`、`off` 关闭 | -| `GITHUB_TOKEN`、`GH_TOKEN` | Available | 提高 Windows GraalPy 发布列表的 GitHub API 限额 | +| `GITHUB_TOKEN`、`GH_TOKEN` | Available、PreInstall | 为查找 GraalPy 发布的 GitHub API 请求提供认证,提高限额 | | `UV_PYTHON_INSTALL_DIR` | Detect | uv 的 Python 目录 | | `PYENV_ROOT` | Detect | pyenv 根目录 | | `ASDF_DATA_DIR` | Detect | asdf 数据目录 | diff --git a/docs/zh-CN/e2e.md b/docs/zh-CN/e2e.md index 878767b..4934113 100644 --- a/docs/zh-CN/e2e.md +++ b/docs/zh-CN/e2e.md @@ -13,7 +13,7 @@ | `common/` | 构建插件 zip、安装 vfox 1.1.0、运行主机命令、读取 uv-build 索引、断言 | | `linux/e2e_test.go` | `TestNativeE2E`:源码构建、镜像、uv-build、GraalPy、`vfox link --detect`、`.python-version` | | `linux/container_test.go` | `TestContainerE2E`:一个没有构建包的 Ubuntu 24.04 容器跑默认安装,每个 GraalPy 版本各一个容器 | -| `linux/Dockerfile` | Ubuntu 24.04,只装 `ca-certificates`、`curl`、`tar`、`xz-utils` 和 `zip`;没有编译器,也没有 `-dev` 包 | +| `linux/Dockerfile` | Ubuntu 24.04,只装 `ca-certificates`、`curl`、`tar`、`xz-utils` 和 `zip`,另装 vfox 1.1.0(`/usr/local/bin/vfox`);没有编译器,也没有 `-dev` 包 | | `windows/e2e_test.go` | `TestNativeE2E`:python.org EXE 安装包、镜像、uv-build、带启动器注册的 GraalPy、`.python-version` | | `windows/container_test.go` | `TestContainerE2E`:由 docker 命令行驱动的 Server Core 容器,装有 PowerShell 7、Visual C++ 运行时和 vfox,跑 GraalPy | | `windows/Dockerfile`、`windows/bootstrap-tools.ps1` | 准备 Server Core 镜像:PowerShell 7、Visual C++ 运行时和 vfox | diff --git a/docs/zh-CN/install-from-source.md b/docs/zh-CN/install-from-source.md index e2f8757..645fca8 100644 --- a/docs/zh-CN/install-from-source.md +++ b/docs/zh-CN/install-from-source.md @@ -7,7 +7,7 @@ ```bash git clone https://github.com/version-fox/vfox-python.git cd vfox-python -zip -qr /tmp/vfox-python.zip metadata.lua hooks lib bin +zip -qr /tmp/vfox-python.zip metadata.lua hooks lib vfox add --source /tmp/vfox-python.zip ``` diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md index f3f1a9f..fa79802 100644 --- a/docs/zh-CN/platforms.md +++ b/docs/zh-CN/platforms.md @@ -203,7 +203,7 @@ Linux 上会自动识别 libc,除非设置了 `VFOX_PYTHON_UV_LIBC`。Windows 约 600 MB。 `tests/e2e` 里的 E2E 套件覆盖这些路径。Linux 上,runner 会安装源码构建、镜像构建、 -按小版本号安装的 uv-build、GraalPy 和 `vfox link`;没有构建包的 Ubuntu 容器会安装 uv-build 和 +按小版本号安装的 uv-build、GraalPy 和 `vfox link`;没有构建包的 Ubuntu 容器会用默认设置安装 CPython(uv-build 预编译包)和 GraalPy。Windows 上,runner 会安装 EXE 安装包、只有 MSI 的 3.4.4、镜像构建、uv-build 和 GraalPy;Server Core 容器会安装 GraalPy。 diff --git a/docs/zh-CN/uv.md b/docs/zh-CN/uv.md index 7645ce4..143e17b 100644 --- a/docs/zh-CN/uv.md +++ b/docs/zh-CN/uv.md @@ -37,7 +37,7 @@ vfox install python@3.12 索引请求遇到网络错误、HTTP 429 或 5xx 状态码,或者 200 响应里不是索引(比如强制门户的页面)时会重发,总共最多三次。重试前,如果服务器返回了 `Retry-After` 头且不超过 10 秒,就等待它指定的秒数;否则依次等待 1 秒和 2 秒。超过 10 秒的 `Retry-After` 不等待:请求立即失败,错误信息里写明服务器要求的等待时间。HTTP 日期格式的 `Retry-After` 不会被读取。其他状态码(如 404)不重试。重试后仍无法读取索引,安装会失败,并提示 `VFOX_PYTHON_USE_UV_BUILD=0`,因此不会在没有说明的情况下开始源码构建。 -如果索引在该平台上没有这个版本的包(比如索引不覆盖某个架构),安装会改为源码构建,并打印一行说明。在 Linux 上,如果无法识别 libc,安装会从源码构建;要使用 uv-build,请设置 `VFOX_PYTHON_UV_LIBC`。 +在默认模式下,如果索引在该平台上没有这个版本的包(比如索引不覆盖某个架构),安装会改为源码构建,并打印一行说明。在 Linux 上,如果无法识别 libc,默认模式同样从源码构建;要使用 uv-build,请设置 `VFOX_PYTHON_UV_LIBC`。 插件向 `https://vault.vfox.dev/python/uv-build` 询问当前平台、架构和 libc 的 构建,然后把包地址和 SHA-256 交给 vfox。vfox 下载、校验、解压,再调用 @@ -74,7 +74,7 @@ vfox install python@3.12 | `VFOX_PYTHON_UV_BUILD_MIRROR` | 让预编译包走镜像下载 | Linux 上先运行 `ldd --version`,再找 musl 的加载器,最后问 -`getconf GNU_LIBC_VERSION`;都失败时打印警告并按 `gnu` 处理。识别不对时设置 +`getconf GNU_LIBC_VERSION`。都失败时,`VFOX_PYTHON_USE_UV_BUILD=1` 打印警告并按 `gnu` 处理;默认模式则改为源码构建。识别不对时设置 上面的变量。 镜像必须是 HTTPS 地址,并按 `<镜像>//<文件名>` 镜像 GitHub 的 release