AGENTS.md: document build workflow with build-redbear.sh, cascade rebuild rule

- Recommended workflow: use build-redbear.sh (enforces policies)
- Cascade rebuild rule: rebuild-cascade.sh after low-level changes
- Toolchain updated to nightly (latest)
- Local-over-WIP policy enforcement documented
This commit is contained in:
2026-06-02 22:56:11 +03:00
parent 707a58074e
commit 4a912db671
+37 -1
View File
@@ -1,7 +1,7 @@
# RED BEAR OS BUILD SYSTEM — PROJECT KNOWLEDGE BASE
**Generated:** 2026-04-12 (P1/P2 complete) · Updated: 2026-06 (source ownership migration)
**Toolchain:** Rust nightly-2025-10-03 (edition 2024)
**Toolchain:** Rust nightly (edition 2024)
**Architecture:** Microkernel OS in Rust, ~38k files, ~294k LoC Rust
**Target Hardware**: AMD64 bare metal, with AMD and Intel machines treated as equal-priority Red Bear OS targets
@@ -286,6 +286,42 @@ redox-master/
## BUILD COMMANDS
### Recommended Workflow (use the build script)
The canonical way to build Red Bear OS ISOs is through `local/scripts/build-redbear.sh`.
It enforces all project policies automatically:
```bash
# Build redbear-mini (text-only, recovery) — ~30 min
./local/scripts/build-redbear.sh redbear-mini
# Build redbear-full (3D desktop + SDDM + KDE) — ~90 min first build
./local/scripts/build-redbear.sh redbear-full
# Clean rebuild (discard caches, force recompile)
./local/scripts/build-redbear.sh redbear-full --no-cache
```
**What `build-redbear.sh` does automatically:**
1. **Enforces local-over-WIP**: Any `recipes/wip/` package shadowing a `local/recipes/` package is replaced with a symlink to the local version (per local/recipes/ priority policy)
2. **Verifies overlay integrity**: Checks that all recipe symlinks resolve correctly
3. **Stashes dirty submodules**: Prevents accidental commits from contaminating the build
4. **Checks firmware**: Warns if AMD GPU firmware is missing for redbear-full
**When to use `--no-cache`:**
- After changing `local/sources/{relibc,kernel,base}` (low-level packages)
- After `make clean` or `make distclean`
- When stale cached packages cause build failures
**Cascade rebuild rule:** When a low-level package changes (relibc, kernel, base),
ALL packages that transitively depend on it must be rebuilt. Use:
```bash
./local/scripts/rebuild-cascade.sh relibc # Rebuild relibc + all dependents
./local/scripts/rebuild-cascade.sh --dry-run relibc # Preview without rebuilding
```
### Legacy Manual Build Commands
```bash
# Prerequisites (Linux x86_64 host)
# rustup + nightly-2025-10-03, cargo install just cbedgen, nasm, qemu-system-x86