参考 · CLIReference · CLI

命令速查Commands

构建、示例、测试、代码生成与质量检查命令集中查阅。Build, example, test, codegen and quality commands in one place.

预计阅读 5 分钟5 min read

应用项目Your app

以下 step 来自模板 templates/minimal-app/build.zig。app step 只在 macOS 目标上注册。These steps come from the template’s templates/minimal-app/build.zig. The app step is registered only for macOS targets.

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 仓库示例Examples in the zenit repo

每个示例都有两个 step：zig build <name> 生成带 ad-hoc 签名的 .app，zig build run-<name> 直接运行可执行文件。Every example has two steps: zig build <name> produces an ad-hoc-signed .app, and zig build run-<name> runs the executable directly.

StepStep.app 名称.app name内容What it is

hello-buttonHello Button最小窗口与按钮Minimal window and button

counter-reactiveReactive CounterSignal / Memo / Effect 演示Signal / Memo / Effect demo

virtual-list-perf100k Virtual List10 万行 VirtualList 压力测试100k-row VirtualList stress test

text-inputText Input DemoInput / Textarea 与 text_core 集成Input / Textarea with text_core

multi-windowMulti Window两个原生窗口，按窗口路由Two native windows, per-window routing

storybookzenit Storybook全组件 showcase，也是 e2e 目标All-component showcase and e2e target

devtools-probeDevTools ProbeDevTools 性能面板真实窗口验收Real-window acceptance for the DevTools performance panel

interop-probezenit Interop Probe富剪贴板 / 拖出的系统级验证Rich clipboard / drag-out system verification

console-probeConsole ProbeConsole + DevTools 真实窗口验证Console + DevTools real-window verification

design-probeDesign Probe设计稿还原比对靶场Target for design-mockup comparison

Terminal

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

测试Tests

总入口Suites

命令Command作用What it does

test等同 test-headlessAlias of test-headless

test-headless确定性测试，不需要真实 Metal 设备Deterministic tests; no live Metal device required

test-all确定性测试 + 需要真实设备的 Metal 测试Deterministic plus live-device Metal tests

test-null-backend用 Null GPU 后端编译并运行确定性测试，验证 RHI 抽象Build and run deterministic tests on the Null GPU backend to prove the RHI abstraction

UI 与响应式UI and reactivity

命令Command作用What it does

test-uiUI 系统测试；-Dtest-filter=<子串> 只跑名称匹配的测试UI system tests; -Dtest-filter=<substring> runs only matching names

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

test-reactive响应式系统测试Reactive system tests

test-allocation-campaign在事务性框架边界上逐点注入分配失败Sweep allocator failure points across transactional framework boundaries

渲染与 GPURendering and GPU

命令Command作用What it does

test-renderrender 模块测试Render module tests

test-gpuGPU 抽象层测试GPU abstraction tests

test-metal需要真实 Metal 设备的测试Tests that need a live Metal device

test-svgSVG 解析 / 栅格化测试SVG parser / rasterizer tests

test-timing-ring帧计时环测试Frame timing ring tests

文本与国际化Text and i18n

命令Command作用What it does

test-texttext 模块测试（字体目录 / 字重）Text module tests (font catalog / weights)

test-text-coretext_core 模块测试text_core module tests

test-text-properties可设种子的确定性文本坐标属性测试Deterministic, seedable text-coordinate property tests

test-i18ni18n 模块测试i18n module tests

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

平台、窗口与打包Platform, windows and packaging

命令Command作用What it does

test-window-lifecycle确定性多窗口生命周期与路由测试Deterministic multi-window lifecycle and routing tests

test-text-hook-owners进程级文本测量钩子的归属栈（关一个窗口不拆掉其他窗口的钩子）Process-wide text-measurement hook ownership stack (closing one window keeps the others’ hooks)

test-selector-scaleHiDPI 下 FontSelector 缩放同步HiDPI FontSelector scale propagation

test-system-sdkSystem SDK 测试System SDK tests

test-system-sdk-backends确定性原生后端测试Deterministic native backend tests

check-system-sdk-cross为 Linux / Windows 编译 System SDK 测试（不运行）Compile System SDK tests for Linux / Windows (no run)

test-harnesstest_harness（file-RPC）测试test_harness (file-RPC) tests

test-package-consumer以直接包与经 Zig 过滤的包两种方式构建并启动下游应用Build and launch a downstream app against direct and Zig-filtered packages

生成与工具Codegen and tools

命令Command作用What it does

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

gen-icons重新生成 -Dicon-set 选中的图标模块（默认 lucide）Regenerate the module chosen by -Dicon-set (lucide by default)

gen-icons-lucide重新生成公开 Lucide 图标模块Regenerate the public Lucide icon module

gen-icons-common重新生成 provider 无关的 common 图标模块Regenerate the provider-neutral common icon module

gen-icons-untitled / gen-icons-all内部图标集；仅内部 checkout 可用Internal icon set; internal checkouts only

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

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

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

构建选项Build options

选项Option默认Default作用Effect

-Dtest-mode=truefalse启用 e2e harness（file-RPC server）Enable the e2e harness (file-RPC server)

-De2e-port=<n>19816E2E 端口，用于默认 RPC 目录名E2E port, used in the default RPC directory name

-Dtest-filter=<s>—只运行名称包含该子串的 test-ui 测试Run only test-ui tests whose name contains the substring

-Dicon-set=<name>lucide内置图标 provider：lucide 或 untitled（仅内部）Built-in icon provider: lucide or untitled (internal only)

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

NOTE

依赖选项要显式转发。Forward dependency options explicitly. Zig 的依赖构建选项彼此隔离。下游应用要在 b.dependency("zenit", ...) 里转发 .@"test-mode" 与 .@"e2e-port"，zig build -Dtest-mode=true 才会传到 zenit；模板已经这样做。Zig isolates dependency build options. A downstream app must forward .@"test-mode" and .@"e2e-port" in b.dependency("zenit", ...) for zig build -Dtest-mode=true to reach zenit; the template already does.

质量脚本Quality scripts

脚本Script作用What it checks

./scripts/check_oss_boundary.sh静态检查 src/ui 的 import，并编译 hello-button 确认没有可达的禁用模块Statically checks src/ui imports, then builds hello-button to confirm no forbidden module is reachable

./scripts/check_style_literals.sh示例代码中裸颜色 / 字号字面量只减不增（ui.arb 逃生舱放行）Ratchets bare color / font-size literals in examples down, never up (ui.arb escapes are allowed)

bash scripts/switch_icon_set.sh lucide用指定图标集跑 test-headless 与 storybook 构建，不修改工作区Runs test-headless and the storybook build with one icon set, without touching the worktree

TIP

使用 ZIG 覆盖。Override with ZIG. 仓库脚本默认使用 PATH 中的 zig。需要指定版本时设置 ZIG=/absolute/path/to/zig。Repo scripts use the zig on PATH. To pin a specific toolchain, set ZIG=/absolute/path/to/zig.

Bundle 检查Bundle checks

示例 bundle 使用 ad-hoc 签名并清除 quarantine 属性。下面的命令验证签名，并列出残留的扩展属性。Example bundles are ad-hoc signed with the quarantine attribute cleared. These commands verify the signature and list any remaining extended attributes.

Terminal

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

← PREV

公开 APIPublic API

问题排查Troubleshooting