Build System Overview

Comprehensive overview of the Redox OS build system architecture and components

Introduction

The Redox OS build system is a sophisticated modular build infrastructure that supports multiple build methods, architectures, and configurations. It orchestrates the compilation of the kernel, userspace applications, and system images through a combination of Makefiles, shell scripts, and Rust-based tools.

Build System Architecture

The build system is organized into several key components:

Core Components

Makefile System

Modular Makefiles in the mk/ directory handle different aspects of the build process

Recipe System

Cookbook-based package management for building and installing software packages

Configuration

TOML-based configuration files defining system variants and package sets

Bootstrap Scripts

Automated setup scripts for both Podman and native build environments

Makefile Structure

The build system consists of multiple specialized Makefiles:

mk/
├── config.mk        # Build system configuration and environment variables
├── podman.mk        # Podman container build configuration
├── prefix.mk        # Cross-compiler toolchain recipes
├── repo.mk          # Recipe/package management commands
├── disk.mk          # Disk image creation and mounting
├── qemu.mk          # QEMU emulation configuration
├── virtualbox.mk    # VirtualBox configuration
├── fstools.mk       # Filesystem tools compilation
├── depends.mk       # Build dependencies
└── ci.mk            # Continuous integration targets

Build Methods

Podman Build (Recommended)

The Podman build method uses containerization to provide a consistent, isolated build environment:

1. Container Setup

   Creates a Podman container with all build dependencies pre-installed

2. Isolated Environment

   Ensures reproducible builds across different host systems

3. Automatic Configuration

   Configures PODMAN_BUILD=1 in .config file

Advantages:

• Consistent build environment across all platforms
• No host system pollution
• Easy to reproduce builds
• Faster setup on systems with package manager support

Native Build

The native build method compiles directly on the host system:

1. Dependency Installation

   Installs toolchain and dependencies on the host system

2. Direct Compilation

   Builds components using host-installed tools

3. Manual Configuration

   Requires manual management of build dependencies

Advantages:

• Direct access to build artifacts
• Faster iteration during development
• Better IDE integration
• Lower memory overhead

Build Targets

Primary Targets

all (default)

Builds the complete hard drive image at build/$(ARCH)/$(CONFIG_NAME)/harddrive.img

make all

live

Creates a bootable live ISO image

make live

image

Rebuilds the hard drive image from scratch (unmounts first)

make image

rebuild

Cleans repo tag and rebuilds everything

make rebuild

Package Management Targets

The build system provides shorthand commands for working with recipes:

Target Pattern	Description	Example
r.PACKAGE	Cook (build) a package	make r.orbital
c.PACKAGE	Clean a package	make c.kernel
f.PACKAGE	Fetch package sources	make f.gcc
p.PACKAGE	Push package to image	make p.shell
cr.PACKAGE	Clean and rebuild	make cr.relibc
rp.PACKAGE	Build and push	make rp.nano

You can operate on multiple packages by separating them with commas: make r.gcc,binutils,newlib

Emulation Targets

# Run with QEMU (various options)
make qemu           # Default QEMU settings
make qemu kvm=yes   # Enable KVM acceleration
make qemu gpu=virtio # Use VirtIO GPU

# Run with VirtualBox
make virtualbox

Build Artifacts

The build system generates artifacts in the build/ directory:

build/
├── $(ARCH)/
│   └── $(CONFIG_NAME)/
│       ├── harddrive.img      # Main disk image
│       ├── redox-live.iso     # Live bootable ISO
│       ├── filesystem/        # Mounted filesystem
│       ├── repo.tag           # Package build completion marker
│       └── bootloader-live.efi # UEFI bootloader
├── fstools/
│   └── bin/
│       ├── redoxfs            # Redox filesystem driver
│       ├── redoxfs-mkfs      # Filesystem creation tool
│       └── redox_installer   # System installer
├── container.tag              # Podman container marker (if using Podman)
└── podman/                    # Podman home directory

Configuration Variables

Key environment variables that control the build:

ARCH · string · default: "x86_64"

Target architecture: x86_64, aarch64, i586, or riscv64gc

CONFIG_NAME · string · default: "desktop"

Configuration profile: desktop, server, minimal, etc.

PODMAN_BUILD · integer · default: "1"

Enable (1) or disable (0) Podman-based builds

PREFIX_BINARY · integer · default: "1"

Use pre-built toolchain binaries (much faster)

REPO_BINARY · integer · default: "0"

Use pre-built package binaries instead of compiling from source

REPO_DEBUG · integer · default: "0"

Enable debug symbols and disable stripping

Build Workflow

A typical build follows this workflow:

1. Environment Setup

   The build system checks for Podman or native dependencies and sets up the build environment

2. Toolchain Build

   If needed, builds or downloads the cross-compilation toolchain for the target architecture

3. Recipe Compilation

   Processes all recipes defined in the configuration file, building packages in dependency order

4. Filesystem Creation

   Creates a RedoxFS filesystem image and populates it with compiled packages

5. Bootloader Installation

   Installs the bootloader and creates the final bootable disk image

Next Steps

Podman Build

Set up a containerized build environment

Native Build

Build directly on your host system

Configuration

Customize your build settings

Recipes

Learn about the recipe system