Initial commit: allium behavioural specs distilled from bDS TypeScript app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-02 18:36:20 +02:00
commit aec533b54f
32 changed files with 4569 additions and 0 deletions
--- a/BUILD.md
+++ b/BUILD.md
@@ -0,0 +1,113 @@
+# RuDS — Build Prerequisites
+
+## macOS system requirements
+
+- macOS 13 (Ventura) or later
+- Apple Silicon or Intel Mac with Metal or Vulkan support (required by Iced's wgpu backend)
+
+## Linux system requirements (optional, for CI or cross-platform development)
+
+- A Vulkan-capable GPU and driver, or software rendering via `WGPU_BACKEND=gl`
+- System packages for GTK and related libraries (for muda and rfd):
+
+```sh
+# Debian/Ubuntu
+sudo apt install build-essential cmake pkg-config libgtk-3-dev libxdo-dev libdbus-1-dev
+```
+
+## Install Homebrew packages (macOS)
+
+```sh
+brew install rust cmake pkg-config
+```
+
+| Package | Why |
+|---|---|
+| `rust` | Rust toolchain (alternatively install via `rustup`, see below) |
+| `cmake` | Required by some native dependencies during `cargo build` |
+| `pkg-config` | Locates system libraries during `cargo build` |
+
+## Install Xcode Command Line Tools (macOS)
+
+```sh
+xcode-select --install
+```
+
+Required for the macOS SDK, Metal framework headers, and the Apple linker. A full Xcode install also works but is not required.
+
+## Recommended: install Rust via rustup
+
+If you prefer managing Rust versions explicitly (recommended for pinning toolchain versions across the team):
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+Then set the stable toolchain:
+
+```sh
+rustup default stable
+```
+
+## Additional dependencies by milestone
+
+### M0–M4 (core through rendering)
+
+No additional system packages beyond the above. Key crates use bundled/vendored native code:
+
+- `rusqlite` with `bundled` feature compiles SQLite from source
+- `refinery` manages SQL migrations against rusqlite
+- `iced` uses wgpu which links to Metal (macOS) or Vulkan (Linux/Windows) at runtime
+- `muda` uses native platform menu APIs (NSMenu on macOS, GTK on Linux, Win32 on Windows)
+- `rfd` uses native platform dialog APIs (NSOpenPanel on macOS, GTK on Linux, Win32 on Windows)
+- `cosmic-text` bundles its own font shaping; uses system font discovery via `fontdb`
+- `syntect` bundles syntax definitions; no system dependency
+- `ropey` is pure Rust; no system dependency
+- `image` crate is pure Rust for most codecs; no system dependency for JPEG/PNG/WEBP
+- `pulldown-cmark`, `liquid`, `quick-xml`, `rayon` are pure Rust; no system dependencies
+- `axum` + `tokio` are pure Rust; no system dependencies
+- `ssh2` links to libssh2 (bundled via `ssh2` crate's default features)
+- `objc2` / `objc2-app-kit` (macOS only, cfg-gated) links to system AppKit frameworks already available via Xcode CLI tools
+
+### M5–M6 (Lua scripting)
+
+When Lua support is added via the `mlua` crate:
+
+```sh
+brew install lua@5.4
+```
+
+Alternatively, use the `vendored` feature flag on `mlua` to compile Lua 5.4 from source and skip the system install entirely. The choice should be made when Wave 6 starts.
+
+### Publishing (SSH/rsync)
+
+The publish engine uses SSH and rsync. Both ship with macOS by default. No Homebrew install needed unless you want a newer rsync:
+
+```sh
+brew install rsync   # optional, for a newer version than the macOS default
+```
+
+## Verify the setup
+
+After installing prerequisites:
+
+```sh
+# check Rust toolchain
+rustc --version
+cargo --version
+
+# check native tooling
+cmake --version
+pkg-config --version
+xcode-select -p          # macOS only
+
+# clone and build
+cargo build
+```
+
+## Environment notes
+
+- The project is a Cargo workspace. Always run `cargo` commands from the repository root.
+- Iced requires a GPU context (Metal, Vulkan, or OpenGL fallback). CI runners must support one of these or use headless test targets that do not create windows.
+- The `bds-core` and `bds-cli` crates do not depend on Iced, muda, or rfd and can be built and tested without a display server.
+- The `bds-editor` crate depends on Iced (for the custom widget trait) but its buffer, highlighting, and layout logic can be unit tested without a display server.