vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate build-system docs + Tier 1 message fixes

Browse Source 
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).
This commit is contained in:
vasilito
2026-07-18 16:32:19 +09:00
parent c2f5bb09fc
commit 1528e04b09
15 changed files with 877 additions and 379 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+261 -225
View File
@@ -1,291 +1,327 @@
# Contributing to Red Bear OS
**Thank you for your interest in contributing to Red Bear OS!**
> **Authority:** This file is a quick orientation for contributors. The canonical contributor
> runbook lives in [`AGENTS.md`](./AGENTS.md) (root) and [`local/AGENTS.md`](./local/AGENTS.md)
> (local fork model, branch/submodule policy, durability rules, operator runbook). When this
> file and AGENTS.md disagree, AGENTS.md wins.
This document will outline the basics of where to start if you wish to contribute to the project. There are many ways to help us out and and we appreciate all of them. We look forward to **your contribution!**
Thank you for your interest in contributing to Red Bear OS. This document will get you from
"fresh clone" to "first merged change" without tripping over the project's discipline rules.
**Please read this document until the end**
**Please read this document until the end.**
## Code Of Conduct
---
We follow the [Rust Code Of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
## Code of Conduct
We follow the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
## License
In general, your contributions to Red Bear OS are governed by the [MIT License](https://en.wikipedia.org/wiki/MIT_License). Each project repository has a `LICENSE` file that provides the license terms for that project.
Please review the `LICENSE` file for the project you are contributing to.
[This](https://doc.redox-os.org/book/philosophy.html) page we explain why we use the MIT license.
Contributions to Red Bear OS are governed by the [MIT License](https://en.wikipedia.org/wiki/MIT_License).
Each repository has a `LICENSE` file with the exact terms. Review it before contributing.
## Contribution Terms
When making a contribution you agree to the following terms:
- I understand these changes in full and will be able to respond to review comments.
- I have read the [Developer Certificate of Origin](https://developercertificate.org/) and certify my contribution under its conditions.
- I have read the [Developer Certificate of Origin](https://developercertificate.org/) and
certify my contribution under its conditions.
## AI Policy
We welcome contributions made with the assistance of LLMs and AI tools. We care about the quality of the result, not how it was produced.
Contributions made with the assistance of LLMs and AI tools are welcome. We care about the
**quality of the result**, not how it was produced.
## Chat
**No AI attribution in commit messages or code comments.** A commit message like
`"feat: add MSR scheme"` is correct; `"feat: add MSR scheme (Co-Authored-By: Claude)"` is not.
Commit content is what matters; authorship tags are noise.
You can join in our chat platforms to discuss development, issues or ask questions.
---
### [Matrix](https://matrix.to/#/#redox-join:matrix.org)
## Project model — read this first
Matrix is the official way to talk with the Red Bear OS team and community (these rooms are English-only, we don't accept other languages because we don't understand them).
Red Bear OS is a **full fork** of Redox OS. Treat it the way Ubuntu treats Debian:
Matrix has several different clients. [Element](https://element.io/) is a commonly used choice, it works on web browsers, Linux, MacOSX, Windows, Android and iOS.
- Upstream Redox is the base platform.
- Red Bear carries integration, packaging, validation, and a subsystem release fork on top.
- Upstream-owned source trees (`recipes/*/source/`) are disposable — they are re-extracted
from immutable archives or copied from local forks on every build.
- **Durable Red Bear state** lives in `local/patches/`, `local/recipes/`, `local/docs/`,
`local/sources/<component>/`, and tracked Red Bear configs. Only changes in these
locations survive `make distclean`.
If you have problems with Element, try [Fractal](https://gitlab.gnome.org/World/fractal).
- Join the [Join Requests](https://matrix.to/#/#redox-join:matrix.org) room and send a message requesting for an invite to the Redox Matrix space (the purpose of this is to avoid spam and bots).
- #redox-join:matrix.org (Use this Matrix room address if you don't want to use the external Matrix link)
(We recommend that you leave the "Join Requests" room after your entry on the Red Bear OS space)
If you want to have a big discussion in our rooms, you should use a Element thread, it's more organized and easy to keep track if more discussions happen on the same room.
You cand find more information on the [Chat](https://doc.redox-os.org/book/chat.html) page.
### [Discord](https://discord.gg/JfggvrHGDY)
We have a Discord server as an alternative for Matrix, open the #join-requests channel and send a message requesting to be a member (the purpose of this is to avoid spam and bots)
The Matrix messages are sent to Discord and vice-versa using a bot, but sometimes some Discord messages aren't sent to Matrix (if this happens to you join in our Matrix space above)
## [Gitea](https://gitea.redbearos.org/vasilito/RedBear-OS)
This document is upstream-derived; the Red Bear project uses **gitea.redbearos.org**, not GitLab.
A slightly more formal way of communication with fellow Red Bear OS developers, but a little less quick and convenient like the chat. Submit an issue when you run into problems compiling or testing. Issues can also be used if you would like to discuss a certain topic: be it features, code style, code inconsistencies, minor changes and fixes, etc.
If you want to create an account, read the [Signing in to Gitea](https://doc.redox-os.org/book/signing-in-to-gitlab.html) page.
Once you create an issue don't forget to post the link on the Dev or Support rooms of the chat, because the Gitea email notifications have distractions (service messages or spam) and most developers don't left their Gitea pages open to receive desktop notifications from the web browser (which require a custom setting to receive issue notifications).
By doing this you help us to pay attention to your issues and avoid them to be accidentally forgotten.
If you have ready MRs (merge requests) you must send the links in the [MRs](https://matrix.to/#/#redox-mrs:matrix.org) room. To join this room, you will need to request an invite in the [Join Requests](https://matrix.to/#/#redox-join:matrix.org) room.
By sending a message in the room, your MR will not be forgotten or accumulate conflicts.
## Best Practices and Guidelines
You can read the best practices and guidelines on the [Best practices and guidelines](https://doc.redox-os.org/book/best-practices.html) chapter.
## Repository Model for Contributors
RedBearOS should be treated as an full fork on top of Redox, in the same way Ubuntu
relates to Debian.
That means contributors should keep this separation in mind:
- upstream-owned trees such as `recipes/*/source/` are immutable archived release snapshot,
- durable Red Bear-specific work belongs in `local/patches/`, `local/recipes/`, `local/docs/`, and
tracked Red Bear configs,
- if a change exists only in an upstream-owned source tree, it is not yet preserved properly for
long-term Red Bear maintenance.
If a change exists only inside `recipes/*/source/`, it is **not yet preserved** for long-term
Red Bear maintenance. Mirror it to the right durable location in the same session. See
`AGENTS.md` § "DURABILITY POLICY" for the mapping table.
### WIP rule for contributors
If an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a local project until
upstream promotes it to first-class status.
If an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a **local
project** until upstream promotes it to first-class status. For contributors:
So for contributors:
- Upstream WIP may still be useful as input/reference.
- Fixes intended for Red Bear shipping should normally land in the Red Bear release fork
(`local/sources/<component>/`) or as patches in `local/patches/<component>/`.
- When upstream later catches up, Red Bear prefers upstream and retires the local patches
that are no longer needed.
- upstream WIP may still be a useful input/reference,
- but fixes intended for Red Bear shipping should normally land in the Red Bear release fork,
- and when upstream later catches up, Red Bear should prefer upstream and retire local patches or
local recipe copies that are no longer needed.
---
## Development Recommendations and Tips
## Where the project lives
- Copy-paste prevent and reduce typos
- Comment out configuration or code while testing is better than removal, to remember the testing conditions and prevent mistakes from forgotten logic
- Read the entire [Build System Reference](https://doc.redox-os.org/book/build-system-reference.html) and [Developer FAQ](https://doc.redox-os.org/book/developer-faq.html) pages
- Make sure your build system is up-to-date, read the [Update The Build System](https://doc.redox-os.org/book/build-system-reference.html#update-the-build-system) section if in doubt.
- If you want to make local changes in recipe sources it's recommended to automatic recipe source update, read [this](https://doc.redox-os.org/book/configuration-settings.html#local-recipe-changes) section to learn how to this for one or multiple recipes and [this](https://doc.redox-os.org/book/configuration-settings.html#cookbook-offline-mode) section for all recipes.
- If you want to make changes to system components, drivers or RedoxFS you need to manually update initfs, read [this](https://doc.redox-os.org/book/coding-and-building.html#how-to-update-initfs) section to learn how to do that.
- If some program can't build or work, something can be missing/hiding on [relibc](https://gitea.redbearos.org/vasilito/RedBear-OS), like a POSIX/Linux function or bug.
- If you have some error on QEMU remember to test different settings or verify your operating system (Pop_OS!, Ubuntu, Debian and Fedora are the recommend Linux distributions to do testing/development for Red Bear OS).
- Remember to log all errors, you can use the following command as example:
Red Bear OS lives on a self-hosted Gitea instance. **No GitHub, GitLab, or Codeberg mirror
is authoritative.**
```sh
your-command 2>&1 | tee file-name.log
| Field | Value |
|----------|---------------------------------------------------|
| Host | `https://gitea.redbearos.org` |
| User | `vasilito` |
| Web UI | `https://gitea.redbearos.org/vasilito` |
| Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` |
**Single-Repo Rule:** there is exactly **one** repository. All component sources (kernel,
relibc, drivers, system utilities) live here as submodule branches or tracked trees in
`local/sources/`. Do not create new repositories, new branches, or new submodules. See
`local/AGENTS.md` § "BRANCH AND SUBMODULE POLICY".
### Communication
- **Issues** — file at `https://gitea.redbearos.org/vasilito/RedBear-OS/issues`. Use the
label filters (`critical`, `high-priority`, `easy`, `good first issue`, `help wanted`) to
find work that matches your skill level.
- **Chat** — upstream Redox has [Matrix](https://matrix.to/#/#redox-join:matrix.org) and
[Discord](https://discord.gg/JfggvrHGDY) rooms. Red Bear contributors are welcome there,
but issue tracking happens on Gitea, not in chat.
- **Merge requests** — open MRs on Gitea against the `0.3.1` branch. Small MRs review faster
than large ones; split big work into reviewable slices.
---
## Quick orientation for new contributors
| You want to… | Read this |
|---|---|
| Build the project | `AGENTS.md` § "BUILD COMMANDS" — canonical entry point is `./local/scripts/build-redbear.sh` |
| Add a new package | `recipes/AGENTS.md` + `AGENTS.md` § "STRUCTURE" + § "CONVENTIONS" |
| Fix a kernel bug | Edit `local/sources/kernel/` directly (path-fork model — see `local/AGENTS.md`) |
| Fix a relibc POSIX gap | Edit `local/sources/relibc/` directly; rebuild prefix with `touch relibc && make prefix` |
| Modify an upstream package | Add a patch in `local/patches/<component>/`, wire it into the recipe's `patches = [...]` |
| Add a custom Red Bear package | Create under `local/recipes/<category>/`, symlink `recipes/<category>/<name>` → local path |
| Bump an upstream version | `local/scripts/upgrade-forks.sh --to=<tag>` (see `local/docs/RELEASE-BUMP-WORKFLOW.md`) |
| Sync in-house crate versions | `./local/scripts/sync-versions.sh --check` (Cat 0/1/2 categories) |
| Validate your change | `make validate` runs `lint-config`, init-service validator, file-ownership validator |
| Understand the build cache | `local/docs/BUILD-CACHE-PLAN.md` — BLAKE3 dep-hash cache, binary store restore |
| Run a sanity check after fork edits | `git -C local/sources/<component> log --oneline -3` + `git -C local/sources/<component> status` |
---
## Build system
The canonical build entry point is `./local/scripts/build-redbear.sh`. It handles `.config`
parsing, prefix staleness detection, protected-recipe authorization, pre-cooking critical
packages, and source fingerprint tracking. Direct `make` invocations bypass these gates.
```bash
# First-time setup
echo 'PODMAN_BUILD?=0' > .config # native build (no Podman container)
# CRITICAL: .config MUST NOT contain REDBEAR_RELEASE=... in development mode.
# Canonical build
./local/scripts/build-redbear.sh redbear-mini # text-only target (dev/CI)
./local/scripts/build-redbear.sh redbear-full # desktop-capable target
./local/scripts/build-redbear.sh redbear-grub # text-only + GRUB bootloader
# With online fetch for non-protected development recipes
./local/scripts/build-redbear.sh --upstream redbear-mini
# Local fork development (protected recipes)
export REDBEAR_ALLOW_PROTECTED_FETCH=1
./local/scripts/build-redbear.sh --upstream redbear-mini
# Boot in QEMU
make qemu
make qemu QEMUFLAGS="-m 4G"
```
- If you have a problem that seems to not have a solution, think on simple/stupid things. Sometimes you are very confident on your method and forget obvious things (very common).
- If you want a quick review of your Merge Request, make it small.
- If your big Merge Request is taking too long to be reviewed and merged try to split it in small MRs. But make sure it don't break anything, if this method break your changes, don't shrink.
After editing a local fork (`relibc`, `kernel`, `base`), rebuild the prefix before any recipe
build:
## Style Guidelines
```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.
See `AGENTS.md` § "BUILD COMMANDS" and `docs/06-BUILD-SYSTEM-SETUP.md` for the full reference.
---
## Patch governance
Red Bear patches are durable artifacts. **Never remove a patch to fix a build failure —
rebase it.** Full rules in `local/docs/PATCH-GOVERNANCE.md`.
Critical rules:
- **Recipe.toml is git-tracked** — changes to it are durable.
- **Source trees are disposable** — `repo clean`/`distclean` destroy them.
- **All source-tree edits must be patches** in `local/patches/<component>/` OR direct
commits to `local/sources/<component>/` (path-fork model).
- **Patch chain ordering matters** — patches that define types must come before patches
that use them; cumulative patches must maintain line-number context.
- **Never remove BINS entries** to fix build failures — fix the source or use `EXISTING_BINS`.
- **Validate patches** with `./target/release/repo validate-patches <recipe>` after any
patch change.
- **Orphan-patch governance** — every patch must correspond to work present in the matching
fork source tree. `verify-patch-content.sh` enforces this on every build preflight. When
an orphan is detected, apply the decision tree in `AGENTS.md` § "Orphan-Patch Supersession
Decision Tree" (do NOT blindly reapply).
---
## Style guidelines
### Rust
Since **Rust** is a relatively small and new language compared to others like C and C++, there's really only one standard. Just follow the official Rust standards for formatting, and maybe run `rustfmt` on your changes, until we setup the CI system to do it automatically.
Follow the official Rust standards. Run `rustfmt` on your changes. Project settings live in
`rustfmt.toml` (max_width=100, brace_style=SameLineWhere) and `clippy.toml`
(cognitive-complexity-threshold=100, type-complexity-threshold=1000).
**Hard rules** (see `AGENTS.md` § "ANTI-PATTERNS"):
- **No `as any` / `@ts-ignore`** — use proper `Result` handling.
- **No `unwrap()` / `expect()` in library/driver code** — pervasive anti-pattern in this
repo (~14k instances of technical debt). Use `Result<T, E>` and `?`.
- **No type suppression** — no `#[allow(...)]` for code you wrote.
- **No speculative fallbacks** — handle errors explicitly.
### TOML (recipes and configs)
- Recipe format: `[source]` + `[build]` + optional `[package]`.
- 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: disable test suites (`BUILD_TESTING=OFF`, `--disable-tests`).
- Configs use `[package_groups.<name>]` sections (underscore, not hyphen).
### Git
Please follow our [Git style](https://doc.redox-os.org/book/creating-proper-pull-requests.html) for pull requests.
For user-visible work, keep the root [`CHANGELOG.md`](CHANGELOG.md) current and update the
README "Current Status" section with the latest highlights so repository visitors can
immediately see what changed.
For user-visible work, keep the root [`CHANGELOG.md`](CHANGELOG.md) current and immutable archived the
README "What's New" section with the latest highlights so GitHub visitors can immediately see what
changed.
When a commit changes the visible system surface, supported hardware, build flow, shipped
configs, or key docs, add a short user-facing changelog note in the same change.
When a commit changes the visible system surface, supported hardware, build flow, shipped configs,
or key docs, add a short user-facing changelog note in the same change.
Commit message style (lowercase prefix + colon + short summary):
## Gitea
### Identity
Once your Gitea account is created, you should add your Matrix or Discord username (the name after the `@` symbol) on the "About" section of your profile, that way we recognize you properly.
### Issues
We use issues to organize and track our current and pending work, to know how to create issues on the Red Bear Gitea read the [Filing Issues](https://doc.redox-os.org/book/filing-issues.html) page.
Once you create an issue don't forget to post the link on the Dev or Support rooms of the chat, because the Gitea email notifications have distractions (service messages or spam) and most developers don't left their Gitea pages open to receive desktop notifications from the web browser (which require a custom setting to receive issue notifications).
By doing this you help us to pay attention to your issues and avoid them to be accidentally forgotten.
You can see all issues on [this](https://gitea.redbearos.org/vasilito/RedBear-OS/issues) link.
### Pull Requests
Please follow [our process](https://doc.redox-os.org/book/creating-proper-pull-requests.html) for creating proper pull requests.
## Important Places to Contribute
Before starting to contribute, we recommend reading the [General FAQ](https://www.redox-os.org/faq/) and the [Redox Book](https://doc.redox-os.org/book/).
All Red Bear OS sources live in the SINGLE repository `gitea.redbearos.org/vasilito/RedBear-OS` per the Single-Repo Rule. Core components are subtrees in `local/sources/<component>/`; user-facing packages are in `recipes/`; kernel-driver work lands in local forks; documents are in `local/docs/` and `docs/`.
### Skill Levels
If you don't know programming:
- Test the [daily images](https://static.redox-os.org/img/) on your computer and add the report on the [Hardware Compatibility](https://gitea.redbearos.org/vasilito/RedBear-OS/blob/branch/0.3.1/HARDWARE.md) list
- Monitor and warn developers if the [daily images](https://static.redox-os.org/img/) are outdated
- Use/test Redox and create issues for bugs or needed features (please check for duplicates first)
- Fix and write documentation
- Find or fix typos in configuration
If you don't know how to code in Rust but know other programming languages:
- Web development on the website (we only accept minimal JavaScript code to preserve performance)
- Write unit tests (may require minimal knowledge of Rust)
- Port C/C++ programs to Redox (read upstream WIP `TODO`s as inputs, but do not assume upstream WIP
recipes are automatically the durable Red Bear shipping source of truth)
- Port programs to Redox
If you know how to code in Rust but don't know operating system development:
- See the [easy](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Aeasy) issues
- See the "[good first issue](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Agood%20first%20issue)" issues
- See the [help wanted](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahelp%20wanted) issues (it's worth noting the skill level varies between projects, but a large subset of these should be approachable by contributors familiar with regular Rust/Unix application programming)
- Improve the package manager, or build system tooling like `redoxer` or `installer`
- Improve the [Ion](https://gitea.redbearos.org/vasilito/RedBear-OS) shell, or other high-level or mid-level projects
- Port Rust programs (also look for issues with the `port` label)
- Improve application compatibility in relibc by e.g. implementing missing POSIX/Linux functions
If you know how to code in Rust, and have experience with systems software/OS development:
- Familiarize yourself with the repository layout, code, and build system
- Update old code to remove warnings
- Search for `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME`, and `PRETTYFYME` and fix the code you find
- Look in general for issues with the following labels: `critical`, `help wanted`, `feature`, `enhancement`, `bug` or `port`
- Improve internal libraries and abstractions, e.g. `libredox`, `redox-scheme`, `redox-event` etc.
- Help upstream Redox-specific functionality to the Rust ecosystem
- Improve Redox's automated testing suite and continuous integration testing processes
- Improve, profile, and optimize code, especially in the kernel, filesystem, and network stack
- Improve or write device drivers
For those who want to contribute to the Redox GUI, our GUI strategy has changed.
- We are concentrating current forward desktop work on the KWin Wayland path in the main build-system repository.
- Legacy GUI toolkit efforts are in maintenance mode, and there is currently no separate Redox-specific GUI toolkit effort underway.
## Priorities
You can use the following Gitea issue label filters to know our development priorities on the moment:
- [Critical](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Acritical)
- [High-priority](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahigh-priority)
- [Medium-priority](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Amedium-priority)
- [Low-priority](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Alow-priority)
## Roadmap
We use tracking issues for the goals in our roadmap, you can see them in the filter below:
- [Tracking issues](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Atracking%20issue)
## RFCs
For more significant changes that affect Redox's architecture, we use the [Request for Comments](https://gitea.redbearos.org/vasilito/RedBear-OS) repository.
## Build System
To download the build system use the following commands:
(You need to have [curl](https://curl.se/) installed on your system)
```sh
# Get the build script (one-time):
curl -sfL https://gitea.redbearos.org/vasilito/RedBear-OS/raw/branch/0.3.1/local/scripts/build-redbear.sh -o build-redbear.sh
chmod +x build-redbear.sh
# Build the ISO (canonical):
./build-redbear.sh redbear-mini # text-only target (recommended for CI / dev)
./build-redbear.sh redbear-full # desktop/graphics target
./build-redbear.sh redbear-grub # text-only + GRUB bootloader
```
feat: <what changed>
fix: <what was broken>
docs: <what was documented>
chore: <housekeeping>
refactor: <what was restructured>
```
Direct `make all` invocations bypass policy gates per `local/AGENTS.md`; always use `build-redbear.sh`.
---
You can find the build system organization and commands on the [Build System](https://doc.redox-os.org/book/build-system-reference.html) page.
## Development recommendations
## Developer FAQ
- **Build incrementally.** `repo cook <recipe>` builds a single recipe; `make r.<recipe>`
is the shorthand. Use `--force-rebuild` to bypass the content-hash cache when debugging.
- **Log everything when debugging.** `your-command 2>&1 | tee file-name.log` — capture
full output for later analysis.
- **Test different QEMU settings** when something fails. Pop!_OS, Ubuntu, Debian, and Fedora
are the recommended host distributions.
- **Check for missing POSIX/Linux functionality in relibc** when a port fails to build or
crashes at runtime. The fork lives at `local/sources/relibc/`.
- **Comment out configuration while testing** rather than removing it — preserves the
record of what you tried. (Production commits should not contain commented-out code.)
- **Small MRs review faster.** If a big MR stalls, split it into reviewable slices that
each leave the tree building cleanly.
- **Verify your change.** `make validate` runs `lint-config`, init-service validator, and
file-ownership validator. For Rust changes: `cargo check`, `cargo clippy --all-targets`,
`cargo test --lib`.
You can see the most common questions and problems on the [Developer FAQ](https://doc.redox-os.org/book/developer-faq.html) page.
---
## Porting Software
## What to work on
You can read how to use the Cookbook recipe system to port applications on the [Application Porting](https://doc.redox-os.org/book/porting-applications.html) page.
### By skill level
**Always verify if a recipe for your program or library already exist before porting to not break the build system with a recipe duplication or waste time.**
**Non-programmers**:
## Libraries and APIs
- Build the current branch (`./local/scripts/build-redbear.sh redbear-mini` or `redbear-full`)
and boot it in QEMU (`make qemu`) or on bare metal. Add a row to
[`HARDWARE.md`](./HARDWARE.md) describing what worked and what didn't.
- File bugs at the Gitea issue tracker (check for duplicates first).
- Fix typos in configuration (`config/`, `recipes/*/recipe.toml`) and documentation.
- Improve documentation under `docs/` or `local/docs/`.
You can read the [Libraries and APIs](https://doc.redox-os.org/book/libraries-apis.html) page to learn about the libraries and APIs used in Redox.
**Know other languages, not Rust**:
## Visual Studio Code (VS Code) Configuration
- Write unit tests (minimal Rust knowledge required).
- Port C/C++ programs to Redox via `recipes/` (treat upstream WIP `TODO`s as inputs, not as
the durable Red Bear shipping source of truth).
- Web development on the website (minimal JavaScript only, for performance).
To learn how to configure your VS Code to do Redox development please read the information below the [Visual Studio Code Configuration](https://doc.redox-os.org/book/coding-and-building.html#visual-studio-code-configuration) section.
**Know Rust, not OS development**:
## References
- See [`easy`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Aeasy) issues.
- See [`good first issue`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Agood%20first%20issue) issues.
- See [`help wanted`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahelp%20wanted) issues.
- Improve build tooling (`installer`, `repo` cookbook binary, `redbear-*` utilities).
- Improve the [Ion shell](https://gitea.redbearos.org/vasilito/RedBear-OS) or other
mid-level projects.
- Port Rust programs (look for the `port` label).
- Improve relibc POSIX/Linux compatibility.
We maintain a list of wikis, articles and videos to learn Rust, OS development and computer science on the [References](https://doc.redox-os.org/book/references.html) page.
**Know Rust + systems/OS development**:
If you are skilled/experienced there's still a possibility that they could improve your knowledge in some way.
- Read `AGENTS.md`, `local/AGENTS.md`, and the relevant subsystem plan under `local/docs/`.
- Search for `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME` and fix what you find.
- Look for issues labeled `critical`, `help wanted`, `feature`, `enhancement`, `bug`, or `port`.
- Improve internal libraries (`libredox`, `redox-scheme`, `redox-event`).
- Improve device drivers (GPU, USB, Wi‑Fi, Bluetooth — all first-class subsystems).
- Improve profiling and optimization in kernel, filesystem, or network stack.
## Other Ways to Contribute
### Current priorities (see README "Current Status" table)
If you aren't good on coding, but you still want to help keep the project going, you can contribute and support in a variety of ways! We'll try to find a way to use anything you have to offer.
The most impactful contributions right now:
1. **Qt6 Wayland `null+8` crash** — the #1 blocker for the graphical desktop. See
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
2. **AMD/Intel GPU hardware validation** on bare metal. See `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md`.
3. **USB controller maturity**. See `local/docs/USB-IMPLEMENTATION-PLAN.md`.
4. **Wi‑Fi native control plane**. See `local/docs/WIFI-IMPLEMENTATION-PLAN.md`.
5. **cub AUR pipeline hardening**. See `local/docs/CUB-PACKAGE-MANAGER.md`.
6. **tlc VFS remote backends and archive support**. See `local/recipes/tui/tlc/README.md`.
7. **Package maintainers** for the growing recipe catalog.
### Labels
| Label | Meaning |
|---|---|
| [`critical`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Acritical) | Blocks release or core functionality |
| [`high-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahigh-priority) | Important, near-term work |
| [`medium-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Amedium-priority) | Should get done |
| [`low-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Alow-priority) | Nice to have |
| [`tracking issue`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Atracking%20issue) | Roadmap tracking |
---
## Other ways to contribute
### Design
If you're a good designer, whether it's 2D graphics, 3D graphics, interfaces, web design, you can help. We need logos, UI design, UI skins, app icons, desktop backgrounds, etc.
Logos, UI design, app icons, desktop backgrounds, and themes are all welcome. Submit via
the main repository or open an issue with attached assets.
- [Red Bear backgrounds](https://gitea.redbearos.org/vasilito/RedBear-OS) - You can send your wallpapers on this repository.
- [Red Bear assets](https://gitea.redbearos.org/vasilito/RedBear-OS) - You can send your logos, icons and themes on this repository.
### Donations
If you have questions about the graphic design, ask us on the [Chat](https://doc.redox-os.org/book/chat.html).
### Donate
If you are interested in donating to the upstream Redox OS project, you can find instructions on the [Donate](https://www.redox-os.org/donate/) page.
To donate to **upstream Redox OS** (the base platform), see
[https://www.redox-os.org/donate/](https://www.redox-os.org/donate/). Red Bear OS itself
does not accept donations — contribute code, testing, or documentation instead.
HARDWARE.md
+3 -3
View File
@@ -2,10 +2,10 @@
> Hardware compatibility inherited from upstream Redox OS. See https://doc.redox-os.org/book/hardware-support.html for the latest upstream data.
>
> **Status note (2026-04-15):** This file is a hardware-reporting/support-tracking surface, not the
> **Status note (2026-07-18):** This file is a hardware-reporting/support-tracking surface, not the
> canonical source for profile support language or project execution order. For current Red Bear
> support framing, also use `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` and
> `local/docs/PROFILE-MATRIX.md`.
> support framing, also use `README.md` (status table) and
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
This document tracks the current hardware compatibility of Red Bear OS.
README.md
+1
View File
@@ -213,6 +213,7 @@ Red Bear OS operates under strict discipline. Full policies: [`local/AGENTS.md`]
- [Bluetooth Plan](local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md) — Bluetooth stack design
- [Build Cache](local/docs/BUILD-CACHE-PLAN.md) — Content-hash (BLAKE3) build cache system
- [Build System Hardening](local/docs/BUILD-SYSTEM-HARDENING-PLAN.md) — Collision detection, init service validation
- [Build System Assessment](local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md) — Architecture, quality, robustness, and gap assessment (2026-07-18)
- [Quirks System](local/docs/QUIRKS-SYSTEM.md) — Hardware quirks infrastructure
- [Documentation Index](docs/README.md) — Full doc map
docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md
+8 -1
View File
@@ -1,5 +1,12 @@
# 07 — Red Bear OS Implementation Plan
> **Status note (2026-07-18):** This file remains the canonical **repository-level** plan
> (profiles, packaging, validation, staged hardware enablement, workstream ordering). For
> **desktop-stack and subsystem detail**, the canonical authority is
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0). When the two conflict on a specific
> subsystem point, prefer the local subsystem plan. Status tables in `README.md` carry the
> current high-level support summary and should be kept in sync with this file.
## Purpose
This is the canonical repository-level implementation plan for Red Bear OS.
@@ -17,7 +24,7 @@ Detailed subsystem planning remains in focused documents under `local/docs/`.
## Repository Model
RedBearOS should be understood as an full fork on top of Redox in the same way Ubuntu
RedBearOS should be understood as a full fork on top of Redox in the same way Ubuntu
relates to Debian.
- Redox is upstream.
docs/README.md
+7 -7
View File
@@ -1,17 +1,17 @@
# Red Bear OS Documentation Index
Technical documentation for Red Bear OS as an full fork on top of Redox OS.
Technical documentation for Red Bear OS, a full fork on top of Redox OS.
This index is the entry point for the documentation set. Its main job is to make the
current/canonical versus historical/reference split obvious.
> **Status note (2026-05-01):** The canonical desktop path document is
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v4.0, single comprehensive plan). It supersedes
> **Status note (2026-07-18):** The canonical desktop path document is
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0, single comprehensive plan). It supersedes
> all earlier individual assessments and is the single authority for current state.
> The historical docs below (01–05) remain useful for architecture reference and implementation
> rationale, but they should be read together with the new plan and the current local subsystem docs.
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v4.0) for current state.
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0) for current state.
> **Red Bear note:** newer subsystem plans can also live under `local/docs/` when they are Red Bear-
> specific rather than general Redox architecture material. In particular, see
@@ -55,7 +55,7 @@ console-to-KDE plan.
## Related Red Bear-local current-state plans
**Consolidation (2026-04-30)**: 13 standalone assessment docs deleted. All current state is now in
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v4.0). Individual subsystem plans remain for detail:
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0). Individual subsystem plans remain for detail:
- `../local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — **CANONICAL** comprehensive plan: kernel→DRM→Mesa→Wayland→KDE path
- `../local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` — kernel credential syscalls + IPC (implemented)
@@ -88,9 +88,9 @@ Do not flatten those into one “supported” claim in public summaries.
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee
## Current State Summary (as of 2026-05-01)
## Current State Summary (as of 2026-07-18)
This summary is only a quick orientation layer. For canonical current-state detail, see `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v4.0).
This summary is only a quick orientation layer. For canonical current-state detail, see `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0).
- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` for repository-wide execution order,
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical comprehensive plan,
local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md
+459
View File
@@ -0,0 +1,459 @@
# Red Bear OS Build System — Comprehensive Assessment
**Date:** 2026-07-18
**Branch:** `0.3.1`
**Baseline:** Redox snapshot `f55acba68`
**Scope:** Makefile + `mk/*.mk` + Rust cookbook (`src/`) + `local/scripts/` + `config/*.toml` + all build-system documentation
**Method:** Five parallel explore/deep agents inventoried (1) docs, (2) user-facing messages, (3) architecture, (4) error-recovery mechanisms; plus (5) the Phase 1 remediation results (P0–P3) and the Phase 15.0 installer collision-detection work.
---
## Executive Summary
The Red Bear OS build system is **mature, well-defended, and largely self-correcting**. Of the ten error-recovery mechanisms assessed, seven are EFFECTIVE, three are PARTIAL, and none are INEFFECTIVE or MISSING. The Phase 1 remediation closed the largest gaps (.DELETE_ON_ERROR, post-build validate gate, unwrap→Result, BLAKE3 source-content cache, REDBEAR_TAG fingerprint, cache integrity check, runtime collision detection) and also surfaced and fixed a latent production bug in `collect_files_recursive` that silently broke content hashing for every non-root-level source file.
The largest remaining risks are **probabilistic, not structural**:
1. No cryptographic integrity verification of cached pkgar files (mtime + existence only).
2. No retry logic in non-prefix network operations (`download_wget`, `git clone`, binary repo download).
3. Documentation drift: ~18 of ~75 build-system docs are stale, 1 is obsolete (self-labeled), and several duplicate authoritative sources.
4. ~15 of 185 user-facing messages are stale, misleading, or unhelpful — concentrated in `build-redbear.sh` (5), `mk/disk.mk` (8 unmount warnings), and `src/bin/repo.rs` (raw Debug output).
None of these block the build; they degrade observability and operator experience. All are addressable with surgical changes that do not require architectural rework.
---
## Part 1 — Architecture & Internal Organization
### 1.1 Layered Structure
```
┌──────────────────────────────────────────────────────────────────┐
│ Operator │
│ └── ./local/scripts/build-redbear.sh <target> │
│ (canonical entry; .config, prefix staleness, stash, etc) │
└──────────────────────────┬───────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────┐
│ make all (Makefile + mk/*.mk — 11 fragments) │
│ ├─ config.mk environment, paths, sentinels │
│ ├─ depends.mk rustup/cbindgen/nasm/just │
│ ├─ fstools.mk cookbook repo binary, installer, redoxfs │
│ ├─ prefix.mk cross-compiler sysroot (binary or source) │
│ ├─ redbear.mk integrate-redbear.sh (fingerprint-gated) │
│ ├─ repo.mk repo cook — the core pipeline │
│ ├─ disk.mk image creation, validation gate │
│ ├─ qemu.mk / virtualbox.mk │
│ ├─ podman.mk / ci.mk │
│ └─ (validate is a prerequisite of `all`) │
└──────────────────────────┬───────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────┐
│ Cookbook Rust binary (src/bin/repo.rs) │
│ ├─ fetch src/cook/fetch.rs source + atomic patches │
│ ├─ cook src/cook/cook_build.rs 3-layer cache + build │
│ ├─ package src/cook/package.rs PKGAR + stage.toml │
│ └─ push install into sysroot │
└──────────────────────────┬───────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────┐
│ Installer (local/sources/installer) │
│ 4-layer install_dir(): │
│ 1. Config pre-install [[files]] (postinstall=false) │
│ 2. install_packages() — package staging │
│ 3. Config post-install [[files]] (postinstall=true) │
│ 4. User/group creation │
│ CollisionTracker wired across all four layers (Phase 15.0). │
└──────────────────────────┬───────────────────────────────────────┘
▼
build/<arch>/<config>.iso
```
### 1.2 Configuration Hierarchy
```
redbear-full.toml ─┐
│ includes
redbear-grub.toml ─┼─► redbear-mini.toml ─► minimal.toml ─► base.toml
│ │
│ ├─ redbear-legacy-base.toml
│ ├─ redbear-netctl.toml
│ ├─ redbear-device-services.toml
│ └─ redbear-boot-stages.toml
│
└─ [package_groups] GPU, Wayland, Qt6, KF6, KWin, greeter, SDDM
```
`Config::from_file()` resolves `include = [...]` and expands `[package_groups.<name>]` references recursively (cycle-detected). Explicit `[packages]` entries override group membership. The cookbook `repo` binary sees only the fully-expanded package list.
### 1.3 Build Pipeline (repo cook)
For each recipe in topological order:
1. **Workspace pollution cleanup** — remove orphaned `Cargo.toml`/`Cargo.lock` from `recipes/` root.
2. **Fetch** — git clone / tarball / path source / same_as; protected recipes gated.
3. **Atomic patch application** — `cp -al` staging dir; full success promotes, any failure rolls back.
4. **Three-layer cache check**:
- Layer A: `SourceContentHash` (BLAKE3 of every source file + recipe.toml + patches).
- Layer B: `DepHashes` (BLAKE3 of every build dep's PKGAR).
- Layer C: `--force-rebuild` bypass.
5. **Binary store restore** — if `target/` is missing but `repo/<arch>/` has the pkgar, extract it.
6. **Build** — dispatch to cargo/cmake/meson/configure/make/custom/remote/none template.
7. **ELF auto-dep discovery** — scan DT_NEEDED, map to pkgar providers.
8. **Package** — PKGAR + stage.toml + dep_hashes.toml + source_hash.txt, all atomic.
### 1.4 Canonical Source of Truth
| Layer | Authority |
|-------|-----------|
| Build policy | `local/AGENTS.md` (96KB, 1827 lines) — supersedes all other docs |
| Public-facing policy | `AGENTS.md` (root, 53KB) — subset of `local/AGENTS.md` |
| Build invariants | `local/docs/BUILD-SYSTEM-INVARIANTS.md` |
| Cache design | `local/docs/BUILD-CACHE-PLAN.md` |
| Hardening history | `local/docs/BUILD-SYSTEM-HARDENING-PLAN.md` |
| Collision detection | `local/docs/COLLISION-DETECTION-STATUS.md` (most recently updated) |
| Tool reference | `local/scripts/TOOLS.md` (15 tools) |
| Desktop plan | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v5.8, 2076 lines) |
---
## Part 2 — Quality & Correctness
### 2.1 Strengths
| Property | Evidence |
|----------|----------|
| Atomic operations | `.partial` + rename pattern across prefix, cook_build, patch staging, hash files. Interrupted operations leave no partial artifacts. |
| Conservative-on-uncertainty | Hash compute failure → rebuild. Corrupt TOML → mtime fallback. Missing dep_hashes → rebuild. The system never silently trusts corrupt state. |
| Defense in depth | Source integrity is protected by 6 layers: atomic patches, local-overlay immutability, source fingerprints, BLAKE3 content hashing, offline-first defaults, git self-heal. |
| Three-layer cache | Content hash + dep hashes + force flag. Catches both source changes and dependency changes that mtime alone would miss. |
| Local-overlay immutability | `is_local_overlay()` is unconditional and un-overridable. The previous `REDBEAR_ALLOW_LOCAL_UNFETCH` escape hatch was removed (commit `cb8b093564`). |
| Protected recipes | ~90 recipes carrying Red Bear patches are gated; only `REDBEAR_ALLOW_PROTECTED_FETCH=1` permits online re-fetch. |
| Phase 15.0 collision detection | `CollisionTracker` in installer catches the D-Bus regression class (Layer 2 overwriting Layer 1) at both build time (Python scan) and runtime (installer). |
### 2.2 Latent Bug Fixed During Phase 1
**`collect_files_recursive` in `cook_build.rs`** computed relative paths from the *current* subdirectory instead of the *root*. Every non-root-level file was hashed as `<unreadable>` because `fs::read` failed on the truncated path. **Impact:** the `SourceContentHash` cache never actually hashed file contents for any file below the root of a source tree — meaning content changes in subdirectories were silently invisible. **Fix:** thread `root` parameter through recursion; also ensure parent dir creation in `DepHashes::write()`.
### 2.3 Correctness Verifications Run During Phase 1
- `cargo check` ✅ clean
- `cargo test --lib cook::cook_build::tests` ✅ 21/22 (1 pre-existing failure in `file_system_loop`, unrelated)
- `cargo clippy --lib` ✅ 0 new warnings (195 pre-existing)
- `make -n` dry-runs ✅ for `all`, `validate`, `redbear`, `cache-restore`, plus all escape hatches
### 2.4 Correctness Gaps (Pre-existing, Not Introduced)
1. **ELF auto-dep loss after binary store restore** — when a recipe is restored from `repo/<arch>/`, the reconstructed `auto_deps.toml` comes from the manifest's declared `depends`, not from DT_NEEDED discovery. Dynamic deps discovered at the original build are lost. Downstream consumers may miss re-build triggers.
2. **Corrupt dep_hashes.toml → silent mtime fallback** — if `dep_hashes.toml` parses as invalid TOML, `DepHashes::read()` returns `None` and the system falls back to mtime. Documented in the test suite but not corrected.
3. **Cached pkgar has no integrity check** — restoration trusts file existence + mtime. A truncated or corrupt pkgar is not caught until extraction (or later).
4. **Layer 3 (postinstall) collisions are suppressed** — by design (intentional overrides), but this means a malicious or accidental config postinstall entry that damages package-provided files would not raise a warning.
---
## Part 3 — Robustness & Error Recovery
### 3.1 Mechanism Scorecard
| # | Mechanism | Detection | Auto-Correction | User Guidance | Workspace State | Rating |
|---|-----------|-----------|-----------------|---------------|-----------------|--------|
| 1 | Stale prefix detection | Effective | Effective (auto `make prefix`, abort on fail) | Clear (shows fork dates) | Clean (`.partial` pattern) | **EFFECTIVE** |
| 2 | Cache restoration | Partial (mtime only) | Partial (warn-only on bad pkgar) | Adequate | Unverified after restore | **PARTIAL** |
| 3 | Patch application | Effective | Effective (atomic rollback) | Excellent (`[ATOMIC]` markers, `.rej` paths) | Immutable | **EFFECTIVE** |
| 4 | Workspace pollution | Effective | Effective (silent cleanup) | Silent (debug log only) | Clean | **EFFECTIVE** |
| 5 | Source tree recovery | Effective | Partial (git self-heal; manual for forks) | Clear | Protected (local-overlay guard) | **EFFECTIVE** |
| 6 | Network failure | Partial | Partial (wget has retry for prefix only) | Adequate | Recoverable | **PARTIAL** |
| 7 | Content-hash cache | Effective | Effective (rebuild on mismatch) | Debug-level only | Clean | **EFFECTIVE** |
| 8 | Binary store restore | Partial | Partial (warn-only, fall through to rebuild) | Warn-only | Partially corruptible | **PARTIAL** |
| 9 | Interrupted build | Effective (.DELETE_ON_ERROR + `.partial`) | Effective | Silent (auto-recovered) | Auto-recovered | **EFFECTIVE** |
| 10 | Protected recipe guard | Effective (~90 recipes) | N/A (prevents damage) | Clear (flag + env var) | Protected | **EFFECTIVE** |
### 3.2 Recovery Paths (Operator-Facing)
```bash
# Light — most auto-correction happens here
./local/scripts/build-redbear.sh redbear-mini
# Medium — wipe target caches, keep sources
./local/scripts/build-redbear.sh --no-cache redbear-mini
# Heavy — distclean + rebuild (preserves local/)
make distclean && ./local/scripts/build-redbear.sh redbear-mini
# Nuclear — wipe everything except local/ sources
make distclean && rm -rf build/ repo/ prefix/ && ./local/scripts/build-redbear.sh redbear-mini
```
### 3.3 Robustness Gaps Requiring Future Work
1. **Cache integrity verification** — `restore-cache.sh --verify` only checks pkgar existence, not BLAKE3. A corrupt cached pkgar propagates silently until extraction. *Recommended fix: store per-pkgar BLAKE3 in the snapshot manifest and verify post-restore.*
2. **Non-prefix network retry** — `download_wget()` in `src/cook/fs.rs` and `git clone` in `fetch.rs` have no retry. A transient blip aborts the build. *Recommended fix: wrap fetch operations with `--tries=3 --timeout=30 --waitretry=5`.*
3. **Binary store post-restore validation** — no check that extracted files match the pkgar's recorded file list. pkgar's signature check at extraction time partially mitigates this; a separate content pass would close the gap.
4. **Auto_deps preservation across binary store restores** — currently lossy. *Recommended fix: copy `auto_deps.toml` from `repo/<arch>/` alongside `dep_hashes.toml`.*
---
## Part 4 — Documentation Quality
### 4.1 Inventory Summary
| Category | Total | CURRENT | STALE | OBSOLETE | ARCHIVED |
|----------|-------|---------|-------|----------|----------|
| Root-level | 5 | 3 | 2 | 0 | 0 |
| `docs/` directory | 7 | 2 | 5 | 0 | 0 |
| `local/AGENTS.md` | 1 | 1 | 0 | 0 | 0 |
| Build-system docs (`local/docs/`) | 16 | 11 | 4 | 1 | 0 |
| Recipe `AGENTS.md` files | 4 | 1 | 3 | 0 | 0 |
| `local/` support docs | 5 | 4 | 1 | 0 | 0 |
| Subsystem plans | 19 | ~16 | ~3 | 0 | 0 |
| Archived + internal | ~18 | — | — | — | 18 |
| **TOTAL** | **~75** | **~38** | **~18** | **1** | **~18** |
### 4.2 Canonical Doc Authority
```
1. local/AGENTS.md (96KB — absolute policy authority)
2. AGENTS.md (root) (53KB — public-facing subset)
3. local/docs/BUILD-SYSTEM-INVARIANTS.md (invariants any change must preserve)
4. Feature docs:
- BUILD-CACHE-PLAN.md
- BUILD-SYSTEM-HARDENING-PLAN.md
- COLLISION-DETECTION-STATUS.md
- RELEASE-BUMP-WORKFLOW.md
5. local/scripts/TOOLS.md (15-tool operator reference)
6. README.md (project overview, status)
```
### 4.3 Stale / Obsolete / Duplicate Findings
#### A. Should be ARCHIVED (self-labeled or unambiguously superseded)
- `local/docs/BUILD-SYSTEM-IMPROVEMENTS.md` — self-labeled "HISTORICAL POST-MORTEM". Content is tracked elsewhere or abandoned.
- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` — uses old P0–P6 phase numbering; superseded by `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
- `local/docs/SLEEP-IMPLEMENTATION-PLAN.md` — references 0.2.4 branch; pre-0.3.1.
#### B. Should be MERGED into authoritative source
- `local/docs/PATCH-GOVERNANCE.md` → fold into `local/AGENTS.md` § "Patch Governance" (already mostly there; only adds 2026-04-26 incident context).
- `docs/06-BUILD-SYSTEM-SETUP.md` → merge mechanics into `AGENTS.md` § "Build Commands"; distro setup into `README.md`.
- `docs/05-KDE-PLASMA-ON-REDOX.md` → mark as historical supplement to `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
#### C. Should be REDIRECTED (replace content with pointer)
- `recipes/AGENTS.md` → replace with short note pointing to `local/recipes/AGENTS.md` + `local/AGENTS.md`.
- `recipes/core/AGENTS.md` → same; current content describes upstream-Redox pattern, not the local fork reality.
#### D. Need FRESHNESS UPDATES
- `docs/README.md` — date "2026-05-01" → current; v4.0 → v5.8 plan reference; remove per-component GitLab URLs.
- `CONTRIBUTING.md` — rewrite for local fork workflow, `build-redbear.sh`, patch governance.
- `HARDWARE.md` — remove reference to nonexistent `PROFILE-MATRIX.md`.
- `local/docs/LOCAL-FORK-SUPREMACY-POLICY.md` — fix "currently 0.1.0" → "currently 0.3.1".
- `local/docs/GRUB-INTEGRATION-PLAN.md` — update `make all CONFIG_NAME=redbear-grub` → `./local/scripts/build-redbear.sh redbear-grub`.
#### E. Definite duplicates (primary should win)
| Duplicate | Primary |
|-----------|---------|
| `recipes/AGENTS.md` | `local/recipes/AGENTS.md` |
| `recipes/core/AGENTS.md` | `local/AGENTS.md` § "LOCAL FORK MODEL" |
| `docs/05-KDE-PLASMA-ON-REDOX.md` | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` |
| `AGENTS.md` (root) | `local/AGENTS.md` (intentional subset — keep both) |
### 4.4 Recommended Doc Hygiene Policy
Adopt project-wide: every build-system doc should carry
```markdown
> **Last verified:** YYYY-MM-DD against branch `<branch>`
> **Authority:** Primary | Supplement | Historical
```
The collision-detection, release-bump, and hooks docs already follow this pattern. Standardize it.
---
## Part 5 — User-Facing Messages
### 5.1 Inventory Summary
**Total:** 185 messages across 16 source files.
| Source | Count |
|--------|-------|
| `Makefile` (root) | 11 |
| `mk/config.mk` | 4 |
| `mk/depends.mk` | 4 |
| `mk/disk.mk` | 12 |
| `mk/podman.mk` | 8 |
| `mk/prefix.mk` | 13 |
| `mk/repo.mk` | 5 |
| `mk/qemu.mk` | 2 |
| `mk/redbear.mk` | 3 |
| `mk/virtualbox.mk` | 8 |
| **`local/scripts/build-redbear.sh`** | **50** (largest surface) |
| `src/cook/status.rs` | 4 |
| `src/cook/cook_build.rs` | 18 |
| `src/cook/fetch.rs` | 27 |
| `src/bin/repo.rs` | 9 |
| `src/bin/repo_builder.rs` | 7 |
### 5.2 Overall Quality
| Rating | Count | % |
|--------|-------|---|
| Current + helpful | ~158 | 85% |
| Stale or misleading | 9 | 5% |
| Unhelpful (noise or vague) | 12 | 6% |
| Debug-level (acceptable) | ~10 | 5% |
### 5.3 Stale / Misleading Messages (Action Required)
| ID | File:Line | Current Text | Issue | Fix |
|----|-----------|--------------|-------|-----|
| M18 | `build-redbear.sh:523` | `"Patches are applied by 'repo fetch' via recipe.toml (atomic mechanism)"` | Implies overlay-patch model is primary; local forks are primary now. | Reword: `"Local fork sources are already committed. Recipe patches (for non-fork recipes) are applied atomically by repo fetch."` |
| M19 | `build-redbear.sh:524` | `"Skipping direct patch application (was bypassing cookbook atomicity)"` | References historical behavior. | Integrate into M18 fix or remove. |
| M26 | `build-redbear.sh:569` | `"This may take 30-60 minutes on first build..."` | Stale for redbear-full with 100+ recipes. | `"varies by config (45-120 minutes for redbear-full, less for redbear-mini)"` |
| M46 | `build-redbear.sh:923` | `"Release mode: building from immutable archives (offline)"` | Implies archive-extraction model; actual build uses local forks. | `"Release mode: building from local forks (offline)"` |
| I2 | `mk/redbear.mk:41` | `"Archiving fully-patched source packages..."` | Misleading for fork-based model — forks already have patches committed. | `"Archiving source packages..."` |
| E1 | `mk/podman.mk:47` | `"please set it to 1 in mk/config.mk"` | Wrong location — it's set in `.config`. | `"please set it to 1 in .config"` |
| F10 | `mk/prefix.mk:346` | `"Incomplete build stages. Please re-run the build"` | Vague directive. | `"Incomplete build stages detected. Run 'make prefix' to rebuild the toolchain."` |
| J2 | `mk/virtualbox.mk:10` | `"RedBearOS directory exists, deleting..."` | Branding inconsistency. | `"Red Bear OS directory exists, deleting..."` (or keep as VBox-internal identifier with a comment). |
| Q1 | `src/bin/repo.rs:207,294,297` | `eprintln!("{:?}", e)` | Raw Rust Debug output, no operator context. | Replace with human-readable messages. |
### 5.4 Noisy / Unhelpful Messages
| ID | File:Line | Issue | Fix |
|----|-----------|-------|-----|
| D1, D2, D6, D7 | `mk/disk.mk:8, 9, 107, 109` | Repeated "Warning: failed to unmount" fires every build even when nothing was mounted. | Suppress when error is just "not mounted" (expected); only warn on real failures. |
| A6, A8 | `Makefile:162, 189` | "container is not built" — doesn't tell operator how to build it first. | Add: `"Run 'make container' first to build the Podman image."` |
| B3 | `mk/config.mk:90` | "sccache not found" — no install hint. | Add: `"Install with 'cargo install sccache' or from your package manager."` |
| H2 | `mk/qemu.mk:140` | "Unsupported ARCH" — doesn't list supported arches. | Add the list: x86_64, aarch64, i686, i586, riscv64gc. |
### 5.5 Strongest Messages (Models to Emulate)
The structured error blocks in `build-redbear.sh` (M1, M2, M14, M15, M17, M49) are exemplary:
- State the problem in one line.
- List affected items (forks, recipes, files).
- Provide the exact override or fix command.
- Reference documentation where applicable.
**Example** (M2):
```
REFUSING TO BUILD — FORKS NOT ON CANONICAL BRANCHES
The following forks are on unexpected branches:
- local/sources/relibc: on 'main' (expected 'submodule/relibc')
...
Fix: checkout the correct branch in each fork, or set
REDBEAR_ALLOW_BRANCH_DRIFT=1 to override.
```
This pattern should be the standard for all error-class messages.
---
## Part 6 — Gaps, Blockers, Improvement Opportunities
### 6.1 No Current Blockers
The build system is fully functional on the canonical path: `./local/scripts/build-redbear.sh redbear-mini` (or `redbear-full`, `redbear-grub`) produces a bootable ISO from a clean checkout. Phase 1 remediation closed the structural gaps; Phase 15.0 closed the runtime collision-detection gap.
### 6.2 Quality Improvement Opportunities (Ordered by Impact)
| # | Opportunity | Effort | Impact |
|---|-------------|--------|--------|
| Q1 | Add per-pkgar BLAKE3 to cache manifest; verify post-restore. | Medium | Closes the largest robustness gap (Mechanism #2). |
| Q2 | Wrap `download_wget()` and `git clone` with retry logic matching prefix.mk's wget pattern. | Small | Eliminates the most common transient-failure abort. |
| Q3 | Preserve `auto_deps.toml` in binary store; copy alongside `dep_hashes.toml`. | Small | Closes correctness gap in restored recipes. |
| Q4 | Validate `dep_hashes.toml` parse strictly; on corrupt, log loud + rebuild instead of silent mtime fallback. | Small | Eliminates a silent correctness gap. |
| Q5 | Adopt the "Last verified / Authority" header policy for all build-system docs. | Small | Prevents future drift. |
| Q6 | Standardize error-message template across `repo.rs` (replace `{:?}` with human-readable). | Small | Improves operator experience for CLI errors. |
| Q7 | Suppress `mk/disk.mk` unmount noise for the "not mounted" case. | Trivial | Removes 8 spurious warnings per build. |
| Q8 | Fix the 9 stale user-facing messages identified in Part 5.3. | Trivial | Removes misleading language. |
| Q9 | Archive/merge the 3+3+2 stale/obsolete/duplicate docs identified in Part 4.3. | Small | Consolidates doc surface; no behavior change. |
| Q10 | Replace `recipes/AGENTS.md` and `recipes/core/AGENTS.md` with redirects to `local/AGENTS.md`. | Trivial | Eliminates misleading upstream-Redox-pattern docs. |
### 6.3 Auto-Correction Capability Summary
The build system auto-corrects the following without operator intervention:
| Failure | Auto-Correction |
|---------|-----------------|
| Stale prefix (fork newer than libc.a) | Auto-runs `make prefix`; aborts on failure. |
| Workspace pollution (orphan Cargo.toml) | Silently removed before every fetch and build. |
| Partially-applied patches | Atomic rollback; source tree never partially patched. |
| Interrupted build (Ctrl-C, OOM) | `.DELETE_ON_ERROR` removes partial targets; `.partial` directories cleaned next run. |
| Damaged git source (no .git) | Auto re-clones from recipe URL. |
| Missing target/ with pkgar in repo/ | Restores from binary store. |
| Source changed without mtime change | BLAKE3 content hash catches it; rebuilds. |
| Dependency pkgar changed | DepHashes catches it; rebuilds. |
| Local-overlay unfetch attempted | Refused; sources are immutable. |
| Protected recipe online fetch attempted | Refused; falls through to offline source. |
The build system does NOT auto-correct:
| Failure | Operator Action Required |
|---------|--------------------------|
| Transient network failure on non-prefix fetch | Re-run the build. |
| Corrupt cached pkgar that passes mtime check | Re-run with `--no-cache` or remove the bad pkgar. |
| Config-vs-package collision (warn mode) | Read the warning; fix the config or accept it. |
| Fork on wrong branch | Checkout correct branch or set override. |
| Dirty fork working tree at build start | Commit or stash; the script stashes automatically but may need manual unstash on failure. |
---
## Part 7 — Recommended Action Plan
### Tier 1 — Safe, surgical fixes (no behavior change, low risk)
Execute immediately, no approval needed beyond this assessment:
1. **Fix 9 stale messages** (Part 5.3): `build-redbear.sh` M18/M19/M26/M46, `mk/redbear.mk` I2, `mk/podman.mk` E1, `mk/prefix.mk` F10, `mk/virtualbox.mk` J2, `src/bin/repo.rs` Q1.
2. **Suppress mk/disk.mk unmount noise** (Part 5.4): gate the four repetitive warnings behind actual error detection.
3. **Archive `local/docs/BUILD-SYSTEM-IMPROVEMENTS.md`** to `local/docs/archived/` — self-labeled historical.
4. **Update `LOCAL-FORK-SUPREMACY-POLICY.md`** version reference 0.1.0 → 0.3.1.
5. **Update `GRUB-INTEGRATION-PLAN.md`** build commands to `build-redbear.sh`.
6. **Update `docs/README.md`** date stamp and version references.
### Tier 2 — Doc consolidation (content rewrite, requires judgment)
Recommend approval before execution:
7. **Replace `recipes/AGENTS.md`** with a 10-line redirect to `local/recipes/AGENTS.md` and `local/AGENTS.md`.
8. **Replace `recipes/core/AGENTS.md`** with a 10-line redirect to `local/AGENTS.md` § "LOCAL FORK MODEL".
9. **Mark `docs/05-KDE-PLASMA-ON-REDOX.md`** as historical supplement; add header pointing to `CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
10. **Mark `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`** as historical; add header pointing to current plan.
11. **Mark `docs/06-BUILD-SYSTEM-SETUP.md`** as historical; the canonical setup is in `AGENTS.md` § "Build Commands" and `README.md`.
12. **Rewrite `CONTRIBUTING.md`** to reflect local fork workflow, `build-redbear.sh`, patch governance.
13. **Fix `HARDWARE.md`** — remove reference to nonexistent `PROFILE-MATRIX.md`; align with `README.md` status table.
### Tier 3 — Code improvements (gaps from Part 6.2)
Defer to a separate work cycle; listed for visibility:
14. Q1 — Cache manifest with per-pkgar BLAKE3 + post-restore verify.
15. Q2 — Retry logic for non-prefix fetches.
16. Q3 — Preserve `auto_deps.toml` in binary store.
17. Q4 — Strict `dep_hashes.toml` parse handling.
18. Q6 — Standardize error messages in `repo.rs`.
---
## Appendix A — Phase 1 Remediation Status (for reference)
| Item | Status | Files |
|------|--------|-------|
| P0.1 — `.DELETE_ON_ERROR` in root Makefile | ✅ Done | `Makefile` |
| P0.2 — Test harness for cook_build | ✅ Done (21 tests + latent bug fix) | `src/cook/cook_build.rs` |
| P1.3 — Installer runtime collision detection | ✅ Done (Phase 15.0) | `local/sources/installer/{src/collision.rs,src/lib.rs,src/installer.rs,tests/collision.rs}` |
| P1.4 — unwrap→Result in fetch_repo/cook_build | ✅ Done | `src/cook/{fetch_repo.rs,cook_build.rs,fetch.rs}` |
| P2.5 — REDBEAR_TAG fingerprint | ✅ Done | `mk/redbear.mk` |
| P2.6 — Cache integrity check | ✅ Done | `Makefile` |
| P3.7 — Post-build validate gate | ✅ Done | `Makefile`, `mk/disk.mk` |
All changes verified: `cargo check` ✅, `cargo test --lib cook::cook_build::tests` ✅ 21/22 (1 pre-existing), `cargo clippy --lib` ✅ 0 new warnings, `make -n` dry-runs ✅. Nothing has been committed (per project policy — agents do not commit without explicit request).
## Appendix B — Source Files Consulted
**Make layer:** `Makefile`, `mk/config.mk`, `mk/depends.mk`, `mk/disk.mk`, `mk/fstools.mk`, `mk/podman.mk`, `mk/prefix.mk`, `mk/qemu.mk`, `mk/repo.mk`, `mk/redbear.mk`, `mk/virtualbox.mk`, `mk/ci.mk`.
**Cookbook Rust:** `Cargo.toml`, `src/lib.rs`, `src/config.rs`, `src/recipe.rs`, `src/staged_pkg.rs`, `src/bin/repo.rs`, `src/bin/repo_builder.rs`, `src/cook/{fetch.rs, cook_build.rs, package.rs, tree.rs, ident.rs, fs.rs, status.rs}`.
**Scripts:** `local/scripts/build-redbear.sh`, `local/scripts/integrate-redbear.sh`, plus the cache/sync/restore scripts.
**Installer:** `local/sources/installer/{src/lib.rs, src/installer.rs, src/collision.rs, tests/collision.rs}`.
**Docs:** All 75 docs inventoried (Part 4).
local/docs/GRUB-INTEGRATION-PLAN.md
+1 -1
View File
@@ -3,7 +3,7 @@
**Date:** 2026-04-17
**Status:** Fully implemented (build-tested, not yet runtime boot-tested). ESP formatted as FAT32
per UEFI spec. Both Phase 1 (post-build script) and Phase 2 (installer-native) are wired.
**Remaining:** Runtime UEFI boot validation in QEMU (`make all CONFIG_NAME=redbear-grub && make qemu`).
**Remaining:** Runtime UEFI boot validation in QEMU (`./local/scripts/build-redbear.sh redbear-grub && make qemu`).
**Prerequisite:** The `grub` package is included in `redbear-grub.toml` for clean-tree builds.
**Approach:** Option A — GRUB as boot manager, chainloading Redox bootloader
local/docs/LOCAL-FORK-SUPREMACY-POLICY.md
+2 -1
View File
@@ -23,7 +23,8 @@ of functionality our system needs, implemented in our tree, maintained by us.
### What Red Bear OS Is
Red Bear OS is a **full fork** of Redox OS, based on frozen Redox snapshots
(currently 0.1.0 at build-system commit `f55acba68`). We are NOT a downstream
(currently branch `0.3.1`; legacy release archive at `sources/redbear-0.1.0/`
at build-system commit `f55acba68`). We are NOT a downstream
distributor of Redox. We are NOT a configuration overlay on top of Redox.
We took Redox as a starting point and are building our own complete operating
local/docs/BUILD-SYSTEM-IMPROVEMENTS.md → local/docs/archived/BUILD-SYSTEM-IMPROVEMENTS.md
View File
mk/podman.mk
+1 -1
View File
@@ -44,7 +44,7 @@ container_shell: build/container.tag
ifeq ($(PODMAN_BUILD),1)
$(PODMAN_RUN) bash
else
@echo PODMAN_BUILD=$(PODMAN_BUILD), please set it to 1 in mk/config.mk
@echo PODMAN_BUILD=$(PODMAN_BUILD), please set it to 1 in .config
endif
container_clean: FORCE
mk/prefix.mk
+1 -1
View File
@@ -343,7 +343,7 @@ else
@echo "\033[1;36;49mBuilding gcc-install\033[0m"
rm -rf "$@.partial" "$@-build.partial" "$@"
if [ ! -d "$(ROOT)/$(GCC_TARGET)" ]; then \
echo "\033[1;38;5;196m Incomplete build stages. Please re-run the build\033[0m"; \
echo "\033[1;38;5;196m Incomplete build stages detected. Run 'make prefix' to rebuild the toolchain (gcc-freestanding-install and relibc-freestanding-install must complete first).\033[0m"; \
rm -rf "$(PREFIX)"/gcc-freestanding-install && "$(PREFIX)"/relibc-freestanding-install && \
exit 1; fi
mkdir -p "$@.partial" "$@-build.partial"
mk/virtualbox.mk
+1 -1
View File
@@ -7,7 +7,7 @@ virtualbox: $(BUILD)/harddrive.img
then \
if [ -d "$$HOME/VirtualBox VMs/RedBearOS" ]; \
then \
echo "RedBearOS directory exists, deleting..."; \
echo "Red Bear OS VM directory exists, deleting..."; \
$(RM) -rf "$$HOME/VirtualBox VMs/RedBearOS"; \
fi \
fi
recipes/AGENTS.md
+62 -67
View File
@@ -1,90 +1,85 @@
# RECIPES — PACKAGE RECIPE SYSTEM
26 categories of package recipes. Each recipe = `recipe.toml` defining fetch→build→stage.
> **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.
## STRUCTURE
## Recipe categories
```
recipes/
├── core/ # kernel, bootloader, relibc, init, base drivers — AGENTS.md
├── wip/ # Wayland, KDE, GNOME, driver WIP ports — AGENTS.md
├── libs/ # Libraries: mesa, cairo, SDL, zlib, openssl (~100+)
├── gui/ # Orbital display server, orbterm, orbutils
├── net/ # curl, wget, openssh, iperf3, smolnetd
├── dev/ # git, cmake, meson, cargo, rustc
├── games/ # spacecadetpinball, dosbox
├── shells/ # bash, ion, fish, zsh
├── tools/ # diffutils, findutils, coreutils, grep
├── sound/ # alsa-lib, pulseaudio, vorbis
├── terminal/ # Terminal emulators
├── video/ # ffmpeg
├── web/ # netsurf, firefox (WIP)
├── fonts/ # dejavu, freefont
├── icons/ # adwaita, cosmic, pop
├── archives/ # tar, unzip, zstd, bzip2
├── demos/ # orbclient demos, osdemo
├── other/ # Uncategorised packages
└── tests/ # Test suites
```
26 categories of package recipes under `recipes/<category>/<name>/recipe.toml` defining
fetch → build → stage. See root `AGENTS.md` for the full category tree.
## WHERE TO LOOK
## How to add a recipe
| Task | Location |
|------|----------|
| Add a Rust app | `recipes/<category>/<name>/recipe.toml` with `template = "cargo"` |
| Add a C/C++ app | `template = "cmake"` or `"configure"` or `"custom"` |
| Find a dependency | Search `recipes/*/recipe.toml` for package name |
| Fix a port | Look for `redox.patch` in the recipe dir |
| Track upstream | Check `upstream =` field in `[source]` |
Prefer the **local fork / local recipe** model over the upstream-Redox `redox.patch` pattern:
## HOW TO ADD A RECIPE
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").
```bash
mkdir -p recipes/<category>/<name>
cat > recipes/<category>/<name>/recipe.toml << 'EOF'
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://github.com/user/repo.git"
upstream = "https://github.com/original/repo.git"
branch = "redox"
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",
]
EOF
template = "cargo" # or cmake, meson, make, configure, custom
dependencies = ["dep1", "dep2"]
```
### Recipe Environment Variables
## Build templates
| Variable | Purpose |
|----------|---------|
| `COOKBOOK_SOURCE` | Extracted source directory |
| `COOKBOOK_STAGE` | Install target (staging dir) |
| `COOKBOOK_SYSROOT` | Sysroot with built dependencies |
| `COOKBOOK_TARGET` | Target triple (e.g. `x86_64-unknown-redox`) |
| `COOKBOOK_CARGO` | Cargo with correct target |
| `COOKBOOK_MAKE` | Make with correct flags |
### Build Templates
| Template | Use For |
|----------|---------|
| 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 (use `script = """..."""`) |
| `custom` | Anything else (`script = """..."""`) |
## CONVENTIONS
## Recipe environment variables
- WIP recipes: MUST start with `#TODO` comment
- Production recipes: BLAKE3 hash required for tar sources
- Patches: `redox.patch` in recipe dir, applied automatically
- Source: `git =` for git repos, `tar =` for tarballs, can use both
- Fork tracking: `git =` points to Redox fork, `upstream =` to original
- Dynamic linking: use `DYNAMIC_INIT` macro in custom scripts
| 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)
recipes/core/AGENTS.md
+69 -70
View File
@@ -1,85 +1,84 @@
# RECIPES/CORE — ESSENTIAL SYSTEM COMPONENTS
Kernel, bootloader, C library, init system, and base drivers. Everything needed to boot Redox.
> **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.
## STRUCTURE
## Path-fork model (CURRENT — supersedes legacy patch model)
```
recipes/core/
├── kernel/ # Redox microkernel (~20-40k LoC Rust)
│ └── source/ # Kernel source (fetched from gitlab.redox-os.org)
├── bootloader/ # UEFI bootloader (x86_64-uefi, aarch64-uefi)
│ └── source/mk/ # Per-arch bootloader build rules
├── relibc/ # POSIX C library written in Rust
│ └── source/ # relibc source (headers, platform, syscalls)
├── base/ # Core userland + all drivers
│ └── source/ # Base repo (audiod, ipcd, ptyd, drivers, netstack, ramfs)
│ └── drivers/ # ALL drivers (userspace daemons)
│ ├── graphics/ # vesad, virtio-gpud, ihdgd (Intel experimental)
│ ├── net/ # e1000d, rtl8168d, rtl8139d, ixgbed
│ ├── storage/ # ided, ahcid, nvmed, usbscsid
│ ├── audio/ # ac97d, ihdad, sb16d
│ ├── usb/ # usbhidd (USB HID)
│ ├── virtio/ # virtio-blkd, virtio-netd, virtio-gpud
│ └── pci/ # pcid, pcid-spawner (PCI enumeration)
├── installer/ # redox_installer (creates filesystem images)
├── redoxfs/ # RedoxFS (default filesystem)
├── init/ # Init system (TOML-based service manager)
├── ion/ # Ion shell (default)
├── userutils/ # Core user management
├── uutils/ # Coreutils (Rust port)
└── netutils/ # Basic network utilities
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/
```
## WHERE TO LOOK
| Task | Location |
|------|----------|
| Fix kernel crash | `kernel/source/src/` — syscall handling, context switching, memory mgmt |
| Add a syscall | `kernel/source/src/scheme/` — scheme registration, then `libredox` binding |
| Fix a driver | `base/source/drivers/<driver>/src/` |
| Fix POSIX compat | `relibc/source/src/header/` — add missing POSIX headers/functions |
| Add bootloader support | `bootloader/source/mk/<arch>-unknown-uefi.mk` |
| Fix PCI enumeration | `base/source/drivers/pci/pcid-spawner/` |
| Fix display output | `base/source/drivers/graphics/` — vesad, virtio-gpud |
| Fix networking | `base/source/drivers/net/` + `base/source/netstack/` |
## KERNEL SCHEME ARCHITECTURE
Kernel provides minimal schemes: `debug`, `event`, `memory`, `pipe`, `irq`, `time`, `sys`, `proc`, `serio`.
All other schemes are userspace daemons registering via `File::create(":myscheme")`.
```
Driver access pattern:
1. iopl() syscall → port I/O privilege
2. Open /scheme/memory/physical → mmap hardware registers
3. Open /scheme/irq/{num} → receive interrupts as messages
4. Register scheme → handle requests from user programs
For fork development with online fetch:
```bash
export REDBEAR_ALLOW_PROTECTED_FETCH=1
./local/scripts/build-redbear.sh --upstream redbear-mini
```
## DRIVER MODEL
## Driver model (unchanged from upstream Redox)
- ALL drivers are userspace daemons (except serio for PS/2)
- Access hardware via: `scheme:memory`, `scheme:irq`, `iopl` syscall
- Register as scheme: daemon name becomes `/scheme/<name>`
- PCI devices discovered via `pcid` daemon → spawns drivers
- 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>`.
## HISTORICAL POSIX GAPS IN RELIBC (Wayland-facing)
## Stale prefix detection (CRITICAL)
| Missing API | Location to implement |
|-------------|----------------------|
| signalfd/signalfd4 | `relibc/source/src/header/signal/` + active `local/patches/relibc/P3-signalfd*.patch` carriers — current support is recipe-applied, not plain-source convergence |
| timerfd_create/settime/gettime | `relibc/source/src/header/sys_timerfd/` + active `local/patches/relibc/P3-timerfd-relative.patch` carrier — current support is recipe-applied |
| eventfd | `relibc/source/src/header/sys_eventfd/` + active `local/patches/relibc/P3-eventfd-mod.patch` carrier — current support is recipe-applied |
| F_DUPFD_CLOEXEC | `relibc/source/src/header/fcntl/` + `local/patches/relibc/redox.patch` — support language should remain evidence-qualified |
| MSG_CMSG_CLOEXEC, MSG_NOSIGNAL | `relibc/source/src/header/sys_socket/` — support language should remain evidence-qualified |
| open_memstream | `relibc/source/src/header/stdio/` + `local/patches/relibc/P3-open-memstream.patch` carrier — current support is patch-carried |
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:
The current relibc work is therefore no longer just “add the missing Wayland APIs.” The higher-value
remaining work is completeness depth, downstream cleanup, and runtime validation.
```bash
touch relibc && make prefix # Rebuild relibc in the cross-toolchain
touch kernel && make prefix # Rebuild kernel-related toolchain parts
```
## ANTI-PATTERNS
`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() in drivers — handle errors properly with Result
- **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
src/bin/repo.rs
+1 -1
View File
@@ -204,7 +204,7 @@ impl CliConfig {
fn main() {
init_config();
if let Err(e) = main_inner() {
eprintln!("{:?}", e);
eprintln!("repo: {e:#}");
process::exit(1);
};
}