messense/cargo-zigbuild

cargo-zigbuild

https://github.com/rust-cross/cargo-zigbuild/workflows/CI/badge.svg](https://github.com/rust-cross/cargo-zigbuild/actions?query=workflow%3ACI) ![Crates.io]([] ![docs.rs]([] ![PyPI]([***]

🚀 支持我成为全职开源开发者：https://github.com/***/messense

使用https://github.com/ziglang/zig%E4%BD%9C%E4%B8%BA%E9%93%BE%E6%8E%A5%E5%99%A8%E7%BC%96%E8%AF%91Cargo%E9%A1%B9%E7%9B%AE%EF%BC%8C%E5%AE%9E%E7%8E%B0%E6%9B%B4%E7%AE%80%E5%8D%95%E7%9A%84%E4%BA%A4%E5%8F%89%E7%BC%96%E8%AF%91%E3%80%82

安装

bash
cargo install --locked cargo-zigbuild

也可通过pip安装，会自动安装ziglang：

bash
pip install cargo-zigbuild

我们还提供Docker镜像，除cargo-zigbuild和Rust外，预安装了macOS SDK。例如，构建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

bash
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版本

默认情况下，*-gnu的--target会让Zig隐式构建基于Zig版本的默认glibc版本（https://github.com/ziglang/zig/blob/0.14.1/lib/std/Target.zig#L473%EF%BC%89%E3%80%82

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

bash
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的主机上运行时应报错却未报错
  • 而指定2.33在glibc 2.31主机上会正确检测为不兼容
• 某些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失败（需额外配置）的常见情况：

console
# 无法找到构建所需的头文件：
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的错误：

rust
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
      |         ^
<command line>: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:**

   bash
   #!/bin/bash
   
   FILE_NAME=$1
   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. 使脚本可执行：

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

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

   console
   $ 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二进制文件/库。

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

注意

目前Cargo的--message-format选项在universal2目标上不工作。

注意事项

1. 目前仅支持Linux和macOS目标，其他目标平台若可正常工作可添加，欢迎提交PR
2. CI仅定期测试当前Ruststable和nightly版本，其他版本可能不工作

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

1. https://github.com/ziglang/zig/issues/4911%EF%BC%9A 某些Rust目标不被zig cc识别（如armv7-unknown-linux-gnueabihf），在https://github.com/rust-cross/cargo-zigbuild/pull/58%E4%B8%AD%E9%80%9A%E8%BF%87%E4%BD%BF%E7%94%A8%60-mcpu=generic%60%E5%92%8C%E6%98%BE%E5%BC%8F%E4%BC%A0%E9%80%92%E7%9B%AE%E6%A0%87%E5%8A%9F%E8%83%BD%E4%BD%9C%E4%B8%BA workaround
2. https://github.com/ziglang/zig/issues/1349%EF%BC%9A 设置SDKROOT环境变量为macOS SDK路径作为 workaround
3. https://github.com/ziglang/zig/issues/1290%EF%BC%8C%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%A7%81%EF%BC%9Ahttps://github.com/ziglang/zig/blob/master/lib/compiler_rt/README.md
4. https://github.com/ziglang/zig/issues/***

许可证

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