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).
This commit is contained in:
@@ -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/<arch>/<config>.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 <recipe>`
|
||||
4. Build: `repo cook <recipe>`
|
||||
5. Verify no `FAILED`, `[ATOMIC] patch application rolled back`, or `.rej` files
|
||||
6. Full image: `make all CONFIG_NAME=<target>`
|
||||
6. Full image: `./local/scripts/build-redbear.sh <target>`
|
||||
|
||||
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)
|
||||
|
||||
|
||||
@@ -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 <config>` 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 |
|
||||
|
||||
|
||||
@@ -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/<arch>/<config>.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
|
||||
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
+16
-25
@@ -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>
|
||||
→ .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 <config>.iso (live ISO) with Red Bear branding
|
||||
→ Output: build/<arch>/<config>.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/<arch>/<config>.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
|
||||
|
||||
@@ -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-<project>-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 <every recipe with a local patch>` 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/<recipe>/*.patch` against the new upstream source. Save rebased versions in place; do not bump `P<N>` 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 <recipe>` 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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user