Native Build Guide

Overview

The native build method compiles Redox OS directly on your host system without using containers. This approach is useful for development work where you need direct access to build artifacts and faster iteration cycles.

Native builds require careful management of dependencies and may behave differently across systems. Podman builds are recommended for most users.

When to Use Native Builds

Development

Faster iteration when working on specific components

Debugging

Direct access to build artifacts and intermediate files

IDE Integration

Better integration with development tools and IDEs

Low Memory

Lower memory overhead without container isolation

Prerequisites

System Requirements

Operating System: Linux (recommended), macOS, FreeBSD, or Redox OS itself
Memory: At least 8GB RAM (16GB recommended)
Disk Space: 20-30GB free space
Time: First build can take 1-4 hours depending on hardware

macOS Users: Native builds on macOS are not recommended. The toolchain relies on FUSE which requires kernel extensions. Use podman_bootstrap.sh instead.

Bootstrap Installation

The easiest way to set up a native build environment is using the bootstrap script.

Using the Bootstrap Script

Download the Script

curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/native_bootstrap.sh -o native_bootstrap.sh

Make it Executable

chmod +x native_bootstrap.sh

Run the Bootstrap

For QEMU (recommended):

./native_bootstrap.sh -e qemu

For non-interactive installation:

./native_bootstrap.sh -e qemu -y

What the Bootstrap Does

Operating System Detection

The script automatically detects your OS and package manager:

Debian/Ubuntu: apt-get
Fedora/RHEL: dnf
Arch Linux: pacman
openSUSE: zypper
Gentoo: emerge
Solus: eopkg
FreeBSD: pkg
macOS: Homebrew or MacPorts

Build Dependencies

Installs comprehensive build tools including:

Compilers: gcc, g++, clang, nasm
Build systems: make, cmake, meson, ninja, scons
Libraries: fuse3, gmp, mpfr, expat, jpeg, png
Tools: autoconf, automake, bison, flex, patch, patchelf
Version control: git, git-lfs
Debugging: gdb or gdb-multiarch
Package tools: pkg-config, protobuf-compiler
Python: python3, python3-mako
Perl modules: HTML::Parser

Rust Toolchain

Sets up the Rust development environment:

Detects existing Rust installations
Offers to install rustup if needed
Configures stable toolchain as default
Installs cargo tools: just and cbindgen
Adds cargo bin directory to PATH

Repository Setup

Prepares the build environment:

Clones Redox repository from GitLab
Creates .config with PODMAN_BUILD=0
Sets up directory structure
Checks Travis CI build status

Manual Setup

For manual setup or if the bootstrap script doesn’t work:

1. Install Build Dependencies

Debian/Ubuntu
Fedora
Arch Linux
macOS (Homebrew)

sudo apt-get update
sudo apt-get install \
  ant appstream autoconf automake bison build-essential \
  clang cmake curl dos2unix doxygen expect file flex \
  fuse3 g++ gdb-multiarch genisoimage git git-lfs \
  gtk-doc-tools help2man intltool \
  libc6-dev-i386 libfuse3-dev libgdk-pixbuf2.0-bin \
  libglib2.0-dev-bin libgmp-dev libhtml-parser-perl \
  libjpeg-dev libmpfr-dev libparse-yapp-perl \
  libsdl1.2-dev libsdl2-ttf-dev llvm lua5.4 lzip \
  m4 make meson nasm ninja-build patch patchelf perl \
  pkg-config po4a protobuf-compiler python3 python3-dev \
  python3-mako python3-venv rsync ruby scons ssh \
  syslinux-utils texinfo unifdef unzip wget xdg-utils \
  xfonts-utils xorg-dev xutils-dev xxd zip zstd

# QEMU (if using QEMU emulator)
sudo apt-get install qemu-system-x86 qemu-kvm \
  qemu-system-arm qemu-efi-aarch64 qemu-system-riscv

sudo dnf install @development-tools \
  ant autoconf automake bison cmake curl doxygen expat \
  expat-devel file flex fuse-devel fuse3-devel gcc gcc-c++ \
  gdb genisoimage gettext-devel glibc-devel.i686 gmp-devel \
  help2man libjpeg-turbo-devel libpng-devel libtool lzip \
  m4 make meson nasm ninja-build openssl patch patchelf \
  perl perl-FindBin perl-HTML-Parser perl-Pod-Html \
  perl-Pod-Xhtml pkgconf-pkg-config po4a protobuf-compiler \
  python3-mako SDL2_ttf-devel sdl12-compat-devel syslinux \
  texinfo unzip vim waf zip zstd

# QEMU
sudo dnf install qemu-system-x86 qemu-kvm \
  qemu-system-arm edk2-aarch64 qemu-system-riscv

sudo pacman -S --needed \
  ant autoconf automake bison cmake curl doxygen expat \
  file flex fuse gdb git gmp libjpeg-turbo libpng libtool \
  m4 make meson nasm patch patchelf perl perl-html-parser \
  pkgconf po4a protobuf python python-mako rsync scons \
  sdl12-compat syslinux texinfo unzip waf wget xdg-utils zip

# QEMU
sudo pacman -S qemu-system-x86 qemu-system-arm qemu-system-riscv

brew update
brew install git make curl podman \
  ant autoconf automake bison cmake curl doxygen expat \
  findutils flex gcc@14 gdb gettext gmp gpatch jpeg libpng \
  libtool llvm m4 macfuse make meson nasm ninja openssl@1.1 \
  openssl@3.0 patchelf perl pkg-config po4a protobuf \
  python@3.11 scons sdl12-compat sdl2_ttf texinfo unzip \
  wget zip

# Cross-compiler
brew install redox-os/gcc_cross_compilers/x86_64-elf-gcc

# QEMU
brew install qemu

macOS native builds are experimental. Consider using Podman instead.

2. Install Rust

curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
source $HOME/.cargo/env

3. Install Cargo Tools

cargo install just --version 1.42.4
cargo install cbindgen --version 0.29.0

4. Clone Repository

git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream
cd redox

5. Configure for Native Build

Create a .config file:

.config

PODMAN_BUILD?=0

Optional optimizations:

.config

PODMAN_BUILD?=0
PREFIX_BINARY=1      # Use pre-built toolchain (faster)
REPO_BINARY=1        # Use pre-built packages (much faster)
CONFIG_NAME=desktop  # Or: server, minimal, etc.

Building Redox OS

Standard Build

make all

The build process will:

Check Tools

Verify all required build tools are available

Build Filesystem Tools

Compile redoxfs, redoxfs-mkfs, and redox_installer

Build or Download Prefix

Either build the cross-compilation toolchain or download pre-built binaries

Build Recipes

Compile all packages specified in your configuration

Create Image

Generate the bootable disk image

Build Time Expectations

Configuration	First Build	Incremental
Minimal (from source)	1-2 hours	5-15 minutes
Desktop (from source)	2-4 hours	10-30 minutes
Minimal (binary)	10-20 minutes	2-5 minutes
Desktop (binary)	20-40 minutes	5-10 minutes

Use REPO_BINARY=1 for your first build to save significant time.

Build Configuration

Environment Variables

Create or modify .config to customize the build:

.config

# Architecture (x86_64, aarch64, i586, riscv64gc)
ARCH?=x86_64

# Configuration profile
CONFIG_NAME?=desktop

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

# Use pre-built packages (faster builds)
REPO_BINARY?=1

# Enable debug symbols
REPO_DEBUG?=0

# Continue building despite errors
REPO_NONSTOP?=0

# Offline mode (no source fetching)
REPO_OFFLINE?=0

# Disable Podman
PODMAN_BUILD?=0

Configuration Profiles

Available configuration profiles in config/:

desktop

Full desktop environment with GUI and applications

server

Server configuration with networking utilities

minimal

Bare minimum system (fastest to build)

dev

Development tools and compilers

Build Targets

Image Targets

# Build hard drive image (default)
make all

# Rebuild from scratch
make rebuild

# Create live ISO
make live

# Just rebuild image without recompiling
make image

Package Management

# Build a specific package
make r.orbital

# Clean a package
make c.kernel

# Rebuild a package (clean + build)
make cr.relibc

# Build and install to image
make rp.nano

# Build multiple packages
make r.gcc,binutils,newlib

Repository Management

# Clean all built packages
make repo_clean

# Clean all source and built packages
make distclean

# Fetch sources without building
make fetch

# Show dependency tree
make repo-tree

Filesystem Operations

# Mount the disk image
make mount

# Unmount the disk image
make unmount

# Push packages to mounted image
make p.package_name

Running Redox

QEMU

# Basic run
make qemu

# With KVM acceleration (Linux hosts)
make qemu kvm=yes

# With different GPU
make qemu gpu=virtio

# With more memory
make qemu QEMU_MEM=4096

# With GDB debugging
make qemu gdb=yes

VirtualBox

make virtualbox

Troubleshooting

Missing dependencies

Symptoms: Build fails with “command not found” or “package not found”Solutions:

Run the bootstrap script again
Check the dependency list for your OS above
Ensure PATH includes cargo binaries: source $HOME/.cargo/env

Toolchain build fails

Symptoms: Errors during prefix buildSolutions:

Use pre-built toolchain: echo 'PREFIX_BINARY=1' >> .config
Check available disk space (need 10+ GB)
Check GCC version: gcc --version (needs 7.0+)

FUSE errors

Symptoms: Cannot mount filesystemSolutions:

Install FUSE: sudo apt-get install fuse3 libfuse3-dev
Check FUSE module: lsmod | grep fuse
Add user to fuse group: sudo usermod -a -G fuse $USER
Log out and back in for group change to take effect
On FreeBSD: sudo kldload fuse.ko

Out of memory

Symptoms: Build killed, system freezesSolutions:

Reduce parallel jobs: make all -j2
Use swap space
Build with fewer packages (minimal config)
Close other applications

Recipe fails to build

Symptoms: Specific package build errorsSolutions:

Clean and rebuild: make cr.package_name
Check recipe logs in build/$(ARCH)/$(CONFIG_NAME)/
Enable verbose output: make r.package_name COOKBOOK_VERBOSE=1
Skip problematic package by removing from config

Advanced Usage

Cross-Compilation

Native builds support cross-compilation for different architectures:

# Build for ARM64 on x86_64 host
make all ARCH=aarch64

# Build for RISC-V
make all ARCH=riscv64gc

# Build for i586 (32-bit x86)
make all ARCH=i586

Custom Toolchain

To use a custom toolchain location:

.config

PREFIX=/path/to/custom/prefix
PREFIX_BINARY=0

Incremental Development

For fast iteration during development:

# Mount the image
make mount

# In another terminal, build and push package
make rp.my_package

# Test in QEMU
make qemu

# Don't forget to unmount
make unmount

Debug Builds

Enable debug symbols:

.config

REPO_DEBUG=1

This will:

Keep debug symbols in binaries
Disable stripping
Enable debug assertions in Rust code

Performance Tips

Use Binary Packages

echo 'REPO_BINARY=1' >> .config

Reduces build time from hours to minutes

Use Binary Toolchain

echo 'PREFIX_BINARY=1' >> .config

Saves 30-60 minutes on first build

Use Minimal Config

echo 'CONFIG_NAME=minimal' >> .config

Builds only essential packages

Parallel Jobs

make all -j$(nproc)

Use all CPU cores

Next Steps

Configuration

Learn about configuration options

Recipes

Understand the recipe system

Get Started

Build System

Architecture

Components

Development

Hardware

​Overview

​When to Use Native Builds

Development

Debugging

IDE Integration

Low Memory

​Prerequisites

​System Requirements

​Bootstrap Installation

​Using the Bootstrap Script

​What the Bootstrap Does

​Manual Setup

​1. Install Build Dependencies

​2. Install Rust

​3. Install Cargo Tools

​4. Clone Repository

​5. Configure for Native Build

​Building Redox OS

​Standard Build

​Build Time Expectations

​Build Configuration

​Environment Variables

​Configuration Profiles

desktop

server

minimal

dev

​Build Targets

​Image Targets

​Package Management

​Repository Management

​Filesystem Operations

​Running Redox

​QEMU

​VirtualBox

​Troubleshooting

​Advanced Usage

​Cross-Compilation

​Custom Toolchain

​Incremental Development

​Debug Builds

​Performance Tips

​Next Steps

Configuration

Recipes

Build docs developers (and LLMs) love

Overview

When to Use Native Builds

Prerequisites

System Requirements

Bootstrap Installation

Using the Bootstrap Script

What the Bootstrap Does

Manual Setup

1. Install Build Dependencies

2. Install Rust

3. Install Cargo Tools

4. Clone Repository

5. Configure for Native Build

Building Redox OS

Standard Build

Build Time Expectations

Build Configuration

Environment Variables

Configuration Profiles

Build Targets

Image Targets

Package Management

Repository Management

Filesystem Operations

Running Redox

QEMU

VirtualBox

Troubleshooting

Advanced Usage

Cross-Compilation

Custom Toolchain

Incremental Development

Debug Builds

Performance Tips

Next Steps