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).
86 lines
3.8 KiB
Markdown
86 lines
3.8 KiB
Markdown
# RECIPES — PACKAGE RECIPE SYSTEM
|
|
|
|
> **Authority:** This file is a quick orientation pointer. The canonical recipe-system
|
|
> documentation lives in the root [`AGENTS.md`](../AGENTS.md) (sections STRUCTURE, WHERE TO LOOK,
|
|
> BUILD FLOW, CONVENTIONS, DURABILITY POLICY, PATCH MANAGEMENT) and
|
|
> [`local/AGENTS.md`](../local/AGENTS.md) (local fork model, custom recipes, branch/submodule
|
|
> policy). Read those first. This file only adds recipe-specific navigation.
|
|
|
|
## Recipe categories
|
|
|
|
26 categories of package recipes under `recipes/<category>/<name>/recipe.toml` defining
|
|
fetch → build → stage. See root `AGENTS.md` for the full category tree.
|
|
|
|
## How to add a recipe
|
|
|
|
Prefer the **local fork / local recipe** model over the upstream-Redox `redox.patch` pattern:
|
|
|
|
1. **Custom package (Red Bear original)** → create `local/recipes/<category>/<name>/recipe.toml`
|
|
and symlink `recipes/<category>/<name>` → `../../local/recipes/<category>/<name>`.
|
|
In-house crates MUST use the current Red Bear OS version (see root `AGENTS.md`
|
|
"In-house crate versioning").
|
|
|
|
2. **Upstream package with Red Bear patches** → edit the recipe in place and add patches under
|
|
`local/patches/<component>/`. Wire them into `recipe.toml` `patches = [...]`. Never delete
|
|
patches to fix a build failure — rebase them (see `local/docs/PATCH-GOVERNANCE.md`).
|
|
|
|
3. **Core component (kernel, relibc, base, bootloader, installer, redoxfs, userutils, syscall,
|
|
libredox)** → consume the local fork via `path = "../../../local/sources/<component>"`.
|
|
These are path-fork recipes; do NOT use the legacy `redox.patch` symlink pattern.
|
|
|
|
## Recipe format (quick reference)
|
|
|
|
```toml
|
|
#TODO: describe what's missing (required for WIP)
|
|
|
|
[source]
|
|
git = "https://..." # Red Bear fork URL
|
|
upstream = "https://..." # Original upstream URL (optional)
|
|
branch = "..." # branch to fetch
|
|
|
|
[build]
|
|
template = "cargo" # or cmake, meson, make, configure, custom
|
|
dependencies = ["dep1", "dep2"]
|
|
```
|
|
|
|
## Build templates
|
|
|
|
| Template | Use for |
|
|
|---|---|
|
|
| `cargo` | Rust projects |
|
|
| `cmake` | CMake-based C/C++ |
|
|
| `meson` | Meson-based projects |
|
|
| `configure` | GNU Autotools |
|
|
| `make` | Simple Makefile projects |
|
|
| `custom` | Anything else (`script = """..."""`) |
|
|
|
|
## Recipe environment variables
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `COOKBOOK_SOURCE` | Extracted source directory |
|
|
| `COOKBOOK_STAGE` | Install target (staging dir) |
|
|
| `COOKBOOK_SYSROOT` | Sysroot with built dependencies |
|
|
| `COOKBOOK_TARGET` | Target triple (`x86_64-unknown-redox`, etc.) |
|
|
| `COOKBOOK_CARGO` | Cargo with correct target |
|
|
| `COOKBOOK_MAKE` | Make with correct flags |
|
|
|
|
## Critical rules (see root AGENTS.md for full list)
|
|
|
|
- **WIP recipes** MUST start with `#TODO` describing what is missing.
|
|
- **Custom flags** MUST be set AFTER `DYNAMIC_INIT` (it overwrites CFLAGS/LDFLAGS/CXXFLAGS).
|
|
- **Cross-compilation tests** MUST be disabled (`BUILD_TESTING=OFF`, `--disable-tests`).
|
|
- **Never delete a BINS entry** to fix a build failure — fix the source or use `EXISTING_BINS`.
|
|
- **All source-tree edits** MUST be mirrored to `local/patches/` or `local/sources/<component>/`
|
|
in the same session (see DURABILITY POLICY).
|
|
- **Protected recipes** require `REDBEAR_ALLOW_PROTECTED_FETCH=1` to re-fetch in dev mode.
|
|
|
|
## Further reading
|
|
|
|
- `local/docs/PACKAGE-BUILD-QUIRKS.md` — DYNAMIC_INIT, m4, ninja-build, cross-compilation patterns
|
|
- `local/docs/BUILD-CACHE-PLAN.md` — BLAKE3 dep-hash cache, binary store restore, package groups
|
|
- `local/docs/PATCH-GOVERNANCE.md` — patch lifecycle, rebase rules, orphan-patch decision tree
|
|
- `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the build scripts guarantee (and don't)
|
|
- `recipes/core/AGENTS.md` — core-component specifics (path-fork model, syscall ABI, driver model)
|
|
- `recipes/wip/AGENTS.md` — WIP ports (Wayland, KDE, drivers)
|