Developing Sqyre

Dev container (recommended)

Open the repository in the dev container (.devcontainer/). It includes Rust 1.92, clang, Tesseract/Leptonica, X11 link deps, AppImage packaging tools (appimage-builder, squashfs-tools), Trunk + wasm32-unknown-unknown (for make wasm), and the Docker CLI (host daemon via socket) so make windows and AppImage Docker fallbacks work inside the container.

Nested docker run -v mounts use the host path via LOCAL_WORKSPACE_FOLDER (${localWorkspaceFolder}). Rebuild the container after pulling that change so the env var is set.

From the repo root:

make            # ./bin/sqyre (debug)
make release    # fmt + check, then ./bin/sqyre (release)
make run        # cargo run -p sqyre-app
make check      # fmt --check + clippy (-D warnings) + cargo deny
make machete    # unused crate deps
make test       # cargo nextest (falls back to cargo test)
make coverage   # llvm-cov HTML + lcov under target/coverage/
make docs-media # regenerate docs/images screenshots
make appimage   # fmt + check, then bin/*.AppImage (Linux)
make windows    # fmt + check, then bin/sqyre.exe (Docker MinGW cross / native on Windows)
make macos      # fmt + check, then bin/sqyre (macOS host)
make wasm       # fmt + check, then bin/wasm/ GUI-only browser editor (Trunk)
make tessdata   # download eng.traineddata into assets/tessdata/

Run make help for the full target list. Workspace layout: RUST.md.

Build caches (all gitignored):

make appimage via Docker reuses CARGO_HOME when Make exports .cargo-home, otherwise .cache/cargo. make windows defaults to CARGO_INCREMENTAL=1; on Docker Desktop it stores cargo caches in Linux volumes (bind-mounted target/ on a Windows host path is very slow). CI uses SQYRE_WINDOWS_SCCACHE=1 instead. See scripts/windows/PACKAGING.md.

Make targets

Set CARGO_FLAGS for extra cargo args. Set RELEASE_VERSION (or write a VERSION file) before make appimage / make release / make windows to stamp the AppImage name and embed SQYRE_VERSION in the binary for auto-update checks. Local builds without either default to 0.0.0-dev (update checks disabled).

WASM editor (make wasm)

Browser-only macro editor (import/export db.yaml). Does not run automation. The dev container already has Trunk and the wasm32-unknown-unknown target — rebuild the container after pulling those Dockerfile changes, then:

make wasm          # → bin/wasm/index.html  (deployable; use this, not trunk serve's dist)
cd crates/sqyre-app && env -u NO_COLOR trunk serve   # local preview + reload only

Serve the release output with any static file server (python3 -m http.server from bin/wasm/, etc.). Do not copy dist/ from a running trunk serve — that injects an unreplaced autoreload WebSocket stub and floods the console. On a bare host (no container), install once:

rustup target add wasm32-unknown-unknown
cargo install --locked trunk

Uses --no-default-features (no global hotkey hooks). Native make / make release are unchanged.

CI and GitHub Releases

Push/PR to main runs tests and a macOS cargo check (capture still stubbed) — not a GitHub Release.

Releases come from .github/workflows/main.yml on schedule or manual dispatch only:

The version job sets should_release=true only when there is no prior v* tag, or main has changed since the latest v* tag excluding docs/** and *.md. Docs-only / markdown-only changes do not publish. If nothing releasable changed, release jobs are skipped.

Tag shape: vYYYY.MM.DD (UTC date). If that tag already exists, CI uses vYYYY.MM.DD.HHMM.

Artifacts: Linux binary + AppImage, Windows .exe (MinGW cross via scripts/windows/), and the WASM editor zip (make wasm). make macos stays native; MSI/DMG packaging is not shipped yet.

Shipped Linux/Windows builds embed SQYRE_VERSION so the in-app updater can compare against GitHub Releases (local 0.0.0-dev builds skip update checks).

CI caches: Linux Docker Buildx (GHA + GHCR), Windows cross-image Buildx + pushed *-windows-cross:latest image, Cargo registry/target (per job), Windows sccache, and tessdata; macOS Homebrew bottles + split Cargo caches.

Native dependencies

OCR uses system tessdata when available, or SQYRE_TESSDATA / assets/tessdata when developing.

Manual setup (without dev container)

Prefer the container when possible. Needs Rust ≥ 1.92, clang, Tesseract/Leptonica, and X11 libs (libx11-dev, libxtst-dev, …). See RUST.md.

make            # or: cargo build -p sqyre-app
./bin/sqyre

For AppImage on the host, also install appimage-builder, patchelf, and squashfs-tools.

Tests

make test
# or: cargo test

Headless CI uses Null* backends / stub hotkeys where hooks are unavailable.

README screenshots

In-memory egui goldens live under images/sqyre/ (test: cargo test -p sqyre-app --test docs_screenshots).

make docs-media
# or: SQYRE_UPDATE_SCREENSHOTS=1 ./scripts/generate-docs-media.sh

Needs wgpu (lavapipe in the dev container / CI image).

Packaging

See scripts/linux/packaging/PACKAGING.md for AppImage builds.