Skip to main content

​
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]
# Prompt for undefined settings
prompt = false

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

# Desktop packages
orbital = {}

# Applications
nano = {}
Each package can have options:
[packages]
gcc = { build_stage = 1 }
mesa = { skip = true }

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

Always include base.toml or another complete configuration as your starting point.
Only specify packages and files that differ from your base configuration.
When creating custom configs, add packages gradually and test each addition.
Add comments to your configuration files explaining custom settings.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us