# 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)