安装与起步——书里的项目和真实的项目差在哪几个文件上Copy Anchor Link

这一章讲三件事: 装 Zig(这部分是真的)、建一个 Zig 项目(这部分是假的, 而且假得可以被一条命令戳穿)、跑起来和交叉编译(半真半假)。 读完你会得到一个能当场验证的对照:书里的项目结构和 zig init 真实生成的文件, 一个一个摆在一起。

1. 这一章讲什么Copy Anchor Link

原书第二章是标准的「起步章」:2.1 装编译器,2.2 建项目,2.3 基本语法, 2.4 构建、运行、交叉编译、调试¹。安装和 Hello World 这两头是真的; 中间「项目结构」这一截,是全书第一个可以在你自己电脑上当场证伪的谎言—— 这也是我们推荐你亲手敲一次 zig init 的原因:它只需要装一个 Zig。

2. 顶层全景:一条命令看清两边Copy Anchor Link

书里的建项目流程和真实 Zig 的建项目流程,各走一遍:

  书里的流程(2.2 节)                     真实的流程(官方文档)
  ─────────────────────────────────────────────────────────
  ① zig init 建项目                       ① zig init 建项目
  ② 得到一个 zig.mod 文件                  ② 得到 build.zig + build.zig.zon
     内容是 module myproject;                 + src/main.zig + src/root.zig
  ③ src 目录放源码                        ③ src 目录放源码(同)
  ④ zig build / zig run 构建运行           ④ zig build run 构建运行(基本同)

  图说:步骤①③④两边几乎一样,差别全部集中在②——那四个文件。

验证方法(任何人都能做): 装一个 Zig,随便找个空目录敲 zig init, 终端会打印 info: created build.zig info: created build.zig.zon info: created src/main.zig info: created src/root.zig——没有 zig.mod²。

3. 核心原理之一:zig.mod 这个文件是哪来的Copy Anchor Link

书里反复把 zig.mod 说成 Zig 项目的标准描述文件:2.2 节让你手动建它, 内容是 module myproject;(还示范了往里面写 dep "std"), 第十一章、第十二章又回来用它管理依赖³。

核对结果:真实 Zig 官方从来没有这个文件。 zig.mod 是社区第三方包管理器 zigmod 的私有配置文件——它真实存在,但身份是「某个第三方工具的约定」, 不是「Zig 的项目文件」²。书把它升格成官方标准,等于把「某个 npm 第三方脚手架的配置文件」 说成「Node.js 的项目文件」。

这里顺带解释一个后面每章都会遇到的词:

标准库(标准函式库,书里写 std)指一门语言官方随编译器一起发布的那个函数与数据类型集合, 所有用这门语言的人都默认可用,通常通过 @import("std") 引入。 它之所以重要,是因为「标准库里有没有某功能」是判断一门语言官方立场最快的尺子。

真实的 Zig 包描述文件叫 build.zig.zon(一个数据文件,记项目名、版本、依赖), 构建逻辑写在 build.zig(一段 Zig 代码)里——连构建脚本都是 Zig 自己, 这正是「Zig 是工具链」而不只是「一门语言」的那一半含义²。

4. 核心原理之二:Hello World 和语法小节——真的那部分Copy Anchor Link

书里的第一个程序是这段(照原书):

const std = @import("std");

pub fn main() void {
    std.debug.print("Hello, world!\n", .{});
}

这段代码逐字是真的,和官方文档的 Hello World 一致²。 pub fn main() void 是程序入口,@import("std") 引入标准库, std.debug.print 是标准库的调试打印——这些词条是全书出现最多次的真词条, 也是这本书披着的「Zig 外衣」的主要成分。

2.3 节的语法速览也大体靠谱:大小写敏感、分号结尾、// 单行注释和 /* */ 多行注释、 类型表(u8 到 i64、f32/f64、bool、[]const u8 字符串、数组 [T; n]、切片 []T、 struct 和 enum)⁴。这些在真实 Zig 里都成立——顺手记一个判别法: 凡是不需要解释「机制」的词条表,这本书就抄得对;一进入「机制」,它就开始借别的语言。

5. 核心原理之三:zig cc 被讲反了Copy Anchor Link

书在 2.4 节给了一段「用 zig cc 编译 Zig 程序」的流程:

  书里的说法:
      zig cc src/main.zig -o main.o     ← 用 zig cc 编译 Zig 源码
      ld main.o -o main                  ← 再用链接器 ld 链接
      ./main

核对结果:方向完全反了。 zig cc 真实身份是「套着 Zig 外壳的 C 编译器」 (底层是 clang),它的用途是编译 C 代码——官方示例是 zig build-exe hello.c -lc, 而不是编译 .zig 文件²。真实 Zig 程序根本不用 zig cc, zig build-exe main.zig 一步到位;交叉编译也只是加一个 -target 参数, 不需要书里那种手工调 ld 的仪式²。

这个错误比 zig.mod 更说明问题:它不是「张冠李戴了社区工具」, 而是把官方文档里一个明确写着用途的命令,安到了相反的用途上—— 对着官方 Getting Started 抄不可能抄成这样。

同节还有两个顺手要改的:书说调试要加 -d 标志(zig build -d)⁵, 真实 Zig 调试信息默认就带(Debug 构建模式),不需要这个 flag; 书说发行优化用 -release-fast,真实参数早已是 -Doptimize=ReleaseFast(从 0.11 起)²。

6. 作者的判断与证据Copy Anchor Link

• 可以照做的部分: 从官网 ziglang.org 下载安装、zig version 验证、 zig build / zig run、交叉编译目标写成 aarch64-linux 这类三元组——这些与真实流程一致¹²。
• 不能照做的部分: zig.mod 项目文件、zig cc 编译 Zig 源码、-d 调试 flag、 -release-fast 参数——四条全部对不上真实工具链²。
• 证据形态: 这一章没有任何一句「我在某台机器上这样跑过」;所有流程都是 「应该如此」的转述。而安装章恰恰是作者最应该、也最容易放截图的章节—— 全书无一张实测截图,这本身就是证据。

7. 边界与局限Copy Anchor Link

• 书的安装说明停在「下载、跑安装器、zig version」层面,没有讲版本管理—— 而真实 Zig 项目普遍锁版本(.zigversion / 手工管理多个 binary), 2024 年还没有官方版本管理器,这是当时入门者第一个真实的坎,书只字未提。
• 书的项目结构里 test 目录、build 目录的说法是通用直觉,不是 Zig 约定; 真实 Zig 的测试写在源文件内的 test "..." 块里,zig build test 跑, 不需要独立 test 目录²。
• 交叉编译一节方向对(真能用 -target),但把「 zig build -target aarch64-linux 」 当成了完整答案;真实项目里交叉目标一般写在 build.zig 里, 通过 -Dtarget=... 传参²。

8. 可带走的Copy Anchor Link

1. 装 Zig 唯一可信的入口是 ziglang.org 的下载页;zig version 验证安装——书上这两步照做无妨。
2. 当场验证法:zig init 生成 build.zig、build.zig.zon、src/main.zig、src/root.zig——生成物里没有 zig.mod。 这一条能一次戳穿书的三章。
3. zig cc 是 C 编译器(clang 外壳),不是编译 Zig 的工具;编译 Zig 用 zig build-exe 或 zig build。
4. 书里的 Hello World 是真的,词条表(u8/i32/f64、[]const u8)也是真的——它们是这本书的「外衣」,别因为外衣合身就信里面的机制。
5. 调试不需要 -d;优化参数是 -Doptimize=ReleaseFast 这种写法。
6. 真 Zig 的测试写在被测文件里(test 块),不需要书里的 test 目录。

9. 原文地图Copy Anchor Link