diff --git a/AGENTS.md b/AGENTS.md index 6cde48835e..c9b42e972e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,67 @@ This means: - If a Cargo dependency breaks, we fork the dependency crate to `local/sources/` and pin our Cargo.toml to our fork. - The Linux kernel in `local/reference/` is read-only reference — never a dependency. +### Safe to Pull from Upstream (Redox System Internals) + +These are Redox-specific libraries, tools, and protocols that form the stable ABI +between the kernel and userspace. We do NOT modify these — we pull them from upstream +with pinned revisions. Forking them would create divergence from the Redox ABI and +cause silent breakage. + +**Crates (pulled via Cargo, NOT via recipe git URLs):** + +| Crate | Why safe | Notes | +|---|---|---| +| `redox_syscall` | Syscall numbers, types, flags — must match kernel ABI | Maintained by Redox; we never modify syscall numbers | +| `redox-scheme` | Scheme protocol (`SchemeSync`, `SchemeAsync` traits) | Stable protocol; our daemons implement it | +| `libredox` | High-level syscall wrappers (`call_ro`, `call_wo`) | Thin wrapper; if it breaks we fork it | +| `pkgar` / `pkgar-core` / `pkgar-keys` | Package format (archive, signing, manifest) | Stable ABI; used by installer and repo tool | +| `redox-pkg` | Package dependency resolution | Used by cookbook; we don't modify | +| `redox_installer` | Filesystem image creation | **We forked this** — ext4 + GRUB support | +| `redoxer` | Cross-compilation wrapper | Build tool; we use it as-is | + +**Recipes (gitlab URLs — safe to pull from upstream):** + +| Recipe | Why safe | Notes | +|---|---|---| +| `core/pkgar` | Package format tools | Matches `pkgar` crate ABI | +| `core/ion` | Shell | We don't modify shells | +| `core/dash` | POSIX shell | Redox port, we don't modify | +| `core/coreutils` | Core utilities | From uutils; we don't modify | +| `core/extrautils` | Extra utilities | Redox-specific; we don't modify | +| `core/findutils` | File search | We don't modify | +| `core/netdb` | Network database | Redox-specific | +| `core/netutils` | Network utilities | Redox-specific | +| `core/pkgutils` | Package utilities | Redox-specific | +| `core/profiled` | Profiler daemon | Redox-specific | +| `core/strace` | Syscall tracer | Redox-specific | +| `core/contain` | Container runtime | Redox-specific | +| `gui/orbital` | Legacy display server | We use Wayland; not modified | +| `gui/orbdata` | Legacy display data | Not modified | +| `gui/orbterm` | Legacy terminal | Not modified | +| `gui/orbutils` | Legacy display utils | Not modified | +| `dev/redoxer` | Cross-compilation wrapper | Build tool | +| `kernel/kernel` | Sub-recipe | Main kernel is OUR fork in `local/sources/kernel/` | + +**Rule of thumb:** If it defines the Redox ABI (syscall numbers, scheme protocol, +package format), we pull from upstream. If we add features to it, we fork it. + +### What We MUST Fork (things we modify) + +| Component | Our fork | Why forked | +|---|---|---| +| Kernel | `local/sources/kernel/` | ACPI, x2APIC, MSI/MSI-X, scheduling, branding | +| relibc | `local/sources/relibc/` | eventfd, signalfd, timerfd, waitid, SysV IPC | +| Base (drivers) | `local/sources/base/` | acpid, pcid, inputd, ps2d, xhcid migrations | +| Bootloader | `local/sources/bootloader/` | UEFI alloc fix, branding, GPT offset | +| Installer | `local/sources/installer/` | ext4 + GRUB bootloader integration | +| Mesa | `local/recipes/libs/mesa/` | virgl disk cache, GBM dumb prime export | +| libdrm | `local/recipes/libs/libdrm/` | ioctl bridge, PCI info, device enumeration | +| QtBase | `local/recipes/qt/qtbase/` | futex redox support, wayland guards | +| redox-driver-sys | `local/recipes/drivers/redox-driver-sys/` | Hardware quirks system | +| linux-kpi | `local/recipes/drivers/linux-kpi/` | GPU + Wi-Fi compatibility headers | +| redox-drm | `local/recipes/gpu/redox-drm/` | Intel + AMD display drivers | + ## BUILD SYSTEM DURABILITY — THE CARDINAL RULE **SOURCE LIVES IN `local/sources//`. EDIT THERE. `recipes/*/source/` IS A SYMLINK