Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 各版本
5 changes: 4 additions & 1 deletion docs/changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
11 changes: 6 additions & 5 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/e2e.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/install-from-source.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
11 changes: 6 additions & 5 deletions docs/uv.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
`<mirror>/<release>/<filename>`. The default GitHub URL becomes
Expand Down
4 changes: 3 additions & 1 deletion docs/zh-CN/changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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

Expand Down
9 changes: 5 additions & 4 deletions docs/zh-CN/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)。

本地命令:
Expand Down Expand Up @@ -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 数据目录 |
Expand Down
2 changes: 1 addition & 1 deletion docs/zh-CN/e2e.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/zh-CN/install-from-source.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion docs/zh-CN/platforms.md
Original file line number Diff line number Diff line change
Expand Up @@ -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。

Expand Down
4 changes: 2 additions & 2 deletions docs/zh-CN/uv.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 下载、校验、解压,再调用
Expand Down Expand Up @@ -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 地址,并按 `<镜像>/<release>/<文件名>` 镜像 GitHub 的 release
Expand Down
Loading