RedBear-OS/docs/06-BUILD-SYSTEM-SETUP.md

06 — Build System Setup Guide

Status note (2026-04-15): This file explains the mechanics of building the repository, but it is not the canonical source for repository ownership policy or current execution order. For the current repository model, use README.md, AGENTS.md, and docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md. For Red Bear-owned subsystem planning, use the current documents under local/docs/.

Repository Model Reminder

Build this repository using the Red Bear overlay model:

• upstream-owned source trees are refreshable working copies,
• durable Red Bear state lives in local/patches/, local/recipes/, local/docs/, and tracked Red Bear configs,
• upstream WIP recipes are useful inputs, but should not automatically be treated as the durable shipping source of truth for Red Bear.

Prerequisites

System Requirements

• OS: Linux (Arch/Manjaro, Debian/Ubuntu, Fedora, Gentoo)
• Architecture: x86_64 (primary), also supports aarch64, i586, riscv64gc
• RAM: 4GB minimum, 8GB+ recommended
• Disk: 20GB+ free space (full build with all recipes)
• Network: Required for downloading sources and toolchain

Install Build Dependencies

Arch / Manjaro

sudo pacman -S --needed --noconfirm \
  autoconf automake bison cmake curl doxygen expat file flex fuse3 \
  gdb git gmp libjpeg-turbo libpng libtool m4 make meson nasm \
  ninja openssl patch patchelf perl pkgconf po4a protobuf python \
  python-mako rsync scons sdl12-compat syslinux texinfo unzip \
  wget xdg-utils zip zstd qemu-system-x86 qemu-system-arm qemu-system-riscv

Debian / Ubuntu

sudo apt-get update
sudo apt-get install --assume-yes \
  ant autoconf automake bison build-essential cmake curl doxygen \
  expect file flex fuse3 g++ gdb-multiarch git libc6-dev-i386 \
  libfuse3-dev libgdk-pixbuf2.0-bin libglib2.0-dev-bin libgmp-dev \
  libhtml-parser-perl libjpeg-dev libmpfr-dev libsdl1.2-dev \
  libsdl2-ttf-dev llvm m4 make meson nasm ninja-build patch \
  patchelf perl pkg-config po4a protobuf-compiler python3 \
  python3-dev python3-mako rsync ruby scons texinfo unzip wget \
  xdg-utils xxd zip zstd qemu-system-x86 qemu-kvm

Fedora

sudo dnf install --assumeyes \
  @development-tools autoconf automake bison cmake curl doxygen \
  expat-devel file flex fuse3-devel gcc gcc-c++ gdb genisoimage \
  gettext-devel glibc-devel.i686 gmp-devel libjpeg-turbo-devel \
  libpng-devel libtool m4 make meson nasm ninja-build openssl \
  patch patchelf perl po4a protobuf-compiler python3-mako \
  SDL2_ttf-devel sdl12-compat-devel syslinux texinfo unzip vim \
  zip zstd qemu-system-x86 qemu-kvm

Install Rust and Cargo Tools

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Install required cargo tools
cargo install just cbindgen

Configuration

Native Build (No Container)

# In the redox-master directory:
echo 'PODMAN_BUILD?=0' > .config

Podman Build (Containerized, Default)

# Default uses Podman — no configuration needed
# Ensure Podman is installed:
# Arch: sudo pacman -S podman
# Debian: sudo apt-get install podman

Select Build Configuration

Mainline configs still exist, but tracked Red Bear work should normally be built and validated through the first-class redbear-* profiles.

Available configs (in config/):

Config	Description
minimal	Bare minimum bootable system
server	Server-oriented (no GUI)
desktop-minimal	Orbital + basic GUI apps
desktop	COSMIC apps + installer
wayland	Wayland compositor (experimental)
x11	X.org + MATE desktop
demo	Demo apps

Building

Full Build (Desktop)

make all

This produces build/x86_64/desktop/harddrive.img.

Export External Toolchain

After make prefix, you can export a relocatable external cross toolchain that provides x86_64-unknown-redox-gcc and the related host-side wrappers in one directory:

make export-toolchain TARGET=x86_64-unknown-redox
source build/toolchain-export/x86_64-unknown-redox/activate.sh
x86_64-unknown-redox-gcc --version

To export somewhere else:

make export-toolchain TARGET=x86_64-unknown-redox \
  TOOLCHAIN_EXPORT_DIR=/opt/redbear/toolchains/x86_64-unknown-redox

For the full layout and rationale, see local/docs/EXTERNAL-TOOLCHAIN.md.

Build with Specific Config

# Preferred Red Bear wrapper:
./local/scripts/build-redbear.sh redbear-desktop
./local/scripts/build-redbear.sh redbear-minimal
./local/scripts/build-redbear.sh redbear-wayland
./local/scripts/build-redbear.sh redbear-full
./local/scripts/build-redbear.sh redbear-kde
./local/scripts/build-redbear.sh redbear-live

# Direct make is still valid when needed:
make all CONFIG_NAME=redbear-desktop
make all CONFIG_NAME=redbear-wayland

For tracked Red Bear work, prefer the redbear-* profiles over older mainline profile names.

Build a Live ISO

make live
# Produces: build/x86_64/desktop/redox-live.iso

Rebuild After Changes

make rebuild    # Clean rebuild of filesystem image

Running

QEMU (Recommended)

# Desktop with Orbital GUI:
make qemu

# With more RAM:
make qemu QEMUFLAGS="-m 4G"

# Without GUI (serial console):
make qemu QEMUFLAGS="-nographic"

# With network (port forwarding):
make qemu QEMUFLAGS="-net nic -net user,hostfwd=tcp::8080-:80"

VirtualBox

make virtualbox

Live USB

# Write image to USB device (replace sdX with your device):
sudo dd if=build/x86_64/desktop/harddrive.img of=/dev/sdX bs=4M status=progress

Building Specific Packages (Recipes)

Build a Single Recipe

# Using the repo tool:
./target/release/repo cook recipes/libs/mesa
./target/release/repo cook recipes/gui/orbital

Under the Red Bear overlay model, remember:

• recipes/*/source/ is a refreshable working tree,
• Red Bear-owned shipping deltas should be preserved under local/patches/ and local/recipes/,
• if a recipe is still upstream WIP, Red Bear may still choose to ship from local/recipes/ instead.

Understanding Recipe Format

Each recipe is in recipes/<category>/<name>/recipe.toml:

[source]
git = "https://example.com/repo.git"    # Git source
# tar = "https://example.com/source.tar.gz"  # Or tar source
# branch = "main"                        # Git branch
# rev = "abc123"                         # Or specific commit
# patches = ["redox.patch"]              # Patches to apply

[build]
template = "cargo"   # Build template: cargo, meson, cmake, make, custom
dependencies = [
    "dep1",           # Other recipe names
    "dep2",
]

# For custom builds:
script = """
DYNAMIC_INIT
cookbook_cargo --release
mkdir -p ${COOKBOOK_STAGE}/usr/bin
cp target/release/myapp ${COOKBOOK_STAGE}/usr/bin/
"""

Build Templates

Template	Description
cargo	Rust project (cargo build)
meson	Meson build system
cmake	CMake build system
make	GNU Make
custom	Custom script in script field

Key Build Variables

Variable	Default	Description
ARCH	Host arch	Target architecture (x86_64, aarch64, i586, riscv64gc)
CONFIG_NAME	desktop	Build config name
PODMAN_BUILD	1	Use Podman container
PREFIX_BINARY	1	Use prebuilt toolchain (faster)
REPO_BINARY	0	Use prebuilt packages (faster, no compilation)
REPO_NONSTOP	0	Continue on build errors
REPO_OFFLINE	0	Don't update source repos

Environment Variables for Recipes

Inside recipe scripts, these are available:

Variable	Description
COOKBOOK_SOURCE	Path to extracted source
COOKBOOK_STAGE	Path to staging directory (install target)
COOKBOOK_SYSROOT	Path to sysroot with deps
COOKBOOK_TARGET	Target triple (e.g., x86_64-unknown-redox)
COOKBOOK_CARGO	Cargo command with correct target
COOKBOOK_MAKE	Make command with correct flags

Troubleshooting

Toolchain Download Fails

# Clean and retry:
rm -rf prefix/
make prefix  # Re-download toolchain

Build Errors in Specific Recipes

# Rebuild a specific recipe:
./target/release/repo cook recipes/<category>/<name>

# Skip failing recipes:
make all REPO_NONSTOP=1

SELinux Issues (Fedora/RHEL)

make all USE_SELINUX=0

Out of Disk Space

# Clean everything:
make clean

# Clean only fetched sources:
make distclean

Directory Layout After Build

redox-master/
├── build/
│   └── x86_64/
│       └── desktop/
│           ├── harddrive.img      # Bootable disk image
│           ├── redox-live.iso     # Live CD ISO
│           ├── filesystem/        # Mounted filesystem (during build)
│           └── repo.tag           # Build completion marker
├── prefix/
│   └── x86_64-unknown-redox/
│       └── clang-install/         # Cross-compilation toolchain
├── repo/
│   └── *.pkgar                    # Built packages
├── source/
│   └── <recipe-name>/             # Extracted recipe sources
└── target/
    └── release/
        └── repo                   # Build system binary