macos: add build script, update AGENTS.md, skip UI tests

This is an update to address common agentic issues I run into,
but the `build.nu` script may be generally helpful to people using
the Nix env since `xcodebuild` is broken by default in Nix due to the
compiler/linker overrides Nix shell does.

.gitignore

@@ -25,3 +25,4 @@ glad.zip
 /ghostty.qcow2
 
 vgcore.*
+

.prettierignore

@@ -11,6 +11,9 @@ zig-out/
 # macos is managed by XCode GUI
 macos/
 
+# Xcode asset catalogs
+**/*.xcassets/
+
 # produced by Icon Composer on macOS
 images/Ghostty.icon/icon.json
 

AGENTS.md

@@ -5,7 +5,12 @@ A file for [guiding coding agents](https://agents.md/).
 ## Commands
 
 - **Build:** `zig build`
+  - If you're on macOS and don't need to build the macOS app, use
+    `-Demit-macos-app=false` to skip building the app bundle and speed up
+    compilation.
 - **Test (Zig):** `zig build test`
+  - Prefer to run targeted tests with `-Dtest-filter` because the full
+    test suite is slow to run.
 - **Test filter (Zig)**: `zig build test -Dtest-filter=<test name>`
 - **Formatting (Zig)**: `zig fmt .`
 - **Formatting (Swift)**: `swiftlint lint --fix`
@@ -14,7 +19,6 @@ A file for [guiding coding agents](https://agents.md/).
 ## Directory Structure
 
 - Shared Zig core: `src/`
-- C API: `include`
 - macOS app: `macos/`
 - GTK (Linux and FreeBSD) app: `src/apprt/gtk`
 

macos/AGENTS.md

@@ -4,6 +4,8 @@
 - If code outside of this directory is modified, use
   `zig build -Demit-macos-app=false` before building the macOS app to update
   the underlying Ghostty library.
-- Use `xcodebuild` to build the macOS app, do not use `zig build`
+- Use `build.nu` to build the macOS app, do not use `zig build`
   (except to build the underlying library as mentioned above).
-- Run unit tests directly with `xcodebuild`
+  - Build: `build.nu [--scheme Ghostty] [--configuration Debug] [--action build]`
+  - Output: `build/<configuration>/Ghostty.app` (e.g. `build/Debug/Ghostty.app`)
+- Run unit tests directly with `build.nu --action test`

macos/build.nu

@@ -0,0 +1,32 @@
+#!/usr/bin/env nu
+
+# Build the macOS Ghostty app using xcodebuild with a clean environment
+# to avoid Nix shell interference (NIX_LDFLAGS, NIX_CFLAGS_COMPILE, etc.).
+
+def main [
+    --scheme: string = "Ghostty"       # Xcode scheme (Ghostty, Ghostty-iOS, DockTilePlugin)
+    --configuration: string = "Debug"  # Build configuration (Debug, Release, ReleaseLocal)
+    --action: string = "build"         # xcodebuild action (build, test, clean, etc.)
+] {
+    let project = ($env.FILE_PWD | path join "Ghostty.xcodeproj")
+    let build_dir = ($env.FILE_PWD | path join "build")
+
+    # Skip UI tests for CLI-based invocations because it requires
+    # special permissions.
+    let skip_testing = if $action == "test" {
+        [-skip-testing GhosttyUITests]
+    } else {
+        []
+    }
+
+    (^env -i
+        $"HOME=($env.HOME)"
+        "PATH=/usr/bin:/bin:/usr/sbin:/sbin"
+        xcodebuild
+        -project $project
+        -scheme $scheme
+        -configuration $configuration
+        $"SYMROOT=($build_dir)"
+        ...$skip_testing
+        $action)
+}

src/build/GhosttyXcodebuild.zig

@@ -104,6 +104,8 @@ pub fn init(
             "test",
             "-scheme",
             "Ghostty",
+            "-skip-testing",
+            "GhosttyUITests",
         });
         if (xc_arch) |arch| step.addArgs(&.{ "-arch", arch });