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

06 — Build System Setup Guide

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

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.

Build with Specific Config

# Using build.sh wrapper:
./build.sh -c wayland all        # Wayland config
./build.sh -c server all         # Server config
./build.sh -c x11 all            # X11 config
./build.sh -a aarch64 -c desktop all  # ARM64 build

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

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