docs/guide/getting-started
Loslegen · 5 Min.

Schnellstart

Erstellen Sie eine native macOS-App, die außerhalb des zenit-Repos liegt und eigenständig baut und läuft.

8 Min. Lesezeit
Sie entwickeln mit Claude Code oder einem anderen Agenten? Installieren Sie zuerst den zenit UI dev Skill.

Er bündelt dieses Handbuch, die Entscheidungstabelle für Komponenten und Fallstricke aus echten Projekten zu Anweisungen, die Ihr Agent bei Bedarf lädt – so folgt der Code, den er schreibt, den zenit-Konventionen.

Voraussetzungen

Diese Version zielt auf macOS, Apple Silicon wird laufend verifiziert. Stellen Sie sicher, dass Zig 0.15.2 und die Xcode Command Line Tools installiert sind; Bun wird nur für End-to-End-Tests benötigt.

Terminal
zig version
xcode-select -p

Projekt anlegen

Starten Sie mit templates/minimal-app im Repo. Es ist ein vollständiges Downstream-Projekt:

templates/minimal-app
minimal-app/
├── README.md
├── build.zig          # zenit.attach() + run / app steps
├── build.zig.zon      # declares the zenit dependency
├── e2e/
│   └── record-demo.ts # drives and records the app through the Harness
└── src/
    └── main.zig       # counter-button app
  1. 1
    Template kopieren

    Kopieren Sie templates/minimal-app in ein neues Verzeichnis außerhalb des zenit-Repos.

  2. 2
    Abhängigkeitspfad anpassen

    Das Template verwendet standardmäßig .path = "../../", was nur innerhalb des Repos auflöst. Richten Sie es nach dem Kopieren relativ zu build.zig.zon auf Ihren zenit-Checkout aus oder pinnen Sie eine veröffentlichte Revision mit zig fetch --save=zenit <url>.

  3. 3
    Fingerprint erzeugen

    Übernehmen Sie nicht den .fingerprint des Templates – zwei Projekte mit demselben Wert kollidieren im Paket-Cache von Zig. Löschen Sie die Zeile, führen Sie zig build einmal aus und fügen Sie den Wert aus der Fehlermeldung ein. Benennen Sie dabei auch .name = .myapp um.

Terminal
git clone https://github.com/version-next/zenit.git
cp -R zenit/templates/minimal-app ./myapp
cd myapp   # then set .zenit = .{ .path = "../zenit" } in build.zig.zon
zig build

zenit einbinden

build.zig.zon deklariert die Abhängigkeit; build.zig erhält über @import("zenit") die Build-API von zenit.

build.zig.zon
.{
    .name = .myapp,
    .version = "0.1.0",
    .fingerprint = 0x8798022a7f8e220e, // replace: delete this line, run zig build once
    .minimum_zig_version = "0.15.2",

    .dependencies = .{
        // Relative to this file. Absolute paths are rejected by Zig 0.15.2.
        .zenit = .{ .path = "../zenit" },
    },

    .paths = .{
        "README.md",
        "build.zig",
        "build.zig.zon",
        "e2e",
        "src",
    },
}

Hier ist das build.zig des Templates im Wortlaut. Es ist mehr als ein attach-Aufruf: Es leitet die Test-Schalter weiter, installiert den Harness-Client und definiert den run-Step und das .app-Packaging:

AufrufFunktion
zenit.attach(zenit_dep, exe)Fügt die Modul-Imports ui und zenit_app hinzu, kompiliert die fünf macOS-ObjC-Bridges und linkt Cocoa, Metal, CoreText und die übrigen Frameworks
.@"test-mode" / .@"e2e-port"Abhängigkeitsoptionen sind in Zig isoliert; leiten Sie sie explizit weiter, damit zig build -Dtest-mode=true zenit erreicht
zenit.installHarnessClient(b, zenit_dep)Installiert den typisierten Harness-Client nach zig-out/share/zenit/harness/client.ts für e2e/record-demo.ts
zenit.bundleApp(b, .{ ... })Erzeugt ein per Doppelklick startbares zig-out/<display_name>.app, hier ad-hoc signiert

Den ersten UI-Baum mounten

App.runWith erzeugt den Root-Scope, ruft Ihre Mount-Funktion einmal auf und übernimmt die Event-Loop. Die Mount-Funktion muss die Signatur fn (cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node haben; Ihre App gibt nur den Wurzelknoten zurück.

cx.bindState übergibt Counter an den Cx, und cx.on macht eine seiner Methoden zum Button-Callback; mit test_id finden E2E-Skripte den Button über seine Bedeutung.

Bauen und ausführen

Terminal
zig build run   # build and run the unbundled executable
zig build app   # package zig-out/My App.app (macOS)
Die echte Hello Button.app, gestartet aus der Build-Ausgabe (examples/hello_button, derselbe Zähler-Button wie im Template): Der harness klickt dreimal mit dem Hand-Cursor, und das Label zeigt „Clicked 3 times“. Fenster, Widget und Reaktion stammen alle aus der öffentlichen API oben.

Das Template enthält auch ein Aufnahmeskript: Bauen Sie mit zig build -Dtest-mode=true, starten Sie die App und führen Sie dann e2e/record-demo.ts aus, um einen ähnlichen Clip zu erhalten – siehe E2E harness.

zenit · DoppellizenzKostenlos für Open-Source-Projekte unter GPL-3.0-only; Closed-Source- oder kommerzielle Produkte benötigen eine kommerzielle Lizenz.Kontakt zum Autor: zongyi.xzy#gmail.com (# durch @ ersetzen)zenit 5f9add5+wip 2026-09-30