196 lines
7.6 KiB
Markdown
196 lines
7.6 KiB
Markdown
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`：代表一个构建步骤（如运行命令、安装文件等）。
|
||
* **基本结构：**
|
||
```zig
|
||
// 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 能够调用的函数。
|
||
```zig
|
||
// math.zig
|
||
export fn add(a: i32, b: i32) i32 {
|
||
return a + b;
|
||
}
|
||
```
|
||
* **构建配置：** 在 `build.zig` 中，你需要创建一个**静态库**而不是可执行文件，因为 WASM 模块本质上是库。
|
||
```zig
|
||
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
|
||
# 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 可以更方便地管理构建命令和卷映射。
|
||
|
||
```yaml
|
||
# 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` 的可执行文件。
|
||
|
||
1. **构建 Docker 镜像：**
|
||
```bash
|
||
docker-compose build
|
||
```
|
||
|
||
2. **编译 Linux x86_64 版本：**
|
||
```bash
|
||
docker-compose run zig-build zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe
|
||
```
|
||
完成后，在宿主机的 `zig-out/bin/` 目录下会找到 `my_app`。
|
||
|
||
3. **编译 Windows x86_64 版本：**
|
||
```bash
|
||
docker-compose run zig-build zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseSafe
|
||
```
|
||
完成后，在宿主机的 `zig-out/bin/` 目录下会找到 `my_app.exe`。
|
||
|
||
4. **编译 WebAssembly：**
|
||
假设你的 `build.zig` 中已经定义了 `wasm_lib`。
|
||
```bash
|
||
# 这个命令会运行 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`。
|
||
|
||
### 总结
|
||
|
||
1. **核心概念：** 理解 Zig 的**目标三元组**和基于 `build.zig` 的**构建系统**。
|
||
2. **WASM 要点：** 使用 `wasm32-freestanding` 目标，创建**静态库**，并使用 `export` 导出函数。
|
||
3. **Docker 化：** 使用 Dockerfile 固化 Zig 编译环境，使用 Docker Compose 简化构建命令的执行。
|
||
4. **工作流：** 通过 `docker-compose run zig-build zig build -Dtarget=...` 来为不同平台交叉编译。
|
||
|
||
这个组合（Zig + Docker）为你提供了一个极其强大、一致且可移植的跨平台编译环境，无论是用于本地开发、CI/CD 流水线，还是为团队统一构建环境，都非常高效。 |