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

docs: rewrite README for public audience — highlight cub, tlc, redbear-* utilities, current status, call for contributors

Browse Source
This commit is contained in:
vasilito
2026-07-04 09:18:22 +03:00
parent d7273ce5cf
commit 5be1ec17b3
2 changed files with 152 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+151 -63
View File
@@ -5,7 +5,7 @@
<h1 align="center">Red Bear OS</h1>
<p align="center">
<strong>A microkernel operating system written in Rust, derived from <a href="https://www.redox-os.org">Redox OS</a></strong>
<strong>A microkernel operating system written in Rust — derived from <a href="https://www.redox-os.org">Redox OS</a>, built for bare metal.</strong>
</p>
<p align="center">
@@ -18,40 +18,60 @@
## What is Red Bear OS?
Red Bear OS is a general-purpose, Unix-like operating system with a **microkernel architecture**, written in **Rust**. It is a full fork of Redox OS, frozen at release 0.1.0, with added hardware support, filesystem drivers, and a KDE Plasma desktop path.
Red Bear OS is a general-purpose, Unix-like operating system with a **microkernel architecture**,
written entirely in **Rust**. It is a full fork of Redox OS (baseline 0.1.0), actively developed
on branch `0.2.5` with hardware enablement, multiple filesystems, a native greeter and login
system, and a KDE Plasma desktop path.
It ships with several **first-in-class Rust-native tools** found nowhere else in the OS world:
- **cub** — an AUR-inspired package manager with pacman-style CLI (`-S`/`-Q`/`-R`) and a ratatui
TUI that converts Arch Linux PKGBUILDs into Red Bear recipes on the fly
- **tlc** (Twilight Commander) — a pure-Rust reimplementation of Midnight Commander; dual-panel
file manager, built-in editor and viewer, 8 color themes, 986 unit tests, zero unsafe code
- **redbear-power** — interactive ratatui TUI for live CPU frequency, governor, and thermal
monitoring with on-the-fly P-state control
These are joined by dozens of `redbear-*` system utilities — `redbear-netctl` (network control),
`redbear-info` (hardware diagnostics), `redbear-acmd` (admin CLI), `redbear-mtr`,
`redbear-nmap`, `redbear-btctl`, and many more — all written in Rust, all built from source
alongside the OS.
**Goals**:
- **AMD & Intel parity** — first-class support for both platforms on bare metal
- **AMD & Intel parity** — equal-priority bare-metal support for both platforms
- **KDE Plasma desktop** — Wayland-based desktop environment via the KWin compositor
- **Hardware GPU acceleration** — AMD GPU (amdgpu) and Intel GPU drivers via `redox-drm`
- **Modern subsystems** — USB, Wi‑Fi, Bluetooth, ext4, GRUB, D-Bus
- **Offline-first builds** — reproducible from archived, BLAKE3-verified sources
- **Hardware GPU acceleration** — AMD (amdgpu) and Intel GPU drivers via `redox-drm`
- **cub package ecosystem** — AUR → recipe.toml pipeline giving access to thousands of packages
- **First-class subsystems** — USB, Wi‑Fi, Bluetooth, ext4, FAT, GRUB, D-Bus (none optional)
- **Power management** — CPU frequency scaling, thermal monitoring, RAPL, sleep states
- **Offline-first, reproducible builds** — BLAKE3-verified source archives with content-hash caching
---
## Our Git Server
Red Bear OS lives on a self-hosted Gitea instance at **https://gitea.redbearos.org**.
This is the canonical home for the fork — there is no GitHub / GitLab / Codeberg
mirror that is authoritative.
This is the canonical home — no GitHub, GitLab, or Codeberg mirror is authoritative.
There is exactly **one repository**: all component sources (kernel, relibc, drivers,
system utilities) live here as submodule branches or tracked trees in `local/sources/`.
| Field | Value |
|----------|------------------------------------------------------|
| Host | `https://gitea.redbearos.org` |
| User | `vasilito` |
| Token | *(session-only — never stored in repo)* |
| Web UI | `https://gitea.redbearos.org/vasilito` |
| Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` |
> **Token policy.** The `vasilito` token is a per-session credential and **must
> never** be committed to any tracked file. Use `git credential.helper` (store /
> cache / libsecret), `~/.netrc`, or `$REDBEAR_GITEA_TOKEN` env var. See
> [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator
> runbook, mirror list, API reference, and recovery procedure.
> Authentication tokens are per-session credentials — never stored in the repo.
> See [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator runbook.
---
## Quick Start
### Prerequisites
Linux x86_64 host with Rust nightly, QEMU, nasm, and standard build tools.
Linux x86_64 host with Rust nightly, QEMU, nasm, and standard build tools.
See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for full setup.
### Build & Run
@@ -61,94 +81,162 @@ See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for
git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git
cd RedBear-OS
# Authenticated clone (one-off) — supply token via env var, not literal here
# Authenticated clone — supply token via env var
git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git
# Recommended: use the Red Bear wrapper
# Canonical build entry point
./local/scripts/build-redbear.sh redbear-mini # Text-only target
./local/scripts/build-redbear.sh redbear-full # Desktop-capable target
# Boot in QEMU with the resulting image
# Boot in QEMU
make qemu
```
> **Build script:** `local/scripts/build-redbear.sh` is the canonical and only
> supported build entry point. It handles `.config` parsing, prefix staleness
> detection, `REDBEAR_ALLOW_PROTECTED_FETCH=1`, pre-cooking critical packages,
> and source fingerprint tracking. Direct `make` invocations bypass these gates
> and should not be used. See `AGENTS.md` § Build Commands for full details.
### Public Scripts
| Script | Purpose |
|--------|---------|
| `local/scripts/build-redbear.sh` | **Canonical** build wrapper for redbear-mini/full/grub |
| `scripts/network-boot.sh` | PXE network boot helper |
| `scripts/dual-boot.sh` | Dual-boot installation helper |
> `local/scripts/build-redbear.sh` is the **only supported build entry point**. It handles
> `.config` parsing, prefix staleness detection, protected-recipe authorization, pre-cooking
> critical packages, and source fingerprint tracking. Direct `make` invocations bypass these
> gates. See [`AGENTS.md` § Build Commands](./AGENTS.md) for details.
### Config Targets
| Target | Type | Description |
|--------|------|-------------|
| `redbear-full` | Desktop | Wayland + KDE + GPU drivers + D-Bus services |
| `redbear-mini` | Console | Text-only recovery / install target |
| `redbear-full` | Desktop-capable | GPU drivers + Wayland compositor + Qt 6.11.1 + KF6 6.27.0 + KWin + SDDM + greeter + D-Bus |
| `redbear-mini` | Console | Text-only recovery / install target with tlc, cub, and redbear-* utilities |
| `redbear-grub` | Console | Text-only with GRUB boot manager |
---
## Current Status
Red Bear OS **boots to a login prompt** in QEMU with working wired networking, D-Bus system bus, hardware detection daemons, and filesystem support (RedoxFS, ext4, FAT).
Red Bear OS **boots to a login prompt** in QEMU with working wired networking, D-Bus system bus,
hardware detection daemons, and three filesystem backends (RedoxFS, ext4, FAT). The ISO builds
successfully on branch `0.2.5`. Graphics packages are frozen at latest upstream stable
(Qt 6.11.1, KF6 6.27.0, Plasma 6.7.2, SDDM 0.21.0, Mesa 24.0.8).
| Area | Status |
|------|--------|
| Boot (ACPI/x2APIC/SMP) | ✅ Bare-metal proven |
| Boot (ACPI, x2APIC, SMP) | ✅ Bare-metal proven — Ryzen Threadripper 128-thread verified |
| Userspace drivers (PCI, storage, net) | ✅ Working in QEMU |
| D-Bus system bus + services | ✅ Working (login1, PolicyKit, UDisks, UPower) |
| ext4 / FAT filesystems | ✅ Compiles, installer-wired |
| POSIX gaps (relibc) | 🚧 Bounded Wayland-facing support |
| DRM/KMS display drivers | 🚧 AMD + Intel compile; HW validation pending |
| Wayland compositor | 🚧 Bounded proof; Qt6/KF6 clients crash at init |
| KDE Plasma desktop | 🔄 In progress (Qt6/KF6 compile; KWin/QML blocked) |
| Wi‑Fi / Bluetooth | 📋 Planned (architected, implementation pending) |
| Filesystems — RedoxFS, ext4, FAT | ✅ Scheme daemons + mkfs/fsck tools |
| D-Bus system bus + services | ✅ Working — login1, PolicyKit, UDisks, UPower |
| **cub** package manager | 🟡 17-module Rust workspace; AUR → recipe pipeline; 70+ tests |
| **tlc** file manager | 🟡 113 .rs files, 46k+ lines; 986 tests; 8 skins; VFS archives |
| IRQ / PCI / MSI-X / IOMMU | 🟡 QEMU-proven; hardware validation open |
| POSIX gaps (relibc) | 🟡 ~85% coverage; ~38 active patches |
| DRM/KMS display drivers | 🟡 AMD + Intel + virtio-gpu compile; HW validation open |
| Mesa — llvmpipe + virgl | 🟡 Builds (`virtio_gpu_dri.so`, 17.4 MB); virgl EGL runtime probe open |
| SDDM display manager + Greeter/Login | 🟡 Wired in `redbear-full`; graphical login blocked by Qt6 Wayland crash |
| Qt 6.11.1 (Core, Gui, DBus, Wayland) | 🟡 Builds successfully; Wayland `null+8` crash blocks runtime |
| KF6 Frameworks — 40/40 | 🟡 All frameworks build; KWin cooks successfully |
| Wayland compositor | 🟡 Bounded proof; blocked by Qt6 Wayland protocol crash |
| KDE Plasma / KWin | 🔴 Blocked by Qt6 Wayland crash in `wl_proxy_add_listener` |
| Wi‑Fi (Intel iwlwifi) | 🟡 VFIO/passthrough bounded runtime validation framework exists |
| USB / Bluetooth | 🔴 USB maturity work in progress; Bluetooth controller path planned |
**Where help is most wanted:**
Qt6 Wayland protocol crash — the #1 blocker for graphical desktop · AMD/Intel GPU hardware validation on bare metal · USB controller maturity · Wi‑Fi native control plane · cub AUR pipeline hardening · package maintainers for the growing recipe catalog · tlc VFS remote backends and archive support
---
## How It Works
Red Bear OS uses a **userspace driver model** — all drivers run as unprivileged daemons:
Red Bear OS uses a **userspace driver model** — all drivers run as unprivileged daemons
communicating through the kernel's scheme-based IPC.
```
Kernel (microkernel)
└── schemes: memory, irq, event, pipe, debug
└── Driver daemons (userspace)
├── pcid → PCI enumeration
├── e1000d → Intel ethernet
├── xhcid → USB controller
└── vesad → Display framebuffer
┌─────────────────────────────────────────────────────────────────┐
│ KERNEL (microkernel) │
│ schemes: memory · irq · event · pipe · debug │
└──────────────────────────┬──────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ pcid │ │ e1000d xhcid │ │ vesad redox-drm │
│ PCI enum │ │ Intel USB 3.0 │ │ fbdev GPU manager │
└──────────┘ └──────────────────┘ └──────────────────────┘
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ ext4d │ │ ps2d evdevd │ │ thermald cpufreqd │
│ fatd │ │ KB+mouse input │ │ thermal CPU freq │
└──────────┘ └──────────────────┘ └──────────────────────┘
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ iommu │ │ acpid │ │ dbus-daemon │
│ DMA map │ │ power mgmt │ │ system + session │
└──────────┘ └──────────────────┘ └──────────────────────┘
```
The kernel provides minimal services (memory, interrupts, IPC). Everything else — filesystems, networking, graphics, input — runs in userspace.
The kernel provides minimal services: memory, interrupts, and IPC. Everything else —
filesystems, networking, graphics, input, power management, D-Bus — runs in userspace.
Hardware quirks are handled by a data-driven system in `redox-driver-sys` with compiled-in
tables, TOML runtime configuration, and DMI matching.
---
## Engineering Standards
Red Bear OS operates under strict discipline. Full policies: [`local/AGENTS.md`](./local/AGENTS.md).
| Rule | |
|------|---|
| **Never delete to "fix" a build** | If a package breaks, fix the root cause. Never remove, ignore, or comment out a package, service, or config to make a build pass. |
| **Zero stubs** | No fake headers, `#ifdef` no-ops, or "make it compile" shortcuts. Missing functionality must be implemented properly in the right component. |
| **Single repository** | All component sources live here — no per-component repos. 9 `submodule/<component>` branches. |
| **Local fork model** | Core components (kernel, relibc, base, etc.) maintained as local forks in `local/sources/` with immutability guarantees. |
| **Adapt to upstream** | Red Bear adapts to upstream API/ABI changes — never pins, downgrades, or holds back a dependency. |
| **Free/libre only** | No proprietary, source-unavailable, or redistributability-restricted dependencies. MIT licensed. |
---
## Documentation
- [Implementation Plan](docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) — roadmap and execution model
- [Desktop Path Plan](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — kernel → DRM → Mesa → Wayland → KDE
- [D-Bus Integration](local/docs/DBUS-INTEGRATION-PLAN.md) — session bus architecture
- [USB Plan](local/docs/USB-IMPLEMENTATION-PLAN.md) — USB stack design
- [Wi‑Fi Plan](local/docs/WIFI-IMPLEMENTATION-PLAN.md) — wireless architecture
- [Bluetooth Plan](local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md) — BT stack design
- [Documentation Index](docs/README.md) — full doc map
- [Desktop Path Plan](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — Canonical plan v6.0: kernel → DRM → Mesa → Wayland → KDE
- [Implementation Plan](docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) — Roadmap and execution model
- [cub Package Manager](local/docs/CUB-PACKAGE-MANAGER.md) — AUR → recipe pipeline, CLI reference, architecture
- [tlc File Manager](local/recipes/tui/tlc/README.md) — Pure-Rust Midnight Commander replacement
- [D-Bus Integration](local/docs/DBUS-INTEGRATION-PLAN.md) — Session bus architecture
- [IRQ & Low-Level Controllers](local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) — IRQ delivery, MSI/MSI-X, IOMMU
- [Greeter & Login](local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md) — Native greeter, auth daemon, session launch
- [DRM Modernization](local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md) — DRM/KMS display and render maturity
- [USB Plan](local/docs/USB-IMPLEMENTATION-PLAN.md) — USB stack design and implementation
- [Wi‑Fi Plan](local/docs/WIFI-IMPLEMENTATION-PLAN.md) — Wireless architecture and driver plan
- [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
- [Quirks System](local/docs/QUIRKS-SYSTEM.md) — Hardware quirks infrastructure
- [Documentation Index](docs/README.md) — Full doc map
---
## Contributing
Red Bear OS uses a **full fork** model. Upstream Redox sources are frozen and archived. All custom work lives in `local/`:
Red Bear OS is a **full fork** of Redox OS. Upstream sources are frozen and archived; all
custom work lives in `local/` and survives every build operation.
```
local/
├── sources/ # Local forks of core components (kernel, relibc, base, bootloader, …)
├── recipes/ # Custom packages — drivers, GPU stack, system daemons, branding
├── patches/ # Durable changes to upstream source trees
├── recipes/ # Custom packages (drivers, GPU, system)
├── docs/ # Integration and planning docs
└── scripts/ # Build, test, and release tooling
├── docs/ # Integration and planning documentation
└── scripts/ # Build, test, validation, and release tooling
```
We welcome contributions made with or without AI assistance — we care about **quality**, not how the code was produced.
### We're Looking For
| Role | What you'd work on |
|------|--------------------|
| **Package maintainers** | Port and maintain AUR packages through cub's pipeline; write and test recipe.toml files for Red Bear OS; improve the PKGBUILD → recipe conversion |
| **Driver developers** | AMD/Intel GPU drivers, USB controller maturity, Wi‑Fi native control plane, Bluetooth |
| **Graphics stack engineers** | Qt6 Wayland crash fix (the #1 desktop blocker), Mesa virgl runtime, KWin Wayland compositor |
| **Systems/Rust engineers** | Kernel syscalls, relibc POSIX gaps, filesystem daemons, D-Bus services, hardware quirks |
| **TUI/app developers** | tlc feature completion, cub TUI polish, redbear-power enhancements, new redbear-* utilities |
Contributions are welcome with or without AI assistance — we care about **quality**, not how
the code was produced. Pick an area from the status table above, check the relevant plan doc,
and dive in.
---
## License
local/sources/relibc
+1 -1
Submodule local/sources/relibc updated: 89a4aa8a05...68ed35f243