From 890be982a6bee3856952c5dc61fa044fd9ad97f3 Mon Sep 17 00:00:00 2001 From: vasilito Date: Thu, 2 Jul 2026 22:54:47 +0300 Subject: [PATCH] docs: enforce canonical build command across all docs Replace all non-canonical build invocations (bare 'make all/live CONFIG_NAME=', 'scripts/build-iso.sh', 'scripts/run.sh') with the canonical './local/scripts/build-redbear.sh' wrapper. Updated: AGENTS.md, local/AGENTS.md, README.md, docs/README.md, docs/06-BUILD-SYSTEM-SETUP.md, and 6 active local/docs plan files. Archived docs and frozen boot-logs left as-is (historical evidence). --- AGENTS.md | 44 +++++++++---------- README.md | 11 +++-- docs/06-BUILD-SYSTEM-SETUP.md | 28 +++++------- docs/README.md | 6 +-- local/AGENTS.md | 41 +++++++---------- local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md | 10 ++--- local/docs/BUILD-SYSTEM-HARDENING-PLAN.md | 2 +- local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md | 2 +- ...ADING-COMPREHENSIVE-ASSESSMENT-AND-PLAN.md | 2 +- local/docs/PATCH-GOVERNANCE.md | 2 +- local/docs/boot-logs/README.md | 2 +- 11 files changed, 65 insertions(+), 85 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9c3de26a3e..0eb3db0e97 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -113,23 +113,25 @@ echo 'PODMAN_BUILD?=1' > .config # Podman container build # archive and ignores the local forks. Remove it if present: grep -v REDBEAR_RELEASE .config > .config.tmp && mv .config.tmp .config -# Build Red Bear OS +# Build Red Bear OS — CANONICAL build command is build-redbear.sh # Supported compile targets: -# redbear-full desktop/graphics target (harddrive.img or live ISO) -# redbear-mini text-only console/recovery target (harddrive.img or live ISO) +# redbear-full desktop/graphics target (live ISO) +# redbear-mini text-only console/recovery target (live ISO) # redbear-grub text-only with GRUB boot manager (live ISO) # Desktop/graphics target: redbear-full # Text-only targets: redbear-mini, redbear-grub -./local/scripts/build-redbear.sh redbear-mini # Recommended (dev mode, local forks) +./local/scripts/build-redbear.sh redbear-mini # Recommended (dev mode, offline) ./local/scripts/build-redbear.sh --upstream redbear-mini # With online fetch (fast iteration) -make all CONFIG_NAME=redbear-mini # Text-only target → harddrive.img -make all CONFIG_NAME=redbear-full # Desktop/graphics target → harddrive.img -make live CONFIG_NAME=redbear-full # Full desktop live ISO -make live CONFIG_NAME=redbear-mini # Text-only mini live ISO -make live CONFIG_NAME=redbear-grub # Text-only mini live ISO with GRUB -CI=1 make all CONFIG_NAME=redbear-mini # CI mode (disables TUI, for non-interactive) +./local/scripts/build-redbear.sh redbear-full # Desktop/graphics target +./local/scripts/build-redbear.sh redbear-grub # Text-only + GRUB +./local/scripts/build-redbear.sh --no-cache redbear-mini # Force clean rebuild -# IMPORTANT: For local fork development, use: +# build-redbear.sh handles: .config parsing, prefix staleness detection, +# local-over-WIP policy, version sync, pre-cooking critical packages, +# source fingerprint tracking, and ultimately calls `make live`. +# Output: build//.iso + +# For local fork development: # export REDBEAR_ALLOW_PROTECTED_FETCH=1 # base/kernel/relibc are protected recipes # ./local/scripts/build-redbear.sh --upstream redbear-mini # Without --upstream, the build is in offline mode and re-extracts from @@ -138,7 +140,6 @@ CI=1 make all CONFIG_NAME=redbear-mini # CI mode (disables TUI, for non-inter # Run make qemu # Boot in QEMU make qemu QEMUFLAGS="-m 4G" # With more RAM -make live # Build live ISO for real bare metal # QEMU with network access (required for testing): qemu-system-x86_64 -cdrom build/x86_64/redbear-mini.iso \ @@ -426,12 +427,7 @@ Red Bear OS is a **fork with frozen sources**. The cookbook tool defaults to `COOKBOOK_OFFLINE=true` (changed from upstream Redox's `false`). Builds use archived sources from `sources/redbear-0.1.0/` — no network access during compilation. -To allow online fetching for non-protected development recipes: -```bash -COOKBOOK_OFFLINE=false make all CONFIG_NAME=redbear-full -``` - -Or use the `--upstream` flag of `build-redbear.sh`: +To allow online fetching for non-protected development recipes, use the `--upstream` flag: ```bash ./local/scripts/build-redbear.sh --upstream redbear-mini ``` @@ -514,7 +510,7 @@ After ANY change to patches or `recipe.toml`: 3. Fetch: `repo --allow-protected fetch ` 4. Build: `repo cook ` 5. Verify no `FAILED`, `[ATOMIC] patch application rolled back`, or `.rej` files -6. Full image: `make all CONFIG_NAME=` +6. Full image: `./local/scripts/build-redbear.sh ` The `repo validate-patches` command (added 2026-05) performs a dry-run patch application against clean upstream source in a temporary staging directory. @@ -707,10 +703,12 @@ base) gains new commits, the prefix must be rebuilt: touch relibc && make prefix # Rebuild relibc in the cross-toolchain ``` -`build-redbear.sh` includes a preflight check that warns when fork commits are newer than -prefix artifacts. **A stale prefix is the #1 cause of "undefined reference" link errors** -after fork changes (e.g., adding `__freadahead` to relibc's `ext.rs` without rebuilding the -prefix). +`build-redbear.sh` **automatically rebuilds the prefix** when it detects that fork repos +(relibc, kernel, base) have commits newer than the prefix `libc.a`. This happens before any +recipe build begins. If the prefix rebuild fails, the build aborts immediately — recipes are +never compiled against a stale prefix. **A stale prefix is the #1 cause of "undefined reference" +link errors** after fork changes (e.g., adding `__freadahead` to relibc's `ext.rs` without +rebuilding the prefix). ### relibc Header Circular Includes (Fixed) diff --git a/README.md b/README.md index 20ddb4fbcf..73452f2a65 100644 --- a/README.md +++ b/README.md @@ -72,18 +72,17 @@ git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/R make qemu ``` -> **Build script:** `local/scripts/build-redbear.sh` is the canonical entry point. Bare -> `make all` works but bypasses the `.config` checking and `REDBEAR_ALLOW_PROTECTED_FETCH=1` -> gates that `build-redbear.sh` enforces. See `AGENTS.md` § Build Commands for full details. +> **Build script:** `local/scripts/build-redbear.sh` is the canonical and only +> supported build entry point. It handles `.config` parsing, prefix staleness +> detection, `REDBEAR_ALLOW_PROTECTED_FETCH=1`, pre-cooking critical packages, +> and source fingerprint tracking. Direct `make` invocations bypass these gates +> and should not be used. See `AGENTS.md` § Build Commands for full details. ### Public Scripts | Script | Purpose | |--------|---------| | `local/scripts/build-redbear.sh` | **Canonical** build wrapper for redbear-mini/full/grub | -| `scripts/run.sh` | Build and run in QEMU (`-b` to build, `-c ` for target) | -| `scripts/build-iso.sh` | Build a live ISO for bare-metal boot | -| `scripts/build-all-isos.sh` | Build all live ISO targets | | `scripts/network-boot.sh` | PXE network boot helper | | `scripts/dual-boot.sh` | Dual-boot installation helper | diff --git a/docs/06-BUILD-SYSTEM-SETUP.md b/docs/06-BUILD-SYSTEM-SETUP.md index 98ab3e45e9..8ac2c80258 100644 --- a/docs/06-BUILD-SYSTEM-SETUP.md +++ b/docs/06-BUILD-SYSTEM-SETUP.md @@ -121,15 +121,12 @@ desktop-capable target. These produce images such as `build/x86_64/harddrive.img` or `build/x86_64/redbear-mini.iso`. -### Bare `make all` (Legacy / Advanced) +### Bare `make all` (Not Supported) -```bash -make all CONFIG_NAME=redbear-mini -``` - -Bare `make all` works but bypasses the policy gates (`.config` checking, -`REDBEAR_ALLOW_PROTECTED_FETCH=1`, etc.) that `build-redbear.sh` enforces. Prefer the wrapper -unless you specifically need to bypass those gates. +Direct `make` invocations bypass the policy gates (`.config` checking, +`REDBEAR_ALLOW_PROTECTED_FETCH=1`, prefix staleness detection, local-over-WIP +enforcement, pre-cooking, source fingerprint tracking) that `build-redbear.sh` +enforces. **Always use `build-redbear.sh`.** ### Export External Toolchain @@ -152,25 +149,20 @@ make export-toolchain TARGET=x86_64-unknown-redox \ ### Build with Specific Config ```bash -# Preferred Red Bear wrapper: +# Canonical Red Bear wrapper (produces live ISO): ./local/scripts/build-redbear.sh redbear-mini ./local/scripts/build-redbear.sh redbear-full ./local/scripts/build-redbear.sh redbear-grub - -# Direct make is still valid when needed: -make all CONFIG_NAME=redbear-full ``` For tracked Red Bear work, prefer these three compile targets over older historical names. -### Build a Live ISO +### Live ISO -```bash -make live CONFIG_NAME=redbear-full -# Produces: build/x86_64/redbear-live.iso -``` +`build-redbear.sh` already produces a live ISO (it calls `make live` internally). +Output: `build//.iso` -Live `.iso` outputs are for real bare-metal boot, install, recovery, and demo workflows. They are not the VM/QEMU execution surface; for virtualization, use `make qemu` and the `harddrive.img` path instead. +Live `.iso` outputs are for real bare-metal boot, install, recovery, and demo workflows. ### Rebuild After Changes diff --git a/docs/README.md b/docs/README.md index 4b43ae3942..54f24a70d5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -100,7 +100,7 @@ This summary is only a quick orientation layer. For canonical current-state deta - and the active subsystem plans under `local/docs/` for detailed current workstreams. - **Compile targets**: the supported compile targets are `redbear-mini`, `redbear-full`, and `redbear-grub` -- **Live ISO policy**: live `.iso` outputs (`make live`) are for real bare-metal boot/install/recovery workflows, not the VM/QEMU execution surface. +- **Live ISO policy**: live `.iso` outputs (`build-redbear.sh`) are for real bare-metal boot/install/recovery workflows, not the VM/QEMU execution surface. - **Wayland**: libwayland + wayland-protocols built. A bounded greeter/compositor-backed login proof now passes, but broader compositor/runtime stability remains incomplete. - **Qt6**: qtbase 6.11.0 (Core+Gui+Widgets+DBus+Wayland), qtdeclarative, qtsvg, qtwayland ALL BUILT - **D-Bus**: 1.16.2 built for Redox. Qt6DBus enabled. @@ -134,8 +134,8 @@ cargo install just cbindgen # 3. Configure for native build (no Podman) echo 'PODMAN_BUILD?=0' > .config -# 4. Build (downloads cross-toolchain, then compiles) -make all +# 4. Build (canonical command — produces live ISO) +./local/scripts/build-redbear.sh redbear-mini # 5. Run in QEMU make qemu diff --git a/local/AGENTS.md b/local/AGENTS.md index d00ef32be2..3c9acd76c3 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -345,12 +345,11 @@ history and force-push the rewritten history on a feature branch before merging. Build flow: ``` -make all CONFIG_NAME=redbear-full - → mk/config.mk resolves to the active desktop/graphics compile target - → Desktop/graphics are available only on redbear-full +./local/scripts/build-redbear.sh + → .config parsing, prefix staleness detection, local-over-WIP policy → repo cook builds all packages from local sources (offline by default) - → mk/disk.mk creates harddrive.img with Red Bear branding - → REDBEAR_RELEASE=0.1.0 ensures immutable, archived sources + → mk/disk.mk creates .iso (live ISO) with Red Bear branding + → Output: build//.iso ``` Release flow: @@ -367,8 +366,8 @@ Release flow: ## ACTIVE COMPILE TARGETS -The supported compile targets are exactly three. All three work for both `make all` (harddrive.img) -and `make live` (ISO): +The supported compile targets are exactly three. `build-redbear.sh` produces +a live ISO for each: - `redbear-full` — Desktop/graphics-enabled target (Wayland + KDE + GPU drivers) - `redbear-mini` — Text-only console/recovery/install target @@ -674,8 +673,10 @@ The prefix provides the cross-compiler sysroot used by ALL recipe builds. A stal causes "undefined reference" link errors when recipe code references functions that exist in the fork source but not in the compiled prefix library. -`build-redbear.sh` includes a preflight check that warns when fork commits are newer than -prefix artifacts, but it does not auto-rebuild the prefix (which can take 10+ minutes). +`build-redbear.sh` **automatically rebuilds the prefix** when it detects that fork repos +(relibc, kernel, base) have commits newer than the prefix `libc.a`. This happens before any +recipe build begins. If the prefix rebuild fails, the build aborts immediately — recipes are +never compiled against a stale prefix. **Historical example:** relibc commit `047e7c0` added `__freadahead()` to `ext.rs`, but the prefix `libc.a` was built before that commit. m4's gnulib expected `__freadahead` to @@ -769,25 +770,15 @@ redox-master/ ← git pull updates mainline Redox ## HOW TO BUILD RED BEAR OS ```bash -# Build targets (all three work for both `make all` and `make live`) +# CANONICAL build command — produces a live ISO for bare metal ./local/scripts/build-redbear.sh redbear-full # Desktop/graphics target ./local/scripts/build-redbear.sh redbear-mini # Text-only console/recovery target ./local/scripts/build-redbear.sh redbear-grub # Text-only with GRUB boot manager -# Or manually: -make all CONFIG_NAME=redbear-full # Desktop/graphics → harddrive.img -make all CONFIG_NAME=redbear-mini # Text-only → harddrive.img -make all CONFIG_NAME=redbear-grub # Text-only + GRUB → harddrive.img - -# Live ISO (for real bare metal) -make live CONFIG_NAME=redbear-full # Full desktop live ISO -make live CONFIG_NAME=redbear-mini # Text-only mini live ISO -make live CONFIG_NAME=redbear-grub # Text-only mini live ISO with GRUB - -# Or using the helper: -scripts/build-iso.sh redbear-full # Full desktop live ISO -scripts/build-iso.sh redbear-mini # Text-only mini (default) -scripts/build-iso.sh redbear-grub # Text-only + GRUB +# Options: +# --upstream Allow online recipe source fetch (fast iteration with local forks) +# --no-cache Force clean rebuild, discarding cached packages +# Output: build//.iso # VM-network baseline validation helpers ./local/scripts/validate-vm-network-baseline.sh @@ -885,7 +876,7 @@ redbear-netctl --help # GRUB boot manager (installer-native): make r.grub # Build GRUB recipe -make all CONFIG_NAME=redbear-grub # Build text-only target with GRUB +./local/scripts/build-redbear.sh redbear-grub # Build text-only target with GRUB # Linux-compatible CLI (add local/scripts to PATH): grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img grub-mkconfig -o local/recipes/core/grub/grub.cfg diff --git a/local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md b/local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md index 9915698209..b17b37dbb3 100644 --- a/local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md +++ b/local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md @@ -254,7 +254,7 @@ Every bump re-introduces drift. Per AGENTS.md §Patch Governance: "DO NOT remove ## 5. Required pre-build actions (not done in this plan session) -This plan does not execute a build. The following actions are required *before* a `make all CONFIG_NAME=redbear-full` can succeed: +This plan does not execute a build. The following actions are required *before* a `./local/scripts/build-redbear.sh redbear-full` can succeed: 1. **Re-pull every Qt subrecipe** to point at `qt-everywhere-src-6.10.3.tar.xz`. Re-blake3. 2. **Re-pull every KF6 subrecipe** to point at `kf6--v6.27.0` tarball. Re-blake3. @@ -296,8 +296,8 @@ The `0.2.5` branch will be **frozen** (no further recipe.toml bumps) when **all* - [ ] `recipes/libs/libxkbcommon` pin to 1.9.2. - [ ] `recipes/libs/mesa` decision recorded: 24.0.8 (fork) or 26.1.4 (upstream rebase). - [ ] `repo validate-patches ` exits 0 for every recipe. -- [ ] `make all CONFIG_NAME=redbear-full` reaches the disk-image stage (filesystem.img + harddrive.img produced). -- [ ] `make live CONFIG_NAME=redbear-full` produces `build/x86_64/redbear-full.iso`. +- [ ] `./local/scripts/build-redbear.sh redbear-full` reaches the disk-image stage (filesystem.img + harddrive.img produced). +- [ ] `./local/scripts/build-redbear.sh redbear-full` produces `build/x86_64/redbear-full.iso`. - [ ] `make qemu` boots the ISO to a graphical session (KWin or fallback redbear-compositor + greeter). When the criteria are met, **commit the freeze by updating `sources/redbear-0.2.5/` archive** and tagging the branch tip. @@ -407,7 +407,7 @@ Note: kde utility versioning convention changed; `konsole` now uses the `v26.04. - **SDDM 0.21.0:** already at upstream latest. - **kf6-attica, kf6-prison, kf6-kirigami, etc:** all targeted at v6.27.0 (real upstream latest) but see above. -### 9.5 Things to do before `make all CONFIG_NAME=redbear-full` can succeed +### 9.5 Things to do before `./local/scripts/build-redbear.sh redbear-full` can succeed In order: 1. Per-recipe: rebase `local/patches//*.patch` against the new upstream source. Save rebased versions in place; do not bump `P` numbers; do not delete patches unless upstream absorbed the change. @@ -415,5 +415,5 @@ In order: 3. `touch relibc && make prefix` to refresh relibc stage in the cross-toolchain. 4. `repo validate-patches ` for each. 5. Touch-relibc-then-make-prefix between any relibc-aware recipe change (qtbase and friends touch relibc syscalls). -6. Re-run `make all CONFIG_NAME=redbear-full` and address new breakage as it surfaces. +6. Re-run `./local/scripts/build-redbear.sh redbear-full` and address new breakage as it surfaces. 7. Address KF6 6.27.0 bump (multi-day; multi-week with 38 patch rebases). diff --git a/local/docs/BUILD-SYSTEM-HARDENING-PLAN.md b/local/docs/BUILD-SYSTEM-HARDENING-PLAN.md index 789d1207c7..0e1ff8df87 100644 --- a/local/docs/BUILD-SYSTEM-HARDENING-PLAN.md +++ b/local/docs/BUILD-SYSTEM-HARDENING-PLAN.md @@ -476,7 +476,7 @@ build artifacts). Updated `BLAKE3SUMS` with the new checksum. ### Acceptance - [x] `repo validate-patches relibc` passes all 25 patches -- [x] `make all CONFIG_NAME=redbear-full` completes successfully +- [x] `./local/scripts/build-redbear.sh redbear-full` completes successfully - [x] QEMU boots to login prompt with virtio-gpu (1280×800) and vesad console (1280×720) - [x] All protected recipes use only archived sources - [x] `diff -ruN` patches apply correctly after normalization diff --git a/local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md b/local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md index 688cafb017..8f3d3435d0 100644 --- a/local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md +++ b/local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md @@ -710,7 +710,7 @@ local/patches/relibc/P4-initgroups.patch |-------|---------| | Kernel compiles | `make r.kernel` | | relibc compiles | `make r.relibc` | -| Full OS builds | `make all CONFIG_NAME=redbear-full` | +| Full OS builds | `./local/scripts/build-redbear.sh redbear-full` | ### 8.2 Runtime Evidence diff --git a/local/docs/MULTITHREADING-COMPREHENSIVE-ASSESSMENT-AND-PLAN.md b/local/docs/MULTITHREADING-COMPREHENSIVE-ASSESSMENT-AND-PLAN.md index 96b39ce551..7ffebcd656 100644 --- a/local/docs/MULTITHREADING-COMPREHENSIVE-ASSESSMENT-AND-PLAN.md +++ b/local/docs/MULTITHREADING-COMPREHENSIVE-ASSESSMENT-AND-PLAN.md @@ -682,7 +682,7 @@ Phase 0 (Patch Recovery) ← BLOCKING FOR ALL OTHERS | Kernel compiles | `make r.kernel` | | relibc compiles | `make r.relibc` | | Prefix rebuilt | `touch relibc kernel && make prefix` | -| Full OS builds | `make all CONFIG_NAME=redbear-mini` | +| Full OS builds | `./local/scripts/build-redbear.sh redbear-mini` | ### 6.2 Runtime Evidence (QEMU) diff --git a/local/docs/PATCH-GOVERNANCE.md b/local/docs/PATCH-GOVERNANCE.md index ca5fcc5ebc..c2b711a96a 100644 --- a/local/docs/PATCH-GOVERNANCE.md +++ b/local/docs/PATCH-GOVERNANCE.md @@ -78,7 +78,7 @@ After ANY change to the patches list or patch files: 2. Full rebuild: `REDBEAR_ALLOW_PROTECTED_FETCH=1 CI=1 make r.base` 3. Verify NO "FAILED" or "rejects" in output 4. Verify all expected binaries in stage: `ls stage/usr/bin/ stage/usr/lib/drivers/` -5. Full image build: `CI=1 make all CONFIG_NAME=redbear-full` +5. Full image build: `./local/scripts/build-redbear.sh redbear-full` ## Known Issues diff --git a/local/docs/boot-logs/README.md b/local/docs/boot-logs/README.md index 8544ee5e9c..ecdcfb71b2 100644 --- a/local/docs/boot-logs/README.md +++ b/local/docs/boot-logs/README.md @@ -53,5 +53,5 @@ integrity, submodule hygiene, firmware presence warning) that bare `make all` / ## QEMU boot ```bash -make qemu CONFIG_NAME=redbear-mini # Boot the latest built image in QEMU +make qemu # Boot the latest built image in QEMU ```