Files

T

vasilito 1528e04b09 docs: consolidate build-system docs + Tier 1 message fixes

Phase 2 of the build-system assessment:

Tier 1 (user-facing message fixes):
- mk/podman.mk: 'mk/config.mk' -> '.config' (the actual config location)
- mk/prefix.mk: vague 're-run the build' -> specific 'make prefix' guidance
- mk/virtualbox.mk: 'RedBearOS directory' -> 'Red Bear OS VM directory'
- src/bin/repo.rs: '{:?}' -> '{:#}' anyhow chain format + 'repo: ' prefix

Tier 2 (doc consolidation):
- Archive BUILD-SYSTEM-IMPROVEMENTS.md to local/docs/archived/ (self-labeled
  'HISTORICAL POST-MORTEM', no longer current).
- Add local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md (459-line
  comprehensive assessment: architecture, quality, robustness, gaps).
- docs/README.md: refresh status note (2026-05-01 -> 2026-07-18, v4.0 ->
  v6.0); fix 'as an full fork' grammar.
- docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md: add status header noting
  canonical/secondary split vs CONSOLE-TO-KDE-DESKTOP-PLAN.md; fix grammar.
- HARDWARE.md: remove nonexistent PROFILE-MATRIX.md reference; repoint to
  README.md and the canonical desktop plan.
- local/docs/LOCAL-FORK-SUPREMACY-POLICY.md: 'currently 0.1.0' -> 'currently
  branch 0.3.1; legacy release archive at sources/redbear-0.1.0/'.
- local/docs/GRUB-INTEGRATION-PLAN.md: 'make all CONFIG_NAME=redbear-grub'
  -> canonical './local/scripts/build-redbear.sh redbear-grub'.
- recipes/AGENTS.md, recipes/core/AGENTS.md: replace upstream-Redox-pattern
  content with proper redirects to root AGENTS.md reflecting the local
  fork / path-fork model actually used by Red Bear.
- CONTRIBUTING.md: full rewrite for local fork workflow (Gitea, single-repo
  rule, path-fork model, patch governance, build-redbear.sh as canonical
  entry point, no AI attribution policy).
- README.md: add BUILD-SYSTEM-ASSESSMENT-2026-07-18.md to Documentation list.

Verified: cargo check (0 errors), cargo test --lib (35/35 passed),
cargo clippy (0 new warnings vs baseline).

2026-07-18 16:32:19 +09:00

4.3 KiB

Raw Blame History

RECIPES/CORE — ESSENTIAL SYSTEM COMPONENTS

Authority: This file is a quick orientation pointer for the core-component recipes. Canonical policy lives in root AGENTS.md. For the local fork model, single-repo rule, branch/submodule policy, and durability rules, read local/AGENTS.md first.

Path-fork model (CURRENT — supersedes legacy patch model)

The following core components are maintained as local forks in local/sources/<component>/ and consumed via path = in the recipe TOML. The legacy redox.patch symlinks in this directory are no longer consumed by build-redbear.sh and remain only as orphan artifacts pending cleanup.

Component	Local fork path	Notes
`kernel`	`local/sources/kernel/`	Microkernel; syscall ABI unstable by design — use `libredox`/`relibc`
`relibc`	`local/sources/relibc/`	POSIX C library in Rust; `local/patches/relibc/` holds reference + archived patches only
`base`	`local/sources/base/`	Drivers + system components; recipe uses `path = "..."`
`bootloader`	`local/sources/bootloader/`	UEFI bootloader (x86_64-uefi, aarch64-uefi)
`installer`	`local/sources/installer/`	`redox_installer` — creates filesystem images
`redoxfs`	`local/sources/redoxfs/`	Default filesystem
`userutils`	`local/sources/userutils/`	Core user management
`syscall`	(Cargo path dep via `redbear-rt` consumers)	NOT wired via `recipe.toml path =`
`libredox`	(Cargo path dep via `redbear-rt` consumers)	NOT wired via `recipe.toml path =`

To rehydrate a fork source tree after make distclean:

rm -rf recipes/core/<component>/source
./local/scripts/build-redbear.sh redbear-mini   # repo cook recopies from local/sources/

For fork development with online fetch:

export REDBEAR_ALLOW_PROTECTED_FETCH=1
./local/scripts/build-redbear.sh --upstream redbear-mini

Driver model (unchanged from upstream Redox)

ALL drivers are userspace daemons (except serio for PS/2).
Hardware access: scheme:memory (MMIO), scheme:irq (interrupts), iopl syscall (port I/O).
PCI devices discovered by pcid daemon → spawns drivers per pcid/config.toml.
Driver registers as scheme: daemon name becomes /scheme/<name>.

Stale prefix detection (CRITICAL)

The prefix toolchain (prefix/x86_64-unknown-redox/) provides the cross-compiler and relibc sysroot (libc.a, system headers) used by ALL recipe builds. When a local fork (relibc, kernel, base) gains new commits:

touch relibc && make prefix    # Rebuild relibc in the cross-toolchain
touch kernel && make prefix    # Rebuild kernel-related toolchain parts

build-redbear.sh auto-detects stale prefix and rebuilds before any recipe build. A stale prefix is the #1 cause of "undefined reference" link errors after fork changes.

Historical POSIX gaps in relibc (now mostly PATCHED-VIA-PATH-FORK)

The current relibc work is no longer "add the missing Wayland APIs" — those are largely in the fork now. The higher-value remaining work is completeness depth, downstream cleanup, and runtime validation. See local/sources/relibc/ for the actual current state.

For evidence-qualified support language, refer to local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md rather than per-API tables here, which can drift from the fork HEAD.

Anti-patterns (see root AGENTS.md for full list)

DO NOT add drivers to kernel — all drivers must be userspace
DO NOT modify syscall ABI — use libredox/relibc wrappers
DO NOT use unwrap()/expect() in drivers — handle errors with Result
DO NOT hardcode /dev/ paths — use scheme paths (/scheme/drm/card0)
DO NOT remove patches to fix build failures — rebase them
DO NOT remove BINS entries — fix the source or use EXISTING_BINS

4.3 KiB Raw Blame History