Knowledge/4 方案/zig 跨平台编译方案/基础知识.md at main

Cheney/Knowledge

Fork 0

Files

T

cheney 7015312702 vault backup: 2026-11-07 16:33:44

2026-11-07 16:33:55 +08:00

7.6 KiB

Raw Permalink Blame History

Zig 的“统一编译”理念和内置的跨平台支持，让它在这个领域表现出色。结合 Docker 可以保证环境的一致性和可复现性。

下面我将为你梳理需要了解的核心概念和基础知识，并提供一个完整的 Docker 化工作流。

第一部分：核心概念与 Zig 基础知识

1. Zig 的“统一编译”理念

这是 Zig 最核心的竞争力之一。它意味着：

单一编译器： 你只需要安装一个 Zig 编译器和对应的标准库源码，就可以为任何支持的目标平台进行编译。无需安装多个交叉编译工具链。
目标三元组： Zig 使用 -target 参数来指定编译目标。格式为：cpu-arch-vendor-os-abi。
- 例如：x86_64-linux-gnu, aarch64-macos-none, wasm32-freestanding。
内置标准库： Zig 编译器内置了所有目标平台的 C 标准库（如 glibc, musl, libc++ 等）的源码，并在编译时按需链接。这确保了编译结果的确定性和可复现性。

2. Zig 构建系统的核心：`build.zig`

Zig 使用一个用 Zig 语言编写的 build.zig 文件来定义构建规则，而不是 Makefile 或 CMakeLists.txt。

运行方式： zig build 命令会读取当前目录的 build.zig 文件。
核心对象：
- std.Build：构建系统的主要对象，提供了创建编译步骤的方法。
- *std.Build.Step.Compile：代表一个可执行文件、静态库或动态库的编译步骤。
- *std.Build.Step：代表一个构建步骤（如运行命令、安装文件等）。

基本结构：

// build.zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    // 标准构建选项
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 定义一个可执行文件
    const exe = b.addExecutable(.{
        .name = "my_app",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });

    // 这将创建一个 `zig build install` 步骤，将可执行文件安装到 `zig-out/bin/`
    b.installArtifact(exe);

    // 定义一个运行测试的步骤
    const exe_tests = b.addTest(.{
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });
    const run_exe_tests = b.addRunArtifact(exe_tests);

    // 创建一个 `zig build test` 步骤来运行测试
    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_exe_tests.step);
}

3. 交叉编译的关键：`std.Build.installArtifact`

在 build.zig 中，b.installArtifact(exe) 是核心。它告诉构建系统：“我想要生成这个可执行文件，并把它安装到标准输出目录（通常是 zig-out/bin/）”。

当你运行 zig build -Dtarget=<target_triple> 时，构建系统会自动处理所有交叉编译的细节，并将对应平台的可执行文件安装到 zig-out/bin/。

4. WebAssembly 的特殊性

对于 WASM，目标通常是 wasm32-freestanding。

Freestanding： 表示没有操作系统。WASM 模块运行在沙箱环境中。
导出函数： 你需要使用 export 关键字来导出希望 JavaScript 能够调用的函数。
```
// math.zig
export fn add(a: i32, b: i32) i32 {
    return a + b;
}
```

构建配置： 在 build.zig 中，你需要创建一个静态库而不是可执行文件，因为 WASM 模块本质上是库。

const wasm_lib = b.addStaticLibrary(.{
    .name = "math",
    .root_source_file = .{ .path = "src/math.zig" },
    .target = b.resolveTargetQuery(.{
        .cpu_arch = .wasm32,
        .os_tag = .freestanding,
    }),
    .optimize = optimize,
});
// 重要：设置链接模式
wasm_lib.override_libc = null; // 我们不链接 libc
wasm_lib.rdynamic = true; // 确保所有符号都被导出

b.installArtifact(wasm_lib); // 会生成 zig-out/lib/math.wasm

第二部分：Docker 环境下的工作流

使用 Docker 可以固化构建环境，确保任何人、任何机器上都能得到完全相同的编译结果。

1. 创建 Dockerfile

这个 Dockerfile 会安装 Zig 编译器并设置工作目录。

# Dockerfile
# 选择一个轻量级的基础镜像
FROM alpine:latest AS zig-builder

# 安装依赖（Alpine 使用 musl libc，非常轻量）
RUN apk add --no-cache xz tar

# 设置工作目录
WORKDIR /workspace

# 从官方地址下载并安装 Zig
# 请替换为最新的稳定版本，可从 https://ziglang.org/download/ 获取
ARG ZIG_VERSION=0.12.0
ARG ZIG_ARCH=x86_64-linux
RUN wget https://ziglang.org/builds/zig-${ZIG_ARCH}-${ZIG_VERSION}.tar.xz && \
    tar -xf zig-${ZIG_ARCH}-${ZIG_VERSION}.tar.xz && \
    rm zig-${ZIG_ARCH}-${ZIG_VERSION}.tar.xz

# 将 Zig 二进制文件路径添加到 PATH
ENV PATH="/workspace/zig-${ZIG_ARCH}-${ZIG_VERSION}:${PATH}"

# 验证安装
RUN zig version

# 设置默认命令
CMD ["/bin/sh"]

2. 创建 docker-compose.yml（推荐）

使用 Docker Compose 可以更方便地管理构建命令和卷映射。

# docker-compose.yml
version: '3.8'

services:
  zig-build:
    build: 
      context: .
      dockerfile: Dockerfile
    volumes:
      # 将宿主机的当前目录挂载到容器的 /workspace
      - .:/workspace
    working_dir: /workspace
    # 默认命令，可以覆盖
    command: zig build --help

3. 项目目录结构

my-zig-project/
├── Dockerfile
├── docker-compose.yml
├── build.zig
├── src/
│   └── main.zig
└── zig-out/ (由 zig build 自动生成)

4. 完整的构建命令示例

假设你的 build.zig 已经配置好，并且定义了名为 my_app 的可执行文件。

构建 Docker 镜像：
```
docker-compose build
```
编译 Linux x86_64 版本：
```
docker-compose run zig-build zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe
```
完成后，在宿主机的 zig-out/bin/ 目录下会找到 my_app。
编译 Windows x86_64 版本：
```
docker-compose run zig-build zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseSafe
```
完成后，在宿主机的 zig-out/bin/ 目录下会找到 my_app.exe。

编译 WebAssembly： 假设你的 build.zig 中已经定义了 wasm_lib。

# 这个命令会运行 build.zig 中定义的安装步骤，生成 .wasm 文件
docker-compose run zig-build zig build -Doptimize=ReleaseSmall
# 或者，如果你为 wasm 定义了一个特定的构建步骤（例如 b.step("wasm", "Build WASM")），你可以运行：
# docker-compose run zig-build zig build wasm

完成后，在宿主机的 zig-out/lib/ 目录下会找到 math.wasm。

总结

核心概念： 理解 Zig 的目标三元组和基于 build.zig 的构建系统。
WASM 要点： 使用 wasm32-freestanding 目标，创建静态库，并使用 export 导出函数。
Docker 化： 使用 Dockerfile 固化 Zig 编译环境，使用 Docker Compose 简化构建命令的执行。
工作流： 通过 docker-compose run zig-build zig build -Dtarget=... 来为不同平台交叉编译。

这个组合（Zig + Docker）为你提供了一个极其强大、一致且可移植的跨平台编译环境，无论是用于本地开发、CI/CD 流水线，还是为团队统一构建环境，都非常高效。

7.6 KiB Raw Permalink Blame History Unescape Escape