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 release fork model:

- sources are frozen, immutable release snapshots at baseline 0.3.1,
- durable Red Bear state lives in `local/patches/`, `local/recipes/`, `local/docs/`, and tracked
  Red Bear configs,
- build from archived sources offline by default; provision new releases explicitly via provision-release.sh.

Resilience policy for package/source inputs:

- default build posture is local-first/offline-capable,
- local copies are used continuously unless release provisioning is explicitly requested,
- release provisioning 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

```bash
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

```bash
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

```bash
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

```bash
# 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)

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

### Podman Build (Containerized, Default)

```bash
# 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

### Quick Build (Recommended)

```bash
# Use the Red Bear wrapper (auto-handles .config, REDBEAR_ALLOW_PROTECTED_FETCH, etc.)
./local/scripts/build-redbear.sh redbear-mini     # Text-only console target
./local/scripts/build-redbear.sh redbear-full     # Desktop-capable target
./local/scripts/build-redbear.sh redbear-grub     # Text-only + GRUB boot manager
```

These produce images such as `build/x86_64/harddrive.img` or `build/x86_64/redbear-mini.iso`.

### Bare `make all` (Not Supported)

Direct `make` invocations bypass the policy gates (`.config` checking,
`REDBEAR_ALLOW_PROTECTED_FETCH=1`, prefix staleness detection, local-over-WIP
enforcement, pre-cooking, source fingerprint tracking) that `build-redbear.sh`
enforces. **Always use `build-redbear.sh`.**

### 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:

```bash
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:

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

### Build with Specific Config

```bash
# Canonical Red Bear wrapper (produces live ISO):
./local/scripts/build-redbear.sh redbear-mini
./local/scripts/build-redbear.sh redbear-full
./local/scripts/build-redbear.sh redbear-grub
```

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

### Live ISO

`build-redbear.sh` already produces a live ISO (it calls `make live` internally).
Output: `build/<arch>/<config>.iso`

Live `.iso` outputs are for real bare-metal boot, install, recovery, and demo workflows.

### Rebuild After Changes

```bash
make rebuild    # Clean rebuild of filesystem image
```

## Running

### QEMU (Recommended)

```bash
# 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

```bash
make virtualbox
```

### Live USB

```bash
# 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

```bash
# Using the repo tool:
./target/release/repo cook recipes/libs/mesa
./target/release/repo cook recipes/wip/kde/kwin
```

Under the Red Bear release fork model, remember:

- `recipes/*/source/` is an immutable archived release snapshot,
- Red Bear-owned shipping deltas should be preserved under `local/patches/` and `local/recipes/`,
- sources are built offline by default; provision new releases via provision-release.sh.

### Understanding Recipe Format

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

```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 release provisioning 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

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

### Build Errors in Specific Recipes

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

# Skip failing recipes:
make all REPO_NONSTOP=1
```

### SELinux Issues (Fedora/RHEL)

```bash
make all USE_SELINUX=0
```

### Out of Disk Space

```bash
# 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:

```bash
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:

```bash
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.