feat(docs): support 0.16.0#320
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to reflect the release of Zig 0.16.0. It includes a new version description file and a comprehensive upgrade guide from version 0.15.1, along with updates to the sidebar and theme configuration. The review feedback identifies two issues in the upgrade guide's code examples: a redundant constant redefinition in the C import section and a syntax error in the representation of the deprecated @type usage.
| pub const c = @cImport({ | ||
| @cInclude("stdio.h"); | ||
| @cInclude("math.h"); | ||
| @cInclude("stdlib.h"); | ||
| }); | ||
|
|
||
| const c = @import("c.zig").c; |
There was a problem hiding this comment.
The "Old way" code block contains a redefinition of the constant c. It first defines c using @cImport and then immediately tries to redefine it using @import. These should be presented as separate examples or the redundant line should be removed to avoid confusion.
| pub const c = @cImport({ | |
| @cInclude("stdio.h"); | |
| @cInclude("math.h"); | |
| @cInclude("stdlib.h"); | |
| }); | |
| const c = @import("c.zig").c; | |
| pub const c = @cImport({ | |
| @cInclude("stdio.h"); | |
| @cInclude("math.h"); | |
| @cInclude("stdlib.h"); | |
| }); |
| 常见迁移： | ||
|
|
||
| ```zig | ||
| @Type(.enum_literal) |
There was a problem hiding this comment.
In the "Old way" example, @Type(.enum_literal) is syntactically incorrect for Zig versions prior to 0.16.0. The @Type built-in expects a std.builtin.Type union value, so it should be @Type(.{ .enum_literal = .{} }).
| @Type(.enum_literal) | |
| @Type(.{ .enum_literal = .{} }) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| bug 修复方面： | ||
|
|
||
| - 大量 “one-possible-value” 类型上的 switch 相关 bug 被修复 |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| - 大量 “one-possible-value” 类型上的 switch 相关 bug 被修复 | |
| - 大量“one-possible-value”类型上的 switch 相关 bug 被修复 |
推动课程进入新阶段，便于后续内容发布与迭代
- 调整所有涉及 libc 链接和构建脚本的示例，统一使用
exe.root_module.linkSystemLibrary("c", .{})
- 大幅重构 build.zig 示例，兼容 Zig 0.16 引入的 Io 模块与新目录 API
- 更新与内存分配相关的文档内容，注明 DebugAllocator 等新接口用法
- 修正线程安全分配器示例，补充 Zig 0.16 移除 ThreadSafeAllocator 的说明
- 优化 C 交互、指针运算、类型转换等文档的说明和措辞以反映新版本变更
- 新增 package_management_importer 的示例和代码，展示包管理用法
本次变更适应 Zig 0.16 新特性，简化了学习曲线，也减少了潜在的 API 误用。
- 为降低读者在 0.16 迁移期的理解成本，统一更新进阶、基础、 工程与环境章节中的过时表述，明确新旧写法边界。 - 新增并重组 `course/code/release` 下的大量示例与工程模板， 让文档引用的代码可直接复现，减少“文档可读但示例不可跑”的落差。 - 调整 `build/0.16.zig` 的构建逻辑，为 C 互操作示例注入 `addTranslateC` 模块
| # 仅获取包的哈希值 | ||
| $ zig fetch https://github.com/webui-dev/zig-webui/archive/main.tar.gz | ||
| 12202809180bab2c7ae3382781b2fc65395e74b49d99ff2595f3fea9f7cf66cfa963 | ||
| # 输出形如：包名-版本-哈希（以实际命令为准） |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| # 输出形如：包名-版本-哈希（以实际命令为准） | |
| # 输出形如：包名 - 版本 - 哈希（以实际命令为准） |
| - `std.process.getCwd*` 改名为 `currentPath*` | ||
| - `fs.path.relative` 变成纯函数，需要显式传入上下文 | ||
| - `File.Stat.atime` 变成可选值 | ||
| - `std.mem` 里 “index of” 系列统一更名为 “find” |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| - `std.mem` 里 “index of” 系列统一更名为 “find” | |
| - `std.mem`里“index of”系列统一更名为“find”� |
|
|
||
| LLVM 后端这一轮的进展有几条： | ||
|
|
||
| - **实验性支持增量编译**——这并不会加速 “LLVM Emit Object” 这一步（LLVM 自己负责的部分我们做不了什么），但加速了 Zig 编译器侧生成 LLVM bitcode 的过程，因此当你的代码本身就有编译错误时，你能在 LLVM 后端下也获得近乎瞬时的反馈 |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| - **实验性支持增量编译**——这并不会加速 “LLVM Emit Object” 这一步（LLVM 自己负责的部分我们做不了什么），但加速了 Zig 编译器侧生成 LLVM bitcode 的过程，因此当你的代码本身就有编译错误时，你能在 LLVM 后端下也获得近乎瞬时的反馈 | |
| - **实验性��——这并不会加速“LLVM Emit Object”这一步（LLVM 自己负责的部分我们做不了什么），但加速了 Zig 编译器侧生成 LLVM bitcode 的过程，因此当你的代码本身就有编译错误时，你能在 LLVM 后端下也获得近乎瞬时的反馈乎瞬时的反馈 |
|
|
||
| LLVM 后端目前通过了 2004 / 2010（100%）行为测试。Matthew 还实验过把 tagged union 和 error union 用 DWARF 的 variant 类型表达，让调试器只显示“当前激活的字段”——但 LLDB 对 variant 类型的支持只有在语言被标成 Rust 时才启用，因此暂未落地。这条路径未来下游若改善还可能再走。 | ||
|
|
||
| 后续还会继续推进 LLVM 后端的并行化：让多个线程同时为不同函数生成 LLVM IR，再由一个 “linker” 线程合并。 |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| 后续还会继续推进 LLVM 后端的并行化：让多个线程同时为不同函数生成 LLVM IR，再由一个 “linker” 线程合并。 | |
| 后续还会继续推进 LLVM 后端的并行化：让多个线程同时为不同函数生成 LLVM IR，再由一个“linker”线程合并。 |
|
|
||
| ### 配套的 AST Smith 已经替 zig fmt 找到 20 个 bug | ||
|
|
||
| 新的 Smith 接口本身已经被用来构建一个 “AST Smith”——专门生成随机但合法的 AST。把它丢给 `zig fmt`（再加上一些更早期的简单随机源码测试），一共发现并修复了 **20 个独立 bug**，其中一部分是新发现的。 |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| 新的 Smith 接口本身已经被用来构建一个 “AST Smith”——专门生成随机但合法的 AST。把它丢给 `zig fmt`（再加上一些更早期的简单随机源码测试），一共发现并修复了 **20 个独立 bug**，其中一部分是新发现的。 | |
| 新的 Smith 接口本身已经被用来构建一个“AST Smith”——专门生成随机但合法的 AST。把它丢给 `zig fmt`（再加上一些更早期的简单随机源码测试），一共发现并修复了 **20 个独立 bug**，其中一部分是新发现的。 |
| All 1 tests passed. | ||
| ``` | ||
|
|
||
| 注意，由于下面 “`extern` 场景必须显式指定 tag type / backing type” 这条规则的存在，现在某些场景下显式指定 packed union 的 backing integer 是必须的。 |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| 注意，由于下面 “`extern` 场景必须显式指定 tag type / backing type” 这条规则的存在，现在某些场景下显式指定 packed union 的 backing integer 是必须的。 | |
| 注意，由于��场景必须显式指定 tag type / backing type”这条规则的存在，现在某些场景下显式指定 packed union 的 backing integer 是必须的。r 是必须的。 |
|
|
||
| 这项 breaking change 是为了避免一个类型的 ABI 完全由字段隐式决定。尤其是因为 `u8` 和 `i8` 在某些上下文中可能有不同 ABI；如果选择是隐式的，就不清楚到底使用哪一个。 | ||
|
|
||
| 如果这在你的代码中引入了编译错误，请添加显式 tag type 或 backing type 来解决。（另见上面 “`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| 如果这在你的代码中引入了编译错误，请添加显式 tag type 或 backing type 来解决。（另见上面 “`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） | |
| 如果这在你的代码中引入了编译错误，请添加显式 tag type 或 backing type 来解决。（另见上面“`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） |
|
|
||
| 这项 breaking change 是为了避免一个类型的 ABI 完全由字段隐式决定。尤其是因为 `u8` 和 `i8` 在某些上下文中可能有不同 ABI；如果选择是隐式的，就不清楚到底使用哪一个。 | ||
|
|
||
| 如果这在你的代码中引入了编译错误，请添加显式 tag type 或 backing type 来解决。（另见上面 “`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| 如果这在你的代码中引入了编译错误，请添加显式 tag type 或 backing type 来解决。（另见上面 “`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） | |
| 如果这在你的代码中引入了编译错误，请添加显式 tag t允许显式 backing integer”这项 Zig上面 “`packed union` 允许显式 backing integer” 这项 Zig `0.16.0` 相关语言变化。） |
|
|
||
| ### 文件系统和路径 API 有一批实用迁移点 | ||
|
|
||
| `fs` 全部 API 都迁到了 `Io`。和 0.15 那次 “writergate” 不同，这次虽然 breaking 范围很大，但绝大多数迁移机械、不需要特别多的判断。最典型的形态就是给原本无参的方法加一个 `io`： |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| `fs` 全部 API 都迁到了 `Io`。和 0.15 那次 “writergate” 不同，这次虽然 breaking 范围很大，但绝大多数迁移机械、不需要特别多的判断。最典型的形态就是给原本无参的方法加一个 `io`： | |
| `fs` 全部 API 都��。和 0.15 那次“writergate”不同，这次虽然 breaking 范围很大，但绝大多数迁移机械、不需要特别多的判断。最典型的形态就是给原本无参的方法加一个法加一个 `io`： |
|
|
||
| 也就是说，Zig 不再想长期维护那批半高层、半底层的历史包装函数。 | ||
|
|
||
| ### `std.mem` 的 “index of” 系列统一更名为 “find” |
There was a problem hiding this comment.
🚫 [AutoCorrect Lint] <AutoCorrect> reported by reviewdog 🐶
| ### `std.mem` 的 “index of” 系列统一更名为 “find” | |
| ### `std.mem`的“index of”系列统一更名为“find”� |
统一中英文混排中的引号与连接符空格，减少阅读视觉噪音， 避免同一课程内出现多套写法，提升术语与示例格式一致性。
1 participant
No description provided.