From a09399702d4808e168e4f37d68d70b51bcc7927d Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Wed, 15 Jul 2026 09:40:17 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20REQUIREMENTS.md=20=E2=80=94=20OpenGL=20?= =?UTF-8?q?4.3=20floor,=20disk/RAM=20planning?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Acer M5-481T fails Ghostty because Ivy Bridge HD 4000 tops out at OpenGL 4.2 in Mesa; Ghostty needs 4.3 — a generation ceiling, not a missing driver. Document that plus UEFI/x86_64, RAM, and storage floors (Nix store generations + BTRFS snapper + hibernate swap≈RAM). Linked from README, docs map, HARDWARE.md; #95 points here. --- README.md | 4 ++ agent/BACKLOG.md | 7 ++ agent/JOURNAL.md | 12 ++++ docs/HARDWARE.md | 4 ++ docs/README.md | 1 + docs/REQUIREMENTS.md | 162 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 190 insertions(+) create mode 100644 docs/REQUIREMENTS.md diff --git a/README.md b/README.md index e096709..6597487 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,10 @@ probably shouldn't exist. ## 2. Try it first (live ISO) +**Before you install:** check **[docs/REQUIREMENTS.md](docs/REQUIREMENTS.md)** +(UEFI x86_64, **OpenGL 4.3** for the default terminal, disk planning for the +Nix store + BTRFS snapshots — 128 GiB is the comfortable floor). + Boot the full desktop from a USB stick or VM without installing anything: ```sh diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md index e05ffd9..6206905 100644 --- a/agent/BACKLOG.md +++ b/agent/BACKLOG.md @@ -149,6 +149,13 @@ browser posture is explicit). **Machine:** Acer Aspire M5-481T only. **Dell XPS 9350 starts Ghostty fine** (Bernardo clarified 2026-07-15 — do not treat XPS as a Ghostty failure). +**Why this hardware fails:** the Aspire is Ivy Bridge–class (**Intel HD +4000**, ~2012). Mesa’s max for that GPU is **OpenGL 4.2**; Ghostty requires +**4.3**. That is a **generation ceiling**, not a missing package — no +Nomarchy or Mesa tweak can make HD 4000 report 4.3 honestly. Documented in +`docs/REQUIREMENTS.md`. The product response is a fallback terminal (or +probe), not “fix Intel drivers.” + On the Acer, Bernardo installed **kitty** by hand (worked) and launched Ghostty from that shell twice — **same box, two lifecycle points, two log shapes**: diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md index 2d1404e..f6512b1 100644 --- a/agent/JOURNAL.md +++ b/agent/JOURNAL.md @@ -19,6 +19,18 @@ Template: --- +## 2026-07-15 — docs/REQUIREMENTS.md (OpenGL floor + disk planning) +- **Task:** Bernardo: why Acer lacks OpenGL 4.3; start documenting minimum + system requirements including storage (Nix store + snapshots). +- **Did:** Answer is hardware generation (HD 4000 / Ivy Bridge tops at GL + 4.2; Ghostty needs 4.3). New `docs/REQUIREMENTS.md` — UEFI/x86_64, GPU + table, RAM, disk floors (40/64/128 GiB) + swap≈RAM, why store+snapper grow; + linked from README, docs map, HARDWARE.md; #95 notes the generation ceiling. +- **Verified:** V0 (docs only). +- **Pending:** #95 still needs a runtime fallback; tighten disk numbers when + a fresh install is `df`-measured end-to-end. +- **Next suggestion:** #123 (installer bake). + ## 2026-07-15 — File install findings from Acer + XPS photos (no code) - **Task:** Bernardo: real installs on Acer Aspire M5-481T + Dell XPS 9350; photos of the install end screens and post-boot sessions. Figure out diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index 76f97e6..2462fd0 100644 --- a/docs/HARDWARE.md +++ b/docs/HARDWARE.md @@ -3,6 +3,10 @@ How Nomarchy enables CPUs, GPUs, laptops, firmware, and peripherals — and what to do when your machine is not in the happy path. +**Minimum bar** (OpenGL, RAM, disk, UEFI): [`REQUIREMENTS.md`](REQUIREMENTS.md) +— read that before calling a machine “unsupported”; this file is the +enablement stack and quirk list. + > **Queue:** [`agent/BACKLOG.md`](../agent/BACKLOG.md) (PROPOSED › Hardware > product). Product framing: [`VISION.md`](VISION.md) § A. Design history: > [`ROADMAP.md`](ROADMAP.md). Docs map: [`README.md`](README.md). diff --git a/docs/README.md b/docs/README.md index 33b2ae7..f755ce6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ tree for the same facts. | Path | Audience | Role | |------|----------|------| | [../README.md](../README.md) | Everyone | What Nomarchy is, install, options tables | +| [REQUIREMENTS.md](REQUIREMENTS.md) | Users + agents | Minimum system requirements (GPU/OpenGL, RAM, disk, UEFI) | | [VISION.md](VISION.md) | Maintainers + agents | Product north star toward **v1.0** and beyond — themes, not a task queue | | [ROADMAP.md](ROADMAP.md) | Maintainers + agents | Design/decision records + shipped log (historical ✓) | | [HARDWARE.md](HARDWARE.md) | Users + agents | Firmware, profiles, drivers, unsupported machines | diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md new file mode 100644 index 0000000..b2c1e41 --- /dev/null +++ b/docs/REQUIREMENTS.md @@ -0,0 +1,162 @@ +# Minimum system requirements + +What Nomarchy expects of a machine. This is a **living floor**, not a +marketing sheet — numbers come from measured installs and known software +floors (Ghostty, NixOS, the ISO). When a real machine pushes a bound, update +this file in the same change. + +Related: [HARDWARE.md](HARDWARE.md) (profiles/drivers), +[TESTING.md](TESTING.md) (ISO/VM), [README](../README.md) § install. + +--- + +## Supported platform (hard) + +| Requirement | Floor | Why | +|-------------|-------|-----| +| Architecture | **x86_64** | Only target the flake builds today | +| Firmware | **UEFI** | Installer uses systemd-boot; BIOS/legacy is LATER | +| Install path | Whole disk (disko) | No dual-boot / partial-disk path yet | + +--- + +## Graphics (default desktop) + +The default terminal is **Ghostty**, which requires **OpenGL 4.3** (desktop +profile). That is a **GPU generation** limit, not a “driver not installed” +problem: + +| Generation (examples) | Typical max OpenGL (Mesa) | Default Ghostty | +|-----------------------|---------------------------|-----------------| +| Ivy Bridge / HD 4000 (e.g. **Acer Aspire M5-481T**, ~2012) | **4.2** | **Does not start** (`OpenGLOutdated`) | +| Haswell and newer Intel iGPU, most AMD GCN+, discrete GPUs of the last decade | ≥ 4.3 | OK | +| Dell XPS 9350 (Skylake) | ≥ 4.3 | OK (verified 2026-07) | + +**Why 4.2 and not 4.3 on HD 4000?** The silicon and Mesa’s feature set for +that generation top out at OpenGL 4.2. No package upgrade on the distro can +turn Ivy Bridge into a 4.3 device. Ghostty is choosing a modern GL baseline +on purpose. + +**Until a fallback ships** (BACKLOG **#95** — alternate terminal or probe when +GL < 4.3): machines below OpenGL 4.3 can still **install and run the +desktop**, but SUPER+Return / the default terminal entry will fail until the +user installs another terminal (e.g. kitty) or we ship an automatic fallback. + +Other Wayland clients vary; Hyprland itself is usually fine on these GPUs. +The Ghostty floor is the one that bit real hardware first. + +--- + +## CPU and memory + +| Resource | Practical minimum | Comfortable | +|----------|-------------------|-------------| +| CPU | 64-bit x86_64, dual-core | Quad-core or better (rebuilds) | +| RAM | **8 GiB** | **16 GiB+** | + +NixOS + Home Manager rebuilds and browser/Electron apps are memory-hungry. +Hibernation (default installer path) sizes a **swapfile ≈ RAM**, so low RAM +also means less disk eaten by swap — but also less headroom when building. + +--- + +## Storage (the important one) + +Nomarchy is a full NixOS desktop with: + +1. **The Nix store** — every generation keeps package closures; updates add + new paths until you GC. Many packages appear once per generation when + inputs move. +2. **Home Manager generations** — desktop switches and `nomarchy-home` leave + profiles behind until cleaned. +3. **BTRFS + snapper** — `@snapshots` timeline (hourly/daily) and + pre-rebuild snaps. Excellent for recovery; **they retain data** and grow + with how full the live filesystem is. +4. **Optional hibernation swapfile** — default size = **RAM** (e.g. 16 GiB + RAM → 16 GiB swapfile on disk). + +Closure size is **not** the same as disk use after hardlink optimisation +and is **not** the ISO size (see ROADMAP § chromium / #121 measurements). +Still, plan for **growth**, not for a single install footprint. + +### Measured / known artifacts (order of magnitude) + +| Artifact | Size (approx.) | Source | +|----------|----------------|--------| +| Offline live ISO | **~8.1 GiB** | Built image, 2026-07 (#103 era) | +| Template HM closure (nominal) | **~9.4 GiB** | `nix path-info` style figures in ROADMAP | +| Desktop store weight (uncompressed, pre-dedupe order) | **tens of GiB** | ISO pin / offline pin analysis (#120) | + +A **fresh** install on empty disk is smaller than a machine that has been +updated and snapshotted for months. + +### Recommended free disk (whole-disk install) + +These are **planning floors** for the target SSD/HDD the installer will wipe +and use entirely — not “free space beside Windows.” + +| Use | Capacity | Notes | +|-----|----------|--------| +| Absolute minimum to finish install + first boot | **≥ 40 GiB** | Tight; little room for GC delay or snapshots | +| Realistic daily driver | **≥ 64 GiB** | Short GC/snap retention still required | +| Comfortable (updates + snapper + apps) | **≥ 128 GiB** | Default recommendation | +| Power user / many generations / big apps | **256 GiB+** | Dev toolchains, Steam, local datasets | + +**Plus swap:** if you keep hibernation (default), add **~RAM** on top of the +table (installer creates `/swap/swapfile` sized to RAM unless you set 0). + +Example: 16 GiB RAM laptop → plan **≥ 128 GiB disk**, of which ~16 GiB is +swapfile, leaving room for store + snapshots. + +### Why Nix “duplicates everything” + +- Each **system** and **home** generation points at a closure of store + paths. Unchanged paths are shared (same `/nix/store/…` hash); changed + inputs pull **new** paths. After several updates you hold old + new until + `nix-collect-garbage` / generation deletion. +- **Snapper** snapshots the BTRFS subvolumes. A snapshot is cheap until you + rewrite a lot of data; then it retains the old blocks. Timeline + rebuild + snaps mean “I deleted that 2 GB download” may not free space until snaps + expire. +- The live **ISO** is large because it pins an offline install closure; that + is a download/USB cost, not permanent free space on the installed machine + after install (the installed system has its own store). + +**Hygiene (user-facing, later doc links):** delete old generations, run GC, +tune snapper retention — see [RECOVERY.md](RECOVERY.md) and the System › +Recovery menu. This requirements page only states why the disk fills up. + +--- + +## What we explicitly do **not** require + +| Non-requirement | Note | +|-----------------|------| +| NVIDIA as first-class | Deferred past v1 (PROPOSED); community/docs only | +| Secure Boot enrolled out of the box | Not the current install path | +| Touch / tablet as primary input | Untested as a bar | +| < 8 GiB RAM as a supported target | May boot; rebuilds and browsers will thrash | + +--- + +## Machines that defined these bounds + +| Machine | Role | +|---------|------| +| **Acer Aspire M5-481T** (~2012, Intel HD 4000, OpenGL 4.2) | Ghostty floor (#95); install bake / old-HW QA | +| **Dell XPS 9350** (Skylake) | Install bake (#123); Ghostty OK | +| AMD dev box / Latitude / T14s | Ongoing V3 (HARDWARE-QUEUE) | + +When you install on something older or smaller than the table, file what +broke in `agent/BACKLOG.md` and tighten this page. + +--- + +## Related work + +| Item | Topic | +|------|--------| +| BACKLOG **#95** | Ghostty fallback when OpenGL < 4.3 | +| BACKLOG **#120** | Lighter netinstall ISO (download size ≠ installed size) | +| BACKLOG **#123** | Installer HM pre-activate (first-boot polish) | +| BACKLOG **#124** | Flake pin vs main/v1 lag after install |