# 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