# anyzig

**Repository Path**: Yoshiera/anyzig

## Basic Information

- **Project Name**: anyzig
- **Description**: anyzig fork: compiler tarballs from community mirrors with enforced sha256, install/remove/default subcommands, exact .zig-version pin
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[English](README.md) | **简体中文**

# anyzig

一个通用的 `zig` 可执行文件：`PATH` 上只留一个 `zig`，它运行你所在项目要求的那个 zig 版本。

## 太长不看版

**这是 [marler8997/anyzig](https://github.com/marler8997/anyzig)（MIT）的 fork**，维护在
<https://gitee.com/Yoshiera/anyzig>。

编译器从 ziglang.org 推荐的社区镜像取回，避免给 ziglang.org 造成拥堵，并安装在
`~/.local/share/anyzig/toolchains/` 下。

在上游的版本解析之外，本 fork 增强了工具链管理：取回并缓存某个版本（不运行它）、删除某个版本、
设置默认版本、把版本固定到项目、为某个目录在本机覆盖版本。每个子命令都有 `--help` 说明。

## 安装

```sh
curl -fsSL https://gitee.com/Yoshiera/anyzig/raw/master/install.sh | sh
zig any version          # → vYYYY_MM_DD
```

不需要源码树，不需要 sudo，也不需要先有编译器。脚本挑出你 OS 与架构对应的归档，从最新
[release](https://gitee.com/Yoshiera/anyzig/releases) 取回，用该 release 的 `SHA256SUMS` 校验，
然后把 shim 放进 `~/.local/bin`。若已经装过 anyzig，它会报出版本并问你要不要升级；目标位置上不是
anyzig 的 `zig` 不会被覆盖。

| 选项 | |
|---|---|
| `--version TAG` | 装指定的 release tag，而不是最新的 |
| `--dir DIR` | 装进 `DIR`（默认 `~/.local/bin`，或已有 anyzig 所在的目录） |
| `--target OS-ARCH` | 取别的平台的归档，例如 `aarch64-linux` |
| `--force` | 已经是最新也重装；并允许替换 `DIR/zig` 上不是 anyzig 的文件 |
| `--yes` | 不提问，升级或降级都接受 |
| `--check` | 只报告已装版本与最新版本，不安装（exit 0 = 已是最新） |

也可以手工来：从 release 里取 `anyzig-<arch-os>.tar.gz`（Windows 是 `.zip`），解开就是一个静态的
`zig`。

## 使用

```sh
zig build                  # 用这个目录解析出来的版本
zig 0.15.2 version         # 显式指定版本，第一次用到时自动取回
zig any help               # anyzig 自己处理的全部子命令
zig any install 0.16.0     # 只取回并缓存，不运行
```

任何 zig 版本都可以来自依赖声明、`.zig-version` 或命令行参数 —— 缺哪个版本，anyzig 就取哪个，
然后运行它。从镜像下载通常几秒。

## 命令

| 命令 | |
|---|---|
| `zig any install VERSION` | 下载、校验并缓存一个精确版本，不运行它 |
| `zig any remove VERSION` | 从 store 与 hashstore 里删掉它 |
| `zig any default [VERSION\|unset]` | 显示、设置或清除兜底版本 |
| `zig any pin [VERSION\|unset]` | 显示、写入或删除 `./.zig-version` |
| `zig any override [VERSION\|unset\|list]` | 同上，但**只在本机**，存在项目树之外 |
| `zig any list-installed` | 列出你已有的编译器，每行 `VERSION<TAB>PATH` |
| `zig any set-verbosity warn\|debug` | anyzig 自己打多少日志 |
| `zig any version` | anyzig 自身的版本，如 `v2026_09_15` |
| `zig any help [SUBCOMMAND]` | 全量列表，或单个子命令的说明页；`-h` / `--help` 等价 |

`install`、`remove`、`default`、`pin`、`override`、`help` 是本 fork 新增的。

## 用哪个版本

要指定版本有几种方式，从最具体到最宽泛：

| | 含义 | 随仓库走？ |
|---|---|---|
| `zig 0.15.2 …` | 就这一次 | — |
| `.zig-version`（`zig any pin`） | **就要这个版本**，所有 checkout 这个仓库的人都一致 | 是，可提交 |
| `zig any override VERSION` | 同上，但只影响本机 —— 给不想改动的仓库、或压根不是项目的目录用 | 否 |
| `build.zig.zon` 里的 `minimum_zig_version` | 项目声明的下界：「至少这么新」 | 是 |
| `zig any default VERSION` | 上面都不适用时的兜底 | 否 |

解析优先级，从高到低 —— anyzig 会打日志说明用了哪一个：

1. 命令之前的 `VERSION` 参数，例如 `zig 0.15.2 build`（没装就先去取）
2. `.zig-version` pin 或目录级 override —— 从当前目录**向上查找**，**最近的赢**。比如放在 home
   目录里的 pin，对其下所有项目都生效。同一个目录里，override 压过 pin。
3. 最近的 `build.zig.zon` 里的 `minimum_zig_version`
4. `$ANYZIG_DEFAULT_VERSION`，否则就是 `zig any default` 的值

下界就是下界：声明 `minimum_zig_version = "0.14.0"` 的项目仍然用 0.14.0 构建；需要处处锁定同一个
版本时，给它一个 `.zig-version`（或 override）。

override 只在本机存在，所以用到时 anyzig 会说明：
`override '0.15.2' applies to '/path'`。

## 下载与校验

- 编译器来自 ziglang.org 官方推荐的社区镜像，每轮打乱顺序尝试；太慢的会被放弃、换下一个，
  ziglang.org 只作最后兜底。
- 每次下载都与 ziglang.org 自己 index 里的 sha256 比对；**没有公布哈希的版本不走镜像**，改从
  ziglang.org 经 TLS 取。
- minisign 签名同样会校验。它目前在 ziglang.org 自己公布的签名上**过不去** —— 这是已知的上游问题
  （ziglang.org#546），会给出警告而不是静默忽略；`ANYZIG_REQUIRE_SIGNATURE=1` 下则直接拒绝安装。

细节与证据：[`docs/VERIFICATION.md`](docs/VERIFICATION.md)。

## 编译器放在哪

`~/.local/share/anyzig/toolchains/p/<hash>/zig`，每个约 380 MB。zig 自己的包缓存（`~/.cache/zig/`）
不动 —— 那里放的是你的依赖包，不是编译器。

`zig any list-installed` 看已有哪些；`zig any remove VERSION` 删掉一个。

从上游 anyzig 或本 fork 的早期版本切过来时，已经解开在 `~/.cache/zig/p/` 下的编译器不会自动搬：

```sh
mv ~/.cache/zig/p/<hash> ~/.local/share/anyzig/toolchains/p/
```

## 环境变量

| 变量 | |
|---|---|
| `ANYZIG_DEFAULT_VERSION` | 默认版本，优先于 `default` 文件 |
| `ANYZIG_TOOLCHAIN_DIR` | 编译器安装目录（默认 `~/.local/share/anyzig/toolchains`） |
| `ANYZIG_OVERRIDES_FILE` | override 表的位置 |
| `ANYZIG_NO_MIRRORS=1` | 不走镜像，直接从 ziglang.org 取（会非常慢） |
| `ANYZIG_REQUIRE_SIGNATURE=1` | 签名校验不过就拒绝安装 |
| `ZIG_GLOBAL_CACHE_DIR` | zig 自己的包缓存 —— 依赖包，不是编译器 |

## 文档

- [`docs/TOOLCHAIN.md`](docs/TOOLCHAIN.md) —— 命令、解析顺序、磁盘布局
- [`docs/VERIFICATION.md`](docs/VERIFICATION.md) —— 下载是怎么校验的
- [`docs/BUILDING.md`](docs/BUILDING.md) —— 构建本 fork，以及发布 release
- [`docs/PITFALLS.md`](docs/PITFALLS.md) —— 已知的坑，附复现
- [`CHANGELOG.md`](CHANGELOG.md) —— 改了什么、什么时候

还没做：自更新、`override --path`，以及 `any` 系列子命令里的 `master`。

## 上游

anyzig 是一个通用的 zig 可执行文件；本 fork 没有改动的部分都照旧适用 —— 上游 README 见
[marler8997/anyzig](https://github.com/marler8997/anyzig)。

zig 版本也可以直接作为第一个参数给出；mach 的 "nominated versions"（`2024.10.0-mach`）走 mach
自己的 index 解析，`build.zig.zon` 里的 `.mach_zig_version` 优先于 `minimum_zig_version`。

## 许可

MIT，与上游相同。见 [LICENSE](LICENSE)。