From b7e070d56497c474527415679f0d2bc21bd26e43 Mon Sep 17 00:00:00 2001 From: vasilito Date: Thu, 23 Jul 2026 06:10:19 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20canonical=20build=20policy=20=E2=80=94?= =?UTF-8?q?=20build-redbear.sh=20is=20the=20ONLY=20build=20tool?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document once and for all that ./local/scripts/build-redbear.sh is the sole sanctioned way to build Red Bear OS, any package, or any target artifact. Forbid cargo check/build/clippy in source trees, cargo test --target in source trees, and repo cook / make r.* / make all / make live as build substitutes (they skip prefix-staleness detection, fingerprint tracking, the concurrency lock, branch gates, and stash-and-restore). Host unit tests (cargo test, no --target) for pure-logic crates are the single sanctioned test alternative. Explain WHY the script is the build (concurrency lock, prefix rebuild, stash-and-restore, branch gate, fingerprints, config parsing). Mark repo cook/make r.* as DIAGNOSTIC ONLY. Give the correct per-component verification flow. --- AGENTS.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 20ed55a872..9a58832f14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,6 +99,59 @@ redox-master/ ## BUILD COMMANDS +### ⛔ CANONICAL BUILD POLICY (ABSOLUTE — READ FIRST) + +**The ONLY way to build Red Bear OS is `./local/scripts/build-redbear.sh`.** + +There is **no other build tool.** Agents and operators **MUST NOT** build Red Bear OS, +any package, or any target artifact with anything else. This is absolute: + +| Forbidden for building Red Bear OS | Why | +|---|---| +| `cargo check` / `cargo build` / `cargo clippy` in any source tree | Bypasses the cross-compile target, sysroot, feature flags, and workspace orchestration. Produces wrong-target or mis-configured output and misleading "it compiles" claims. | +| `cargo test --target x86_64-unknown-redox` (or any target) in a source tree | Same problem — compiles outside the cookbook's sysroot/prefix. | +| `./target/release/repo cook ` **as a substitute for a build** | Diagnostic/diagnostic-only. Outside build-redbear.sh it runs without prefix-staleness detection, source-fingerprint tracking, the concurrency lock, branch gates, or the stash-and-restore guard. The cookbook itself warns: *"repo invoked outside build-redbear.sh"*. | +| `make r.` / `make cr.` **as a substitute for a build** | Same — a thin wrapper over `repo cook`, with the same missing guarantees. | +| `make all` / `make live` directly | build-redbear.sh wraps these with the required preflight (prefix rebuild, version sync, config parsing, protected-fetch policy). Calling them directly skips that preflight. | + +**What "build" means here:** producing any Red Bear OS artifact — a cooked package +(`.pkgar`), a cross-compiled binary for `x86_64-unknown-redox`, a bootable ISO, or the +prefix toolchain. All of these go through build-redbear.sh, and only build-redbear.sh. + +**The single sanctioned alternative — host unit tests.** Running `cargo test` +(without `--target`, on the host) for crates whose tests are pure host-runnable logic +(protocol parsers, quirk tables, format decoders) is a **test** action, not a build +action, and is allowed. This is how `redox-driver-sys`, `firmware-loader`, +`redbear-iwlwifi`, `redbear-wifictl`, `redbear-btusb` host tests are run. It never +produces a Red Bear target artifact. + +**Why build-redbear.sh is the only path (it is not a wrapper — it is the build):** +- **Concurrency lock** (`flock`) — two builds at once corrupt cookbook caches and the prefix. +- **Prefix staleness detection + rebuild** — the #1 cause of "undefined reference" link + errors after relibc/kernel/base fork changes is a stale prefix; only build-redbear.sh + detects and rebuilds it before any recipe compiles. +- **Stash-and-restore** — dirty fork sources (`local/sources/*`) are stashed before the + build and popped on EXIT, so fingerprints reflect committed HEAD. **Uncommitted fork + changes are NOT built** — commit to the `submodule/` branch first. +- **Branch topology gate** — every fork worktree must be on its canonical + `submodule/` branch; the build refuses otherwise. +- **Source-fingerprint tracking + content-hash cache** — correct incremental rebuilds. +- **`.config` parsing + protected-fetch policy + version sync + pre-cooking.** +- Sets `REDBEAR_CANONICAL_BUILD=1` so the cookbook knows it is inside the pipeline. + +**Correct per-component verification flow (the ONLY flow):** +1. Make your edits. +2. Commit to the right branch: fork code → `submodule/` in `local/sources/`; + original recipe code → the release branch in `local/recipes/...`. Push. +3. Bump the parent's submodule pointers if a fork moved; commit + push. +4. Run `./local/scripts/build-redbear.sh redbear-mini` (or `redbear-full`). That is the + build. That is also the compile verification. +5. Run host unit tests (`cargo test`) for pure-logic crates as the test pass. + +If a recipe is not yet included in any `config/redbear-*.toml` target, build-redbear.sh +will not build it — wiring it into a config is a separate integration step, and until +then its verification is host unit tests only. + ```bash # Prerequisites (Linux x86_64 host) # rustup + nightly-2026-05-24, cargo install just cbedgen, nasm, qemu-system-x86 @@ -152,12 +205,16 @@ qemu-system-x86_64 -cdrom build/x86_64/redbear-mini.iso \ # Stale prefix artifacts are the #1 cause of "undefined reference" link errors # after fork changes. build-redbear.sh now warns when prefix is stale. -# Single recipe -./target/release/repo cook recipes/libs/mesa # Build one recipe (uses content-hash cache) -./target/release/repo cook mesa --force-rebuild # Bypass cache, force rebuild -./target/release/repo fetch recipes/core/kernel # Fetch source only -make r.mesa # Make shorthand for cook -make cr.mesa # Clean + rebuild +# Single recipe — DIAGNOSTIC ONLY, NOT A BUILD SUBSTITUTE (see policy above). +# `repo cook` / `make r.*` skip prefix-staleness detection, fingerprint tracking, +# the concurrency lock, and branch gates. Use ONLY for quick diagnostics while a +# canonical build-redbear.sh run is the actual build. When in doubt, use +# build-redbear.sh instead. +./target/release/repo cook recipes/libs/mesa # DIAGNOSTIC: cook one recipe +./target/release/repo cook mesa --force-rebuild # DIAGNOSTIC: bypass cache +./target/release/repo fetch recipes/core/kernel # DIAGNOSTIC: fetch source only +make r.mesa # DIAGNOSTIC: shorthand for cook +make cr.mesa # DIAGNOSTIC: clean + rebuild # Clean make clean # Remove build artifacts