AGENTS.md: update overlay-patch references to match path-fork model
Ground-truth staleness fix for AGENTS.md, aligned to section A of /tmp/rb-ground-truth.txt (core forks use PATCHED-VIA-PATH-FORK; e.g. base 4d09ab7f, kernel 22f5f622).
This commit is contained in:
@@ -35,7 +35,7 @@ This rule exists because agents have repeatedly destroyed months of work by deci
|
||||
packages were "unnecessary" and silently removing them during syncs and config changes.
|
||||
|
||||
The current baseline is **Red Bear OS 0.3.1** (Redox snapshot at build-system commit `f55acba68`).
|
||||
All recipe sources are pinned and archived in `sources/redbear-0.3.1/`.
|
||||
All recipe sources are pinned and archived in `sources/redbear-0.1.0/`.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
@@ -52,7 +52,7 @@ redox-master/
|
||||
├── src/ # Cookbook Rust tooling (repo binary, cook logic, content-hash cache)
|
||||
├── docs/ # Architecture docs (6 detailed integration guides) — See docs/AGENTS.md
|
||||
├── local/ # OUR CUSTOM WORK — survives mainline updates — See local/AGENTS.md
|
||||
│ ├── config/ # Custom configs (my-amd-desktop.toml)
|
||||
│ ├── config/ # Custom configs (redbear-full.toml)
|
||||
│ ├── recipes/ # Custom recipes (AMD drivers, GPU stack, Wayland)
|
||||
│ ├── patches/ # Patches against mainline sources (kernel, relibc, base)
|
||||
│ ├── Assets/ # Branding assets (icon, loading background)
|
||||
@@ -290,6 +290,8 @@ After building an image, run `make validate` to verify:
|
||||
- Override effectiveness and scheme binary existence (via `validate-init-services.sh`)
|
||||
- File ownership conflicts (via `validate-file-ownership.sh`)
|
||||
|
||||
For path-fork recipes (`kernel`, `base`, `relibc`, `bootloader`, `installer`, `redoxfs`, `userutils`, `syscall`, `libredox`), the equivalent validation is `git -C local/sources/<component> log --oneline -3` plus `git -C local/sources/<component> status`. To rehydrate a fork source tree, remove `recipes/core/<component>/source` and rerun `./local/scripts/build-redbear.sh redbear-mini`; `repo cook` recopies from `local/sources/`.
|
||||
|
||||
See `local/docs/BUILD-SYSTEM-HARDENING-PLAN.md` for the full plan.
|
||||
|
||||
## ANTI-PATTERNS (THIS PROJECT)
|
||||
@@ -337,22 +339,21 @@ only inside a fetched source tree is not preserved.
|
||||
|
||||
**Required actions after any source-tree edit:**
|
||||
|
||||
1. **Generate a patch** from the source git diff and save it under `local/patches/<component>/`.
|
||||
2. **Wire the patch** into the recipe's `recipe.toml` `patches = [...]` list.
|
||||
3. **Commit** the patch file and recipe change before the session ends.
|
||||
1. For core components (`base`, `kernel`, `relibc`, `bootloader`, `installer`, `redoxfs`, `userutils`, `syscall`, `libredox`), commit changes directly into `local/sources/<component>/` fork history.
|
||||
2. For non-core recipes (e.g. `mesa`, `libwayland`, `dbus`, `kf6-*`), generate a patch from the source git diff and save it under `local/patches/<component>/`, then wire it into the recipe's `recipe.toml` `patches = [...]` list.
|
||||
3. Commit the relevant fork or patch changes before the session ends.
|
||||
|
||||
**Why:** `make distclean`, `make clean`, and source immutable archivedes all
|
||||
**Why:** `make distclean`, `make clean`, and source immutable archives all
|
||||
discard or replace `recipes/*/source/` trees. Only `local/patches/`, `local/recipes/`,
|
||||
tracked configs, `local/docs/`, and `sources/redbear-0.3.1/` survive.
|
||||
tracked configs, `local/docs/`, and `local/sources/*/` survive.
|
||||
|
||||
**Examples of changes that require immediate patching:**
|
||||
|
||||
| What you edited | Durable location |
|
||||
|---|---|
|
||||
| `recipes/core/relibc/source/src/header/sys_select/mod.rs` | `local/patches/relibc/P3-select-not-epoll-timeout.patch` + `recipe.toml` |
|
||||
| `recipes/core/relibc/source/src/header/signal/cbindgen.toml` | same patch as above |
|
||||
| `recipes/core/userutils/source/res/issue` | `local/patches/userutils/redox.patch` + `recipe.toml` |
|
||||
| `recipes/core/kernel/source/...` | `local/patches/kernel/redox.patch` (symlinked from recipe) |
|
||||
| `recipes/libs/mesa/source/src/mesa/drm.c` | `local/patches/mesa/01-fix-drm-paths.patch` + `recipe.toml` |
|
||||
| `recipes/wip/wayland/libwayland/source/src/wayland-client.c` | `local/patches/libwayland/redox.patch` + `recipe.toml` |
|
||||
| `recipes/system/dbus/source/...` | `local/patches/dbus/dbus-root-uid.patch` + `recipe.toml` |
|
||||
|
||||
**What does NOT need patching:** Files that already live in `local/`, tracked `config/redbear-*.toml`,
|
||||
or any path that is already git-tracked and not inside a fetched source tree.
|
||||
@@ -542,8 +543,7 @@ all committed to git.
|
||||
|
||||
**Current state (2026-06):**
|
||||
- All `local/patches/base/P*.patch` files are tracked in git.
|
||||
- The dangling `recipes/core/base/redox.patch` symlink (the old mega-patch
|
||||
shortcut) has been removed.
|
||||
- Note: the orphaned `recipes/core/base/redox.patch` symlink still exists and is recreated by `apply-patches.sh:157`; it is no longer consumed by the build (path-fork model). Cleanup pending.
|
||||
- For components that need extensive changes (base, relibc, kernel), we now
|
||||
use **local forks** in `local/sources/<component>/` instead of accumulating
|
||||
many patches. See "LOCAL FORK MODEL" in `local/AGENTS.md`.
|
||||
@@ -667,11 +667,13 @@ reapply orphan patches.
|
||||
|
||||
### Structure
|
||||
|
||||
For core components (`kernel`, `base`, `relibc`, `bootloader`, `installer`, `redoxfs`, `userutils`, `syscall`, `libredox`), this symlink pattern is **LEGACY** — the recipes use `path =` to consume the local fork directly. The `redox.patch` symlinks still exist because they were never cleaned up, but they are NOT consumed by `build-redbear.sh`. See path-fork section above.
|
||||
|
||||
```
|
||||
local/patches/
|
||||
├── kernel/redox.patch # Applied to kernel source during build (symlinked from recipe)
|
||||
├── kernel/redox.patch # Legacy symlink artifact; not consumed by build-redbear.sh
|
||||
├── kernel/P0-*.patch # Individual logical patches (for reference/merge)
|
||||
├── base/redox.patch # Applied to base source during build (symlinked from recipe)
|
||||
├── base/redox.patch # Legacy symlink artifact; not consumed by build-redbear.sh
|
||||
├── base/P0-*.patch # Individual logical patches
|
||||
├── relibc/P3-*.patch # POSIX gap patches (eventfd, signalfd, timerfd, etc.)
|
||||
├── installer/redox.patch # Installer ext4 + GRUB bootloader support
|
||||
@@ -684,14 +686,14 @@ local/patches/
|
||||
|
||||
### Protection Mechanism
|
||||
|
||||
1. **Recipe patches** (`kernel/redox.patch`, `base/redox.patch`): Canonical copy lives in
|
||||
`local/patches/`. The recipe directory contains a **symlink** to it:
|
||||
1. **Path-fork recipes** (`kernel`, `base`, `relibc`, `bootloader`, `installer`, `redoxfs`, `userutils`, `syscall`, `libredox`): the recipes use `path = "../../../local/sources/<component>"` and consume the fork directly.
|
||||
|
||||
Legacy reference only (`kernel/redox.patch`, `base/redox.patch`): canonical copy used to live in `local/patches/`, and the recipe directory contained a **symlink** to it:
|
||||
```
|
||||
recipes/core/kernel/redox.patch → ../../../local/patches/kernel/redox.patch
|
||||
recipes/core/base/redox.patch → ../../../local/patches/base/redox.patch
|
||||
```
|
||||
The build system follows symlinks transparently. Patches are never touched by `make clean`
|
||||
or `make distclean`. Only `local/` modifications affect them.
|
||||
Those symlinks now survive as orphaned artifacts and are no longer consumed by `build-redbear.sh`.
|
||||
|
||||
2. **Build-system patches**: Generated via `git diff` against the upstream base commit.
|
||||
These serve as a backup — the working tree already has patches applied (via git commits).
|
||||
|
||||
Reference in New Issue
Block a user