vasilito
1528e04b09
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).
85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# 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`](../../AGENTS.md). For the local fork model,
|
|
> single-repo rule, branch/submodule policy, and durability rules, read
|
|
> [`local/AGENTS.md`](../../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`:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`
|
|
|
|
## Further reading
|
|
|
|
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — canonical desktop path plan
|
|
- `local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` — kernel credential syscalls + IPC (implemented)
|
|
- `local/docs/ACPI-IMPROVEMENT-PLAN.md` — ACPI ownership, robustness, validation
|
|
- `local/docs/PATCH-GOVERNANCE.md` — patch lifecycle and orphan-patch decision tree
|
|
- `local/docs/LOCAL-FORK-SUPREMACY-POLICY.md` — fork-version coherence requirements
|