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

3.8 KiB

Raw Blame History

RECIPES — PACKAGE RECIPE SYSTEM

Authority: This file is a quick orientation pointer. The canonical recipe-system documentation lives in the root AGENTS.md (sections STRUCTURE, WHERE TO LOOK, BUILD FLOW, CONVENTIONS, DURABILITY POLICY, PATCH MANAGEMENT) and 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:

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").
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).
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)

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

3.8 KiB Raw Blame History