---
title: "Commands | zenit Zig UI Docs"
description: "Build, example, test, codegen and quality commands in one place."
url: https://ui.surf/zenit/docs/reference/commands
language: en
alternate_zh: https://ui.surf/zenit/zh/docs/reference/commands.md
alternate_es: https://ui.surf/zenit/es/docs/reference/commands.md
alternate_ja: https://ui.surf/zenit/ja/docs/reference/commands.md
alternate_ko: https://ui.surf/zenit/ko/docs/reference/commands.md
alternate_fr: https://ui.surf/zenit/fr/docs/reference/commands.md
alternate_de: https://ui.surf/zenit/de/docs/reference/commands.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# Commands

Build, example, test, codegen and quality commands in one place.

## Your app

These steps come from the template’s `templates/minimal-app/build.zig`. The `app` step is registered only for macOS targets.

```sh
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)
```

## Examples in the zenit repo

Every example has two steps: `zig build <name>` produces an ad-hoc-signed `.app`, and `zig build run-<name>` runs the executable directly.

| Step | .app name | What it is |
| --- | --- | --- |
| `hello-button` | Hello Button | Minimal window and button |
| `counter-reactive` | Reactive Counter | Signal / Memo / Effect demo |
| `virtual-list-perf` | 100k Virtual List | 100k-row VirtualList stress test |
| `text-input` | Text Input Demo | Input / Textarea with text\_core |
| `multi-window` | Multi Window | Two native windows, per-window routing |
| `storybook` | zenit Storybook | All-component showcase and e2e target |
| `devtools-probe` | DevTools Probe | Real-window acceptance for the DevTools performance panel |
| `interop-probe` | zenit Interop Probe | Rich clipboard / drag-out system verification |
| `console-probe` | Console Probe | Console + DevTools real-window verification |
| `design-probe` | Design Probe | Target for design-mockup comparison |

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

## Tests

### Suites

| Command | What it does |
| --- | --- |
| `test` | Alias of test-headless |
| `test-headless` | Deterministic tests; no live Metal device required |
| `test-all` | Deterministic plus live-device Metal tests |
| `test-null-backend` | Build and run deterministic tests on the Null GPU backend to prove the RHI abstraction |

### UI and reactivity

| Command | What it does |
| --- | --- |
| `test-ui` | UI system tests; -Dtest-filter=<substring> runs only matching names |
| `test-ui-core` | 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 |

### Rendering and GPU

| Command | What it does |
| --- | --- |
| `test-render` | Render module tests |
| `test-gpu` | GPU abstraction tests |
| `test-metal` | Tests that need a live Metal device |
| `test-svg` | SVG parser / rasterizer tests |
| `test-timing-ring` | Frame timing ring tests |

### Text and i18n

| Command | What it does |
| --- | --- |
| `test-text` | Text module tests (font catalog / weights) |
| `test-text-core` | text\_core module tests |
| `test-text-properties` | Deterministic, seedable text-coordinate property tests |
| `test-i18n` | i18n module tests |
| `test-bidi-conformance` | 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-scale` | HiDPI FontSelector scale propagation |
| `test-system-sdk` | System SDK tests |
| `test-system-sdk-backends` | Deterministic native backend tests |
| `check-system-sdk-cross` | Compile System SDK tests for Linux / Windows (no run) |
| `test-harness` | test\_harness (file-RPC) tests |
| `test-package-consumer` | Build and launch a downstream app against direct and Zig-filtered packages |

## Codegen and tools

| Command | What it does |
| --- | --- |
| `bench` | Perf baselines: zig build bench \[-- filter\] \[-- json=path\] |
| `gen-icons` | Regenerate the module chosen by -Dicon-set (lucide by default) |
| `gen-icons-lucide` | Regenerate the public Lucide icon module |
| `gen-icons-common` | Regenerate the provider-neutral common icon module |
| `gen-icons-untitled / gen-icons-all` | Internal icon set; internal checkouts only |
| `gen-component-index` | AST-scan src/ui and regenerate component\_index\_generated.zig |
| `capability-matrix` | Print the generated macOS capability matrix |
| `text-corpus-dump` | Print the committed T0 text-coordinate corpus |

## Build options

| Option | Default | Effect |
| --- | --- | --- |
| `-Dtest-mode=true` | `false` | Enable the e2e harness (file-RPC server) |
| `-De2e-port=<n>` | `19816` | E2E port, used in the default RPC directory name |
| `-Dtest-filter=<s>` | — | Run only test-ui tests whose name contains the substring |
| `-Dicon-set=<name>` | `lucide` | Built-in icon provider: lucide or untitled (internal only) |
| `-Dgpu-backend=<name>` | `metal` | GPU backend: metal or null |

> NOTE
> 
> **Forward dependency options explicitly.** 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` | Statically checks src/ui imports, then builds hello-button to confirm no forbidden module is reachable |
| `./scripts/check_style_literals.sh` | Ratchets bare color / font-size literals in examples down, never up (ui.arb escapes are allowed) |
| `bash scripts/switch_icon_set.sh lucide` | Runs test-headless and the storybook build with one icon set, without touching the worktree |

> TIP
> 
> **Override with ZIG.** Repo scripts use the `zig` on PATH. To pin a specific toolchain, set `ZIG=/absolute/path/to/zig`.

## Bundle checks

Example bundles are ad-hoc signed with the quarantine attribute cleared. These commands verify the signature and list any remaining extended attributes.

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