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.

Resilience policy for package/source inputs:

• default build posture is local-first/offline-capable,
• local copies are used continuously unless upstream refresh is explicitly requested,
• upstream refresh is an explicit operation, not an implicit background requirement for normal builds.

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

Tracked Red Bear work should normally be built and validated through the three supported redbear-* compile targets. For desktop work specifically, redbear-full is the tracked desktop-capable target.

Building

Full Build (Desktop)

make all

This produces the image for the selected target, such as build/x86_64/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-mini
./local/scripts/build-redbear.sh redbear-full
./local/scripts/build-redbear.sh redbear-grub

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

For tracked Red Bear work, prefer these three compile targets over older historical names.

Build a Live ISO

make live CONFIG_NAME=redbear-full
# Produces: build/x86_64/redbear-live.iso

Live .iso outputs are for real bare-metal boot, install, recovery, and demo workflows. They are not the VM/QEMU execution surface; for virtualization, use make qemu and the harddrive.img path instead.

Rebuild After Changes

make rebuild    # Clean rebuild of filesystem image

Running

QEMU (Recommended)

# Default desktop-capable tracked target:
make qemu

# Explicit desktop-capable tracked target:
make qemu CONFIG_NAME=redbear-full

# 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/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/wip/kde/kwin

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	redbear-full	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; Red Bear policy treats local-first sourcing as the normal operating mode and upstream refresh as explicit opt-in

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/
│       ├── harddrive.img      # Bootable disk image
│       ├── redbear-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 (in-target location)
├── packages/                      # Collected build artifacts (post-build step)
│   └── x86_64-unknown-redox/
│       └── *.pkgar                # All built .pkgar packages — portable artifact export
│                                  # Populated by copying from repo/x86_64-unknown-redox/ after build
├── sources/                       # Archived recipe sources (post-build step)
│   └── x86_64-unknown-redox/
│       └── *.tar.gz               # Source tarballs for build reproducibility
├── source/
│   └── <recipe-name>/             # Extracted recipe sources
└── target/
    └── release/
        └── repo                   # Build system binary

Post-Build: Collect Packages and Sources

After a successful build, copy all built .pkgar packages into the packages/ directory for portable artifact export and archive:

mkdir -p packages/x86_64-unknown-redox
cp repo/x86_64-unknown-redox/*.pkgar packages/x86_64-unknown-redox/

Archive all recipe source trees into the sources/ directory for build reproducibility:

mkdir -p sources/x86_64-unknown-redox
for d in recipes/*/* local/recipes/*/*; do
    [ -d "$d/source" ] || continue
    name=$(echo "$d" | tr '/' '-')
    if [ -d "$d/source/.git" ]; then
        (cd "$d/source" && git archive --format=tar HEAD | gzip > "../../../sources/x86_64-unknown-redox/$name.tar.gz")
    else
        tar czf "sources/x86_64-unknown-redox/$name.tar.gz" -C "$d" source/
    fi
done

Both packages/ and sources/ are git-ignored (generated artifacts).

• repo/x86_64-unknown-redox/ remains the canonical in-repo package location
• recipes/*/source/ remains the canonical in-repo source location
• packages/ and sources/ are export copies for portability and archival

Known Package Conflicts

The installer resolves file collisions between packages by replacing with the later package's files. These known overlaps are pre-existing and do not block the build:

Conflict	Packages	Files
info/dir	bash ↔ diffutils	/usr/share/info/dir
clear/reset	coreutils ↔ ncursesw	/usr/bin/clear, /usr/bin/reset
linux-kpi headers	redbear-iwlwifi ↔ redox-drm	39 header files under /usr/include/linux-kpi/
motd	redbear-release ↔ userutils	/etc/motd (both Red Bear branded; userutils motd already patched)

Known Build Warnings (Pre-Existing)

The build produces compiler warnings in several packages. These are pre-existing in the codebase and not introduced by the build process:

Package	Warnings	Examples
linux-kpi	4	dead_code (size, GFP_*), FFI-unsafe type
redox-drm	2	unreachable patterns
relibc	2+ C warnings	unused macro, maybe-uninitialized (e_lgamma)
redbear-iwlwifi	3	unreachable statements, deprecated usleep

These are tracked for eventual cleanup but do not block the build.

Known Outdated Packages

Some packages are marked outdated because optional dependencies are not built for redbear-full:

Package	Reason
git	Missing dependency nghttp2 (present but marked outdated in redbear-full)
nghttp2	Built but marked outdated (source ident mismatch or dependency chain issue)

These do not affect the base system or desktop image.