════════════════════════════════════════════════════════════════════════
  BUILDING GNOMAD FOR MACOS, LINUX, AND WINDOWS
  Gnomad Desktop Assistant · docs/BUILD_PLATFORMS.md
════════════════════════════════════════════════════════════════════════

BUILDING GNOMAD FOR MACOS, LINUX, AND WINDOWS
=============================================

PREREQUISITES (ALL PLATFORMS)
-----------------------------

  • Node.js LTS
  • Rust stable (rustup)
  • Platform SDKs for the OS you are building on (cross-compiling is possible but not covered here)

  [bash]
    npm install
    npm run build

MACOS
-----

  [bash]
    npm run tauri:build:mac

Output: src-tauri/target/release/bundle/macos/Gnomad.app

  • Panel / Pop out: menu-bar accessory, in-app toolbar
  • Windowed: full menu bar (Gnomad, File, Edit, View, Window, Help), Gemini-style body without duplicate toolbar
  • Close button hides to menu bar; Quit from tray menu

Notarization (v1.0): CI builds are unsigned for Gatekeeper until Apple Developer ID secrets are configured. See MACOS_NOTARIZATION.md and npm run notarize:macos.

CROSS-PLATFORM PARITY (MACOS, WINDOWS, LINUX)
---------------------------------------------

The same React UI ships in every build: chat, attachments, API keys (keychain / Credential Manager / Secret Service), cursor bloom, knowledge base, settings, and window modes (tray panel, pop-out, windowed, fullscreen).

  Area                   |  macOS                        |  Windows                                                       |  Linux                     
  Tray / status area     |  Menu bar icon                |  System tray                                                   |  System tray (AppIndicator)
  Global shortcut        |  ⌘⇧Space                      |  Ctrl+Shift+Space                                              |  Ctrl+Shift+Space          
  Panel placement        |  Under menu bar / tray click  |  Top-right near tray (or under tray click)                     |  Same as Windows           
  Title bar              |  Overlay + in-app toolbar     |  Native caption; toolbar hidden in Windowed (menus in OS bar)  |  Same as Windows           
  Active window context  |  AppleScript                  |  PowerShell + Win32                                            |  xdotool (optional)        
  Clipboard context      |  pbpaste                      |  PowerShell Get-Clipboard                                      |  wl-paste / xclip          
  API keys               |  Keychain                     |  Credential Manager                                            |  Secret Service            
  Admin commands         |  osascript sudo               |  User runs elevated terminal                                   |  pkexec                    

Optional Linux packages for full context pills: xdotool (X11), wl-paste (Wayland) or xclip.

CI (.github/workflows/build.yml) builds macOS, Linux x86_64, Linux ARM64, and Windows on every push to main / master.

Cross-platform verification (features & UI tweaks)

Whenever you add or change UI, settings, or OS-facing behavior, use CROSS_PLATFORM_CHECKLIST.md so work on macOS translates—or is explicitly handled—for Windows and Linux.

Quick rules:

  1. Shared React (src/) — same bundle everywhere; smoke panel and windowed on Win/Linux (toolbar may be hidden in windowed).
  2. Platform shell (title bar, tray, shortcuts) — update platform.rs, window_manager.rs, and .platform-* CSS in index.css.
  3. Before merge — npm run build, cargo test, CI green on all three OS jobs.

LINUX
-----

Build on a Linux host (Ubuntu/Debian recommended):

  [bash]
    npm run tauri:build:linux

Install Tauri Linux dependencies first (webkit2gtk, etc.).

Output under src-tauri/target/release/bundle/:

  • .deb — Debian, Ubuntu, Mint, Pop!\_OS
  • .rpm — Fedora, RHEL, Rocky, openSUSE
  • AppImage — distro-agnostic (Arch, NixOS, etc.)

See LINUX_PACKAGES.md for install commands per distribution.

  [bash]
    npm run tauri:build:linux          # all three
    npm run tauri:build:linux:deb      # deb only
    npm run tauri:build:linux:rpm      # rpm only
    npm run tauri:build:linux:appimage # AppImage only
    npm run tauri:build:linux:arm64    # ARM64 deb + AppImage (native or cross)

CI also builds Linux ARM64 on ubuntu-24.04-arm (see .github/workflows/build.yml).

  • Same UI and features as macOS (Gemini layout, sidebar, composer, attachments, API keys)
  • Full File / Edit / View / Window / Help menus in the window menu bar
  • View → System Tray Panel / Windowed — labels match Linux tray UX; windowed mode uses the OS menu bar (in-app toolbar hidden)
  • System tray supported; close hides to tray

WINDOWS
-------

Build on a Windows PC (recommended):

  [bash]
    npm run tauri:build:win

CI: Pushes to main/master run .github/workflows/build.yml on windows-latest, ubuntu-22.04, and macos-latest and upload installers as artifacts.

Cross-compile from macOS (optional): install MinGW (brew install mingw-w64), add rustup target add x86_64-pc-windows-gnu, set CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=x86_64-w64-mingw32-gcc, then npm run tauri:build:win.

Output: .msi / .exe under src-tauri/target/release/bundle/

  • Same UI and features as macOS; menus in the window menu bar
  • Ctrl+Shift+Space toggles visibility
  • Tray panel opens near the system tray; Windowed hides the duplicate in-app toolbar
  • Active window + clipboard context via PowerShell
  • Close hides to system tray; exit via tray Quit Gnomad

DEVELOPMENT
-----------

  [bash]
    npm run tauri dev

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════