The first build is slow because Nix compiles everything from source — there are no pre-built binaries. Here's what it builds:

Native C/C++ Libraries (27 packages):

Rust Backend (186 crates):

Platform Tooling:

Total first build: ~30–60 minutes depending on your Mac's CPU and SSD speed.

Good news: Subsequent builds are fast (~10–30 seconds) because Nix caches every derivation. Only changed crates rebuild.

Wawona's Nix store footprint is large because it builds an entire graphics stack, compositor, and cross-compilation toolchains from source. Here's the breakdown:

Per-Platform Storage Estimate:

Why so big?

1. No shared system libraries — Nix builds everything hermetically. Even zlib and libffi are compiled from source rather than using system copies
2. Multiple target triples — iOS needs aarch64-apple-ios + aarch64-apple-ios-sim; Android needs aarch64-linux-android; macOS needs native. Each target has its own compiled copy of every library
3. Graphics stacks — MoltenVK, KosmicKrisp, ANGLE, SwiftShader are complete GPU driver implementations
4. Weston — a full reference compositor compiled for macOS, with all its dependencies
5. FFmpeg — full multimedia framework for waypipe video compression

Mitigation: Run nix store gc periodically to clean up old build artifacts. Only the current generation is kept.

Nix is the only dependency you need to install — it replaces every other tool:

Why not Cargo alone? Wawona depends on 27 native C/C++ libraries (libwayland, xkbcommon, FFmpeg, OpenSSL, etc.) that don't exist on macOS. Cargo can compile Rust crates, but it can't build C libraries, cross-compile for iOS/Android, or manage platform SDKs.

Why not Homebrew? Homebrew installs pre-built macOS binaries, but Wawona needs iOS and Android cross-compiled variants of every library. Homebrew can't cross-compile.

Nix gives you:

• Reproducible builds — same result on every Mac
• Hermetic isolation — doesn't pollute your system
• Cross-compilation — one command for macOS, iOS, and Android
• Incremental caching — only rebuild what changed

We recommend Determinate Nix because it enables flakes out of the box.

We're working on it! Pre-built binaries are planned but not available yet. Here's the status:

Why not yet?

1. Code signing — Apple requires a paid Developer Program enrollment ($99/year) for distributing .app and .ipa files. We're a student-funded project
2. Fastlane setup — We're planning to integrate Fastlane for automated TestFlight and Play Store deployment, but the CI/CD pipeline isn't configured yet
3. Rapid development — Wawona is still in active development (v0.2.2). Building from source ensures you always get the latest version with all protocol improvements

For now: nix run is the fastest way to build and launch. Once Fastlane is configured, beta testers will be able to install directly via TestFlight (iOS) or sideload an APK (Android).

Wawona doesn't "port" Linux apps — it runs them as-is by implementing the Wayland protocol natively on macOS. Here's how it works:

What Wawona does:

1. Creates a Wayland compositor socket (wayland-0) on macOS
2. Any Wayland client that connects to this socket can display its windows
3. Wawona translates Wayland protocol messages into native macOS rendering (Metal) and input (NSEvent)

How to run a Linux Wayland app on your Mac:

Example — Running a remote Linux app:

# On your Mac, with Wawona running:
nix run .#waypipe -- ssh user@linux-server foot

This runs foot (a Wayland terminal) on the Linux server and displays it on your Mac through Wawona. No porting required.

Example — Building a Wayland app locally:

If the app supports Wayland and compiles on macOS (or can be cross-compiled with Nix), you can add it as a Nix package in dependencies/libs/ following the same pattern as Weston. The key requirements are:

1. The app must use the Wayland protocol (not X11)
2. It must link against libwayland-client (which Wawona builds for macOS)
3. Any Linux-specific APIs (epoll, signalfd, etc.) need shims — Wawona includes epoll-shim for this

Wawona registers 68 Wayland protocol globals, but not all are fully implemented yet:

Fully functional protocols include: wl_compositor, wl_shm, wl_output, xdg_wm_base, and zxdg_decoration_manager_v1.

For the complete list, see Protocol Support.

Currently, Wawona targets Apple Silicon (M1, M2, M3, M4) only. Intel Mac support is not actively tested or maintained. The Nix build system and Rust backend could theoretically compile for x86_64-darwin, but the Metal rendering pipeline and native libraries are only validated on ARM64.

See the full walkthrough in the Getting Started — Team ID guide. The short version:

1. Run nix run .#xcodegen to generate the Xcode project
2. Open in Xcode → Signing & Capabilities → sign in and select your team
3. Copy the Team ID from the .pbxproj file
4. Save it: echo 'export TEAM_ID="YOUR_ID"' > .envrc
5. From now on: nix develop → nix run .#xcodegen auto-fills your signing identity

Protocol modules live in src/core/wayland/ and follow a consistent pattern:

1. Pick a stub protocol from the Protocol Support page (– status)
2. Study the spec at wayland.app for the protocol's expected behavior
3. Implement handlers — turn the tracing::debug!() stubs into real state mutations and response events
4. Test with a known client that uses that protocol (e.g., foot for zwp_text_input_manager_v3)

See Architecture for how the source is organized.