A high-performance native Wayland compositor for macOS, iOS, and Android /images/logo/Wawona-iOS-Default-1024x1024@1x.png /images/logo/Wawona-iOS-Default-1024x1024@1x.png Zola 2026-02-25T00:00:00+00:00 /atom.xml 2026-02-25T00:00:00+00:00 2026-02-25T00:00:00+00:00 Unknown /gallery/native-compositing/ <p>This screenshot demonstrates Wawona's ability to render Wayland clients directly into the macOS windowing system with full transparency and hardware acceleration.</p> <div class="screenshot-wrapper" style="margin-top: 2rem;"> <figure style="margin: 0; animation: fadeIn 1s ease-out;"> <div class="screenshot-container" onmouseover="this.style.transform='scale(1.02)'" onmouseout="this.style.transform='scale(1)'"> <img src="&#x2F;images&#x2F;wawona-screenshots&#x2F;wawona-screenshot-1.png" alt="Wawona Screenshot" style="width: 100%; height: auto; display: block;"> </div> <figcaption style="margin-top: 1.5rem; text-align: center; color: var(--text-2); font-family: var(--header-font); font-size: 1rem; letter-spacing: 0.02em;"> Wawona rendering Wayland clients directly into the macOS windowing system. </figcaption> </figure> </div> <style> .screenshot-container { border-radius: 12px; overflow: hidden; position: relative; transition: transform 0.4s cubic-bezier(0.175, 0.885, 0.32, 1.275); box-shadow: var(--premium-shadow); border: 1px solid var(--border-color); background-color: var(--bg-1); } :root.dark { --premium-shadow: 0 30px 60px rgba(0, 0, 0, 0.6); } :root.light { --premium-shadow: 0 20px 40px rgba(0, 0, 0, 0.12); } @keyframes fadeIn { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } } </style> 2026-02-24T00:00:00+00:00 2026-02-24T00:00:00+00:00 Unknown /gallery/wayland-seamless/ <p>Wawona manages each Wayland window as a first-class macOS window, including title bar management and native resize behavior.</p> <div class="screenshot-wrapper" style="margin-top: 2rem;"> <figure style="margin: 0; animation: fadeIn 1s ease-out;"> <div class="screenshot-container" onmouseover="this.style.transform='scale(1.02)'" onmouseout="this.style.transform='scale(1)'"> <img src="&#x2F;images&#x2F;wawona-screenshots&#x2F;wawona-screenshot-1.png" alt="Wawona Screenshot" style="width: 100%; height: auto; display: block;"> </div> <figcaption style="margin-top: 1.5rem; text-align: center; color: var(--text-2); font-family: var(--header-font); font-size: 1rem; letter-spacing: 0.02em;"> Wayland windows integrated with the macOS desktop. </figcaption> </figure> </div> <style> .screenshot-container { border-radius: 12px; overflow: hidden; position: relative; transition: transform 0.4s cubic-bezier(0.175, 0.885, 0.32, 1.275); box-shadow: var(--premium-shadow); border: 1px solid var(--border-color); background-color: var(--bg-1); } :root.dark { --premium-shadow: 0 30px 60px rgba(0, 0, 0, 0.6); } :root.light { --premium-shadow: 0 20px 40px rgba(0, 0, 0, 0.12); } @keyframes fadeIn { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } } </style> 2026-02-23T00:00:00+00:00 2026-02-23T00:00:00+00:00 Unknown /gallery/high-res-rendering/ <p>Wawona supports native scaling for high-density displays, ensuring your Wayland apps look as sharp as native macOS applications.</p> <div class="screenshot-wrapper" style="margin-top: 2rem;"> <figure style="margin: 0; animation: fadeIn 1s ease-out;"> <div class="screenshot-container" onmouseover="this.style.transform='scale(1.02)'" onmouseout="this.style.transform='scale(1)'"> <img src="&#x2F;images&#x2F;wawona-screenshots&#x2F;wawona-screenshot-1.png" alt="Wawona Screenshot" style="width: 100%; height: auto; display: block;"> </div> <figcaption style="margin-top: 1.5rem; text-align: center; color: var(--text-2); font-family: var(--header-font); font-size: 1rem; letter-spacing: 0.02em;"> High-resolution rendering on a Retina display. </figcaption> </figure> </div> <style> .screenshot-container { border-radius: 12px; overflow: hidden; position: relative; transition: transform 0.4s cubic-bezier(0.175, 0.885, 0.32, 1.275); box-shadow: var(--premium-shadow); border: 1px solid var(--border-color); background-color: var(--bg-1); } :root.dark { --premium-shadow: 0 30px 60px rgba(0, 0, 0, 0.6); } :root.light { --premium-shadow: 0 20px 40px rgba(0, 0, 0, 0.12); } @keyframes fadeIn { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } } </style> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/android/ <h1 id="android-architecture">Android Architecture</h1> <p>How Wawona runs on Android — Kotlin frontend, JNI bridge, Vulkan rendering, and SSH binary bundling.</p> <hr /> <h2 id="platform-frontend">Platform Frontend</h2> <pre><code>java&#x2F;com&#x2F;aspauldingcode&#x2F;wawona&#x2F; ├── MainActivity.kt # Jetpack Compose host, EdgeToEdge, safe area ├── WawonaSurfaceView.kt # Touch&#x2F;key capture, IME InputConnection ├── WawonaNative.kt # JNI external declarations ├── FabMenu.kt # Material 3 FAB — Settings, Waypipe actions ├── SettingsScreen.kt # SSH host&#x2F;user&#x2F;command config └── Theme.kt # Material 3 Expressive theming </code></pre> <p>The native side (<code>android_jni.c</code>) handles Vulkan init, render threading, input dispatch, waypipe threads, and SSH binary resolution.</p> <hr /> <h2 id="data-flow">Data Flow</h2> <h3 id="input">Input</h3> <pre><code>MotionEvent &#x2F; KeyEvent → WawonaSurfaceView (Kotlin) → JNI (nativeTouchDown &#x2F; nativeKeyEvent) → WWNCoreInjectTouch* &#x2F; WWNCoreInjectKey (Rust FFI) → Wayland protocol handlers → surface commits </code></pre> <h3 id="rendering">Rendering</h3> <pre><code>Render loop (C pthread in android_jni.c): WWNCoreProcessEvents → WWNCoreGetRenderScene → iterate CRenderNode[] → Vulkan textured quad draw (SHM → VkImage upload) → WWNCoreNotifyFramePresented per node → WWNRenderSceneFree </code></pre> <h3 id="waypipe-ssh">Waypipe + SSH</h3> <pre><code>SharedPreferences → nativeRunWaypipe → resolve_ssh_binary_paths() → dladdr() finds native lib dir → waypipe_main(argc, argv) [Rust entry point] → SSH bridge thread: fork() → exec(ssh_bin_path) [Dropbear] → SSHPASS env var → remote waypipe server </code></pre> <hr /> <h2 id="ssh-binary-bundling">SSH Binary Bundling</h2> <p>Android doesn't ship with SSH tools. Wawona bundles <strong>Dropbear SSH</strong> and <strong>sshpass</strong> as static ARM64 executables:</p> <table><thead><tr><th>Step</th><th>What Happens</th></tr></thead><tbody> <tr><td><strong>Build-time</strong></td><td>Nix cross-compiles Dropbear and sshpass for <code>aarch64-linux-android</code></td></tr> <tr><td><strong>APK bundling</strong></td><td>Binaries packaged as <code>libssh_bin.so</code> / <code>libsshpass_bin.so</code> in <code>jniLibs/arm64-v8a/</code></td></tr> <tr><td><strong>Runtime</strong></td><td><code>AndroidManifest.xml</code> sets <code>extractNativeLibs="true"</code> so Android extracts to <code>/data/app/.../lib/arm64/</code></td></tr> <tr><td><strong>Path resolution</strong></td><td><code>resolve_ssh_binary_paths()</code> uses <code>dladdr()</code> to find the native lib directory</td></tr> <tr><td><strong>Execution</strong></td><td>SSH bridge thread uses <code>exec()</code> with absolute paths to the extracted binaries</td></tr> </tbody></table> <hr /> <h2 id="android-specific-dependencies">Android-Specific Dependencies</h2> <table><thead><tr><th>Library</th><th>Purpose</th></tr></thead><tbody> <tr><td>xkbcommon</td><td>Keyboard keymaps (XKB)</td></tr> <tr><td>openssl</td><td>TLS/crypto (Dropbear, waypipe)</td></tr> <tr><td>Dropbear SSH</td><td>Lightweight SSH client (fork/exec)</td></tr> <tr><td>sshpass</td><td>Password automation (optional)</td></tr> <tr><td>libwayland</td><td>Wayland protocol library</td></tr> <tr><td>pixman</td><td>Pixel manipulation</td></tr> <tr><td>zstd / lz4</td><td>Waypipe compression</td></tr> </tbody></table> <hr /> <h2 id="modifier-accessory-bar">Modifier Accessory Bar</h2> <p>Android includes a <strong>Modifier Accessory Bar</strong> (<code>ModifierAccessoryBar.kt</code>) with 1:1 parity to iOS:</p> <p><strong>Row 1:</strong> ESC, <code>`</code>, TAB, <code>/</code>, <code>—</code>, HOME, ↑, END, PGUP</p> <p><strong>Row 2:</strong> ⇧, CTRL, ALT, ⌘, ←, ↓, →, PGDN, ⌨↓</p> <p>All modifier keys are sticky (tap to toggle).</p> <hr /> <h2 id="nix-build-pipeline">Nix Build Pipeline</h2> <ol> <li><strong>Cross-compile C deps</strong> — xkbcommon, openssl, libwayland, pixman, etc. for <code>aarch64-linux-android</code></li> <li><strong>Cross-compile SSH tools</strong> — Dropbear, sshpass as static ARM64 executables</li> <li><strong>Rust backend</strong> — <code>libwawona.a</code> for <code>aarch64-linux-android</code> with waypipe</li> <li><strong>JNI C compilation</strong> — <code>android_jni.c</code> compiled and linked with all static deps into <code>libwawona.so</code></li> <li><strong>APK assembly</strong> — Gradle builds the final APK with Kotlin sources + native libraries</li> <li><strong>Deploy</strong> — <code>nix run .#wawona-android</code> installs via <code>adb install -r</code> and launches</li> </ol> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/architecture/ <h1 id="architecture">Architecture</h1> <p>Wawona is a <strong>Rust-first, cross-platform Wayland compositor</strong>. All compositor logic lives in Rust. Platform frontends are thin native adapters written in Objective-C/Swift (macOS/iOS) and Kotlin/JNI (Android).</p> <hr /> <h2 id="design-philosophy">Design Philosophy</h2> <ul> <li><strong>Core</strong>: All shared logic is OS-agnostic and fully testable in isolation</li> <li><strong>Platform</strong>: Thin adapters translate native events and render buffers via Metal/Vulkan</li> <li><strong>FFI</strong>: UniFFI boundary ensures safe memory and threading — no Wayland types leak across</li> <li><strong>Protocol modules</strong>: Each protocol owns its state and handler logic</li> <li><strong>Rendering</strong>: Native GPU APIs consume a <code>RenderScene</code> produced by the Rust core</li> </ul> <hr /> <h2 id="high-level-flow">High-Level Flow</h2> <pre data-lang="mermaid" class="language-mermaid "><code class="language-mermaid" data-lang="mermaid">flowchart TD A[&quot;Native OS Events\n(NSEvent &#x2F; UIEvent &#x2F; MotionEvent)&quot;] B[&quot;Native Frontend\n(Obj-C &#x2F; Swift &#x2F; Kotlin)&quot;] C[&quot;FFI Layer — src&#x2F;ffi&#x2F;* (UniFFI)\ninject_key · inject_pointer · process_events&quot;] D[&quot;Rust Core — src&#x2F;core&#x2F;*\nWayland protocols, surfaces, windows\ninput, frame timing&quot;] E[&quot;RenderScene\nget_render_scene()&quot;] F[&quot;Native Renderer\n(Metal &#x2F; Vulkan)&quot;] G[&quot;Display Output&quot;] A --&gt; B --&gt; C --&gt; D --&gt; E --&gt; F --&gt; G </code></pre> <hr /> <h2 id="source-layout">Source Layout</h2> <pre><code>src&#x2F; ├── lib.rs # Crate root, UniFFI scaffolding ├── main.rs # CLI entry point │ ├── core&#x2F; # Platform-agnostic compositor logic │ ├── compositor.rs # Lifecycle, Wayland display, client connections │ ├── runtime.rs # Event loop, frame timing, task scheduling │ ├── socket_manager.rs # Wayland socket management │ ├── ipc.rs # Inter-process communication │ ├── surface&#x2F; # Surface &amp; buffer lifecycle │ ├── window&#x2F; # Window management, z-order, focus │ ├── wayland&#x2F; # All protocol implementations │ ├── input&#x2F; # Input event types │ ├── render&#x2F; # Render scene generation │ └── time&#x2F; # Frame timing │ ├── ffi&#x2F; # FFI boundary (UniFFI + C API) │ ├── api.rs # WawonaCore — main FFI object │ ├── types.rs # FFI-safe structs and enums │ ├── c_api.rs # C-compatible API wrappers │ ├── callbacks.rs # Platform callback traits │ └── errors.rs # FFI error mapping │ ├── platform&#x2F; # Platform trait definitions │ └── api.rs # Platform trait + StubPlatform │ ├── rendering&#x2F; # Native rendering code │ ├── metal_shaders.metal # Metal shaders (Apple) │ ├── renderer_apple.m # Metal renderer (macOS&#x2F;iOS) │ └── renderer_android.c # Vulkan renderer (Android) │ └── input&#x2F; # Native input handling ├── input_handler.m # macOS&#x2F;iOS input (NSEvent → Wayland) └── wayland_seat.c # Seat implementation </code></pre> <hr /> <h2 id="platform-frontends">Platform Frontends</h2> <table><thead><tr><th>Platform</th><th>Language</th><th>Rendering</th><th>Window System</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>Objective-C + Swift</td><td>Metal (CAMetalLayer)</td><td>AppKit (NSWindow)</td></tr> <tr><td><strong>iOS</strong></td><td>Objective-C + Swift</td><td>Metal (CAMetalLayer)</td><td>UIKit (UIWindow)</td></tr> <tr><td><strong>Android</strong></td><td>Kotlin + JNI + C</td><td>Vulkan</td><td>SurfaceView</td></tr> </tbody></table> <p>Each frontend:</p> <ol> <li><strong>Captures</strong> native OS events (touch, keyboard, mouse)</li> <li><strong>Translates</strong> them to Wayland-compatible input via FFI (<code>inject_key</code>, <code>inject_pointer_motion</code>, etc.)</li> <li><strong>Calls</strong> <code>process_events()</code> to advance the compositor state</li> <li><strong>Retrieves</strong> a <code>RenderScene</code> via <code>get_render_scene()</code></li> <li><strong>Renders</strong> each scene node using the native GPU API</li> </ol> <hr /> <h2 id="wayland-protocol-support">Wayland Protocol Support</h2> <p>Wawona registers <strong>68 protocol globals</strong> at startup, organized by category:</p> <table><thead><tr><th>Category</th><th>Protocols</th><th>Examples</th></tr></thead><tbody> <tr><td><strong>Core</strong> (6)</td><td>Fundamental Wayland</td><td><code>wl_compositor</code>, <code>wl_shm</code>, <code>wl_seat</code>, <code>wl_output</code></td></tr> <tr><td><strong>XDG</strong> (9)</td><td>Desktop shell</td><td><code>xdg_wm_base</code>, <code>xdg_decoration</code>, <code>xdg_output</code></td></tr> <tr><td><strong>wlroots</strong> (10)</td><td>Compositor extensions</td><td><code>layer_shell</code>, <code>screencopy</code>, <code>foreign_toplevel</code></td></tr> <tr><td><strong>Buffer &amp; Sync</strong> (5)</td><td>GPU sharing</td><td><code>linux_dmabuf</code>, <code>explicit_sync</code>, <code>drm_syncobj</code></td></tr> <tr><td><strong>Input</strong> (10)</td><td>Advanced input</td><td><code>pointer_constraints</code>, <code>text_input</code>, <code>tablet</code></td></tr> <tr><td><strong>Timing</strong> (8)</td><td>Frame control</td><td><code>presentation_time</code>, <code>fractional_scale</code>, <code>fifo</code></td></tr> <tr><td><strong>Session</strong> (5)</td><td>Security</td><td><code>session_lock</code>, <code>idle_inhibit</code>, <code>security_context</code></td></tr> <tr><td><strong>Desktop</strong> (4)</td><td>Integration</td><td><code>foreign_toplevel_list</code>, <code>workspace</code></td></tr> <tr><td><strong>Capture</strong> (4)</td><td>Screen capture</td><td><code>image_copy_capture</code>, <code>xwayland_shell</code></td></tr> <tr><td><strong>Plasma</strong> (7)</td><td>KDE protocols</td><td><code>kde_decoration</code>, <code>blur</code>, <code>contrast</code></td></tr> </tbody></table> <p>For detailed implementation status per protocol, see <a href="/docs/protocols/">Protocols</a>.</p> <hr /> <h2 id="rendering-pipeline">Rendering Pipeline</h2> <h3 id="apple-macos-ios-metal">Apple (macOS / iOS) — Metal</h3> <ol> <li>Client writes pixel data to a shared buffer</li> <li>Wawona wraps it in an <code>IOSurface</code> (zero-copy GPU access)</li> <li>Metal renderer reads directly from the <code>IOSurface</code></li> <li>Composited via custom Metal shaders (MSL)</li> <li>Synchronized with display via <code>CVDisplayLink</code> (macOS) / <code>CADisplayLink</code> (iOS)</li> </ol> <h3 id="android-vulkan">Android — Vulkan</h3> <ol> <li>Client submits SHM buffers over the Wayland protocol</li> <li>Buffer data uploaded to <code>VkImage</code></li> <li>Rendered as textured quads via SPIR-V shaders</li> <li>Presented through Android's <code>SurfaceView</code></li> <li>Synchronized with <code>Choreographer</code> frame callbacks</li> </ol> <hr /> <h2 id="threading-model">Threading Model</h2> <pre data-lang="mermaid" class="language-mermaid "><code class="language-mermaid" data-lang="mermaid">flowchart TD T1[&quot;Input Thread\nReceive OS events · Translate via FFI&quot;] T2[&quot;Core Thread\nRust state update · Scene graph build · Damage tracking&quot;] T3[&quot;Render Thread\nMetal &#x2F; Vulkan draw · Present to display&quot;] T1 --&gt; T2 --&gt; T3 </code></pre> <hr /> <h2 id="build-system">Build System</h2> <p>Wawona uses <strong>Nix</strong> as the single build system for all platforms:</p> <table><thead><tr><th>Platform</th><th>Strategy</th><th>Command</th></tr></thead><tbody> <tr><td>macOS</td><td>Pure Nix build</td><td><code>nix run</code></td></tr> <tr><td>iOS</td><td>Nix + XcodeGen</td><td><code>nix run .#wawona-ios</code></td></tr> <tr><td>Android</td><td>Nix + GradleGen</td><td><code>nix run .#wawona-android</code></td></tr> </tbody></table> <p>The Rust backend is compiled via <strong>crate2nix</strong>, which generates per-crate Nix derivations for incremental caching. See <a href="/docs/compilation/">Compilation Reference</a> for details.</p> <hr /> <h2 id="next-steps">Next Steps</h2> <ul> <li><a href="/docs/getting-started/">Getting Started</a> — build and run Wawona</li> <li><a href="/docs/macos/">macOS Implementation</a> — deep dive into the Metal rendering pipeline</li> <li><a href="/docs/protocols/">Protocols</a> — detailed protocol implementation status</li> <li><a href="/docs/nix-build-system/">Nix Build System</a> — how the build pipeline works</li> </ul> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/compilation/ <h1 id="compilation-reference">Compilation Reference</h1> <p>Wawona uses <strong>Nix Flakes</strong> for all builds across macOS, iOS, and Android. Nix is the only build dependency — it manages the Rust toolchain, native C/C++ libraries, and app packaging.</p> <hr /> <h2 id="quick-build">Quick Build</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash"># macOS app — build and launch nix run # iOS Simulator — build, install, and launch nix run .#wawona-ios # Android — build APK, install, and launch nix run .#wawona-android </code></pre> <h2 id="build-only-no-launch">Build Only (No Launch)</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix build .#wawona-macos # macOS .app bundle nix build .#wawona-macos-backend # macOS Rust static library only nix build .#wawona-ios-backend # iOS device Rust static library nix build .#wawona-ios-sim-backend # iOS simulator Rust static library nix build .#wawona-android-backend # Android Rust shared library </code></pre> <hr /> <h2 id="project-generators">Project Generators</h2> <p>Generate IDE projects that reference the Nix-built libraries:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#xcodegen # Generate Wawona.xcodeproj (iOS + macOS) nix run .#xcodegen-ios # iOS target only nix run .#gradlegen # Generate Gradle project for Android </code></pre> <p>After generating, open the project in your IDE:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">open Wawona.xcodeproj # Xcode </code></pre> <p>See <a href="/docs/getting-started/">Getting Started — Team ID</a> for automatic code signing setup.</p> <hr /> <h2 id="common-nix-flags">Common Nix Flags</h2> <table><thead><tr><th>Flag</th><th>Purpose</th></tr></thead><tbody> <tr><td><code>-L</code></td><td>Show full build logs</td></tr> <tr><td><code>--show-trace</code></td><td>Stack trace on Nix evaluation errors</td></tr> <tr><td><code>--rebuild</code></td><td>Force rebuild (ignore cache)</td></tr> </tbody></table> <p>Example:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-ios -L --show-trace </code></pre> <hr /> <h2 id="debug-builds">Debug Builds</h2> <p>Add <code>--debug</code> to launch under LLDB:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-macos -- --debug # macOS — LLDB from start nix run .#wawona-ios -- --debug # iOS — pause at spawn, LLDB attaches nix run .#wawona-android -- --debug # Android — lldb-server, remote attach </code></pre> <p>See <a href="/docs/debugging/">Debugging Guide</a> for details.</p> <hr /> <h2 id="dev-shell">Dev Shell</h2> <p>Enter a full development environment with all tools pre-configured:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix develop </code></pre> <p>The dev shell provides:</p> <ul> <li>Rust toolchain with cross-compilation targets (iOS, Android)</li> <li><code>XDG_RUNTIME_DIR</code> and <code>WAYLAND_DISPLAY</code> pre-set</li> <li><code>TEAM_ID</code> loaded from <code>.envrc</code> for code signing</li> <li>All native libraries and build tools</li> </ul> <hr /> <h2 id="how-the-build-works">How the Build Works</h2> <p>The Nix build pipeline has three layers:</p> <pre><code>┌─────────────────────────────────────────────┐ │ Layer 3: App Packaging │ │ .app bundles, .xcodeproj, Gradle project │ ├─────────────────────────────────────────────┤ │ Layer 2: Rust Backend (crate2nix) │ │ Per-crate Nix derivations for incremental │ │ builds — only changed crates rebuild │ ├─────────────────────────────────────────────┤ │ Layer 1: Native C&#x2F;C++ Libraries │ │ libwayland, xkbcommon, ffmpeg, zstd, lz4, │ │ openssl, libssh2, etc. │ └─────────────────────────────────────────────┘ </code></pre> <p>Each crate and library is its own Nix derivation, cached independently. Changing a Rust source file only rebuilds the root <code>wawona</code> crate — all ~120 dependency crates are served from cache.</p> <p>For the full Nix pipeline deep dive, see <a href="/docs/nix-build-system/">Nix Build System</a>.</p> <hr /> <h2 id="requirements-summary">Requirements Summary</h2> <table><thead><tr><th>Requirement</th><th>When Needed</th></tr></thead><tbody> <tr><td>Apple Silicon Mac</td><td>Always</td></tr> <tr><td>Nix with flakes</td><td>Always (<a rel="noopener" target="_blank" href="https://determinate.systems/nix-installer/">Determinate Nix</a> recommended)</td></tr> <tr><td>Xcode</td><td>iOS builds</td></tr> <tr><td><code>.envrc</code> with <code>TEAM_ID</code></td><td>iOS device deployment</td></tr> <tr><td><code>adb</code> + Android emulator</td><td>Android builds</td></tr> </tbody></table> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/debugging/ <h1 id="debugging">Debugging</h1> <p>Launch Wawona under LLDB on macOS, iOS, or Android using the <code>--debug</code> flag.</p> <hr /> <h2 id="quick-reference">Quick Reference</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-macos -- --debug # macOS nix run .#wawona-ios -- --debug # iOS Simulator nix run .#wawona-android -- --debug # Android </code></pre> <hr /> <h2 id="macos">macOS</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-macos -- --debug </code></pre> <ul> <li>Wawona starts <strong>under LLDB</strong> from the beginning</li> <li>You can set breakpoints before typing <code>run</code></li> <li>On exit, LLDB prints a full backtrace (<code>bt all</code>)</li> <li><strong>Alternative:</strong> <code>WAWONA_LLDB=1 nix run .#wawona-macos</code></li> </ul> <hr /> <h2 id="ios-simulator">iOS Simulator</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-ios -- --debug </code></pre> <ol> <li>Simulator boots and Wawona.app is installed</li> <li>App launches with <code>--wait-for-debugger</code> (paused at spawn)</li> <li>LLDB attaches to the app PID</li> <li>dSYM is loaded for symbols (if present)</li> <li>Simulator logs stream in the background</li> </ol> <p>Type <code>continue</code> in LLDB to resume execution.</p> <hr /> <h2 id="android">Android</h2> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#wawona-android -- --debug </code></pre> <ol> <li>Emulator starts (or uses existing device)</li> <li>App launches with <code>am start -D</code> (waits for debugger)</li> <li><code>lldb-server</code> is pushed to the device and started</li> <li>LLDB connects via <code>gdb-remote</code> on port 5039</li> <li>Java VM resumes after ~4 seconds; native code runs under LLDB</li> </ol> <p><strong>Requirements:</strong> <code>adb</code> and <code>emulator</code> in PATH; device/emulator with USB debugging enabled.</p> <p>On crash, LLDB stops and gives an interactive prompt. Use <code>bt</code> for backtrace.</p> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/getting-started/ <h1 id="getting-started-with-wawona">Getting Started with Wawona</h1> <p>Wawona is a native Wayland compositor for <strong>macOS</strong>, <strong>iOS</strong>, and <strong>Android</strong>. Whether you want to run Wayland apps on your Mac or contribute to the project, this guide will get you up and running.</p> <hr /> <h2 id="for-users">For Users</h2> <blockquote> <p><strong>You do NOT need to install Nix.</strong> Nix is a developer tool for building Wawona from source. If you just want to <em>use</em> Wawona, read this section instead.</p> </blockquote> <h3 id="the-easy-way-app-store-play-store">The Easy Way: App Store &amp; Play Store</h3> <p>Wawona will be distributed as a native app on each platform:</p> <table><thead><tr><th>Platform</th><th>Where to Get It</th><th>Status</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>Mac App Store</td><td>Coming Soon</td></tr> <tr><td><strong>iOS / iPadOS</strong></td><td>App Store</td><td>Coming Soon</td></tr> <tr><td><strong>Android</strong></td><td>Google Play Store</td><td>Coming Soon</td></tr> </tbody></table> <p>Once available, simply download and install — no terminal, no build tools, no Nix. Just a regular app.</p> <blockquote> <p><strong>Visit the <a href="/download/">Downloads</a> page</strong> for the latest availability info.</p> </blockquote> <h3 id="while-we-re-still-in-development">While We're Still in Development…</h3> <p>Wawona is in active development (v0.2.x) and <strong>not yet available on public app stores</strong>. Here's how you can get involved right now:</p> <h4 id="join-the-ios-testflight-beta">Join the iOS TestFlight Beta</h4> <p>We have an active <strong>TestFlight</strong> for iOS beta testing. Join to get early access and help shape Wawona before launch:</p> <ol> <li>Join our <a rel="noopener" target="_blank" href="https://discord.gg/wHVSV52uw5">Discord server</a></li> <li>Request access to the TestFlight beta in the <code>#beta-testing</code> channel</li> <li>You'll receive a TestFlight invite link directly to your device</li> </ol> <h4 id="join-the-discord-community">Join the Discord Community</h4> <p>Stay up to date with development progress, ask questions, and share feedback:</p> <p>👉 <strong><a rel="noopener" target="_blank" href="https://discord.gg/wHVSV52uw5">discord.gg/wHVSV52uw5</a></strong></p> <h4 id="star-the-repository">Star the Repository</h4> <p>Follow development on GitHub to get notified of new releases:</p> <p>👉 <strong><a rel="noopener" target="_blank" href="https://github.com/Wawona/Wawona">github.com/Wawona/Wawona</a></strong></p> <blockquote> <p><strong>TL;DR:</strong> You do <strong>not</strong> need Nix, Rust, Xcode, or any developer tools. When Wawona ships, it will be a one-click install from the App Store or Play Store. Until then, join the <a rel="noopener" target="_blank" href="https://discord.gg/wHVSV52uw5">Discord</a> and the iOS <a rel="noopener" target="_blank" href="https://discord.gg/wHVSV52uw5">TestFlight</a> beta.</p> </blockquote> <hr /> <h2 id="for-developers">For Developers</h2> <blockquote> <p>Everything below this line is for people who want to <strong>build Wawona from source</strong> or contribute to the project. This requires Nix.</p> </blockquote> <h3 id="prerequisites">Prerequisites</h3> <table><thead><tr><th>Requirement</th><th>Notes</th></tr></thead><tbody> <tr><td><strong>Apple Silicon Mac</strong></td><td>M1, M2, M3, or M4</td></tr> <tr><td><strong>Nix</strong> (with flakes)</td><td><a rel="noopener" target="_blank" href="https://determinate.systems/nix-installer/">Determinate Nix</a> recommended</td></tr> <tr><td><strong>Xcode</strong></td><td>Required for iOS builds and code signing</td></tr> </tbody></table> <h3 id="build-run">Build &amp; Run</h3> <table><thead><tr><th>Command</th><th>What it does</th></tr></thead><tbody> <tr><td><code>nix run</code></td><td>Build + launch macOS app</td></tr> <tr><td><code>nix run .#wawona-ios</code></td><td>Build + launch on iOS Simulator</td></tr> <tr><td><code>nix run .#wawona-android</code></td><td>Build + install on Android device/emulator</td></tr> </tbody></table> <h3 id="build-only-no-launch">Build Only (No Launch)</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix build .#wawona-macos # macOS .app bundle nix build .#wawona-ios-backend # iOS Rust static library nix build .#wawona-android-backend # Android Rust shared library </code></pre> <h3 id="generate-xcode-project">Generate Xcode Project</h3> <p>To open the project in Xcode (for debugging, profiling, or deploying to a physical device):</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#xcodegen # Generate Wawona.xcodeproj (iOS + macOS targets) nix run .#xcodegen-ios # iOS target only open Wawona.xcodeproj </code></pre> <h3 id="generate-gradle-project-android">Generate Gradle Project (Android)</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#gradlegen </code></pre> <hr /> <h2 id="setting-up-your-team-id-ios-device-deployment">Setting Up Your Team ID (iOS Device Deployment)</h2> <p>To deploy Wawona to a physical iOS device, you need an Apple Development Team ID for code signing. Here's the workflow:</p> <h3 id="1-find-your-team-id">1. Find Your Team ID</h3> <p>If you don't know your Team ID, the easiest way to find it:</p> <ol> <li>Run <code>nix run .#xcodegen</code> to generate the Xcode project</li> <li>Open <code>Wawona.xcodeproj</code> in Xcode</li> <li>Go to <strong>Signing &amp; Capabilities</strong> for the Wawona-iOS target</li> <li>Sign in with your Apple ID and select your development team</li> <li>Xcode writes your Team ID into the <code>.xcodeproj</code> — you can find it there (look for <code>DEVELOPMENT_TEAM</code> in the <code>.pbxproj</code> file)</li> </ol> <h3 id="2-save-your-team-id">2. Save Your Team ID</h3> <p>Create a <code>.envrc</code> file in the project root (this file is gitignored):</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">echo &#x27;export TEAM_ID=&quot;YOUR_TEAM_ID_HERE&quot;&#x27; &gt; .envrc </code></pre> <p>Replace <code>YOUR_TEAM_ID_HERE</code> with the Team ID you found (e.g., <code>G6EJA4DJKW</code>).</p> <h3 id="3-use-the-dev-shell">3. Use the Dev Shell</h3> <p>Enter the Nix development shell, which automatically reads your Team ID from <code>.envrc</code>:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix develop </code></pre> <p>You'll see <code>Loaded TEAM_ID from .envrc.</code> confirming it worked.</p> <h3 id="4-generate-with-signing">4. Generate With Signing</h3> <p>Now, from inside the dev shell, run xcodegen:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#xcodegen </code></pre> <p>Your Team ID is automatically injected into the generated <code>.xcodeproj</code> — no need to manually navigate to Signing &amp; Capabilities in Xcode every time. Just open the project and build to your device.</p> <blockquote> <p><strong>Tip:</strong> Once your <code>.envrc</code> is set up, the workflow is just <code>nix develop</code> → <code>nix run .#xcodegen</code> → open in Xcode → build to device. Your signing identity is preserved across project regenerations.</p> </blockquote> <hr /> <h2 id="dev-shell">Dev Shell</h2> <p>The Nix dev shell provides a complete development environment with all tools and environment variables pre-configured:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix develop </code></pre> <p>This gives you:</p> <ul> <li>Rust toolchain with iOS, macOS, and Android cross-compilation targets</li> <li><code>XDG_RUNTIME_DIR</code> and <code>WAYLAND_DISPLAY</code> set for local testing</li> <li>Your <code>TEAM_ID</code> loaded from <code>.envrc</code> for code signing</li> <li>All native dependencies available</li> </ul> <hr /> <h2 id="useful-nix-flags">Useful Nix Flags</h2> <table><thead><tr><th>Flag</th><th>Purpose</th></tr></thead><tbody> <tr><td><code>-L</code></td><td>Show full build logs</td></tr> <tr><td><code>--show-trace</code></td><td>Stack trace on Nix evaluation errors</td></tr> <tr><td><code>--rebuild</code></td><td>Force rebuild (ignore cache)</td></tr> </tbody></table> <hr /> <h2 id="next-steps">Next Steps</h2> <ul> <li><a href="/docs/usage/">Usage Guide</a> — run Weston, waypipe, connect clients</li> <li><a href="/docs/architecture/">Architecture</a> — understand the Rust core + native frontend design</li> <li><a href="/docs/compilation/">Compilation Reference</a> — deep dive into the Nix build system</li> <li><a href="/docs/settings/">Settings Reference</a> — all configurable options</li> </ul> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/graphics/ <h1 id="graphics-drivers-validation">Graphics Drivers &amp; Validation</h1> <p>Vulkan, OpenGL, and Metal driver configuration for Wawona across macOS, iOS, and Android.</p> <hr /> <h2 id="quick-reference">Quick Reference</h2> <table><thead><tr><th>Platform</th><th>Native Vulkan?</th><th>Default Driver</th><th>Alternatives</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>No (Metal)</td><td>MoltenVK</td><td>KosmicKrisp</td></tr> <tr><td><strong>iOS</strong></td><td>No (Metal)</td><td>MoltenVK</td><td>KosmicKrisp</td></tr> <tr><td><strong>Android</strong></td><td>Yes</td><td>System</td><td>SwiftShader, Turnip</td></tr> </tbody></table> <hr /> <h2 id="driver-settings">Driver Settings</h2> <p>Configure graphics drivers in <strong>Settings → Graphics</strong>.</p> <h3 id="vulkan-drivers">Vulkan Drivers</h3> <table><thead><tr><th>Platform</th><th>Options</th><th>Default</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>None, MoltenVK, KosmicKrisp</td><td><code>moltenvk</code></td></tr> <tr><td><strong>iOS</strong></td><td>None, MoltenVK, KosmicKrisp</td><td><code>moltenvk</code></td></tr> <tr><td><strong>Android</strong></td><td>None, SwiftShader, Turnip, System</td><td><code>system</code></td></tr> </tbody></table> <ul> <li><strong>MoltenVK</strong> — Mature Vulkan-over-Metal implementation</li> <li><strong>KosmicKrisp</strong> — Mesa-based Vulkan-on-Metal (experimental)</li> <li><strong>SwiftShader</strong> — Software Vulkan renderer (fallback)</li> <li><strong>Turnip</strong> — Qualcomm Adreno Vulkan driver</li> </ul> <h3 id="opengl-drivers">OpenGL Drivers</h3> <table><thead><tr><th>Platform</th><th>Options</th><th>Default</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>None, ANGLE, MoltenGL</td><td><code>angle</code></td></tr> <tr><td><strong>iOS</strong></td><td>None, ANGLE</td><td><code>angle</code></td></tr> <tr><td><strong>Android</strong></td><td>None, ANGLE, System</td><td><code>system</code></td></tr> </tbody></table> <hr /> <h2 id="driver-validation-cts">Driver Validation (CTS)</h2> <p>Run Khronos Conformance Test Suites to validate your driver:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash"># Quick Vulkan probe (JSON output) nix run .#graphics-smoke # Full validation (smoke + Vulkan CTS + GL CTS) nix run .#graphics-validate-macos # iOS Vulkan CTS (in simulator) nix run .#vulkan-cts-ios # Android CTS (requires adb) nix run .#vulkan-cts-android nix run .#graphics-validate-android </code></pre> <h3 id="all-cts-outputs">All CTS Outputs</h3> <table><thead><tr><th>Output</th><th>Platform</th><th>Description</th></tr></thead><tbody> <tr><td><code>graphics-smoke</code></td><td>macOS</td><td>Vulkan probe, JSON output</td></tr> <tr><td><code>graphics-validate-macos</code></td><td>macOS</td><td>Full validation suite</td></tr> <tr><td><code>graphics-validate-ios</code></td><td>macOS host</td><td>iOS Simulator Vulkan CTS</td></tr> <tr><td><code>graphics-validate-android</code></td><td>Any</td><td>Android CTS via adb</td></tr> <tr><td><code>vulkan-cts</code></td><td>macOS</td><td>Khronos Vulkan CTS</td></tr> <tr><td><code>gl-cts</code></td><td>macOS</td><td>Khronos OpenGL/GLES CTS</td></tr> </tbody></table> <p>Results are saved in <code>./graphics-validate-results/</code>.</p> <hr /> <h2 id="macos-driver-override">macOS Driver Override</h2> <p>Override the Vulkan driver via environment variable:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash"># Use MoltenVK explicitly VK_DRIVER_FILES=&#x2F;path&#x2F;to&#x2F;MoltenVK_icd.json nix run .#graphics-smoke </code></pre> <hr /> <h2 id="ios-static-drivers">iOS Static Drivers</h2> <p>All iOS graphics drivers must be <strong>static libraries</strong> (<code>.a</code>) — dynamic libraries are not allowed by Apple.</p> <table><thead><tr><th>Driver</th><th>Purpose</th></tr></thead><tbody> <tr><td>KosmicKrisp</td><td>Vulkan over Metal</td></tr> <tr><td>MoltenVK</td><td>Vulkan over Metal</td></tr> <tr><td>ANGLE</td><td>OpenGL ES over Metal</td></tr> </tbody></table> <p>Only one Vulkan implementation can be linked at build time.</p> <hr /> <h2 id="troubleshooting">Troubleshooting</h2> <table><thead><tr><th>Issue</th><th>Fix</th></tr></thead><tbody> <tr><td>"No Vulkan loader"</td><td>Ensure vulkan-loader in closure; use MoltenVK or KosmicKrisp</td></tr> <tr><td>"deqp-vk not found"</td><td>Run <code>nix build .#vulkan-cts</code> first</td></tr> <tr><td>iOS simulator not booting</td><td>Install iOS runtime via Xcode: <code>xcrun simctl list runtimes</code></td></tr> <tr><td>Android "device offline"</td><td><code>adb kill-server &amp;&amp; adb start-server</code></td></tr> <tr><td>GL CTS missing data</td><td>Ensure <code>--deqp-archive-dir</code> points to built archive</td></tr> </tbody></table> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/macos/ <h1 id="macos-implementation">macOS Implementation</h1> <p>A deep dive into how Wawona achieves a native macOS experience while acting as a high-performance Wayland compositor.</p> <hr /> <h2 id="native-first">Native First</h2> <p>Wawona is not a port of a Linux compositor — it's a <strong>re-imagining of a Wayland compositor as a native Mac application</strong>. Every user-facing layer uses Apple's first-party frameworks:</p> <table><thead><tr><th>Component</th><th>Framework</th><th>What It Means</th></tr></thead><tbody> <tr><td><strong>Window Host</strong></td><td>AppKit (<code>NSWindow</code>)</td><td>Every Wayland app is a real macOS window</td></tr> <tr><td><strong>UI</strong></td><td>AppKit / UIKit</td><td>Settings, About panel use standard Cocoa controls</td></tr> <tr><td><strong>Graphics</strong></td><td>Metal</td><td>Apple's high-performance GPU API</td></tr> <tr><td><strong>Input</strong></td><td><code>NSEvent</code></td><td>macOS events translate directly to Wayland keycodes</td></tr> </tbody></table> <p>Because Wawona uses actual <code>NSWindow</code> objects, Wayland applications get native macOS window management — snapping, resizing, Mission Control, Stage Manager, and full-screen transitions all work out of the box.</p> <hr /> <h2 id="the-rendering-pipeline">The Rendering Pipeline</h2> <h3 id="surface-management">Surface Management</h3> <p>Each Wayland client creates surfaces. In Wawona, these map directly to CoreAnimation layers:</p> <ol> <li><strong><code>WawonaSurfaceLayer</code></strong> — Objective-C wrapper managing the surface lifecycle</li> <li><strong><code>CAMetalLayer</code></strong> — Hardware-accelerated rendering layer</li> </ol> <h3 id="zero-copy-via-iosurface">Zero-Copy via IOSurface</h3> <p>Wawona uses <code>IOSurface</code> for high-performance buffer sharing:</p> <ol> <li><strong>Client Submission</strong>: Wayland client writes pixel data to a shared buffer</li> <li><strong>Surface Wrapping</strong>: Wawona wraps the buffer in an <code>IOSurfaceRef</code>, accessible by the GPU</li> <li><strong>Zero-Copy Rendering</strong>: Metal reads directly from the <code>IOSurface</code> — no CPU copies</li> </ol> <p>This minimizes latency and battery drain.</p> <h3 id="metal-compositing">Metal Compositing</h3> <p>The final output is composited using custom Metal shaders:</p> <ul> <li><strong>MSL Shaders</strong>: Handle texture sampling, alpha blending, and scaling</li> <li><strong>V-Sync</strong>: <code>CVDisplayLink</code> synchronizes rendering with the display refresh rate</li> </ul> <hr /> <h2 id="the-rust-apple-bridge">The Rust–Apple Bridge</h2> <pre><code>┌─────────────────────────────────────┐ │ Apple Frontend (Objective-C) │ │ NSApplication → WawonaWindow → │ │ CompositorView → Metal Renderer │ └──────────────┬──────────────────────┘ │ ┌──────────────▼──────────────────────┐ │ Bridge (UniFFI &#x2F; C FFI) │ │ WawonaCompositorBridge │ └──────────────┬──────────────────────┘ │ ┌──────────────▼──────────────────────┐ │ Rust Core (src&#x2F;core&#x2F;*) │ │ Protocol Handler → Surface State │ │ → Client Management │ └─────────────────────────────────────┘ </code></pre> <ul> <li><strong>Rust Core</strong>: Manages Wayland protocol state and client communication</li> <li><strong>Objective-C Frontend</strong>: Manages window server integration, system events, and rendering</li> <li><strong>UniFFI</strong>: High-speed binding between Rust and Objective-C</li> </ul> <hr /> <h2 id="gpu-acceleration-dmabuf-via-iosurface">GPU Acceleration (DMABUF via IOSurface)</h2> <p>For hardware-accelerated clients (e.g., Weston with GL), Wawona implements a custom zero-copy path:</p> <ol> <li><strong>Allocation</strong>: Client (via Mesa/Waypipe) allocates an <code>IOSurface</code>, sends its global ID in the modifier field of <code>zwp_linux_dmabuf_v1</code></li> <li><strong>Intercept</strong>: Rust core detects the custom modifier, extracts the ID, creates <code>BufferType::Native</code></li> <li><strong>Scanout</strong>: ID passed to macOS frontend via FFI</li> <li><strong>Zero-Copy</strong>: Objective-C bridge performs <code>IOSurfaceLookup</code> and assigns directly to <code>CAMetalLayer.contents</code></li> </ol> <hr /> <h2 id="window-decorations">Window Decorations</h2> <p>Wawona implements <code>zxdg_decoration_manager_v1</code> with three policies:</p> <table><thead><tr><th>Policy</th><th>Behavior</th></tr></thead><tbody> <tr><td><strong>Prefer Client</strong></td><td>Client draws its own titlebar (CSD)</td></tr> <tr><td><strong>Prefer Server</strong></td><td>Wawona draws macOS-native titlebar (SSD)</td></tr> <tr><td><strong>Force Server</strong></td><td>Always use macOS titlebar, regardless of client preference</td></tr> </tbody></table> <p>When Force SSD is enabled, the compositor sends <code>configure(server_side)</code> and the host draws the only window chrome. Clients must not draw CSD.</p> <p>Configure in <strong>Settings → Display → Force Server-Side Decorations</strong>.</p> <hr /> <h2 id="liquid-glass">Liquid Glass</h2> <p>Wawona implements Apple's <strong>Liquid Glass</strong> design language using <code>NSVisualEffectView</code>, providing vibrant, translucent, depth-aware window chrome that adapts to content behind it.</p> <hr /> <h2 id="performance-benefits">Performance Benefits</h2> <ul> <li><strong>Low Latency</strong>: <code>IOSurface</code> + Metal bypass traditional buffer copy bottlenecks</li> <li><strong>Battery Efficiency</strong>: Native hardware acceleration reduces CPU overhead</li> <li><strong>System Integration</strong>: Full support for Mission Control, Stage Manager, keyboard shortcuts</li> <li><strong>Retina</strong>: Automatic HiDPI scaling via the compositor's Auto Scale setting</li> </ul> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/nix-build-system/ <h1 id="nix-build-system">Nix Build System</h1> <p>How Nix compiles everything in Wawona — from native C libraries to Rust backends to final app bundles for macOS, iOS, and Android.</p> <hr /> <h2 id="why-nix">Why Nix?</h2> <p>Nix provides <strong>hermetic, reproducible builds</strong> with a single dependency. No vendored source code, no global system pollution. Every artifact is content-addressed and cached independently.</p> <hr /> <h2 id="three-layer-architecture">Three-Layer Architecture</h2> <pre><code>┌──────────────────────────────────────────────────┐ │ Layer 3: App Packaging │ │ .app bundles, Xcode projects, Gradle projects │ ├──────────────────────────────────────────────────┤ │ Layer 2: Rust Backend (crate2nix) │ │ Per-crate Nix derivations for incremental │ │ builds — only changed crates rebuild │ ├──────────────────────────────────────────────────┤ │ Layer 1: Native C&#x2F;C++ Libraries │ │ libwayland, xkbcommon, ffmpeg, zstd, lz4, │ │ openssl, libssh2, mbedtls, etc. │ └──────────────────────────────────────────────────┘ </code></pre> <hr /> <h2 id="layer-1-native-libraries">Layer 1: Native Libraries</h2> <p>Each library has per-platform <code>.nix</code> files in <code>dependencies/libs/</code>:</p> <pre><code>dependencies&#x2F;libs&#x2F; ├── ffmpeg&#x2F; # android.nix, ios.nix, macos.nix ├── libssh2&#x2F; # android.nix, ios.nix ├── libwayland&#x2F; # android.nix, ios.nix, macos.nix ├── lz4&#x2F; # android.nix, ios.nix, macos.nix ├── openssl&#x2F; # android.nix, ios.nix ├── waypipe&#x2F; # ios.nix, macos.nix, android.nix ├── xkbcommon&#x2F; # android.nix, ios.nix, macos.nix ├── zstd&#x2F; # android.nix, ios.nix, macos.nix └── ... </code></pre> <p>The <code>dependencies/toolchains/default.nix</code> dispatcher exports:</p> <ul> <li><code>buildForIOS name entry</code> — dispatches to <code>libs/&lt;name&gt;/ios.nix</code></li> <li><code>buildForMacOS name entry</code> — dispatches to <code>libs/&lt;name&gt;/macos.nix</code></li> <li><code>buildForAndroid name entry</code> — dispatches to <code>libs/&lt;name&gt;/android.nix</code></li> </ul> <p>Each library is a standalone Nix derivation. Changing <code>zstd</code> does not rebuild <code>openssl</code>.</p> <hr /> <h2 id="layer-2-rust-backend-crate2nix">Layer 2: Rust Backend (crate2nix)</h2> <h3 id="why-crate2nix">Why crate2nix?</h3> <p>The previous <code>buildRustPackage</code> approach treated the entire workspace as a single derivation — any Rust change forced a full rebuild.</p> <p><strong>crate2nix</strong> generates a separate Nix derivation for every crate in <code>Cargo.lock</code>. Nix caches each independently. Changing one crate only rebuilds that crate and its reverse dependencies.</p> <h3 id="the-pipeline">The Pipeline</h3> <pre><code>Cargo.toml + Cargo.lock │ ▼ crate2nix generates Cargo.nix │ ▼ Per-crate Nix derivations (~120 crates) │ ▼ Final libwawona.a &#x2F; libwawona.so </code></pre> <h3 id="cross-compilation">Cross-Compilation</h3> <table><thead><tr><th>Platform</th><th>Cargo Target</th><th>Strategy</th></tr></thead><tbody> <tr><td>macOS</td><td>Native (no <code>--target</code>)</td><td>Direct build</td></tr> <tr><td>iOS device</td><td><code>aarch64-apple-ios</code></td><td>Override <code>stdenv.hostPlatform</code></td></tr> <tr><td>iOS simulator</td><td><code>aarch64-apple-ios-sim</code></td><td>Override <code>stdenv.hostPlatform</code></td></tr> <tr><td>Android</td><td><code>aarch64-linux-android</code></td><td>NDK toolchain via override</td></tr> </tbody></table> <p>For iOS/Android, Nix overrides <code>stdenv.hostPlatform</code> so that <code>buildRustCrate</code> correctly sets <code>TARGET</code>, <code>CARGO_CFG_TARGET_OS</code>, and the <code>--target</code> flag.</p> <h3 id="features-by-platform">Features by Platform</h3> <table><thead><tr><th>Platform</th><th>Enabled Features</th><th>Why</th></tr></thead><tbody> <tr><td>macOS</td><td>(none)</td><td>No waypipe in macOS backend</td></tr> <tr><td>iOS</td><td><code>waypipe-ssh</code></td><td>In-process waypipe with static libssh2</td></tr> <tr><td>Android</td><td><code>waypipe</code></td><td>In-process waypipe</td></tr> </tbody></table> <hr /> <h2 id="layer-3-app-packaging">Layer 3: App Packaging</h2> <h3 id="macos">macOS</h3> <p>Standard <code>mkDerivation</code> that compiles Obj-C sources and links against the Rust backend. Produces a <code>.app</code> bundle.</p> <h3 id="ios">iOS</h3> <p>Two stages:</p> <ol> <li><strong>Nix build</strong>: Compiles Obj-C, links <code>libwawona.a</code> + native C libs into <code>.app</code></li> <li><strong>Simulator automation</strong>: Generates Xcode project via <code>xcodegen.nix</code>, builds with <code>xcodebuild</code>, installs, launches, attaches LLDB</li> </ol> <h3 id="android">Android</h3> <p>Compiles JNI C code, links native libraries, bundles SSH binaries, and uses Gradle for final APK assembly.</p> <h3 id="project-generators">Project Generators</h3> <table><thead><tr><th>Generator</th><th>Nix Module</th><th>Output</th></tr></thead><tbody> <tr><td>XcodeGen</td><td><code>dependencies/generators/xcodegen.nix</code></td><td><code>Wawona.xcodeproj</code></td></tr> <tr><td>GradleGen</td><td><code>dependencies/generators/gradlegen.nix</code></td><td>Gradle project files</td></tr> </tbody></table> <hr /> <h2 id="caching-behavior">Caching Behavior</h2> <table><thead><tr><th>Change</th><th>Rebuild Scope</th></tr></thead><tbody> <tr><td>Rust source in <code>src/</code></td><td>Only <code>wawona</code> crate + final assembly</td></tr> <tr><td>Waypipe source</td><td><code>waypipe</code> crate + <code>wawona</code> crate</td></tr> <tr><td>Native C library (e.g. zstd)</td><td>That library + crates linking it</td></tr> <tr><td><code>flake.nix</code> or <code>rust-backend-c2n.nix</code></td><td>May invalidate crate2nix generation (full rebuild)</td></tr> <tr><td>Switch platform (e.g. iOS sim → device)</td><td>Full rebuild (target triple change)</td></tr> </tbody></table> <hr /> <h2 id="build-commands">Build Commands</h2> <table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody> <tr><td><code>nix run</code></td><td>macOS app (build + launch)</td></tr> <tr><td><code>nix run .#wawona-ios</code></td><td>iOS Simulator (xcodegen + build + run)</td></tr> <tr><td><code>nix run .#wawona-android</code></td><td>Android app</td></tr> <tr><td><code>nix build .#wawona-macos-backend</code></td><td>macOS Rust static library</td></tr> <tr><td><code>nix build .#wawona-ios-backend</code></td><td>iOS device Rust static library</td></tr> <tr><td><code>nix build .#wawona-ios-sim-backend</code></td><td>iOS sim Rust static library</td></tr> <tr><td><code>nix build .#wawona-android-backend</code></td><td>Android Rust shared library</td></tr> <tr><td><code>nix run .#xcodegen</code></td><td>Generate Xcode project (iOS + macOS)</td></tr> <tr><td><code>nix run .#xcodegen-ios</code></td><td>Generate Xcode project (iOS only)</td></tr> <tr><td><code>nix run .#gradlegen</code></td><td>Generate Gradle project</td></tr> </tbody></table> <hr /> <h2 id="flake-inputs">Flake Inputs</h2> <table><thead><tr><th>Input</th><th>Purpose</th></tr></thead><tbody> <tr><td><code>nixpkgs</code></td><td>Base package set (unstable)</td></tr> <tr><td><code>rust-overlay</code></td><td>Rust toolchain with iOS/Android targets</td></tr> <tr><td><code>crate2nix</code></td><td>Per-crate Nix derivation generator</td></tr> </tbody></table> <hr /> <h2 id="key-files">Key Files</h2> <table><thead><tr><th>File</th><th>Role</th></tr></thead><tbody> <tr><td><code>flake.nix</code></td><td>Top-level: inputs, overlays, all packages</td></tr> <tr><td><code>dependencies/wawona/rust-backend-c2n.nix</code></td><td>crate2nix Rust backend</td></tr> <tr><td><code>dependencies/wawona/workspace-src.nix</code></td><td>Cargo workspace assembly</td></tr> <tr><td><code>dependencies/wawona/ios.nix</code></td><td>iOS app bundle + simulator automation</td></tr> <tr><td><code>dependencies/wawona/macos.nix</code></td><td>macOS app bundle</td></tr> <tr><td><code>dependencies/wawona/android.nix</code></td><td>Android project</td></tr> <tr><td><code>dependencies/toolchains/default.nix</code></td><td>Platform dispatcher</td></tr> <tr><td><code>dependencies/generators/xcodegen.nix</code></td><td>Xcode project generator</td></tr> <tr><td><code>dependencies/generators/gradlegen.nix</code></td><td>Gradle project generator</td></tr> </tbody></table> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/protocols/ <h1 id="wayland-protocol-support">Wayland Protocol Support</h1> <p>Wawona registers <strong>68 protocol globals</strong> at compositor startup. This page documents the implementation status of each protocol.</p> <hr /> <h2 id="status-legend">Status Legend</h2> <table><thead><tr><th>Status</th><th>Meaning</th></tr></thead><tbody> <tr><td>✓ <strong>Functional</strong></td><td>Handles requests, mutates state, sends proper events</td></tr> <tr><td>~ <strong>Partial</strong></td><td>Global registered, some requests handled, incomplete semantics</td></tr> <tr><td>– <strong>Stub</strong></td><td>Global registered, request handlers log only (no state changes)</td></tr> </tbody></table> <p><strong>Summary:</strong> ~10 Functional, ~8 Partial, ~49 Stub</p> <hr /> <h2 id="core-protocols-6">Core Protocols (6)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>wl_compositor</code> v6</td><td>✓ Functional</td><td>Surface creation, commit, frame callbacks</td></tr> <tr><td><code>wl_shm</code> v1</td><td>✓ Functional</td><td>Pool creation, buffer creation, mmap</td></tr> <tr><td><code>wl_seat</code> v8</td><td>~ Partial</td><td>Keyboard/pointer/touch binding works; XKB uses hardcoded minimal keymap fallback</td></tr> <tr><td><code>wl_output</code> v3</td><td>✓ Functional</td><td>Mode, geometry, scale, done events</td></tr> <tr><td><code>wl_subcompositor</code> v1</td><td>~ Partial</td><td>Subsurface creation tracked; z-order and sync/desync partially implemented</td></tr> <tr><td><code>wl_data_device_manager</code> v3</td><td>~ Partial</td><td>Data source/device creation; selection and DnD logic incomplete</td></tr> </tbody></table> <hr /> <h2 id="xdg-protocols-9">XDG Protocols (9)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>xdg_wm_base</code> v5</td><td>✓ Functional</td><td>Surface/toplevel/popup lifecycle, configure/ack, ping/pong</td></tr> <tr><td><code>zxdg_decoration_manager_v1</code></td><td>✓ Functional</td><td>CSD/SSD negotiation, mode switching, Force SSD support</td></tr> <tr><td><code>zxdg_output_manager_v1</code></td><td>~ Partial</td><td>Logical position/size sent; updates on output change incomplete</td></tr> <tr><td><code>xdg_activation_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>xdg_wm_dialog_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>xdg_toplevel_drag_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>xdg_toplevel_icon_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zxdg_exporter_v2</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zxdg_importer_v2</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="wlroots-protocols-10">wlroots Protocols (10)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>zwlr_layer_shell_v1</code></td><td>~ Partial</td><td>Layer surface creation tracked; anchor/margin/exclusive zone stored</td></tr> <tr><td><code>zwlr_output_management_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_output_power_management_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_foreign_toplevel_management_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_screencopy_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_gamma_control_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_data_control_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_export_dmabuf_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwlr_virtual_pointer_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_virtual_keyboard_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="buffer-sync-5">Buffer &amp; Sync (5)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>zwp_linux_dmabuf_v1</code> v4</td><td>~ Partial</td><td>Params creation tracked; IOSurface path for macOS exists; feedback stubbed</td></tr> <tr><td><code>zwp_linux_explicit_synchronization_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_single_pixel_buffer_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_linux_drm_syncobj_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_drm_lease_device_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="input-interaction-10">Input &amp; Interaction (10)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>zwp_relative_pointer_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_pointer_constraints_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_pointer_gestures_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_tablet_manager_v2</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_text_input_manager_v3</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_keyboard_shortcuts_inhibit_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_cursor_shape_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_primary_selection_device_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_input_timestamps_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_pointer_warp_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="presentation-timing-8">Presentation &amp; Timing (8)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>wp_presentation</code></td><td>~ Partial</td><td>Feedback collection exists; presentation events incomplete</td></tr> <tr><td><code>wp_viewporter</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_fractional_scale_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_fifo_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_tearing_control_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_commit_timing_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_content_type_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_color_representation_manager_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="session-security-5">Session &amp; Security (5)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>zwp_idle_inhibit_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_session_lock_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_idle_notifier_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>wp_security_context_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_transient_seat_manager_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="desktop-integration-4">Desktop Integration (4)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>wp_alpha_modifier_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_foreign_toplevel_list_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_workspace_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_background_effect_manager_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="screen-capture-xwayland-4">Screen Capture &amp; XWayland (4)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>ext_output_image_capture_source_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>ext_image_copy_capture_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>zwp_xwayland_keyboard_grab_manager_v1</code></td><td>– Stub</td><td></td></tr> <tr><td><code>xwayland_shell_v1</code></td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="kde-plasma-protocols-7">KDE / Plasma Protocols (7)</h2> <table><thead><tr><th>Protocol</th><th>Status</th><th>Notes</th></tr></thead><tbody> <tr><td><code>org_kde_kwin_server_decoration_manager</code></td><td>– Stub</td><td></td></tr> <tr><td>Blur manager</td><td>– Stub</td><td></td></tr> <tr><td>Contrast manager</td><td>– Stub</td><td></td></tr> <tr><td>Shadow manager</td><td>– Stub</td><td></td></tr> <tr><td>DPMS manager</td><td>– Stub</td><td></td></tr> <tr><td>Idle timeout</td><td>– Stub</td><td></td></tr> <tr><td>Slide manager</td><td>– Stub</td><td></td></tr> </tbody></table> <hr /> <h2 id="notes">Notes</h2> <p>All 68 protocol globals are registered correctly at compositor startup. The issue for stub protocols is not registration — it's that request handlers need semantic implementation (state mutations, response events, error handling). Currently, stub handlers log incoming requests via <code>tracing::debug!()</code> but do not implement protocol semantics.</p> <p>Contributing protocol implementations is one of the most impactful ways to help Wawona. See the <a href="/docs/architecture/">Architecture</a> page for how protocol modules are structured.</p> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/settings/ <h1 id="settings-reference">Settings Reference</h1> <p>All configurable settings in Wawona, organized by category. Settings are available on macOS, iOS, and Android unless noted otherwise.</p> <hr /> <h2 id="display">Display</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Platforms</th><th>Description</th></tr></thead><tbody> <tr><td><strong>Force Server-Side Decorations</strong></td><td>Off (macOS/iOS), On (Android)</td><td>All</td><td>Compositor draws window borders; clients don't draw their own titlebar</td></tr> <tr><td><strong>Auto Scale</strong></td><td>On</td><td>All</td><td>Match platform UI scaling (Retina, Android density)</td></tr> <tr><td><strong>Respect Safe Area</strong></td><td>On</td><td>All</td><td>Avoid notches, Dynamic Island, display cutouts</td></tr> <tr><td><strong>Show macOS Cursor</strong></td><td>Off</td><td>macOS</td><td>Toggle visibility of the macOS system cursor</td></tr> </tbody></table> <hr /> <h2 id="graphics">Graphics</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Platforms</th><th>Description</th></tr></thead><tbody> <tr><td><strong>Vulkan Driver</strong></td><td><code>moltenvk</code> (macOS/iOS), <code>system</code> (Android)</td><td>All</td><td>Vulkan implementation. macOS/iOS: None, MoltenVK, KosmicKrisp. Android: None, SwiftShader, Turnip, System</td></tr> <tr><td><strong>OpenGL Driver</strong></td><td><code>angle</code> (macOS/iOS), <code>system</code> (Android)</td><td>All</td><td>OpenGL/GLES implementation. macOS: None, ANGLE, MoltenGL. iOS: None, ANGLE. Android: None, ANGLE, System</td></tr> <tr><td><strong>DmaBuf Support</strong></td><td>On</td><td>All</td><td>Zero-copy texture sharing between clients</td></tr> </tbody></table> <hr /> <h2 id="input">Input</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Platforms</th><th>Description</th></tr></thead><tbody> <tr><td><strong>Touch Input Type</strong></td><td>Multi-Touch</td><td>iOS</td><td>Multi-Touch (direct) or Touchpad mode (1-finger = pointer, tap = click, 2-finger = scroll)</td></tr> <tr><td><strong>Touchpad Mode</strong></td><td>Off</td><td>Android</td><td>Same behavior as Touchpad on iOS</td></tr> <tr><td><strong>Swap CMD with ALT</strong></td><td>On</td><td>macOS, iOS</td><td>Swap Command and Alt keys for Wayland clients</td></tr> <tr><td><strong>Universal Clipboard</strong></td><td>On</td><td>All</td><td>Sync clipboard with host platform</td></tr> <tr><td><strong>Enable Text Assist</strong></td><td>Off</td><td>All</td><td>Autocorrect, suggestions, smart punctuation</td></tr> <tr><td><strong>Enable Dictation</strong></td><td>Off</td><td>All</td><td>Voice dictation to focused Wayland client</td></tr> </tbody></table> <hr /> <h2 id="connection">Connection</h2> <p><em>macOS and iOS only.</em></p> <table><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody> <tr><td><strong>XDG_RUNTIME_DIR</strong></td><td>Runtime directory for Wayland socket (read-only)</td></tr> <tr><td><strong>WAYLAND_DISPLAY</strong></td><td>Socket name, e.g. <code>wayland-0</code> (read-only)</td></tr> <tr><td><strong>Socket Path</strong></td><td>Full path to Wayland socket (read-only)</td></tr> <tr><td><strong>Shell Setup</strong></td><td>Copy-paste <code>export</code> commands for your terminal (read-only)</td></tr> <tr><td><strong>TCP Port</strong></td><td>Port for TCP listener (default: 6000)</td></tr> </tbody></table> <hr /> <h2 id="advanced">Advanced</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Platforms</th><th>Description</th></tr></thead><tbody> <tr><td><strong>Color Operations</strong></td><td>Off (macOS/iOS), On (Android)</td><td>All</td><td>Color profiles, HDR requests</td></tr> <tr><td><strong>Nested Compositors</strong></td><td>On</td><td>All</td><td>Support nested Wayland compositors</td></tr> <tr><td><strong>Multiple Clients</strong></td><td>On (macOS), Off (mobile)</td><td>All</td><td>Allow multiple Wayland clients simultaneously</td></tr> <tr><td><strong>Enable Launcher</strong></td><td>Off</td><td>All</td><td>Start built-in Wayland shell</td></tr> <tr><td><strong>Enable Native Weston</strong></td><td>Off</td><td>All</td><td>Start full Weston compositor on launch</td></tr> <tr><td><strong>Enable Weston Terminal</strong></td><td>Off</td><td>All</td><td>Start weston-terminal on launch</td></tr> <tr><td><strong>Enable Weston Simple SHM</strong></td><td>Off</td><td>All</td><td>Start weston-simple-shm on launch</td></tr> </tbody></table> <hr /> <h2 id="waypipe">Waypipe</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Description</th></tr></thead><tbody> <tr><td><strong>Display Number</strong></td><td>0</td><td>Display number (0 = wayland-0)</td></tr> <tr><td><strong>Socket Path</strong></td><td>Platform-specific</td><td>Unix socket path</td></tr> <tr><td><strong>Compression</strong></td><td>lz4</td><td>none, lz4, zstd</td></tr> <tr><td><strong>Compression Level</strong></td><td>7</td><td>Zstd level (1–22)</td></tr> <tr><td><strong>Threads</strong></td><td>0 (auto)</td><td>Worker thread count</td></tr> <tr><td><strong>Video Compression</strong></td><td>none</td><td>none, h264, vp9, av1</td></tr> <tr><td><strong>Remote Command</strong></td><td>—</td><td>Command to run remotely (e.g. <code>weston-terminal</code>)</td></tr> <tr><td><strong>Debug Mode</strong></td><td>Off</td><td>Verbose waypipe logging</td></tr> <tr><td><strong>Disable GPU</strong></td><td>Off</td><td>Force software rendering</td></tr> <tr><td><strong>One-shot</strong></td><td>Off</td><td>Exit when client disconnects</td></tr> <tr><td><strong>Login Shell</strong></td><td>Off</td><td>Run in login shell on remote</td></tr> </tbody></table> <hr /> <h2 id="ssh">SSH</h2> <table><thead><tr><th>Setting</th><th>Default</th><th>Description</th></tr></thead><tbody> <tr><td><strong>SSH Host</strong></td><td>—</td><td>Remote host IP or hostname</td></tr> <tr><td><strong>SSH User</strong></td><td>—</td><td>SSH username</td></tr> <tr><td><strong>Auth Method</strong></td><td>Password</td><td>Password or Public Key</td></tr> <tr><td><strong>Password</strong></td><td>—</td><td>SSH password</td></tr> <tr><td><strong>Key Path</strong></td><td><code>~/.ssh/id_ed25519</code></td><td>Path to private key</td></tr> <tr><td><strong>Key Passphrase</strong></td><td>—</td><td>Passphrase for encrypted key</td></tr> </tbody></table> <hr /> <h2 id="platform-defaults-summary">Platform Defaults Summary</h2> <table><thead><tr><th>Setting</th><th>macOS</th><th>iOS</th><th>Android</th></tr></thead><tbody> <tr><td>Force SSD</td><td>Off</td><td>Off</td><td>On</td></tr> <tr><td>Multiple Clients</td><td>On</td><td>Off</td><td>Off</td></tr> <tr><td>Vulkan Driver</td><td>moltenvk</td><td>moltenvk</td><td>system</td></tr> <tr><td>OpenGL Driver</td><td>angle</td><td>angle</td><td>system</td></tr> </tbody></table> <hr /> <h2 id="storage">Storage</h2> <ul> <li><strong>macOS / iOS</strong>: <code>NSUserDefaults</code> (UserDefaults)</li> <li><strong>Android</strong>: <code>SharedPreferences</code></li> </ul> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/usage/ <h1 id="usage-guide">Usage Guide</h1> <p>How to run Wayland apps with Wawona — locally and remotely.</p> <hr /> <h2 id="native-weston-on-macos">Native Weston on macOS</h2> <p>Wawona includes a <strong>native port of Weston</strong> for macOS. No Linux, no VM — Weston runs as a nested compositor client inside Wawona.</p> <h3 id="weston-full-compositor">Weston (Full Compositor)</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#weston </code></pre> <p>Launches the full Weston compositor as a nested client inside Wawona's Wayland session.</p> <h3 id="weston-terminal">Weston Terminal</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#weston-terminal </code></pre> <p>Launches Weston Terminal — a native Wayland terminal client connected to Wawona's display.</p> <h3 id="other-weston-clients">Other Weston Clients</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#weston-debug # Weston debug client nix run .#weston-simple-shm # Simple SHM test client </code></pre> <h3 id="enable-bundled-clients-from-settings">Enable Bundled Clients From Settings</h3> <p>You can also enable Weston and other bundled clients to <strong>auto-launch</strong> when Wawona starts — no terminal needed:</p> <ol> <li>Open <strong>Wawona</strong> → <strong>Settings</strong> → <strong>Advanced</strong></li> <li>Toggle on any combination: <ul> <li><strong>Enable Native Weston</strong> — starts the full Weston nested compositor</li> <li><strong>Enable Weston Terminal</strong> — starts a weston-terminal client</li> <li><strong>Enable Weston Simple SHM</strong> — starts the simple SHM test client</li> </ul> </li> </ol> <p>This works on <strong>macOS, iOS, and Android</strong> — useful when you don't have terminal access (mobile) or want clients to start automatically.</p> <hr /> <h2 id="connecting-wayland-clients-locally">Connecting Wayland Clients Locally</h2> <p>When Wawona is running, any Wayland client can connect via the Wayland socket.</p> <h3 id="set-up-your-shell">Set Up Your Shell</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">export XDG_RUNTIME_DIR=&quot;&#x2F;tmp&#x2F;wawona-$(id -u)&quot; export WAYLAND_DISPLAY=&quot;wayland-0&quot; </code></pre> <p>You can also find these values in <strong>Settings → Connection</strong> inside the Wawona app.</p> <h3 id="run-a-client">Run a Client</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash"># With the exports above, run any Wayland client: nix run .#weston-terminal nix run .#foot </code></pre> <hr /> <h2 id="waypipe-remote-wayland-apps">Waypipe: Remote Wayland Apps</h2> <p>Waypipe forwards Wayland applications over SSH. Run apps on a remote machine and display them on your device.</p> <h3 id="quick-start-macos">Quick Start (macOS)</h3> <ol> <li>Make sure Wawona is running</li> <li>Set up your shell (see above)</li> <li>Run waypipe:</li> </ol> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">nix run .#waypipe -- ssh user@remote-host weston-terminal </code></pre> <h3 id="quick-start-ios-android">Quick Start (iOS / Android)</h3> <ol> <li>Open <strong>Wawona</strong> → <strong>Settings</strong> → <strong>Waypipe</strong></li> <li>Set <strong>SSH Host</strong>, <strong>SSH User</strong>, <strong>SSH Password</strong></li> <li>Set <strong>Remote Command</strong> (e.g., <code>nix run ~/Wawona#weston-terminal</code>)</li> <li>Tap <strong>Start Waypipe</strong></li> </ol> <h3 id="remote-command-examples">Remote Command Examples</h3> <table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody> <tr><td><code>nix run ~/Wawona#weston-terminal</code></td><td>Weston Terminal (if Wawona repo on remote)</td></tr> <tr><td><code>weston-terminal</code></td><td>Weston Terminal (if installed on remote)</td></tr> <tr><td><code>foot</code></td><td>Foot terminal</td></tr> <tr><td><code>nix run ~/Wawona#weston</code></td><td>Full Weston compositor</td></tr> <tr><td><code>gnome-calculator</code></td><td>GNOME Calculator</td></tr> </tbody></table> <h3 id="prepare-a-remote-mac">Prepare a Remote Mac</h3> <p>If your remote host is a Mac:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">bash scripts&#x2F;prepare_mac_remote.sh </code></pre> <p>This verifies Remote Login (SSH) is enabled, Waypipe is available, and Weston Terminal is buildable.</p> <p>For detailed waypipe configuration, see <a href="/docs/waypipe/">Waypipe Guide</a>.</p> <hr /> <h2 id="platform-notes">Platform Notes</h2> <table><thead><tr><th>Platform</th><th>Local Weston</th><th>Waypipe Transport</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td><code>nix run .#weston</code>, <code>.#weston-terminal</code></td><td>OpenSSH (process spawn)</td></tr> <tr><td><strong>iOS</strong></td><td>Via Settings → Advanced toggles</td><td>libssh2 (in-process)</td></tr> <tr><td><strong>Android</strong></td><td>Via Settings → Advanced toggles</td><td>Dropbear SSH (fork/exec)</td></tr> </tbody></table> <p>On iOS and Android, enable <strong>Native Weston</strong> and <strong>Weston Terminal</strong> in <strong>Settings → Advanced</strong> to auto-launch on app start.</p> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /docs/waypipe/ <h1 id="waypipe-guide">Waypipe Guide</h1> <p>Waypipe forwards Wayland applications over SSH. Run apps on a remote Linux or Mac machine and display them on your device running Wawona.</p> <hr /> <h2 id="platform-overview">Platform Overview</h2> <table><thead><tr><th>Platform</th><th>SSH Transport</th><th>Buffer Path</th><th>Status</th></tr></thead><tbody> <tr><td><strong>macOS</strong></td><td>OpenSSH (process spawn)</td><td>IOSurface → Metal</td><td>Working</td></tr> <tr><td><strong>iOS</strong></td><td>libssh2 (in-process)</td><td>IOSurface → Metal</td><td>Working</td></tr> <tr><td><strong>Android</strong></td><td>Dropbear SSH (fork/exec)</td><td>SHM → Vulkan</td><td>Working</td></tr> </tbody></table> <hr /> <h2 id="quick-start">Quick Start</h2> <h3 id="macos-command-line">macOS (Command Line)</h3> <p>With Wawona running:</p> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">export XDG_RUNTIME_DIR=&quot;&#x2F;tmp&#x2F;wawona-$(id -u)&quot; export WAYLAND_DISPLAY=&quot;wayland-0&quot; nix run .#waypipe -- ssh user@remote-host weston-terminal </code></pre> <h3 id="ios-android-in-app">iOS / Android (In-App)</h3> <ol> <li>Open <strong>Wawona</strong> → <strong>Settings</strong> → <strong>Waypipe</strong> (or <strong>SSH</strong>)</li> <li><strong>SSH Host</strong>: IP address or hostname of the remote machine</li> <li><strong>SSH User</strong>: Your username on the remote</li> <li><strong>SSH Password</strong>: Your login password (or configure Public Key auth)</li> <li><strong>Remote Command</strong>: The app to run, e.g., <code>nix run ~/Wawona#weston-terminal</code></li> <li>Tap <strong>Start Waypipe</strong></li> </ol> <h3 id="prepare-a-remote-mac">Prepare a Remote Mac</h3> <pre data-lang="bash" class="language-bash "><code class="language-bash" data-lang="bash">bash scripts&#x2F;prepare_mac_remote.sh </code></pre> <p>This checks that Remote Login (SSH) is enabled, Python 3 is installed, and Waypipe is available.</p> <hr /> <h2 id="remote-command-examples">Remote Command Examples</h2> <table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody> <tr><td><code>nix run ~/Wawona#weston-terminal</code></td><td>Weston Terminal (Wawona repo on remote)</td></tr> <tr><td><code>weston-terminal</code></td><td>Weston Terminal (if installed)</td></tr> <tr><td><code>foot</code></td><td>Foot terminal</td></tr> <tr><td><code>nix run ~/Wawona#weston</code></td><td>Full Weston compositor</td></tr> <tr><td><code>geary</code></td><td>Geary email client</td></tr> <tr><td><code>gnome-calculator</code></td><td>GNOME Calculator</td></tr> </tbody></table> <hr /> <h2 id="how-it-works">How It Works</h2> <h3 id="macos">macOS</h3> <p>Waypipe runs as a local process that connects to Wawona's Wayland socket, then spawns an SSH connection to the remote host. The remote waypipe server captures Wayland protocol data and forwards it through the SSH tunnel.</p> <p>Buffer sharing uses <strong>IOSurface</strong> for zero-copy Metal rendering.</p> <h3 id="ios-libssh2-streamlocal">iOS — libssh2 + Streamlocal</h3> <p>iOS can't spawn processes, so Wawona uses <strong>libssh2</strong> in-process with <code>streamlocal-forward@openssh.com</code>:</p> <pre><code>iOS App SSH Remote ────────────────────────────────────────────────────────────────── 1. connect_ssh2() ├── TCP connect + handshake + auth ├── streamlocal-forward ──────► sshd creates │ (path=&#x2F;tmp&#x2F;wp-XXX.sock) &#x2F;tmp&#x2F;wp-XXX.sock │ ├── exec channel: ──────────► waypipe --socket │ waypipe server -- &lt;app&gt; &#x2F;tmp&#x2F;wp-XXX.sock │ server -- &lt;app&gt; │ └── bridge thread: pumps data forwarded channel ↔ local socket </code></pre> <p><strong>Remote requirements:</strong> Stock waypipe + OpenSSH ≥ 6.7. No socat, nc, or patched tools needed.</p> <h3 id="android-dropbear-ssh">Android — Dropbear SSH</h3> <p>Android bundles <strong>Dropbear SSH</strong> (lightweight SSH client) as a static ARM64 executable:</p> <ol> <li>SSH binaries packaged as <code>libssh_bin.so</code> / <code>libsshpass_bin.so</code> in the APK</li> <li>Android extracts them at install time</li> <li>Waypipe Rust backend exposes <code>waypipe_main()</code> for JNI</li> <li>SSH bridge thread: <code>fork()</code> → <code>exec(dbclient)</code> with <code>SSHPASS</code> env</li> </ol> <hr /> <h2 id="compression">Compression</h2> <table><thead><tr><th>Option</th><th>Speed</th><th>Ratio</th><th>Use Case</th></tr></thead><tbody> <tr><td><strong>none</strong></td><td>Fastest</td><td>1:1</td><td>Local network</td></tr> <tr><td><strong>lz4</strong> (default)</td><td>Fast</td><td>Good</td><td>General use</td></tr> <tr><td><strong>zstd</strong></td><td>Slower</td><td>Better</td><td>Slow connections</td></tr> </tbody></table> <p>Configure in <strong>Settings → Waypipe → Compression</strong>.</p> <hr /> <h2 id="troubleshooting">Troubleshooting</h2> <table><thead><tr><th>Issue</th><th>Fix</th></tr></thead><tbody> <tr><td>"streamlocal-forward failed"</td><td>Check <code>AllowStreamLocalForwarding</code> in <code>sshd_config</code> (default: yes)</td></tr> <tr><td>"Timed out waiting for channel"</td><td>Verify waypipe is installed and in PATH on remote</td></tr> <tr><td>"Missing Wayland socket"</td><td>Start a Wayland compositor on the remote first</td></tr> <tr><td>Remote command not found</td><td>Use full path: <code>nix run ~/Wawona#weston-terminal</code></td></tr> <tr><td>Black screen after connect</td><td>Check that the remote app supports Wayland</td></tr> </tbody></table> 2026-02-22T00:00:00+00:00 2026-02-22T00:00:00+00:00 Unknown /posts/introducing-wawona/ <p>Wawona isn’t just another display server—it is a native Wayland substrate designed from the ground up for the Apple and Android ecosystems. We are bringing high-performance, bare-metal Wayland execution to the hardware where it was previously impossible.</p> <h2 id="why-wawona">Why Wawona?</h2> <p>For years, running Wayland applications on a Mac meant living in a Virtual Machine or a slow emulation layer. Wawona changes that. By implementing a native Wayland compositor in Rust and targeting platform-native graphics APIs, we provide a bridge between the Linux ecosystem and Apple/Android hardware without the overhead of a guest OS.</p> <h2 id="high-performance-architecture">High-Performance Architecture</h2> <p>Wawona is built on three core pillars that ensure it feels like a first-class citizen on every platform it touches:</p> <h3 id="1-the-rust-core">1. The Rust Core</h3> <p>The heart of Wawona is a shared Rust backend managing the complex state of a Wayland compositor. With over <strong>186 Rust crates</strong> integrated into our core, we handle everything from protocol registration to internal surface management with memory safety and high concurrency.</p> <h3 id="2-native-graphics-frontends">2. Native Graphics Frontends</h3> <p>We don't rely on generic abstraction layers.</p> <ul> <li><strong>Liquid Glass (macOS &amp; iOS)</strong>: A bespoke Metal-based rendering engine that leverages <strong>zero-copy IOSurface integration</strong> for near-instant frame delivery.</li> <li><strong>Android Vulkan</strong>: A specialized Vulkan frontend designed for the mobile GPU pipeline.</li> </ul> <h3 id="3-the-nix-build-system">3. The Nix Build System</h3> <p>Developing across Three platforms (macOS, iOS, Android) usually requires a nightmare of SDK management. Wawona uses <strong>Nix</strong> to provide a hermetic, reproducible environment. We cross-compile <strong>27 native C/C++ libraries</strong> (like FFmpeg, OpenSSL, and Weston) for every target automatically.</p> <h2 id="beyond-macos">Beyond macOS</h2> <p>While Wawona started as a macOS project, our vision is multi-platform.</p> <ul> <li><strong>iOS</strong>: A native iPadOS/iOS app that turns your mobile device into a portable Wayland workstation.</li> <li><strong>Android</strong>: A Kotlin/JNI frontend that bundles its own Dropbear SSH and Vulkan rendering stack.</li> </ul> <h2 id="getting-started">Getting Started</h2> <p>Wawona is currently in active development (v0.2.x). Whether you are looking to run remote apps via <strong>Waypipe</strong> or test native Wayland clients locally, we are building the fastest way to bridge your Linux-style workflows into the hardware you love.</p> <p><a href="/docs/getting-started/">Read our Documentation</a> to start building, or check the <a href="/faq/">FAQ</a> for deep-dives into our architecture.</p>