参考 · CLI

命令速查

构建、示例、测试、代码生成与质量检查命令集中查阅。

预计阅读 5 分钟

应用项目

以下 step 来自模板 templates/minimal-app/build.zig。app step 只在 macOS 目标上注册。

Terminal

zig build                      # build the executable
zig build run                  # build and run
zig build app                  # package a macOS .app bundle (zig-out/)
zig build -Dtest-mode=true     # enable the automation harness (forwarded to zenit)

zenit 仓库示例

每个示例都有两个 step：zig build <name> 生成带 ad-hoc 签名的 .app，zig build run-<name> 直接运行可执行文件。

Step.app 名称内容

hello-buttonHello Button最小窗口与按钮

counter-reactiveReactive CounterSignal / Memo / Effect 演示

virtual-list-perf100k Virtual List10 万行 VirtualList 压力测试

text-inputText Input DemoInput / Textarea 与 text_core 集成

multi-windowMulti Window两个原生窗口，按窗口路由

storybookzenit Storybook全组件 showcase，也是 e2e 目标

devtools-probeDevTools ProbeDevTools 性能面板真实窗口验收

interop-probezenit Interop Probe富剪贴板 / 拖出的系统级验证

console-probeConsole ProbeConsole + DevTools 真实窗口验证

design-probeDesign Probe设计稿还原比对靶场

Terminal

zig build run-hello-button
zig build run-counter-reactive
zig build run-storybook

测试

总入口

命令作用

test等同 test-headless

test-headless确定性测试，不需要真实 Metal 设备

test-all确定性测试 + 需要真实设备的 Metal 测试

test-null-backend用 Null GPU 后端编译并运行确定性测试，验证 RHI 抽象

UI 与响应式

命令作用

test-uiUI 系统测试；-Dtest-filter=<子串> 只跑名称匹配的测试

test-ui-coreui_core 集成测试（src/ui/core/tests.zig）

test-reactive响应式系统测试

test-allocation-campaign在事务性框架边界上逐点注入分配失败

渲染与 GPU

命令作用

test-renderrender 模块测试

test-gpuGPU 抽象层测试

test-metal需要真实 Metal 设备的测试

test-svgSVG 解析 / 栅格化测试

test-timing-ring帧计时环测试

文本与国际化

命令作用

test-texttext 模块测试（字体目录 / 字重）

test-text-coretext_core 模块测试

test-text-properties可设种子的确定性文本坐标属性测试

test-i18ni18n 模块测试

test-bidi-conformance完整 Unicode 17.0.0 UAX #9 一致性数据

平台、窗口与打包

命令作用

test-window-lifecycle确定性多窗口生命周期与路由测试

test-text-hook-owners进程级文本测量钩子的归属栈（关一个窗口不拆掉其他窗口的钩子）

test-selector-scaleHiDPI 下 FontSelector 缩放同步

test-system-sdkSystem SDK 测试

test-system-sdk-backends确定性原生后端测试

check-system-sdk-cross为 Linux / Windows 编译 System SDK 测试（不运行）

test-harnesstest_harness（file-RPC）测试

test-package-consumer以直接包与经 Zig 过滤的包两种方式构建并启动下游应用

生成与工具

命令作用

bench性能基线：zig build bench [-- filter] [-- json=path]

gen-icons重新生成 -Dicon-set 选中的图标模块（默认 lucide）

gen-icons-lucide重新生成公开 Lucide 图标模块

gen-icons-common重新生成 provider 无关的 common 图标模块

gen-icons-untitled / gen-icons-all内部图标集；仅内部 checkout 可用

gen-component-indexAST 扫描 src/ui，重新生成 component_index_generated.zig

capability-matrix打印生成的 macOS 能力矩阵

text-corpus-dump打印已提交的 T0 文本坐标语料

构建选项

选项默认作用

-Dtest-mode=truefalse启用 e2e harness（file-RPC server）

-De2e-port=<n>19816E2E 端口，用于默认 RPC 目录名

-Dtest-filter=<s>—只运行名称包含该子串的 test-ui 测试

-Dicon-set=<name>lucide内置图标 provider：lucide 或 untitled（仅内部）

-Dgpu-backend=<name>metalGPU 后端：metal 或 null

NOTE

依赖选项要显式转发。 Zig 的依赖构建选项彼此隔离。下游应用要在 b.dependency("zenit", ...) 里转发 .@"test-mode" 与 .@"e2e-port"，zig build -Dtest-mode=true 才会传到 zenit；模板已经这样做。

质量脚本

脚本作用

./scripts/check_oss_boundary.sh静态检查 src/ui 的 import，并编译 hello-button 确认没有可达的禁用模块

./scripts/check_style_literals.sh示例代码中裸颜色 / 字号字面量只减不增（ui.arb 逃生舱放行）

bash scripts/switch_icon_set.sh lucide用指定图标集跑 test-headless 与 storybook 构建，不修改工作区

TIP

使用 ZIG 覆盖。 仓库脚本默认使用 PATH 中的 zig。需要指定版本时设置 ZIG=/absolute/path/to/zig。

Bundle 检查

示例 bundle 使用 ad-hoc 签名并清除 quarantine 属性。下面的命令验证签名，并列出残留的扩展属性。

Terminal

zig build hello-button
codesign --verify --deep --strict "zig-out/Hello Button.app"
xattr -lr "zig-out/Hello Button.app"

← PREV

公开 API

问题排查