Installation Guide

This guide provides comprehensive installation instructions for setting up the Redox OS build environment on various platforms.

System Requirements

Disk Space

At least 10-20 GB free for build artifacts

RAM

Minimum 4 GB, 8 GB+ recommended

CPU

Multi-core processor recommended for faster builds

Network

Stable internet for downloading sources

Supported Platforms

Redox can be built on:

Linux: Arch, Ubuntu, Debian, Fedora, openSUSE, Gentoo, Solus
BSD: FreeBSD, macOS (Homebrew or MacPorts)
Experimental: Redox OS itself (bootstrapping)

macOS Users: Native builds require kernel extensions (FUSE). The Podman build method is strongly recommended for macOS.

Installation Methods

Podman Build (Recommended)
Native Build

Podman Build Installation

The Podman build method uses containers for an isolated, consistent build environment.

Step 1: Download Bootstrap Script

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

Step 2: Run Bootstrap

The bootstrap script automatically detects your OS and installs dependencies:

time bash -e podman_bootstrap.sh

What Gets Installed

The Podman bootstrap installs:

Core Dependencies

Podman: Container runtime
git: Version control
make/gmake: Build system
curl: Download tool
gdb/gdb-multiarch: Debugger
Rustup: Rust toolchain manager (stable)

FUSE Support

fuse3/libfuse3-dev: File system in userspace
fuse-overlayfs: Overlay filesystem
slirp4netns: User-mode networking

Emulator (QEMU)

qemu-system-x86: x86/x86_64 emulation
qemu-system-arm: ARM emulation
qemu-system-riscv: RISC-V emulation
qemu-kvm: Kernel-based virtualization
edk2-aarch64: ARM64 UEFI firmware (on Fedora/Ubuntu)

Platform-Specific Packages

Arch Linux: fuse3, fuse-overlayfs, slirp4netnsUbuntu/Debian: pkg-config, fuse3, libfuse3-devFedora: fuse3, fuse3-develSUSE: fuse, fuse-overlayfs

Step 3: Configuration

After bootstrap completes, navigate to the repository:

cd redox

The .config file is created automatically with:

PODMAN_BUILD?=1

On Apple Silicon (M1/M2/M3):

PODMAN_BUILD?=1
ARCH=aarch64

Speed up builds with binary packages:

echo REPO_BINARY=1 >> .config

Step 4: Build and Run

Build System Image

make all

Or without SELinux:

make all USE_SELINUX=0

Launch in QEMU

make qemu

Native Build Installation

Native builds compile directly on your host system with full toolchain installation.

Step 1: Download Bootstrap Script

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

Step 2: Bootstrap Options

bash -e native_bootstrap.sh -e qemu

Bootstrap Flags

-e [emulator]: Install qemu or virtualbox
-y: Non-interactive mode (auto-accept)
-d: Install dependencies only, skip repo clone
-u [branch]: Update existing repo (defaults to master)
-p [manager]: Choose package manager (Ubuntu: apt-fast, aptitude)
-h: Show help

What Gets Installed

Native builds require extensive development tools:

Build Essentials

Rust toolchain: rustc, cargo, rustup
GNU tools: make, autoconf, automake, libtool
Compilers: gcc, g++, clang, nasm
Build systems: cmake, meson, ninja, scons
Utilities: git, curl, wget, rsync, patch, m4, bison, flex

Libraries & Development Files

FUSE: fuse3, fuse3-dev/devel
Graphics: libjpeg-dev, libpng-dev, libgdk-pixbuf2.0
SDL: libsdl1.2-dev, libsdl2-ttf-dev
Crypto: openssl, libgmp-dev
Other: expat, protobuf-compiler, pkg-config

Documentation & Internationalization

Docs: doxygen, texinfo, help2man, gtk-doc-tools
i18n: gettext, intltool, po4a, autopoint
Perl modules: libhtml-parser-perl, libparse-yapp-perl

System Tools

Debug: gdb-multiarch (Linux), gdb +multiarch (macOS)
Packaging: patchelf, syslinux-utils, genisoimage
Fonts: xfonts-utils
Python: python3, python3-dev, python3-mako, python3-venv

Cargo Tools

Installed via cargo:

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

Platform-Specific Instructions

Ubuntu / Debian

Uses apt-get by default. The bootstrap installs 60+ packages including:

sudo apt-get update
sudo apt-get install build-essential git curl fuse3 libfuse3-dev \
  gdb-multiarch qemu-system-x86 qemu-kvm cmake nasm pkg-config \
  autoconf automake libtool m4 python3-mako libgmp-dev ...

On Debian, VirtualBox requires manual installation. See Debian VirtualBox Wiki.

Fedora

Uses dnf. Installs development groups and individual packages:

sudo dnf install @development-tools git-all cmake nasm gcc gcc-c++ \
  fuse3-devel qemu-system-x86 qemu-kvm edk2-aarch64 ...

Arch Linux

Uses pacman:

sudo pacman -S --needed git make curl fuse cmake nasm \
  qemu-system-x86 qemu-system-arm qemu-system-riscv ...

macOS (Homebrew)

brew update
brew install git make curl cmake nasm qemu gdb \
  redox-os/gcc_cross_compilers/x86_64-elf-gcc ...

macOS builds require macfuse (kernel extension). Consider using Podman instead.

macOS (MacPorts)

sudo port -v selfupdate
sudo port install git gmake curl cmake qemu nasm \
  'gdb +multiarch' x86_64-elf-gcc ...

FreeBSD

sudo pkg install git gmake curl cmake nasm qemu \
  fusefs-libs3 gcc gdb ...

openSUSE

Uses zypper:

sudo zypper install git make curl cmake nasm fuse-devel \
  gcc gcc-c++ qemu-x86 qemu-kvm ...

Gentoo

Uses emerge:

sudo emerge dev-vcs/git sys-fs/fuse dev-util/cmake \
  dev-lang/nasm app-emulation/qemu ...

QEMU requires manual configuration: Add QEMU_SOFTMMU_TARGETS="x86_64" to /etc/portage/make.conf

Solus

Uses eopkg:

sudo eopkg it git make cmake nasm fuse-devel qemu \
  gcc g++ autoconf automake ...

Step 3: Rust Installation

The bootstrap script handles Rustup installation:

curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable

Update your shell environment:

source $HOME/.cargo/env

Add to your shell profile permanently:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

Step 4: Clone and Configure

The bootstrap clones the repository:

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

Creates .config:

PODMAN_BUILD?=0

Step 5: Build

make all

On FreeBSD, load FUSE kernel module first:

kldload fuse.ko
make all

Build System Architecture Selection

Use build.sh for architecture-specific builds:

# x86_64 (default)
./build.sh -X -c desktop qemu

# ARM64 / aarch64  
./build.sh -A -c desktop qemu

# i586 (32-bit x86)
./build.sh -5 -c desktop qemu

# RISC-V 64-bit
./build.sh -R -c desktop qemu

Configuration Profiles

desktop: Full desktop environment with COSMIC apps
server: Server configuration, minimal GUI
demo: Demonstration configuration

Custom configs are in config/<ARCH>/<CONFIG>.toml

Makefile Targets Reference

make all              # Build harddrive.img
make live             # Build bootable ISO (redox-live.iso)
make popsicle         # Create bootable USB with Popsicle
make image            # Clean and rebuild images
make rebuild          # Full rebuild (removes repo.tag)
make clean            # Remove build artifacts
make distclean        # Clean including fetched sources
make pull             # Update repository
make repo             # Build repository tag
make env              # Enter build environment shell
make qemu             # Run in QEMU
make virtualbox       # Run in VirtualBox
make gdb              # Debug kernel with GDB
make wireshark        # Analyze network capture

Configuration Variables

Edit .config or set as environment variables:

# Build method
PODMAN_BUILD?=1        # Use Podman (1) or native (0)

# Binary packages for faster builds
REPO_BINARY=1

# SELinux support (Fedora/RHEL)
USE_SELINUX=1          # Set to 0 if not using SELinux

# Architecture (auto-detected or override)
ARCH=x86_64            # x86_64, aarch64, i586, riscv64gc

# Configuration name
CONFIG_NAME=desktop    # desktop, server, demo, or custom

# Filesystem configuration
FILESYSTEM_CONFIG=config/x86_64/desktop.toml

Troubleshooting

SELinux Errors

If you encounter build errors on non-SELinux systems:

make all USE_SELINUX=0

Or add to .config:

echo 'USE_SELINUX?=0' >> .config

Rustup Installation Issues

Manual Rustup installation:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

FUSE Errors

Linux: Ensure FUSE 3 is installed

# Ubuntu/Debian
sudo apt install fuse3 libfuse3-dev

# Fedora
sudo dnf install fuse3 fuse3-devel

FreeBSD: Load kernel module

sudo kldload fuse

Podman Permissions

Add user to Podman group (Linux):

sudo usermod -aG podman $USER
# Log out and back in

Disk Space Issues

Clean build artifacts:

make clean

Remove all downloaded sources:

make distclean

macOS Build Warnings

Native macOS builds are not recommended. The toolchain requires FUSE kernel extensions.Solution: Use Podman build instead:

bash podman_bootstrap.sh -e qemu

Development Best Practices

Keep Build System Updated

cd redox
git pull upstream master

Log Build Errors

make all 2>&1 | tee build.log

Local Recipe Changes

Disable auto-updates for modified recipes:See Configuration Settings

Update initfs

After modifying drivers or system components:See Coding and Building

Debugging the Build

GDB Integration

Debug the kernel:

make qemu &  # Start QEMU with GDB stub
make gdb     # Connect debugger

The debugger connects to localhost:1234 and loads symbols from:

recipes/core/kernel/target/<TARGET>/build/kernel.sym

Set RUST_GDB=gdb-multiarch when debugging for architectures different from your host.

Network Analysis

Capture and analyze network traffic:

make qemu  # QEMU creates network.pcap
make wireshark

Advanced Configuration

Custom Filesystem Config

Create custom TOML configuration:

cp config/x86_64/desktop.toml config/x86_64/myconfig.toml
# Edit myconfig.toml
./build.sh -X -f config/x86_64/myconfig.toml all

Environment Shell

Enter build environment with correct PATH:

make env

This spawns a shell with:

Cross-compiler tools in PATH
All build dependencies accessible
Environment variables configured

Next Steps

Quick Start

Fast-track guide to building Redox

Contributing

Contribute to Redox development

Build System Reference

Detailed build system documentation

Developer FAQ

Common development questions

Getting Support

If you encounter issues:

Check logs: Always save build output with 2>&1 | tee log.txt
Search issues: GitLab Issues
Ask on chat: Matrix or Discord
Read docs: Redox Book

Post issue links in the Dev or Support chat rooms to avoid them being forgotten due to email notification noise.

Get Started

Build System

Architecture

Components

Development

Hardware

​System Requirements

Disk Space

RAM

CPU

Network

​Supported Platforms

​Installation Methods

​Podman Build Installation

​Step 1: Download Bootstrap Script

​Step 2: Run Bootstrap

​What Gets Installed

​Step 3: Configuration

​Step 4: Build and Run

​Native Build Installation

​Step 1: Download Bootstrap Script

​Step 2: Bootstrap Options

​Bootstrap Flags

​What Gets Installed

​Platform-Specific Instructions

​Step 3: Rust Installation

​Step 4: Clone and Configure

​Step 5: Build

​Build System Architecture Selection

​Configuration Profiles

​Makefile Targets Reference

​Configuration Variables

​Troubleshooting

​Development Best Practices

Keep Build System Updated

Log Build Errors

Local Recipe Changes

Update initfs

​Debugging the Build

​GDB Integration

​Network Analysis

​Advanced Configuration

​Custom Filesystem Config

​Environment Shell

​Next Steps

Quick Start

Contributing

Build System Reference

Developer FAQ

​Getting Support

Build docs developers (and LLMs) love

System Requirements

Supported Platforms

Installation Methods

Podman Build Installation

Step 1: Download Bootstrap Script

Step 2: Run Bootstrap

What Gets Installed

Step 3: Configuration

Step 4: Build and Run

Native Build Installation

Step 1: Download Bootstrap Script

Step 2: Bootstrap Options

Bootstrap Flags

What Gets Installed

Platform-Specific Instructions

Step 3: Rust Installation

Step 4: Clone and Configure

Step 5: Build

Build System Architecture Selection

Configuration Profiles

Makefile Targets Reference

Configuration Variables

Troubleshooting

Development Best Practices

Debugging the Build

GDB Integration

Network Analysis

Advanced Configuration

Custom Filesystem Config

Environment Shell

Next Steps

Getting Support