Skip to main content

​
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

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

Builds the complete hard drive image at build/$(ARCH)/$(CONFIG_NAME)/harddrive.img
make all
Creates a bootable live ISO image
make live
Rebuilds the hard drive image from scratch (unmounts first)
make image
Cleans repo tag and rebuilds everything
make rebuild

​
Package Management Targets

The build system provides shorthand commands for working with recipes:
Target PatternDescriptionExample
r.PACKAGECook (build) a packagemake r.orbital
c.PACKAGEClean a packagemake c.kernel
f.PACKAGEFetch package sourcesmake f.gcc
p.PACKAGEPush package to imagemake p.shell
cr.PACKAGEClean and rebuildmake cr.relibc
rp.PACKAGEBuild and pushmake 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

Build docs developers (and LLMs) love

Get started for freeTalk to us