# Redox OS Build System

Redox OS is an open-source operating system written in Rust, featuring a microkernel architecture with a focus on safety, efficiency, performance, reliability, and security. The build system provides comprehensive tools for compiling the entire operating system, including the kernel, C library (relibc), display server (Orbital), and hundreds of packages and applications from source code.

This repository serves as the central build system that orchestrates compilation of all Redox components. It uses a recipe-based cookbook system to manage packages, supports multiple CPU architectures (x86_64, aarch64, i586, riscv64gc), and provides containerized builds via Podman for reproducibility. The build system handles cross-compilation toolchains, system image creation, and emulator integration for testing.

## Quick Setup with Bootstrap Script

Downloads and sets up the complete Redox OS build environment using the bootstrap script.

```bash
# Download the bootstrap script
curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh

# Run the bootstrap (installs dependencies, clones repo, sets up Podman)
time bash -e podman_bootstrap.sh

# Change to the redox directory
cd redox

# Build the entire Redox OS image (uses Podman by default)
make all

# Expected output: Creates build/x86_64/desktop/harddrive.img
```

## Build the Full System Image

Compiles all packages and creates a bootable hard drive image.

```bash
# Build the default desktop configuration for x86_64
make all

# Build with SELinux disabled (for systems without SELinux)
make all USE_SELINUX=0

# Build a minimal server configuration
make all CONFIG_NAME=server

# Build for a different architecture
make all ARCH=aarch64

# Expected output:
# - build/x86_64/desktop/harddrive.img (or specified arch/config)
# - build/x86_64/desktop/repo.tag (marks successful repo build)
```

## Run Redox in QEMU Emulator

Launches the built Redox OS image in QEMU for testing.

```bash
# Run with default settings (KVM enabled if available)
make qemu

# Run without KVM (slower but works on all systems)
make qemu kvm=no

# Run without graphics (serial console only)
make qemu gpu=no

# Run with network port forwarding for SSH access
make qemu net=redir
# SSH available on host port 8022: ssh -p 8022 user@localhost

# Run with VirtIO GPU and OpenGL acceleration
make qemu gpu=virtio-gl

# Run with custom memory and CPU settings
make qemu QEMU_MEM=4096 QEMU_SMP=8

# Run a live ISO image instead of hard drive
make live
make qemu live=yes
```

## Build Individual Recipes

Compiles specific packages using the recipe system with make targets.

```bash
# Build a single recipe (e.g., the Ion shell)
make r.ion

# Build multiple recipes at once (comma-separated)
make r.ion,bash,nano

# Clean and rebuild a recipe
make cr.ion

# Unfetch (remove source), clean, and rebuild
make ucr.ion

# Fetch source code for a recipe without building
make f.ion

# Clean build artifacts for a recipe
make c.ion

# Find which recipe provides a package
make find.ion
# Output: recipes/core/ion

# Show the build dependency tree for a recipe
make rt.ion
```

## Push Packages to Running Image

Updates packages in an existing disk image without full rebuild.

```bash
# Build and push a single package to the mounted filesystem
make rp.ion

# Push an already-built package
make p.ion

# Push multiple packages
make p.ion,bash,nano

# Push with all package dependencies
make pp.ion

# Show what would be pushed (dry run)
make pt.ion

# Clean, rebuild, and push in one step
make crp.ion
```

## Mount and Unmount Filesystem Image

Access the Redox filesystem for manual inspection or modification.

```bash
# Mount the hard drive image
make mount
# Filesystem available at: build/x86_64/desktop/filesystem/

# Mount the live ISO image
make mount_live

# Mount the extra disk image
make mount_extra

# Unmount when done
make unmount

# Manual access example
make mount
ls build/x86_64/desktop/filesystem/
# bin  dev  etc  home  lib  root  tmp  usr  var
make unmount
```

## Build for Different Architectures

Cross-compile Redox OS for different CPU architectures using the build.sh script.

```bash
# Using build.sh helper script
./build.sh -X all          # x86_64 (default)
./build.sh -A all          # aarch64 (ARM 64-bit)
./build.sh -5 all          # i586 (32-bit x86)
./build.sh -R all          # riscv64gc (RISC-V)

# Using make directly with ARCH variable
make all ARCH=aarch64
make all ARCH=i586
make all ARCH=riscv64gc

# Build and run in QEMU for ARM
make all ARCH=aarch64
make qemu ARCH=aarch64

# Build for Raspberry Pi 3B+
make all ARCH=aarch64 BOARD=raspi3bp CONFIG_NAME=minimal
make qemu ARCH=aarch64 BOARD=raspi3bp
```

## Configuration Files

Customize the build using filesystem configuration files that define which packages to include.

```toml
# config/desktop.toml - Example desktop configuration
include = ["desktop-minimal.toml", "server.toml"]

[general]
filesystem_size = 650  # Size in MiB

[packages]
cosmic-edit = {}
cosmic-files = {}
cosmic-term = {}
dejavu = {}
netsurf = {}
rustpython = {}
# Ignore a package from included configs
orbterm = "ignore"
```

```toml
# config/server.toml - Example server configuration
include = ["base.toml"]

[general]
filesystem_size = 256

[packages]
openssh = {}
git = {}
```

## Recipe Configuration

Define build instructions for packages using the recipe.toml format.

```toml
# recipes/core/ion/recipe.toml - Example Rust package
[source]
git = "https://gitlab.redox-os.org/redox-os/ion.git"

[build]
template = "cargo"
```

```toml
# recipes/core/kernel/recipe.toml - Custom build script example
[source]
git = "https://gitlab.redox-os.org/redox-os/kernel.git"

[build]
template = "custom"
script = """
make -f ${COOKBOOK_SOURCE}/Makefile
mkdir -v "${COOKBOOK_STAGE}/boot"
cp -v kernel "${COOKBOOK_STAGE}/boot"
"""
```

```toml
# recipes/tools/nano/recipe.toml - Example autotools package
[source]
tar = "https://www.nano-editor.org/dist/v7/nano-7.2.tar.xz"

[build]
template = "configure"
configure_args = ["--enable-utf8"]
```

## Podman Container Build

Use containerized builds for reproducibility and isolation.

```bash
# Build using Podman (default, PODMAN_BUILD=1)
make all

# Rebuild the container if needed
make container_clean
make all

# Enter the container shell for debugging
make container_shell

# Disable Podman and build natively
make all PODMAN_BUILD=0

# Touch container tag to skip rebuild (if image exists)
make container_touch

# Kill a stuck container
make container_kill
```

## Debug with GDB

Debug the kernel or userspace applications using GDB integration.

```bash
# Start QEMU with GDB server (blocks until debugger connects)
make qemu gdb=yes

# In another terminal, connect with GDB
make gdb
# Opens rust-gdb connected to localhost:1234

# Start QEMU with GDB server (non-blocking)
make qemu gdb=nonblock

# Debug a specific recipe binary (experimental)
REPO_DEBUG=1 make cr.drivers-initfs rebuild
make debug.drivers-initfs DEBUG_BIN=pcid
# Opens gdbgui on http://localhost:5000
```

## Environment Variables Reference

Key environment variables for customizing the build process.

```bash
# Architecture and configuration
export ARCH=x86_64           # Target architecture
export CONFIG_NAME=desktop   # Configuration name
export FILESYSTEM_CONFIG=config/x86_64/desktop.toml

# Build options
export PODMAN_BUILD=1        # Use Podman container (default)
export PREFIX_BINARY=1       # Use prebuilt toolchain (faster)
export REPO_BINARY=0         # Use prebuilt packages
export REPO_NONSTOP=1        # Continue building on errors
export REPO_OFFLINE=1        # Build without network
export REPO_DEBUG=1          # Keep debug symbols

# Apply and run
make all
make qemu

# View current environment
make setenv
# Output:
# export ARCH='x86_64'
# export CONFIG_NAME='desktop'
# BUILD='build/x86_64/desktop'
```

## Clean Build Artifacts

Remove build artifacts at various levels.

```bash
# Clean everything (build directory, prefix, repo)
make clean

# Clean and remove downloaded sources
make distclean

# Clean specific recipe
make c.ion

# Clean recipe and remove source
make uc.ion

# Clean relibc and sysroot (requires rebuild of many packages)
make c.relibc

# Clean all statically linked recipes
make static_clean

# Remove cross-compiler prefix
make prefix_clean

# Pull latest changes and mark for rebuild
make pull
```

## Create Live ISO Image

Build a bootable live ISO image for installation or testing.

```bash
# Build the live ISO image
make live
# Output: build/x86_64/desktop/redox-live.iso

# Create live ISO and write to USB with Popsicle
make popsicle

# Force rebuild of the hard drive image
make image

# Force full rebuild of repo and image
make rebuild

# Test live image in QEMU
make qemu live=yes disk=cdrom
```

## Network Configuration in QEMU

Configure network options for testing in the emulator.

```bash
# Default user-mode networking with packet capture
make qemu
# Captures to: build/x86_64/desktop/network.pcap

# Port forwarding for SSH and HTTP
make qemu net=redir
# Ports: 8022->22 (SSH), 8080->80 (HTTP), 8081-8083, 64126 (GDB)

# Bridged networking (requires bridge setup)
make qemu bridge=br0

# Different network adapters
make qemu net=virtio    # VirtIO (fastest)
make qemu net=rtl8139   # Realtek RTL8139
make qemu net=e1000     # Intel E1000 (default)

# Disable networking
make qemu net=no

# Network boot with iPXE
make qemu netboot=yes

# Analyze network traffic
make wireshark
```

## Cross-Compiler Toolchain

Build or download the cross-compilation toolchain.

```bash
# Download prebuilt toolchain (default, faster)
make prefix PREFIX_BINARY=1

# Build toolchain from source (slower, for development)
make prefix PREFIX_BINARY=0

# Components built/downloaded:
# - GCC cross-compiler
# - Rust compiler with Redox target
# - Clang/LLVM with Redox support
# - relibc (C library)
# - binutils, libtool

# Toolchain location
ls prefix/x86_64-unknown-redox/sysroot/bin/
# x86_64-unknown-redox-gcc, rustc, cargo, clang, etc.

# Enter environment with toolchain in PATH
make env
# Now in bash with cross-compilers available
```

The Redox OS build system provides a comprehensive solution for building an entire operating system from source. The primary use case is for developers who want to contribute to Redox OS development, port applications, or customize the operating system for specific hardware. The recipe-based cookbook system makes it straightforward to add new packages, while the Makefile targets provide convenient shortcuts for common operations like building, cleaning, and testing.

Integration with development workflows is facilitated through the modular design - developers can work on individual recipes without rebuilding the entire system, push changes to a running image for rapid testing, and use the GDB integration for debugging both kernel and userspace code. The support for Podman containers ensures builds are reproducible across different host systems, while native builds remain an option for those who prefer direct system access. The multi-architecture support enables testing on x86_64, ARM, and RISC-V platforms using QEMU emulation.