Build Configuration

Complete guide to configuring the Redox OS build system

Overview

The Redox OS build system is highly configurable through TOML configuration files and environment variables. This guide covers all configuration options and how to customize your build.

Configuration Methods

There are three ways to configure the build system:

.config File

Set build-time variables and options

TOML Configs

Define system packages and files

Environment

Override settings at runtime

The .config File

The .config file in the repository root controls build system behavior.

Basic Configuration

Create .config in the repository root:

.config

# Build method: 1 for Podman, 0 for native
PODMAN_BUILD?=1

# Target architecture: x86_64, aarch64, i586, riscv64gc
ARCH?=x86_64

# Configuration profile: desktop, server, minimal, dev, etc.
CONFIG_NAME?=desktop

Build Optimization

.config

# Use pre-built toolchain (much faster, highly recommended)
PREFIX_BINARY?=1

# Use pre-built packages instead of compiling (fastest option)
REPO_BINARY?=1

# Enable sccache for faster Rust compilation
SCCACHE_BUILD?=1

For first-time builds, use PREFIX_BINARY=1 and REPO_BINARY=1 to reduce build time from hours to minutes.

Debug Options

.config

# Enable debug symbols and disable stripping
REPO_DEBUG?=1

# Continue building even if some packages fail
REPO_NONSTOP?=1

# Build without fetching sources (offline mode)
REPO_OFFLINE?=1

# Build appstream metadata for packages
REPO_APPSTREAM?=1

Filesystem Configuration

.config

# Override filesystem size in MB (default: auto-calculated)
FILESYSTEM_SIZE?=1024

# Flags for redoxfs-mkfs (e.g., --encrypt for encryption)
REDOXFS_MKFS_FLAGS?=

Podman-Specific Options

.config

# Image tag for the Podman container
IMAGE_TAG?=redox-base

# Enable SELinux volume flags (for Fedora/RHEL)
USE_SELINUX?=1

# Run filesystem tools inside Podman
FSTOOLS_IN_PODMAN?=1

# Custom containerfile path
CONTAINERFILE?=podman/redox-base-containerfile

# Enable layer cache push/pull
PODMAN_CACHE_PUSH?=0
PODMAN_CACHE_PULL?=1

Advanced Options

.config

# Use upstream Rust compiler instead of Redox fork (experimental)
PREFIX_USE_UPSTREAM_RUST_COMPILER?=0

# Board/device type for ARM builds (e.g., raspi3bp)
BOARD?=

# Disable FUSE mounting (for container environments)
FSTOOLS_NO_MOUNT?=0

TOML Configuration Files

Configuration File Location

Configuration files are stored in the config/ directory:

config/
├── base.toml              # Base configuration (included by others)
├── desktop.toml           # Desktop configuration
├── server.toml            # Server configuration
├── minimal.toml           # Minimal configuration
├── dev.toml               # Development configuration
├── x11.toml               # X11 desktop environment
├── wayland.toml           # Wayland desktop environment
├── acid.toml              # ACID test configuration
├── auto-test.toml         # Automated testing
└── $(ARCH)/
    └── $(CONFIG_NAME).toml  # Architecture-specific configs

TOML File Structure

Configuration files use TOML format with these main sections:

[general] - General Settings

[general]
# Prompt for undefined settings
prompt = false

[packages] - Package Selection

[packages]
# Core system packages
kernel = {}
relibc = {}

# Desktop packages
orbital = {}

# Applications
nano = {}

Each package can have options:

[packages]
gcc = { build_stage = 1 }
mesa = { skip = true }

[[files]] - File Definitions

# Regular file with content
[[files]]
path = "/etc/hostname"
data = "redox"

# Directory
[[files]]
path = "/usr/bin"
data = ""
directory = true
mode = 0o755

# Symlink
[[files]]
path = "/bin"
data = "usr/bin"
symlink = true

[users] - User Configuration

[users.root]
password = "password"
uid = 0
gid = 0
shell = "/usr/bin/ion"

[users.user]
password = ""
shell = "/usr/bin/ion"

[groups] - Group Configuration

[groups.sudo]
gid = 1
members = ["user"]

Example: base.toml

Let’s examine the base configuration that all others include:

config/base.toml

# Base configuration included by other configurations

[general]
prompt = false

[packages]
base = {}
base-initfs = {}
bootloader = {}
kernel = {}
libgcc = {}
libstdcxx = {}
netdb = {}
netutils = {}
relibc = {}
userutils = {}
uutils = {}

# Init script for base system
[[files]]
path = "/usr/lib/init.d/00_base"
data = """
# clear and recreate tmpdir with 0o1777 permission
rm -rf /tmp
mkdir -m a=rwxt /tmp

notify ipcd
notify ptyd
nowait sudo --daemon
"""

# Network configuration
[[files]]
path = "/etc/net/ip"
data = "10.0.2.15"

[[files]]
path = "/etc/net/ip_router"
data = "10.0.2.2"

[[files]]
path = "/etc/net/ip_subnet"
data = "255.255.255.0"

[[files]]
path = "/etc/net/dns"
data = "9.9.9.9"

# Users
[users.root]
password = "password"
uid = 0
gid = 0
shell = "/usr/bin/ion"

[users.user]
password = ""
shell = "/usr/bin/ion"

[groups.sudo]
gid = 1
members = ["user"]

Example: desktop.toml

A simple desktop configuration:

config/desktop.toml

# Include base configuration
include = "base.toml"

[packages]
# Desktop environment
orbital = {}

# Applications
file-manager = {}
viewer = {}
terminal = {}
editor = {}

# Graphics
mesa = {}
mesa-demos = {}

# Fonts
fonts-fira = {}

Example: minimal.toml

config/minimal.toml

include = "base.toml"

[packages]
# Only core packages from base.toml
# No additional packages

[[files]]
path = "/etc/motd"
data = "Welcome to Redox OS (minimal configuration)\n"

Creating Custom Configurations

Step-by-Step Guide

1. Create Configuration File

   Create a new TOML file in the config/ directory:

   touch config/mycustom.toml
   
2. Include Base Configuration

   Start by including the base configuration:

   config/mycustom.toml

   include = "base.toml"
   
   [general]
   prompt = false
   
3. Add Packages

   Define packages to include:

   [packages]
   # Add your desired packages
   nano = {}
   bash = {}
   git = {}
   
4. Configure Files

   Add custom files or configuration:

   [[files]]
   path = "/etc/motd"
   data = "Welcome to My Custom Redox\n"
   
5. Build with Custom Config

   Use your configuration:

   echo 'CONFIG_NAME=mycustom' >> .config
   make all
   

Custom Package Configuration

Packages can have additional options:

[packages]
# Simple package inclusion
nano = {}

# Package with build stage (for dependencies)
gcc = { build_stage = 1 }

# Skip package (useful when inheriting configs)
mesa = { skip = true }

# Package with custom environment
python = { env = { PYTHON_VERSION = "3.11" } }

Architecture-Specific Configuration

You can create architecture-specific configurations:

config/
├── x86_64/
│   ├── desktop.toml
│   └── server.toml
├── aarch64/
│   ├── desktop.toml
│   └── raspi/
│       └── desktop.toml
└── riscv64gc/
    └── minimal.toml

The build system automatically selects the most specific configuration:

1. config/$(ARCH)/$(BOARD)/$(CONFIG_NAME).toml
2. config/$(ARCH)/$(CONFIG_NAME).toml
3. config/$(CONFIG_NAME).toml

Environment Variables

You can override configuration at build time:

# Override architecture
make all ARCH=aarch64

# Override configuration
make all CONFIG_NAME=server

# Multiple overrides
make all ARCH=x86_64 CONFIG_NAME=minimal REPO_BINARY=1

# Override filesystem size
make all FILESYSTEM_SIZE=2048

Common Configuration Scenarios

Fast Build for Testing

.config

PODMAN_BUILD?=1
CONFIG_NAME?=minimal
REPO_BINARY?=1
PREFIX_BINARY?=1

Development Build

.config

PODMAN_BUILD?=0
CONFIG_NAME?=dev
REPO_DEBUG?=1
REPO_BINARY?=1

Full Desktop from Source

.config

PODMAN_BUILD?=1
CONFIG_NAME?=desktop
REPO_BINARY?=0
PREFIX_BINARY?=1

CI/CD Build

.config

PODMAN_BUILD?=1
REPO_NONSTOP?=1
REPO_BINARY?=1
CI?=1

Encrypted Filesystem

.config

REDOXFS_MKFS_FLAGS?=--encrypt

Configuration Reference

Build System Variables

ARCH · string · default: "x86_64"

Target architecture: x86_64, aarch64, i586, or riscv64gc

BOARD · string · default: ""

Board/device type for ARM (e.g., raspi3bp)

CONFIG_NAME · string · default: "desktop"

Configuration profile name

FILESYSTEM_CONFIG · string · default: "auto"

Path to TOML configuration file (auto-detected)

FILESYSTEM_SIZE · integer · default: "auto"

Filesystem size in MB (calculated from config if not set)

PODMAN_BUILD · integer · default: "1"

Use Podman for building (1=yes, 0=no)

PREFIX_BINARY · integer · default: "1"

Use pre-built toolchain binaries

REPO_BINARY · integer · default: "0"

Use pre-built package binaries

REPO_DEBUG · integer · default: "0"

Enable debug builds (keep symbols, no stripping)

REPO_NONSTOP · integer · default: "0"

Continue building even if packages fail

REPO_OFFLINE · integer · default: "0"

Do not fetch sources (offline mode)

REPO_APPSTREAM · integer · default: "0"

Build appstream metadata

SCCACHE_BUILD · integer · default: "auto"

Enable sccache for Rust builds (auto-enabled in containers)

QEMU Variables

kvm · string · default: "auto"

Enable KVM acceleration (yes, no, or auto)

gpu · string · default: "vga"

GPU type: vga, virtio, ramfb, none

audio · string · default: "auto"

Audio device: ac97, hda, no

disk · string · default: "auto"

Disk interface: ata, nvme, sdcard

QEMU_MEM · integer · default: "2048"

QEMU memory size in MB

QEMU_SMP · integer · default: "4"

Number of CPU cores for QEMU

Best Practices

Use Base Configuration

Always include base.toml or another complete configuration as your starting point.

Keep Configs Minimal

Only specify packages and files that differ from your base configuration.

Test Incrementally

When creating custom configs, add packages gradually and test each addition.

Document Changes

Add comments to your configuration files explaining custom settings.

Version Control

Keep your .config and custom TOML files in version control (but not in the main Redox repo).

Next Steps

Recipe System

Learn how packages are built

Podman Build

Set up Podman build environment