yaze/docs/public/build/install-options.md

YAZE Installation Options (Distribution Guide)

Status: Draft
Audience: Users/distributors who want alternatives to direct GitHub release binaries.

Overview

YAZE is distributed primarily via GitHub release binaries. This guide summarizes current install paths and outlines packaging-friendly options per platform. Use the table to pick what is available today vs. what would require packaging work.

Platform Matrix

Platform	Status	Recommended Path	Notes
macOS (Intel/Apple)	Available	GitHub release tarball; custom Homebrew tap (see below)	Prefer Apple silicon builds; Intel works under Rosetta.
Windows (x64)	Available	GitHub release zip; vcpkg-from-source (community)	No official winget/choco package yet.
Linux (x86_64)	Available	GitHub release AppImage (if provided) or build from source	Test on Ubuntu/Debian/Fedora; Wayland users may need XWayland.
Web (WASM)	Preview	Hosted demo or local npm http-server of build-wasm artifact	Requires modern browser; no install.

macOS

1) Release binary (recommended)

1. Download the macOS tarball from GitHub releases.
2. tar -xf yaze-<version>-macos.tar.gz && cd yaze-<version>-macos
3. Run ./yaze.app/Contents/MacOS/yaze (GUI) or ./bin/z3ed (CLI).

2) Homebrew (custom tap)

• If you publish a tap: brew tap <your/tap> then brew install yaze.
• Sample formula inputs:
  • URL: GitHub release tarball.
  • Dependencies: cmake, ninja, pkg-config, sdl2, glew, glm, ftxui, abseil, protobuf, gtest.
• For development builds: cmake --preset mac-dbg then cmake --build --preset mac-dbg.

Windows

1) Release zip (recommended)

1. Download the Windows zip from GitHub releases.
2. Extract to a writable directory.
3. Run yaze.exe (GUI) or z3ed.exe (CLI) from the bin folder.

2) vcpkg-from-source (DIY)

If you prefer source builds with vcpkg dependencies:

1. Install vcpkg and integrate: vcpkg integrate install.
2. Configure: cmake --preset win-dbg -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake.
3. Build: cmake --build --preset win-dbg.
4. Run tests (optional): ctest --test-dir build.

Linux

1) Release AppImage (if available)

• chmod +x yaze-<version>-linux.AppImage && ./yaze-<version>-linux.AppImage
• If graphics fail under Wayland, try XWAYLAND_FORCE=1 ./yaze-<version>-linux.AppImage.

2) Build from source

Prereqs: cmake, ninja-build, pkg-config, libsdl2-dev, libglew-dev, libglm-dev, protobuf-compiler, libprotobuf-dev, libabsl-dev, libftxui-dev (or build from source), zlib1g-dev.

cmake --preset lin-dbg
cmake --build --preset lin-dbg
ctest --test-dir build -L stable   # optional

Web (WASM Preview)

• Use the published web build (if provided) or self-host the build-wasm output:

cd build-wasm && npx http-server .

• Open the local URL in a modern browser; no installation required.

Packaging Notes

• Prefer static/runtime-complete bundles for end users (AppImage on Linux, app bundle on macOS, zip on Windows).
• When creating packages (Homebrew/Chocolatey/winget), pin the release URL and checksum and align dependencies to the CMake presets (mac-*/lin-*/win-*).
• Keep CLI and GUI in the same archive to avoid mismatched versions; CLI entry is z3ed, GUI entry is yaze.

Quick Links

• Build quick reference: docs/public/build/quick-reference.md
• CMake presets: CMakePresets.json
• Tests (optional after build): ctest --test-dir build -L stable