ghcr.io/rust-cross/cargo-zigbuild:0.23.1

cargo-zigbuild

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

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

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

安装

cargo install --locked cargo-zigbuild

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

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

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

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

• 创建文件 /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

• 使脚本可执行：

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

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

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

提示 - 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

这使得可以在.cargo/config.toml中将target-cpu限定到特定别名，而不是应用于该目标的每次构建：

[alias]
build-prod = "zigbuild --release --target x86_64-unknown-linux-gnu --config target.x86_64-unknown-linux-gnu.rustflags=['-C','target-cpu=x86-64-v4']"

相反，如果为x86_64-unknown-linux-gnu构建的二进制文件在较旧硬件上因Illegal instruction而崩溃，请检查您的RUSTFLAGS/.cargo/config.toml是否设置了比部署目标机器更新的target-cpu。

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 正常工作。这是因为 zig 0.15+ 捆绑了 libc++ 19 头文件，需要兼容的 libclang 版本。

已知的上游 zig https://github.com/ziglang/zig/labels/zig cc：

1. https://github.com/ziglang/zig/issues/4911：`zig cc无法识别某些 Rust 目标，例如armv7-unknown-linux-gnueabihf，解决方法是在 https://github.com/rust-cross/cargo-zigbuild/pull/58 中使用 -mcpu=generic` 并显式传递目标特性
2. https://github.com/ziglang/zig/issues/1349：将 SDKROOT 环境变量设置为 macOS SDK 路径以解决此问题
3. https://github.com/ziglang/zig/issues/1290，这可能导致某些目标出现未定义符号错误。另请参见：https://github.com/ziglang/zig/blob/master/lib/compiler_rt/README.md。
4. https://github.com/ziglang/zig/issues/***

许可证

本作品以 MIT 许可证发布。许可证副本位于 LICENSE 文件中。