跳转至

标准库与生态——模块名半真半假,包管理把社区工具当官方

这一章讲两件事: 原书第十一章列标准库「常用模块」,第十二章介绍第三方库和包管理。 这是全书最有迷惑性的两章——模块名、函数名、安装命令,真假混排在同一段里, 没有任何排版能区分它们。我们的拆解把两章的词条逐个过筛: 筛完你会有一张「可带走的 std 地图」和一份「查无此库」的名单。

1. 这一章讲什么

  原书内容                    真假分布
  ──────────────────────────────────────────────────
  std 模块总览(math/mem/strings/os/io/fmt/time/rand/testing)  7 个名字里 6 真 1 假(strings)
  常用模块示例(sqrt、mem.copy、strings.len、os.open、io.getStdOut)  调用形状一半真一半编
  自定义模块与库              概念真,zig.mod 假(第 02 章旧账)
  包管理器(zigmod / Zig Packages / ZPM)  zigmod 真,后两个存疑;身份全被说错
  第三方库名单(zig-net、zig-sqlite、zig-http 等 8 个)  整页虚构
  外部库集成(std.c.link / std.c.include)  编造的 API;真实是 @cImport 或 build.zig

  图说:两章合计约 1.2 万字符,「真的那半」恰好都是不需要动脑的词条,
  「假的那半」恰好都是需要查证才能写出的东西。

2. 顶层全景:一张过筛的 std 地图

把书 11.1 节列的九个模块逐个核对,得到这张可以放心使用的地图:

书里的模块名 存在吗 干什么(真实口径)
std.math 真 数学函数:sqrt、sin、pi 都在1
std.mem 真 内存与切片操作:复制、填充、比较、查找1
std.strings 假 不存在;字符串操作分散在 std.mem(长度/比较/查找)和 std.fmt(格式化)里
std.os 真 操作系统底层接口(偏原始);日常文件操作更常用 std.fs
std.io 真(在变迁中) 输入输出抽象;2025 年后经历大改(Writergate),API 形态随版本剧烈变化
std.fmt 真 格式化打印与解析(allocPrint、parseInt)
std.time 真 时间与计时
std.rand 真 随机数
std.testing 真 测试工具(expect、test allocator 抓泄漏)

九中八真——这一节的词条层可信度,创下了全书纪录。 为什么这里突然变准? 因为这些模块名在 Zig 教程、博客、官方文档里出现频率最高, 属于「抄也抄得到」的表层素材;而后文的函数签名和第三方库,属于「要真用过才知道」 的深层素材,书一碰就穿。这个深浅分界,比任何单条核对都更能说明这本书的成色。

顺带两个函数级的修正:书说 std.math.sqrt(4.0)——真,可以跑; 书说 std.mem.copy(dest, src) 直接吃两个切片——真实签名要带类型和方向 (std.mem.copyForwards(u8, dest, src)),少一个参数都编不过; 书说 std.strings.len(str)——模块本身不存在1。

3. 核心原理之一:11.3 节的「自定义库」——又回到 zig.mod

11.3 节教建自定义库:目录里放 zig.mod,内容写 module mylibrary;, zig build 之后「在 zig-out/lib 目录得到一个编译好的库文件」2。

第 02 章的病在这里复发并加重:

  • zig.mod 仍然不是官方文件(真实清单是 build.zig.zon,构建脚本是 build.zig)3;
  • 「zig build 产出 zig-out/lib 里的编译产物」半真:zig-out 是真实的默认输出目录 (这个词条对),但库项目要安装到 lib 目录,需要在 build.zig 里写 install 步骤, 书把「目录约定」和「构建脚本要写什么」混成了一句话;
  • 分享库一节说「发布到 Zigmod 和 Zig Packages 的 registry」—— zigmod 真实存在(第三方),「Zig Packages Registry」查无此物2。

4. 核心原理之二:包管理——身份错认三连

12.1 节列了三个包管理器:Zigmod、Zig Packages、ZPM, 并给了 zigmod 的安装命令(curl -fsSL https://zigmod.io/install.sh | sh) 和用法(zigmod install)4。对账:

  书说的                真相
  ────────────────────────────────────────────────────
  zigmod               真实存在的第三方包管理器(2019–2022 年间流行,
                       2020 年代中期随着官方包管理推进已基本沉寂)
  Zig Packages          查无此工具;可能是把别的名字记岔了
  ZPM                  查无此工具
  「Zig 没有内置包管理器」   书出版时(2024-10)官方包管理刚落地(build.zig.zon
                       依赖 + zig fetch),书这句话半过时

  图说:一节里一真二假,而真的那个(zigmod)已经被时代抛下——
  照着书装 zigmod,你装的是一条死路。

这里要讲清真实的时间线,因为初学者最容易在这里被书害到: Zig 官方的包管理功能以 build.zig.zon(项目清单:名字、版本、依赖列表) + zig fetch(拉依赖)+ 构建脚本消费 的形态,在 0.11–0.14 年间逐步落地3。 到 2024 年书出版时,官方机制已经可用,只是文档稀缺、生态未成; 书却把「无内置包管理」当现状、把 zigmod 当答案——等于在官方过河之后, 教读者去修一座已经没人维护的浮桥。

12.3 节的外部库集成也是编造:书教 std.c.link("mylibrary") 和 std.c.include("mylibrary.h")5。真实 Zig 的两条路: ① 源码级直接用 @cImport(@cInclude("mylibrary.h"))—— 让 Zig 当场读懂 C 头文件,连手写绑定都省掉(官方演示用它直接调 libsoundio 发声)3;② 编译链接级在 build.zig 里声明 exe.linkSystemLibrary("mylibrary")。没有 std.c.link 这种运行期 API。

5. 核心原理之三:第三方库名单——一页虚构

12.2 节列了八个「流行的第三方库」:zig-net、zig-sqlite、zig-http、 zig-tls、zig-json、zig-xml、zig-opengl、zig-raylib, 并给了一段 zig-net 建 TCP 服务器的完整代码6。

八个名字在 Zig 生态里全部查无对应实体。 真实生态的命名习惯其实不一样: 知名项目多用独立名字(zap、mach、Bun、TigerBeetle、ghostty), 或带 .zig 后缀的描述性名字(websocket.zig、known-folders); 而书的八个名字是同一个模板「zig- + 通用功能词」—— 像从「库名生成器」里按行抽出来的。这段 TCP 服务器代码自然也是 对着不存在的 API 写的(zig_net.tcp.listen("127.0.0.1:8080"))。

这一页是判定这本书出处的关键物证之一: 说它写错 API,还能辩解是笔误; 凭空生成八个库的完整名单加示例代码,只有一种解释—— 文本的生成过程里没有一个真实的包注册表可查。

6. 作者的判断与证据

  • 经核对可用: std 模块地图(去掉 strings)、sqrt 调用、zigmod 的存在、 zig-out 目录约定、选库的四条标准(功能/兼容/维护/社区)14。
  • 经核对不可用: std.strings、std.mem.copy 签名、std.c.link/include、 八个第三方库、zig build -deps 的复用(第 05 章已拆)、「Zig Packages / ZPM」56。
  • 证据形态: 这一章的「真」集中在名词表,「假」集中在动词(调用、命令、流程)—— 名词可以从任何二手材料抄到,动词必须经过实践。

7. 边界与局限

  • 书对 std 的描述停在「函数列表」层面,完全没讲真实 Zig 用 std 的姿势: 分配器参数怎么穿过 std 的容器(ArrayList 要传 allocator)、 错误联合怎么从 std 函数里冒出来(try 满天飞的样子)—— 这才是日常写 Zig 的真实体验。
  • std.io 一节书教的 std.io.getStdOut() 是 0.10 时代的旧 API; 2025 年的 Writergate 大改之后面目全非——书出版时这样写已过时, 今天照抄直接报错。这提醒我们:std 的真实 API 面在 0.x 阶段以「年」为单位翻新, 任何静态教材(包括真教材)都会过时,官方文档是唯一稳的锚。
  • 生态一章对真实 Zig 的招牌项目(Bun、TigerBeetle、mach、zap 等) 只字未提——这本书出版时它们已经是 Zig 生态最大的广告牌, 书里一个真实名字都没有,本身就是「没看过生态」的证据。

8. 可带走的

  1. std 地图可用:math/mem/os/io/fmt/time/rand/testing 八个模块名是真的;strings 不存在。
  2. std.math.sqrt(4.0) 真;std.mem.copy(dest, src) 签名假(真实是 copyForwards 带类型参数)。
  3. 官方包管理是 build.zig.zon + zig fetch,不是 zig.mod;zigmod 是已沉寂的第三方旧工具。
  4. 「Zig Packages」「ZPM」查无此物;八个 zig-* 第三方库名单整页虚构。
  5. 集成 C 库的真实姿势:@cImport(@cInclude("xxx.h")) 直接读头文件,或 build.zig 里 linkSystemLibrary。
  6. 真实生态的知名项目:Bun(JS 运行时)、TigerBeetle(数据库)、mach(游戏工具链)、zap(Web 框架)——书一个没提。
  7. 选库四标准(功能/兼容/维护/社区)通用可信,这一页的判断句是全章最耐用的部分。

9. 原文地图

主题 原书章 原文位置
std 模块总览九模块 Chapter 11: The Zig Standard Library text/13-ch11-chapter-11-the-zig-standard-library.txt:9(搜「Key Modules in the Standard Library」) · text/13-ch11-chapter-11-the-zig-standard-library.txt:43(搜「std.math.sqrt」)
mem/strings/os/io 示例 Chapter 11: The Zig Standard Library text/13-ch11-chapter-11-the-zig-standard-library.txt:57(搜「std.mem.copy」) · text/13-ch11-chapter-11-the-zig-standard-library.txt:97(搜「std.strings.len」) · text/13-ch11-chapter-11-the-zig-standard-library.txt:115(搜「std.os.open」) · text/13-ch11-chapter-11-the-zig-standard-library.txt:135(搜「getStdOut」)
自定义库与 zig.mod Chapter 11: The Zig Standard Library text/13-ch11-chapter-11-the-zig-standard-library.txt:181(搜「Creating a Library」) · text/13-ch11-chapter-11-the-zig-standard-library.txt:213(搜「zig-out/lib」)
包管理器名单与 zigmod 用法 Chapter 12: The Zig Ecosystemy text/14-ch12-chapter-12-the-zig-ecosystemy.txt:13(搜「Zigmod: A simple」) · text/14-ch12-chapter-12-the-zig-ecosystemy.txt:29(搜「curl -fsSL https://zigmod.io」) · text/14-ch12-chapter-12-the-zig-ecosystemy.txt:55(搜「Zigmod Registry」)
第三方库名单 Chapter 12: The Zig Ecosystemy text/14-ch12-chapter-12-the-zig-ecosystemy.txt:81(搜「zig-net: A library」) · text/14-ch12-chapter-12-the-zig-ecosystemy.txt:113(搜「zig_net.tcp.listen」)
std.c.link / include Chapter 12: The Zig Ecosystemy text/14-ch12-chapter-12-the-zig-ecosystemy.txt:169(搜「std.c.link」)

  1. 出处:「Chapter 11: The Zig Standard Library」第 9–141 段(text/13-ch11-chapter-11-the-zig-standard-library.txt:9,搜「Key Modules」;:43,搜「std.math.sqrt」;:57,搜「std.mem.copy」;:97,搜「std.strings.len」;:135,搜「getStdOut」)。模块名九中八真,函数签名多处编造。 ↩↩↩↩

  2. 出处:「Chapter 11: The Zig Standard Library」第 143–245 段(text/13-ch11-chapter-11-the-zig-standard-library.txt:181,搜「Creating a Library」;:191,搜「zig.mod」;:213,搜「zig-out/lib」;:235,搜「Zigmod and Zig Packages」)。 ↩↩

  3. 补充(不在书里,来自权威外部资料):官方 zig init 生成 build.zig.zon;@cImport(@cInclude(...)) 直接导入 C 头文件(官方 libsoundio 示例);构建脚本里 linkSystemLibrary。来源:《Overview — Zig Programming Language》https://ziglang.org/learn/overview/(查阅于 2026-10-19)。 ↩↩↩

  4. 出处:「Chapter 12: The Zig Ecosystemy」第 5–73 段(text/14-ch12-chapter-12-the-zig-ecosystemy.txt:7,搜「does not have a built-in package manager」;:13,搜「Zigmod: A simple」;:29,搜「curl -fsSL」;:55,搜「Zigmod Registry」)。 ↩↩

  5. 出处:「Chapter 12: The Zig Ecosystemy」第 141–201 段(text/14-ch12-chapter-12-the-zig-ecosystemy.txt:141,搜「Building and Using External Libraries」;:169,搜「std.c.link」;:171,搜「std.c.include」)。 ↩↩

  6. 出处:「Chapter 12: The Zig Ecosystemy」第 75–139 段(text/14-ch12-chapter-12-the-zig-ecosystemy.txt:81,搜「zig-net: A library」;:113,搜「zig_net.tcp.listen」)。所列 zig-net/zig-sqlite/zig-http/zig-tls/zig-json/zig-xml/zig-opengl/zig-raylib 在 Zig 生态中均无对应实体。 ↩↩