cargo-zigbuild

🚀 通过在 GitHub 上赞助我，帮助我成为全职开源开发者

🚀 通过在 GitHub 上赞助我，帮助我成为全职开源开发者

使用 zig 作为链接器编译 Cargo 项目，以简化交叉编译过程。

安装

cargo install --locked cargo-zigbuild

你也可以使用 pip 安装，它会自动安装 ziglang：

pip install cargo-zigbuild

我们还提供预安装了 macOS SDK 的 Docker 镜像，此外还包含 cargo-zigbuild 和 Rust，例如构建 x86_64 macOS 目标：

• Linux Docker 镜像（ghcr.io、Docker Hub）：

docker run --rm -it -v $(pwd):/io -w /io ghcr.io/rust-cross/cargo-zigbuild \
cargo zigbuild --release --target x86_64-apple-darwin

使用

• 按照官方文档安装 zig，在 macOS、Windows 和 Linux 上，你也可以通过 pip3 从 PyPI 安装 zig：

pip3 install ziglang

• 通过 rustup 安装 Rust 目标，例如：

rustup target add aarch64-unknown-linux-gnu

• 运行 cargo zigbuild，例如：

cargo zigbuild --target aarch64-unknown-linux-gnu

环境变量

指定 glibc 版本

默认情况下，--target 为 *-gnu 时，Zig 会隐式构建基于 Zig 版本的默认 glibc 版本（v12 到 v14 版本默认使用 glibc 2.28）。

要为特定的最低 glibc 版本构建，可在 --target 值后添加版本后缀。例如，要使用 --target aarch64-unknown-linux-gnu 为 glibc 2.17 编译：

cargo zigbuild --target aarch64-unknown-linux-gnu.2.17

glibc 版本目标功能存在以下注意事项：

• 如果未提供 --target，将不使用 Zig，命令实际上会运行常规的 cargo build。
• 如果指定了无效的 glibc 版本，cargo zigbuild 不会转发 zig cc 发出的关于所选回退版本的警告。
• 此功能不一定与在构建主机上动态链接到特定版本 glibc 的行为一致。可以指定版本 2.32，但在仅提供 2.31 的主机上仍能运行，而此时本应报错终止。同时，在 glibc 2.31 的主机上指定 2.33 会正确检测为不兼容。
• 可以指定版本 2.32，但在仅提供 2.31 的主机上仍能运行，而此时本应报错终止。
• 同时，在 glibc 2.31 的主机上指定 2.33 会正确检测为不兼容。
• 某些 RUSTFLAGS（如 -C linker）会选择不使用 Zig，而 -L path/to/files 会导致 Zig 忽略 -C target-feature=+crt-static。
• -C target-feature=+crt-static 不支持静态链接到特定 glibc 版本（上游 zig cc 缺乏支持）

提示 - cargo zigbuild 找不到已存在的头文件（*.h 文件）或库

你可能需要在 cargo zigbuild 命令前添加以下环境变量，指定系统路径或类似路径：

• CFLAGS='-isystem /usr/include'
• RUSTFLAGS='-L /usr/lib64'

cargo zigbuild 始终使用 zig cc 的 -nostdinc 选项，该选项会排除标准头文件位置（如 /usr/include）。当 Zig 配置了 --target 时，这也是其默认行为，此外还会选择不使用标准系统搜索路径。

这可能导致一种常见情况：cargo build 成功，而 cargo zigbuild 未经过额外配置则失败：

# 无法找到构建所需的头文件：
fatal error: 'libelf.h' file not found

# 无法找到要链接的共享库：
error: unable to find dynamic system library 'elf' using strategy 'no_fallback'. searched paths

有多种解决方法，但对于 /usr/include 等系统路径，必须注意避免将系统 glibc 头文件与 Zig 自身提供的 glibc 头文件混合，否则会产生类似 CPATH=/usr/include 导致的错误：

In file included from /usr/local/lib64/python3.13/site-packages/ziglang/lib/libunwind/src/gcc_personality_v0.c:21:
In file included from /usr/local/lib64/python3.13/site-packages/ziglang/lib/libunwind/include/unwind.h:18:
In file included from /usr/include/stdint.h:26:
In file included from /usr/include/bits/libc-header-start.h:33:
/usr/include/features.h:516:9: warning: '__GLIBC_MINOR__' macro redefined [-Wmacro-redefined]
516 | #define __GLIBC_MINOR__ 41
| ^
:2:9: note: previous definition is here
2 | #define __GLIBC_MINOR__ 37
|

当你安装的系统包已将项目构建所需的头文件添加到 /usr/include 时，你会希望 Zig 仅对这些头文件回退到 /usr/include，同时使用自身的 glibc 头文件。这可以通过 zig cc -isystem /usr/include 实现，对于 cargo zigbuild，可通过环境变量 CFLAGS='-isystem /usr/include' 进行配置。

对于共享库的类似问题，如果你的包将系统库安装在 /usr/lib64，通常会使用 LDFLAGS='-L /usr/lib64'，但 rustc 和 cargo 不读取此环境变量，而是必须通过带有 build.rs 的 crate 配置搜索路径，以查找要动态/静态链接的库。因此，你需要使用 RUSTFLAGS='-L /usr/lib64'。

cargo-zigbuild

🚀 请通过 https://github.com/***/messense 帮助我成为全职开源开发者

使用 https://github.com/ziglang/zig 作为 链接器 编译 Cargo 项目，实现 更简单的交叉编译。

安装

cargo install --locked cargo-zigbuild

你也可以使用 pip 安装，它会自动安装 ziglang：

pip install cargo-zigbuild

我们还提供预安装了 macOS SDK 以及 cargo-zigbuild 和 Rust 的 Docker 镜像，例如构建 x86_64 macOS 目标：

• Linux Docker 镜像（https://github.com/rust-cross/cargo-zigbuild/pkgs/container/cargo-zigbuild%E3%80%81https://hub.docker.com/r/messense/cargo-zigbuild%EF%BC%89%EF%BC%9A

docker run --rm -it -v $(pwd):/io -w /io ghcr.io/rust-cross/cargo-zigbuild \
cargo zigbuild --release --target x86_64-apple-darwin

使用方法

1. 按照 官方文档 安装 zig，在 macOS、Windows 和 Linux 上，你也可以通过 pip3 install ziglang 从 PyPI 安装 zig
2. 通过 rustup 安装 Rust 目标，例如 rustup target add aarch64-unknown-linux-gnu
3. 运行 cargo zigbuild，例如 cargo zigbuild --target aarch64-unknown-linux-gnu

环境变量

指定 glibc 版本

默认情况下，--target 对于 *-gnu 目标会让 Zig 隐式构建针对特定 glibc 版本，该版本因 Zig 版本而异（https://github.com/ziglang/zig/blob/0.14.1/lib/std/Target.zig#L473%EF%BC%89%E3%80%82

要针对特定的最低 glibc 版本构建，请在 --target 值后添加该版本作为后缀。例如，要使用 --target aarch64-unknown-linux-gnu 为 glibc 2.17 编译：

cargo zigbuild --target aarch64-unknown-linux-gnu.2.17

[!NOTE] glibc 版本目标功能存在https://github.com/rust-cross/cargo-zigbuild/issues/231#issuecomment-***%EF%BC%9A

• 如果未提供 --target，则不会使用 Zig，该命令实际上会运行常规的 cargo build。
• 如果指定了无效的 glibc 版本，cargo zigbuild 不会转发 zig cc 发出的关于所选回退版本的警告。
• 此功能不一定与在构建主机上动态链接到特定版本 glibc 的行为一致。
• 可以指定版本 2.32，但在仅提供 2.31 的主机上运行时本应中止并报错，却能正常运行。
• 同时，在 glibc 2.31 的主机上指定 2.33 会被正确检测为不兼容。
• 某些 RUSTFLAGS（如 -C linker）会退出使用 Zig，而 -L path/to/files 会导致 Zig 忽略 -C target-feature=+crt-static。
• -C target-feature=+crt-static 用于静态链接到特定 glibc 版本不受支持（上游 zig cc 缺乏支持）

提示 - cargo zigbuild 无法找到已存在的头文件（*.h 文件）或库

你可能需要在 cargo zigbuild 命令前添加以下环境变量（或类似系统路径）：

• CFLAGS='-isystem /usr/include'
• RUSTFLAGS='-L /usr/lib64'

---

cargo zigbuild 始终使用 zig cc 的 -nostdinc 选项，该选项会排除 /usr/include 等标准头文件位置。这也是 Zig 在配置了 --target 时的默认行为，此外还会退出标准系统搜索路径。

这可能导致一种常见情况：cargo build 成功，而 cargo zigbuild 因缺少额外配置而失败：

# 无法找到构建所需的头文件：
fatal error: 'libelf.h' file not found

# 无法找到要链接的共享库：
error: unable to find dynamic system library 'elf' using strategy 'no_fallback'. searched paths

有多种解决方法，但对于 /usr/include 等系统路径，必须注意避免将系统 glibc 头文件与 Zig 自身提供的 glibc 头文件混合，否则会产生类似 CPATH=/usr/include 导致的错误：

In file included from /usr/local/lib64/python3.13/site-packages/ziglang/lib/libunwind/src/gcc_personality_v0.c:21:
In file included from /usr/local/lib64/python3.13/site-packages/ziglang/lib/libunwind/include/unwind.h:18:
In file included from /usr/include/stdint.h:26:
In file included from /usr/include/bits/libc-header-start.h:33:
/usr/include/features.h:516:9: warning: '__GLIBC_MINOR__' macro redefined [-Wmacro-redefined]
516 | #define __GLIBC_MINOR__ 41
| ^
:2:9: note: previous definition is here
2 | #define __GLIBC_MINOR__ 37
|

当你安装的系统包已将项目构建所需的头文件添加到 /usr/include 时，你需要让 Zig 仅对这些头文件回退到 /usr/include，同时使用自身的 glibc 头文件。这可以通过 zig cc -isystem /usr/include 实现，对于 cargo zigbuild，可通过通用环境变量 CFLAGS='-isystem /usr/include' 进行配置。

对于共享库的类似问题，如果你的包将系统库安装在 /usr/lib64，通常会使用 LDFLAGS='-L /usr/lib64'，但 rustc 和 cargo 不读取此环境变量，而是必须通过 build.rs 配置 crate 的搜索路径以查找要动态/静态链接的库。因此，你需要使用 RUSTFLAGS='-L /usr/lib64'。

提示 - 验证所需的最低 GLIBC 版本

如果你的构建二进制文件未剥离符号，在 Linux 上可运行以下脚本扫描 glibc 版本化符号并找出最高版本（即运行所需的最低版本）

1. 创建文件 /usr/local/bin/get-min-glibc:

#!/bin/bash

FILE_NAME=$1
LANG=C readelf -W --version-info --dyn-syms ${FILE_NAME} \
| grep 'Name: GLIBC' \
| sed -re 's/.*GLIBC_(.+) Flags.*/\1/g' \
| sort -t . -k1,1n -k2,2n \
| tail -n 1

2. 使脚本可执行：

chmod +x /usr/local/bin/get-min-glibc

3. 使用可执行文件/库的路径运行命令进行检查：

$ get-min-glibc target/x86_64-unknown-linux-gnu/release/hello-world
2.28

macOS universal2 目标

cargo zigbuild 支持特殊的 universal2-apple-darwin 目标，用于在 Rust 1.64.0 及更高版本上构建 macOS universal2 二进制文件/库。

rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin
cargo zigbuild --target universal2-apple-darwin

[!NOTE] 注意，Cargo 的 --message-format 选项目前不适用于 universal2 目标。

注意事项

1. 目前仅支持 Linux 和 macOS 目标，其他目标平台可在实现支持后添加，欢迎提交拉取请求。
2. CI 仅定期测试当前 Rust stable 和 nightly 版本，其他版本可能无法正常工作。
3. 当使用 zig 0.15+ 与使用 https://github.com/rust-lang/rust-bindgen 的 crate 时，可能需要安装 clang 18+ 才能使 bindgen 正常工作。这是因为 zig0.15+ 捆绑了 libc++ 19 头文件，需要兼容的 libclang 版本。

已知的上游 zig https://github.com/ziglang/zig/labels/zig%20cc%EF%BC%9A

1. https://github.com/ziglang/zig/issues/4911%EF%BC%9A%E6%9F%90%E4%BA%9B Rust 目标不被 zig cc 识别（例如 armv7-unknown-linux-gnueabihf），解决方法是在 https://github.com/rust-cross/cargo-zigbuild/pull/58 中使用 -mcpu=generic 并显式传递目标特性。
2. https://github.com/ziglang/zig/issues/1349%EF%BC%9A%E8%AE%BE%E7%BD%AE SDKROOT 环境变量为 macOS SDK 路径可解决此问题。
3. https://github.com/ziglang/zig/issues/1290%EF%BC%9A%E5%8F%AF%E8%83%BD%E5%AF%BC%E8%87%B4%E6%9F%90%E4%BA%9B%E7%9B%AE%E6%A0%87%E5%87%BA%E7%8E%B0%E6%9C%AA%E5%AE%9A%E4%B9%89%E7%AC%A6%E5%8F%B7%E9%94%99%E8%AF%AF%E3%80%82%E5%8F%A6%E8%AF%B7%E5%8F%82%E8%A7%81%EF%BC%9Ahttps://github.com/ziglang/zig/blob/master/lib/compiler_rt/README.md%E3%80%82
4. https://github.com/ziglang/zig/issues/***

许可证

本作品以 MIT 许可证发布。许可证副本见 LICENSE 文件。