diff --git a/local/docs/STUBS-FIX-PROGRESS.md b/local/docs/STUBS-FIX-PROGRESS.md index 203e9d4d7a..c1cb8ee2a4 100644 --- a/local/docs/STUBS-FIX-PROGRESS.md +++ b/local/docs/STUBS-FIX-PROGRESS.md @@ -459,3 +459,181 @@ Two agents refused to perform tasks that would have been policy violations: **New forks:** 4 (libdrm, redox-drm, pipewire, wireplumber) at `local/sources/`. **New local/recipes subdirectories:** `data/`, `wayland/`, `libs/redbear-qml-runtime/` (planned), `libs/pipewire/`, `libs/wireplumber/`, `libs/libxkbcommon/`, `drivers/redbear-hid-core/`. +--- + +## Architectural Decision: Red Bear Forks vs. Direct Edits (2026-06-09) + +This section records the policy decision for **where Red Bear source modifications must live**. +It is the durable, in-tree statement of the two-rule model already encoded in +`local/AGENTS.md` under "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)". + +### The policy in one sentence + +> **Big external projects (mesa, wayland, qt, KF6, KWin, SDDM, llvm, libdrm, redox-drm, libepoxy, +> pipewire, wireplumber, …) must live as Red Bear forks at `local/sources//`, not as +> direct edits inside the mainline `recipes//source/` tree.** + +### Why + +Direct edits to `recipes//source/` are **clobbered by `make clean` and by upstream syncs**. +A Red Bear fork at `local/sources//` is a separate git repo, owned by Red Bear, +git-tracked, rebase-friendly, and never touched by the build system's source-regeneration step. +It survives every `make clean`, every `make distclean`, every `provision-release.sh`, and every +upstream `git pull` we ever run. + +### The 12 Red Bear forks already in place (verified 2026-06-09) + +| # | Fork | Path | Why a fork | +|---|------|------|------------| +| 1 | `base` | `local/sources/base/` | Red Bear userspace drivers fork — acpid, pcid, inputd, ps2d, xhcid migrations | +| 2 | `bootloader` | `local/sources/bootloader/` | UEFI bootloader fork — UEFI alloc fix, branding, GPT offset | +| 3 | `installer` | `local/sources/installer/` | Installer fork — ext4 + GRUB support | +| 4 | `kernel` | `local/sources/kernel/` | Microkernel fork — ACPI, x2APIC, MSI/MSI-X, scheduling, branding | +| 5 | `libdrm` | `local/sources/libdrm/` | DRM/KMS userspace library — ioctl bridge, PCI info, device enumeration | +| 6 | `mesa` | `local/sources/mesa/` | Mesa 3D graphics library — virgl disk cache, GBM dumb prime export, hardware driver work | +| 7 | `pipewire` | `local/sources/pipewire/` | PipeWire audio server — Redox compat shims | +| 8 | `redox-drm` | `local/sources/redox-drm/` | DRM/KMS scheme daemon — Intel + AMD display drivers, MSI/MSI-X fallback, DISABLE_ACCEL | +| 9 | `redoxfs` | `local/sources/redoxfs/` | RedoxFS — primary filesystem, Red Bear schema/improvements | +| 10 | `relibc` | `local/sources/relibc/` | C library — eventfd, signalfd, timerfd, waitid, SysV IPC, credential syscalls | +| 11 | `userutils` | `local/sources/userutils/` | Userland utilities — login/getty/login helpers, prompt/welcome text | +| 12 | `wireplumber` | `local/sources/wireplumber/` | WirePlumber session manager — PipeWire policy | + +**Verification command:** + +```bash +ls -1 /home/kellito/Builds/RedBear-OS/local/sources/ +# Expected (12 entries): +# base bootloader installer kernel libdrm mesa +# pipewire redox-drm redoxfs relibc userutils wireplumber +``` + +### The exception: in-tree Red Bear components + +`kernel`, `relibc`, `base`, `installer`, and `bootloader` are listed in **both** the +"in-tree Red Bear components" and the "forks at `local/sources/`" tables above. That is +intentional. These components are forked at `local/sources//` (Rule 2 — big +project, durability matters), but the mainline `recipes///recipe.toml` +**points at the fork** (not the other way around — no symlink, no overlay, no patch +file). The fork IS the source of truth; the recipe just builds it. + +For **small Red Bear-initiated new packages** (cub, redbear-info, redbear-netctl, +redbear-sessiond, redbear-authd, …) the rule is Rule 1: a `local/recipes///` +fork replaces the upstream recipe entirely. No symlinks, no overlay layer. + +For **upstream Redox system internals that we do not modify** (core/pkgar, core/ion, +core/dash, core/coreutils, gui/orbital, …) we pull from upstream at a pinned revision +and the build is fine. The Redox ABI must not diverge. + +### Concrete walk-through: direct edit vs. fork + +**Scenario:** You want to add `-Dplatforms=wayland` to the Mesa build to enable the +Wayland EGL platform, which is the prerequisite for KWin to find an EGL/GBM/GLES2 surface. + +#### Direct edit (WRONG — Rule 1 anti-pattern) + +1. Edit `recipes/libs/mesa/recipe.toml` to add `-Dplatforms=wayland` to the meson args. +2. Run `repo cook recipes/libs/mesa`. The build succeeds. Mesa now exposes Wayland EGL. +3. Two days later, upstream Mesa 25.0 is released. +4. You run `make distclean` (or `make clean` or `repo fetch recipes/libs/mesa`). +5. The cookbook refetches Mesa from the pinned git URL. The `recipe.toml` is overwritten + with whatever is at the new rev. **Your `-Dplatforms=wayland` change may be wiped, + may be preserved, or may collide with a new upstream flag. Outcome is non-deterministic.** +6. If the recipe `rev` is bumped, the source tree is also refetched. Your hand-edited + Meson build files inside `recipes/libs/mesa/source/` are GONE. +7. If you try to recover by re-applying, you are now maintaining a patch series on top + of multi-million-line upstream Mesa. Every upstream bump is a `git apply` rebase. +8. **Your Red Bear patches are LOST or have become unmaintainable.** + +#### Fork (CORRECT — Rule 2, what we actually do) + +1. The Mesa fork is already at `local/sources/mesa/`, on branch `0.2.3`, with our existing + EGL Wayland commits. (See `local/sources/mesa/` for the current state.) +2. Add a Red Bear commit on `local/sources/mesa/0.2.3`: + ```bash + cd local/sources/mesa + # Edit meson.build, meson_options.txt to add Wayland EGL platform support + git add meson.build meson_options.txt + git commit -m "mesa: enable Wayland EGL platform (-Dplatforms=wayland) for KWin" + ``` +3. The mainline `recipes/libs/mesa/recipe.toml` already points at the fork: + ```toml + [source] + path = "../../../local/sources/mesa" + ``` + No change needed there. +4. Run `./local/scripts/build-redbear.sh redbear-full`. Mesa builds with Wayland EGL. + The build artifact lands in `repo/x86_64-unknown-redox/mesa.pkgar` + `mesa.toml`. +5. Two days later, upstream Mesa 25.0 is released. We want to pull it. +6. Bump the upstream reference in the fork: + ```bash + cd local/sources/mesa + git remote add upstream https://gitlab.freedesktop.org/mesa/mesa.git # one-time + git fetch upstream + git checkout 0.2.3 + git rebase upstream/25.0 # rebase OUR patches on top of new upstream + # Resolve the (rare, well-localized) conflicts in meson.build, meson_options.txt + git push origin 0.2.3 + ``` +7. The mainline recipe's `rev` is updated in `local/recipes/libs/mesa/recipe.toml` (or + in the upstream mainline recipe that points at the fork), and the build proceeds. +8. **Our Red Bear patches SURVIVE — they live on the `0.2.3` branch of our fork, are + rebased forward at our discretion, and are visible in `git log` of the fork.** + +### Rule-of-thumb decision matrix + +| Is the component … | Then … | +|---|---| +| An in-tree Red Bear core (kernel, relibc, base, installer, bootloader) | **Rule 1 + Rule 2 hybrid** — fork at `local/sources//` is the source of truth; mainline recipe points at the fork. No patches, no symlinks. | +| A small Red Bear-initiated new package (cub, redbear-info, redbear-netctl, redbear-sessiond, redbear-authd, …) | **Rule 1** — `local/recipes///` fork replaces the upstream recipe. No symlinks, no overlay. | +| A big external project (mesa, wayland, qt, KF6, KWin, SDDM, llvm, libdrm, redox-drm, libepoxy, pipewire, wireplumber, …) | **Rule 2** — Red Bear fork at `local/sources//`. Mainline recipe points at the fork via `path = "../../../local/sources/"` or `git = "https://gitea.redbearos.org/redbear/.git"`. | +| An upstream Redox system-internal that we do not modify (core/pkgar, core/ion, core/dash, core/coreutils, gui/orbital, …) | No fork. Pull from upstream at pinned revision. The Redox ABI must not diverge. | +| A pure Cargo dep that we do not fork (redox_syscall, libredox, redox-scheme, pkgar, …) | Pulled via Cargo from upstream crates.io. No recipe. | + +The default for anything multi-thousand-line external is **Rule 2 (fork)**. +The default for anything Red Bear-initiated is **Rule 1 (local recipe that replaces upstream)**. +In-tree Red Bear core components live at `local/sources//` and the mainline +recipe points at them. + +### Cross-references + +- `local/AGENTS.md` — "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)" sections, + Rule 1 (in-tree Red Bear components) and Rule 2 (big external projects). +- `local/AGENTS.md` — "SOURCE-OF-TRUTH RULE" section, two-layer architecture + (`recipes/*/source/` is ephemeral; `local/sources/`, `local/recipes/`, `local/docs/`, + tracked configs are durable). +- `local/AGENTS.md` — "STUB AND WORKAROUND POLICY — ZERO TOLERANCE" for what to do when + a fork's build breaks (fix it in the fork, never disable features in the consumer). +- `local/AGENTS.md` — "DESIGN PRINCIPLE" and "RELEASE MODEL (FORK — NOT OVERLAY)" for + the upstream-baseline + fork-on-top architecture. +- `local/AGENTS.md` — "STRUCTURE" for the full directory map. +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — canonical desktop path plan that consumes + the mesa, wayland, qt, KF6, KWin, SDDM, libdrm, redox-drm, libepoxy forks. + +### Audit commands + +Verify no overlay state has crept back into the tree: + +```bash +# (a) Every recipe must have exactly one source — no duplicate recipe.toml, +# no symlinks hiding the fork. +find recipes/ -name "recipe.toml" -path "*/local/*" -o -lname "*/local/*" 2>/dev/null + +# (b) Every Red Bear fork at local/sources/ must be a git repo. +for d in local/sources/*/; do + [ -d "$d/.git" ] || echo "MISSING .git: $d" +done + +# (c) Every mainline recipe that claims a fork must point at the right path. +grep -r "local/sources/" recipes/ --include="recipe.toml" | head -50 +``` + +If any of these checks return unexpected output, the build is in an overlay state. Fix by +forking the recipe properly per `local/AGENTS.md` Rule 1 or Rule 2. + +**Decision date:** 2026-06-09 +**Decision authority:** `local/AGENTS.md` "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)" +**Verification status:** 12 of 12 expected Red Bear forks present at `local/sources/`. +**Out-of-scope:** This section does not change the per-component build flags, the +`redbear-full` package set, or the relibc POSIX surface — those are tracked in +`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`, `local/docs/STUBS-FIX-PROGRESS.md` Phase tables, +and `local/recipes/` per-component recipes respectively. diff --git a/local/sources/base b/local/sources/base index 0df7977d45..cffacf5918 160000 --- a/local/sources/base +++ b/local/sources/base @@ -1 +1 @@ -Subproject commit 0df7977d45d16808e1e0bb0eb0897545849c6688 +Subproject commit cffacf5918a83ac7a026201ac0c547916d8a911a