Configuration Options Reference

Overview

The Redox OS build system is highly configurable through environment variables, Make variables, and TOML configuration files. This reference documents all available configuration options.

Build Configuration Variables

These variables are set in .config, mk/config.mk, or via environment variables.

Architecture Configuration

ARCH

Target architecture for Redox OS.

make ARCH=x86_64

ARCH

string

default:"$(HOST_ARCH)"

Target architecture: x86_64, i586, aarch64, or riscv64gc

Defaults to the host architecture. Set to i586 instead of i686 for 32-bit x86.

BOARD

Sub-device type for architecture-specific boards.

make ARCH=aarch64 BOARD=raspi3bp

BOARD

string

default:""

Board identifier (e.g., raspi3bp for Raspberry Pi 3 B+)

Currently used only for aarch64 boards.

CONFIG_NAME

Filesystem configuration profile name.

make CONFIG_NAME=desktop

CONFIG_NAME

string

default:"desktop"

Configuration profile: desktop, server, demo, minimal, etc.

Matches TOML files in config/ directory.

FILESYSTEM_CONFIG

Path to the filesystem configuration file.

make FILESYSTEM_CONFIG=config/custom.toml

FILESYSTEM_CONFIG

path

default:"auto"

Path to filesystem TOML configuration. Auto-detected from ARCH, BOARD, and CONFIG_NAME.

Default resolution order:

config/$(ARCH)/$(BOARD)/$(CONFIG_NAME).toml
config/$(ARCH)/$(CONFIG_NAME).toml
config/$(CONFIG_NAME).toml

Toolchain Configuration

PREFIX_BINARY

Use prebuilt cross-compiler toolchain.

make PREFIX_BINARY=1

PREFIX_BINARY

0|1

default:"1"

Download and use binary toolchain packages instead of building from source

Binary toolchains are much faster to set up. Set to 0 to build the toolchain from source.

PREFIX_USE_UPSTREAM_RUST_COMPILER

Use official Rust nightly compiler.

make PREFIX_USE_UPSTREAM_RUST_COMPILER=1

PREFIX_USE_UPSTREAM_RUST_COMPILER

0|1

default:"0"

Use upstream Rust nightly instead of Redox-patched version. Experimental.

Only available for Tier 2 targets. May require -Zbuild-std for Tier 3 targets.

Repository Configuration

REPO_BINARY

Use binary packages instead of building from source.

make REPO_BINARY=1

REPO_BINARY

0|1

default:"0"

Download and install binary packages instead of compiling recipes

Sets COOKBOOK_HOST_SYSROOT and passes --repo-binary to repo tool.

REPO_APPSTREAM

Build AppStream metadata.

make REPO_APPSTREAM=1

REPO_APPSTREAM

0|1

default:"0"

Generate AppStream metadata for package repositories

Sets COOKBOOK_APPSTREAM=true.

REPO_NONSTOP

Continue building after failures.

make REPO_NONSTOP=1

REPO_NONSTOP

0|1

default:"0"

Keep building remaining packages even if some fail

Sets COOKBOOK_NONSTOP=true. Useful for CI builds.

REPO_OFFLINE

Build without network access.

make REPO_OFFLINE=1

REPO_OFFLINE

0|1

default:"0"

Prevent internet access during builds. Requires pre-fetched sources.

Sets COOKBOOK_OFFLINE=true. Run make cargo-fetch first.

REPO_DEBUG

Enable debug builds.

make REPO_DEBUG=1

REPO_DEBUG

0|1

default:"0"

Build with debug symbols and disable stripping

Sets COOKBOOK_NOSTRIP=true and COOKBOOK_DEBUG=true.

Filesystem Configuration

FILESYSTEM_SIZE

Size of the filesystem image in megabytes.

make FILESYSTEM_SIZE=1024

FILESYSTEM_SIZE

number

default:"from config"

Filesystem size in MB. Defaults to value from FILESYSTEM_CONFIG.

REDOXFS_MKFS_FLAGS

Flags passed to redoxfs-mkfs.

make REDOXFS_MKFS_FLAGS="--encrypt"

REDOXFS_MKFS_FLAGS

string

default:""

Additional flags for filesystem creation. Use --encrypt for encryption.

Container Configuration

PODMAN_BUILD

Build inside Podman container.

make PODMAN_BUILD=1

PODMAN_BUILD

0|1

default:"1"

Execute builds inside Podman container for reproducibility

Set to 0 to build directly on the host system. Required for native Redox builds.

FSTOOLS_IN_PODMAN

Build filesystem tools in container.

make FSTOOLS_IN_PODMAN=1

FSTOOLS_IN_PODMAN

0|1

default:"0"

Build redoxfs and installer tools inside Podman instead of on host

FSTOOLS_NO_MOUNT

Disable FUSE mounting.

make FSTOOLS_NO_MOUNT=1

FSTOOLS_NO_MOUNT

0|1

default:"0"

Build without FUSE support. Required when FUSE is unavailable (e.g., in containers).

SCCACHE_BUILD

Enable sccache for Cargo builds.

make SCCACHE_BUILD=1

SCCACHE_BUILD

0|1

default:"auto"

Use sccache to speed up Cargo compilation. Auto-enabled inside Podman.

CONTAINERFILE

Path to Containerfile for base image.

make CONTAINERFILE=podman/custom-containerfile

CONTAINERFILE

path

default:"podman/redox-base-containerfile"

Containerfile used to build the Podman base image

Derived Variables

These are automatically computed and should not normally be set manually:

Computed Build Variables

TARGET: Full target triple (e.g., x86_64-unknown-redox)
BUILD: Build directory path (build/$(ARCH)/$(CONFIG_NAME))
PREFIX: Toolchain prefix directory
MOUNT_DIR: Filesystem mount point
INSTALLER: Path to redox_installer binary
REDOXFS: Path to redoxfs binary
REPO_BIN: Path to repo tool binary

Filesystem Configuration Files

Filesystem configurations are TOML files in the config/ directory that specify which packages to include in images.

Location

config/
├── desktop.toml           # Cross-platform configs
├── server.toml
├── minimal.toml
├── x86_64/
│   ├── desktop.toml       # Architecture-specific
│   └── demo.toml
├── aarch64/
│   ├── raspi3bp/
│   │   └── minimal.toml   # Board-specific
│   └── demo.toml
└── riscv64gc/
    └── demo.toml

Structure

# Include other configuration files
include = ["base.toml", "server.toml"]

# General settings
[general]
filesystem_size = 650  # Size in MB
repo_binary = false    # Use binary packages

# Package configuration
[packages]
coreutils = {}         # Include with default settings
bash = {}              # Include package
gcc = "source"         # Force build from source
llvm = "binary"        # Force use binary package
debug-tools = "ignore" # Don't include
kernel = "local"       # Build from local source

General Section

filesystem_size

general.filesystem_size

number

required

Size of the filesystem in megabytes

[general]
filesystem_size = 1024

repo_binary

general.repo_binary

boolean

default:"false"

Whether to use binary packages by default

[general]
repo_binary = true

Packages Section

Specifies which packages to include and how to build them.

Package Rules

packages.*

object | string

Package configuration. Can be {}, "source", "binary", "local", or "ignore"

[packages]
# Include with defaults
coreutils = {}

# Build from source (even if repo_binary=true)
gcc = "source"

# Use binary package (even if repo_binary=false)
rust = "binary"

# Build from local source, ignore remote changes
kernel = "local"

# Don't include this package
old-editor = "ignore"

Build Modes

source

Build the package from source code. Downloads sources and compiles them.

[packages]
gcc = "source"

binary

Download and install pre-built binary package from the repository.

[packages]
rust = "binary"

local

Build from local source without updating from remote. Useful for development.

[packages]
my-driver = "local"

ignore

Skip this package entirely. Used to exclude packages from included configs.

include = ["desktop.toml"]

[packages]
# Override package from desktop.toml
games = "ignore"

Include Directive

Load packages from other configuration files.

include = ["base.toml", "wayland.toml"]

[general]
filesystem_size = 800

[packages]
# Add more packages or override included ones
cosmic-term = {}
orbterm = "ignore"  # Override from base.toml

Later includes and local definitions override earlier ones. Package rules are merged.

Example Configurations

Minimal Desktop

include = ["base.toml"]

[general]
filesystem_size = 350

[packages]
orbital = {}
orbterm = {}
orbtk = {}
orbutils = {}

Full Desktop

include = ["desktop-minimal.toml", "server.toml"]

[general]
filesystem_size = 650

[packages]
cosmic-edit = {}
cosmic-files = {}
cosmic-term = {}
netsurf = {}
games = {}

Server Configuration

include = ["base.toml"]

[general]
filesystem_size = 400

[packages]
sshd = {}
httpd = {}
iptables = {}
orbital = "ignore"  # No GUI on servers

Development Configuration

include = ["desktop.toml"]

[general]
filesystem_size = 1200

[packages]
gcc = {}
rust = {}
llvm = {}
git = {}
make = {}
kernel = "local"  # Build from working directory

QEMU Configuration Variables

These variables control QEMU emulation behavior.

Hardware Emulation

kvm

yes|no

default:"auto"

Enable KVM/HVF hardware acceleration

make qemu kvm=yes
make qemu kvm=no

Auto-enabled when host and guest architectures match.

gpu

default:"vga"

Graphics adapter type

make qemu gpu=virtio
make qemu gpu=no  # Headless

vga: Standard VGA adapter (x86 only)
virtio: VirtIO GPU (better performance)
virtio-gl: VirtIO GPU with OpenGL acceleration
ramfb: RAM framebuffer (ARM/RISC-V)
multi: Multiple displays
no: No graphics (serial only)

audio

hda|ac97|no

default:"hda"

Audio device type

make qemu audio=ac97
make qemu audio=no

hda: Intel High Definition Audio
ac97: AC’97 audio (i586 default)
no: No audio

net

e1000|rtl8139|virtio|usb-net|redir|bridge|no

default:"e1000"

Network adapter type

make qemu net=virtio
make qemu net=redir  # With port forwarding
make qemu net=no

e1000: Intel E1000 (default, best compatibility)
rtl8139: Realtek RTL8139
virtio: VirtIO network (better performance)
usb-net: USB network adapter
redir: E1000 with port forwarding
bridge: Bridge to host network
no: No network

disk

default:"nvme"

Disk controller type

make qemu disk=ata
make qemu disk=nvme

nvme: NVMe controller (default, fastest)
ata: ATA/AHCI controller
usb: USB storage
virtio: VirtIO block device
sdcard: SD card (ARM boards)
cdrom: Boot from ISO as CD-ROM

System Configuration

QEMU_SMP

number

default:"arch-specific"

Number of CPU cores

make qemu QEMU_SMP=8

Defaults: x86_64=4, i586=1, aarch64=1, riscv64gc=4

QEMU_MEM

number

default:"arch-specific"

Memory size in megabytes

make qemu QEMU_MEM=4096

Defaults: x86_64=2048, i586=1024, others=2048

serial

yes|no

default:"yes"

Enable serial console

make qemu serial=no

gdb

yes|no|nonblock

default:"no"

GDB debugging support

make qemu gdb=yes  # Wait for GDB
make qemu gdb=nonblock  # Don't wait

Starts GDB server on port 1234.

live

yes|no

default:"no"

Boot from live ISO

make qemu live=yes

uefi

yes|no

default:"yes"

Use UEFI boot (x86_64/aarch64)

make qemu uefi=no  # Legacy BIOS on x86_64

iommu

yes|no

default:"no"

Enable IOMMU

make qemu iommu=yes

usb

yes|no

default:"yes"

Enable USB controllers

make qemu usb=no

Advanced Options

qemu_serial_logfile

path

Log serial output to file

make qemu qemu_serial_logfile=serial.log

bridge

string

Bridge network adapter to host bridge

make qemu bridge=br0

netboot

yes|no

default:"no"

Enable network boot

make qemu netboot=yes

redoxer

yes|no

default:"no"

Enable Redoxer exit codes

make qemu redoxer=yes

Exit code 51 = success, 53 = failure.

Per-Host Variables

These are automatically detected based on the host OS:

macOS

FUMOUNT=umount
SED=gsed
FIND=gfind
VB_AUDIO=coreaudio

FreeBSD

FIND=gfind
FUMOUNT=sudo umount
VB_AUDIO=pulse

Linux

FUMOUNT=fusermount3 -u (or fusermount -u)
VB_AUDIO=pulse

Redox

PODMAN_BUILD=0
HOSTED_REDOX=1

Make Commands

All available Makefile targets

Repo Tool

Command-line tool for package management

Build Commands

Porting

Support

​Overview

​Build Configuration Variables

​Architecture Configuration

​ARCH

​BOARD

​CONFIG_NAME

​FILESYSTEM_CONFIG

​Toolchain Configuration

​PREFIX_BINARY

​PREFIX_USE_UPSTREAM_RUST_COMPILER

​Repository Configuration

​REPO_BINARY

​REPO_APPSTREAM

​REPO_NONSTOP

​REPO_OFFLINE

​REPO_DEBUG

​Filesystem Configuration

​FILESYSTEM_SIZE

​REDOXFS_MKFS_FLAGS

​Container Configuration

​PODMAN_BUILD

​FSTOOLS_IN_PODMAN

​FSTOOLS_NO_MOUNT

​SCCACHE_BUILD

​CONTAINERFILE

​Derived Variables

​Filesystem Configuration Files

​Location

​Structure

​General Section

​filesystem_size

​repo_binary

​Packages Section

​Package Rules

​Build Modes

​Include Directive

​Example Configurations

​Minimal Desktop

​Full Desktop

​Server Configuration

​Development Configuration

​QEMU Configuration Variables

​Hardware Emulation

​kvm

​gpu

​audio

​net

​disk

​System Configuration

​QEMU_SMP

​QEMU_MEM

​serial

​gdb

​live

​uefi

​iommu

​usb

​Advanced Options

​qemu_serial_logfile

​bridge

​netboot

​redoxer

​Per-Host Variables

​macOS

​FreeBSD

​Linux

​Redox

​See Also

Make Commands

Repo Tool

Build docs developers (and LLMs) love

Overview

Build Configuration Variables

Architecture Configuration

ARCH

BOARD

CONFIG_NAME

FILESYSTEM_CONFIG

Toolchain Configuration

PREFIX_BINARY

PREFIX_USE_UPSTREAM_RUST_COMPILER

Repository Configuration

REPO_BINARY

REPO_APPSTREAM

REPO_NONSTOP

REPO_OFFLINE

REPO_DEBUG

Filesystem Configuration

FILESYSTEM_SIZE

REDOXFS_MKFS_FLAGS

Container Configuration

PODMAN_BUILD

FSTOOLS_IN_PODMAN

FSTOOLS_NO_MOUNT

SCCACHE_BUILD

CONTAINERFILE

Derived Variables

Filesystem Configuration Files

Location

Structure

General Section

filesystem_size

repo_binary

Packages Section

Package Rules

Build Modes

Include Directive

Example Configurations

Minimal Desktop

Full Desktop

Server Configuration

Development Configuration

QEMU Configuration Variables

Hardware Emulation

kvm

gpu

audio

net

disk

System Configuration

QEMU_SMP

QEMU_MEM

serial

gdb

live

uefi

iommu

usb

Advanced Options

qemu_serial_logfile

bridge

netboot

redoxer

Per-Host Variables

macOS

FreeBSD

Linux

Redox

See Also