From 948b8864e543c7029a7122493e82498b1604d3c7 Mon Sep 17 00:00:00 2001 From: saymrwulf Date: Thu, 14 May 2026 15:51:39 +0200 Subject: [PATCH] =?UTF-8?q?Add=20INSTALL.md=20=E2=80=94=20clone-to-running?= =?UTF-8?q?=20on=20a=20fresh=20macOS=20box?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit End-to-end install guide aimed at a developer who has just cloned the repo onto an unconfigured Mac. Covers: - prerequisites (macOS 26 Tahoe, Xcode 17+, Python 3.11, git); - Python venv + editable install + pytest verification; - regenerating crisis_data.json and copying it into the bundled visualizer resources; - three Swift build paths — `swift build`/`swift run` for the dev binary, `bundle.sh` for the .app, `package-dmg.sh` for a distributable DMG; - testbed run + where the five report files land; - troubleshooting for the common first-time failures (Gatekeeper, missing data, missing toolchain, blank window). This is the document we hand to someone who wants the visualizer to run on a target Mac without first having to reverse-engineer the project layout. Co-Authored-By: Claude Opus 4.7 --- INSTALL.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..662ebaa --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,143 @@ +# INSTALL — Crisis & CrisisViz + +End-to-end setup on a fresh macOS box, from a blank checkout to a running visualizer. Follow top-to-bottom. + +--- + +## 1. Prerequisites + +| Tool | Minimum | How to install | +|---|---|---| +| **macOS** | 26 Tahoe | The Swift visualizer targets `.macOS(.v26)`. The Python side runs on any macOS with Python ≥3.11. | +| **Xcode** | 17 | `xcode-select --install` for command-line tools only, or the full Xcode app from the App Store. Provides Swift 6.2 + the macOS 26 SDK. | +| **Python** | 3.11 | Pre-installed on recent macOS; otherwise `brew install python@3.11`. | +| **git** | any | `xcode-select --install` installs it. | +| **Homebrew** | optional | Only needed if you don't already have Python 3.11. Install per [brew.sh](https://brew.sh). | + +Verify: + +```sh +sw_vers # ProductVersion: 26.x +xcodebuild -version # Xcode 17.x +swift --version # swift-driver version: 1.x (Apple Swift version 6.2) +python3.11 --version # Python 3.11.x +``` + +--- + +## 2. Clone and verify + +```sh +git clone https://github.com/saymrwulf/crisis.git +cd crisis +ls Crisis.mirco-richter-2019.pdf # the spec — must exist +``` + +--- + +## 3. Python side — protocol PoC + +Create a virtualenv and install the package in editable mode with dev extras: + +```sh +python3.11 -m venv .venv +source .venv/bin/activate +pip install --upgrade pip +pip install -e ".[dev]" +``` + +Run the unit tests to verify the algorithm implementations: + +```sh +pytest -q +``` + +Expected: all tests pass in under a second. If any fail, stop and investigate before continuing — the visualizer's data pipeline depends on these. + +Try a deterministic in-process simulation: + +```sh +python -m crisis.demo --nodes 3 --byzantine 0 --rounds 5 +``` + +You should see consensus rounds advance and a total order emerge. + +--- + +## 4. Regenerate `crisis_data.json` (optional) + +The repo ships with a pre-recorded `crisis_data.json` at the root and a bundled copy in `CrisisViz/Sources/CrisisViz/`. Regenerate when you change the protocol code or want a different simulation: + +```sh +python -m crisis.export_json --steps 80 -o crisis_data.json +cp crisis_data.json CrisisViz/Sources/CrisisViz/crisis_data.json +``` + +The defaults (6 honest + 1 byzantine, 80 steps) produce full convergence from step 40 onward — the visualizer's chapters on total order and Byzantine detection depend on having a converged tail. + +--- + +## 5. Swift side — the visualizer + +### 5a. Quick dev loop + +```sh +cd CrisisViz +swift build # ~4s on Apple Silicon +swift run CrisisViz # launches the dev binary +``` + +Note: the dev binary does not have a Dock icon and lives in `.build/`. For a real `.app` use `bundle.sh`. + +### 5b. Build the `.app` bundle + +```sh +./bundle.sh # build + assemble CrisisViz.app + open +./bundle.sh --no-launch # build only +``` + +`CrisisViz.app` is created in the current directory. Open it from Finder or the Dock to get the full activation-policy behavior. + +### 5c. Build a DMG installer + +```sh +./package-dmg.sh # produces CrisisViz.dmg in the current directory +``` + +The DMG is ad-hoc signed — on first open macOS Gatekeeper will refuse to launch the app directly. Right-click `CrisisViz` in `/Applications` → **Open** → **Open** in the confirmation dialog. macOS remembers your approval; subsequent launches behave normally. + +Distribution flow for a new machine: +1. Copy `CrisisViz.dmg` to the target Mac. +2. Double-click to mount. +3. Drag `CrisisViz` onto the `Applications` symlink. +4. Eject the DMG; launch from `/Applications` (right-click → Open the first time). + +### 5d. Run the QA testbed + +```sh +swift run CrisisViz --testbed +``` + +Writes to `~/Desktop/CrisisViz_Testbed/`: + +- `INVARIANTS.md` — 38 logical curriculum assertions +- `SOURCE_AUDIT.md` — forbidden-pattern scan (lane jitter, hardcoded palette, etc.) +- `VIDEO_CLIPS.md` — 36 MP4 clips at 8s / 30fps +- `MANIFEST.md` — PNG sweep across all scenes / time offsets +- `SANITY.md` — file-size and freeze-frame checks + +All five should be green before shipping changes. + +--- + +## 6. Troubleshooting + +**`swift build` fails with “unsupported deployment target”.** Your Xcode does not provide the macOS 26 SDK. Update Xcode to ≥17, or downgrade `Package.swift` to your installed SDK (not recommended — visual features depend on macOS 26 Liquid Glass APIs). + +**`swift run CrisisViz` shows a blank window.** The bundled `crisis_data.json` is missing or empty. Run `cp crisis_data.json CrisisViz/Sources/CrisisViz/crisis_data.json` and rebuild. + +**Gatekeeper refuses to open the app from the DMG.** Right-click → **Open** the first time. Or remove the quarantine attribute manually: `xattr -dr com.apple.quarantine /Applications/CrisisViz.app`. + +**`pytest` fails on `ModuleNotFoundError: crisis`.** Activate the venv (`source .venv/bin/activate`) and reinstall with `pip install -e ".[dev]"`. The `-e` (editable) flag is what makes `import crisis` resolve to `src/crisis/`. + +**The visualizer freezes mid-chapter / animations are stuck.** You're running the unbundled `swift-run` binary while the Dock icon launches `CrisisViz.app`. Rebuild the bundle: `./bundle.sh --no-launch && open CrisisViz.app`.