RedBear-OS/local/docs/BUILD-SYSTEM.md

Red Bear OS — Build System (canonical reference)

This is the single authoritative description of how Red Bear OS is built. Deeper dives live in companion docs and are linked where relevant: BUILD-SYSTEM-INVARIANTS.md (surfaces & propagation order), SCRIPT-BEHAVIOR-MATRIX.md (per-script roles), PATCH-GOVERNANCE.md, BUILD-CACHE-PLAN.md, RELEASE-BUMP-WORKFLOW.md, and host setup in ../../docs/06-BUILD-SYSTEM-SETUP.md.

---

1. The one entry point

./local/scripts/build-redbear.sh [OPTIONS] [CONFIG]

build-redbear.sh is the ONLY supported way to build. It sets REDBEAR_CANONICAL_BUILD=1 and orchestrates every stage below. Do not invoke repo cook, make live, or cargo build --target … directly as a build substitute — they run outside the gates and produce off-pipeline artifacts (diagnostic use only).

CONFIG is one of:

Config	What it builds
redbear-full	Desktop/graphics target (Wayland/KDE/Qt/Mesa). Default.
redbear-mini	Text-only console/recovery target
redbear-grub	Text-only with the GRUB boot manager
redbear-bare	Kernel + 7-daemon initfs + login shell (minimum bootable)

The running script prints its own version banner (magenta) at start, e.g. ══════ build-redbear.sh v1.3 ══════. --version prints full provenance (script version, OS version from the git branch, repo commit, host, arch).

2. Options (flags)

Flags are the canonical interface. Colored output is automatic on a TTY and suppressed when piped or when NO_COLOR is set.

Common:

Flag	Effect
-j, --jobs N	Parallel build jobs (default: nproc)
--upstream	Allow upstream recipe source refresh (goes online)
--no-cache	Force a clean rebuild, discarding cached packages
--release VER	Build from the immutable release archive VER
--allow-dirty	Build with uncommitted fork edits — cooks the working tree AS-IS
--keep-build-state	Keep the diagnostic state dir after exit
-h, --help / -V, --version	Help / version

Advanced escape hatches stay as environment variables (rare; emergency/CI): REDBEAR_ALLOW_CONCURRENT, REDBEAR_ALLOW_WRONG_BRANCH, REDBEAR_SKIP_PREFIX_REBUILD, REDBEAR_FORCE_TOOLCHAIN_RECOOK, REDBEAR_SKIP_FORK_VERIFY, REDBEAR_SKIP_DRIFT_CHECK, REDBEAR_SKIP_FUNCTION_CHECK, REDBEAR_SKIP_COLLISION_CHECK, REDBEAR_SKIP_PATCH_CONTENT_CHECK, REDBEAR_STRICT_DURABILITY, REDBEAR_STRICT_METADATA, REDBEAR_NO_VALIDATE, REDBEAR_COLLISIONS_WARN. The common flags' old env vars (REDBEAR_ALLOW_DIRTY, REDBEAR_KEEP_BUILD_STATE, REDBEAR_ALLOW_UPSTREAM, REDBEAR_RELEASE, JOBS) are still honored as deprecated fallbacks; a flag always overrides the environment.

3. What a build does, in order

1. Concurrency lock — a flock refuses a second concurrent build (REDBEAR_ALLOW_CONCURRENT=1 overrides).
2. Cookbook binary — rebuilds target/release/repo if any src/*.rs changed (content fingerprint, not mtime).
3. Overlay integrity — verifies recipes/ → local/recipes/ symlinks; repairs via guard-recipes.sh --fix if needed.
4. Local-over-WIP — recipes/wip/* that shadow a local/recipes/ package are replaced with symlinks to the local version.
5. Dirty-source gate — refuses to build if any local/sources/<fork> has uncommitted edits, unless --allow-dirty (then it cooks the tree as-is). The build does not stash your tree — see §6.
6. Branch gate — each fork must be on its submodule/<name> branch.
7. Staleness invalidation — if a fork changed, invalidate the right pkgars. relibc/base/etc. only relink the static initfs-critical binaries (base, redoxfs, userutils, bootstrap); the dynamically-linked desktop is untouched (shared libc.so, the glibc model). Host fstools are rebuilt if installer/redoxfs changed.
8. Prefix sysroot — if relibc is newer than the prefix libc.a, the derived prefix markers are removed and make prefix genuinely re-cooks relibc into the sysroot (a no-op is reported honestly, never as success). kernel/base-only staleness does not touch the prefix.
9. Preflight — build-preflight.sh: repairs broken recipe symlinks, fork version/drift/function verification, collision detection, source-tree validation. The fork-function check treats inert std-trait methods (fmt/eq/clone/…) as warnings; intentional divergences are listed in each fork's .verify-fork-functions.exclude.
10. Version sync check — sync-versions.sh --check (see §7).
11. Pre-cook — cooks a small ordered set of critical packages (CI=1, offline unless --upstream).
12. make live — the cookbook builds the config's package graph and the installer assembles the image.
13. Critical-package gate — for redbear-full, fails loudly if mesa/qt/… pkgars are missing (cookbook returns 0 even when recipes fail).
14. Fingerprints — fork source fingerprints are recorded only after a successful build, so a failed build never marks forks as "built".

On failure the EXIT trap dumps diagnostics (last log lines, orphaned cook processes, and per-recipe state scoped to this build so a mini build never lists leftover graphical packages) and preserves the state dir under --keep-build-state.

4. Offline / release mode

Cooking is offline by default (COOKBOOK_OFFLINE=true, REPO_OFFLINE=1). --upstream goes online for non-protected recipes. --release VER builds from sources/redbear-<VER>/ immutable archives and forces offline; new releases are created only via provision-release.sh. A stray REDBEAR_RELEASE= line in .config silently switches the whole build off the local forks — the script never auto-sets it. See RELEASE-BUMP-WORKFLOW.md.

5. Caching & staleness

Per-recipe caching is BLAKE3 content-hash based (dep_hashes.toml + source_hash.txt), not mtime. --no-cache wipes repo/ and recipe target/ dirs. Cargo path-dep crates (syscall/libredox/redox-scheme) have no pkgar, so build-redbear.sh tracks their source fingerprints and forces a userspace relink when they change. See BUILD-CACHE-PLAN.md.

6. No working-tree stashing (design)

The build never stashes your working tree. An earlier version stashed dirty forks and restored them on exit, but modern git's stash push does not print the stash SHA on stdout, so the stash was recorded incorrectly and never restored — stranding operator WIP in git stash list on every dirty build. The machinery was removed entirely. Today: a clean tree cooks committed HEAD; --allow-dirty cooks the tree as-is. A read-only startup advisory reports any leftover redbear-build-* stashes from the old code (recover them from git stash list; see ../recovered-stashes/README.md).

7. Forks & versioning

local/sources/<fork>/ (the 9 submodule forks) take precedence over recipes/<fork>/. Version policy (sync-versions.sh):

• Cat 1 — in-house crates under local/recipes/*/source/: version = <branch> (e.g. 0.3.1).
• Cat 2 — upstream forks under local/sources/*/: version = <upstream-tag>+rb<branch> (e.g. 0.9.0+rb0.3.1; +rb build metadata, never -rb).
• Vendored upstream under local/recipes/ (e.g. brush, a Cargo workspace): keeps its upstream crate versions (internal ^ requirements). Mark it with a .vendored-upstream file in the recipe dir so sync-versions.sh skips it — do not stamp it with the branch version. zbus/tlc are excluded by name.

sync-versions.sh --check is a build-time gate; sync-versions.sh applies the sync. See PATCH-GOVERNANCE.md for the durability rules (source trees are disposable; only local/ survives).

8. Self-versioning of this script

BUILD_REDBEAR_VERSION in build-redbear.sh starts at 1.0 and is auto-bumped (minor) by a pre-commit git hook (bump-build-version.sh) whenever the script is committed. Install hooks with ./local/scripts/install-git-hooks.sh.