Skip to content

development.md

Latest commit

 

History

History
102 lines (76 loc) · 3.34 KB

development.md

File metadata and controls

102 lines (76 loc) · 3.34 KB

Development

This document covers local setup, build/test commands, and release steps.

Prerequisites

  • Nix with flakes enabled
  • macOS: Xcode Command Line Tools if you plan to use Homebrew dependencies

Setup

  1. (Optional) Pre-fetch the ghostty dependency to speed up the first build:

    just setup

    just setup caches the ghostty source tarball; the regular build will fetch it automatically if you skip this step.

  2. Enter the development shell:

    nix develop

    Or, if using direnv:

    direnv allow

    On macOS hosts where the active MacOSX.sdk only exposes arm64e targets, Zig 0.15.2 can fail during native Darwin linking with errors such as undefined symbol: __availability_version_check. The upstream tracker for this regression is https://codeberg.org/ziglang/zig/issues/31756.

    The dev shell works around that by exposing MacOSX15.4.sdk through a fake DEVELOPER_DIR whose usr/bin/xcrun is a narrow shim for xcrun --sdk macosx --show-sdk-path. build.zig also resolves framework paths through DEVELOPER_DIR and xcrun before it falls back to hardcoded SDK locations, so the workaround does not need to force SDKROOT. Keeping the shim inside the fake developer tree means tools like git can still invoke /usr/bin/xcrun without tripping over the overridden DEVELOPER_DIR.

    Remove this workaround once Architect no longer uses Zig 0.15.2, or once Zig handles the arm64e-only macOS SDK stubs correctly. If the active MacOSX.sdk/usr/lib/libSystem.tbd advertises arm64-macos again, the shell hook becomes a no-op.

  3. Verify the environment:

    zig version  # Should show 0.15.2+ (compatible with ghostty-vt)
just --list  # Show available commands

Build and Run

Build the project:

just build
# or
zig build

Build optimized release:

zig build -Doptimize=ReleaseFast

Run the application:

just run
# or
zig build run

Dependencies and Tooling

  • ghostty-vt is fetched as a pinned tarball via the Zig package manager (build.zig.zon).
  • SDL3 and SDL3_ttf are provided by Nix. SDL3 is pinned to 3.4.0 via overlays/sdl3-3-4-0.nix with binaries cached in the public forketyfork Cachix to avoid rebuilds.

Tests and Formatting

Run tests:

just test
# or
zig build test

Check formatting and script linting:

just lint
# or
zig fmt --check src/
shellcheck scripts/*.sh scripts/verify-setup.sh
ruff check scripts/*.py

Format code:

zig fmt src/

Release Process

macOS release binaries are automatically built for both ARM64 (Apple Silicon) and x86_64 (Intel) architectures via GitHub Actions when a version tag is pushed:

git tag v0.1.0
git push origin v0.1.0

The release workflow packages ad-hoc-signed app bundles with local codesign --sign -. It does not import macOS signing certificates, does not produce Developer ID-signed artifacts, and does not notarize the app. Release downloads therefore still require clearing the quarantine attribute after extraction, as described in the README installation instructions. You can also run the Release workflow manually with workflow_dispatch to validate the packaging flow before pushing a real release tag.

Each release includes:

  • architect-macos-arm64.tar.gz - Apple Silicon
  • architect-macos-x86_64.tar.gz - Intel