레퍼런스 · 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전체 컴포넌트 쇼케이스이자 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

테스트

스위트

명령역할

testtest-headless의 별칭

test-headless결정적 테스트, 실제 Metal 장치 불필요

test-all결정적 테스트 + 실제 장치가 필요한 Metal 테스트

test-null-backendNull GPU 백엔드로 결정적 테스트를 빌드·실행해 RHI 추상화를 검증

UI와 반응성

명령역할

test-uiUI 시스템 테스트. -Dtest-filter=<substring>로 이름이 일치하는 것만 실행

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-crossLinux / 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-commonprovider 중립 common 아이콘 모듈 재생성

gen-icons-untitled / gen-icons-all내부 아이콘 세트, 내부 checkout 전용

gen-component-indexsrc/ui를 AST 스캔해 component_index_generated.zig 재생성

capability-matrix생성된 macOS 기능 매트릭스 출력

text-corpus-dump커밋된 T0 텍스트 좌표 코퍼스 출력

빌드 옵션

옵션기본값효과

-Dtest-mode=truefalsee2e harness 활성화 (file-RPC 서버)

-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는 의존성 빌드 옵션을 서로 격리합니다. zig build -Dtest-mode=true가 zenit까지 전달되려면 다운스트림 앱이 b.dependency("zenit", ...)에서 .@"test-mode"와 .@"e2e-port"를 전달해야 합니다. 템플릿은 이미 그렇게 되어 있습니다.

품질 스크립트

스크립트검사 내용

./scripts/check_oss_boundary.shsrc/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

문제 해결