Installation Guide

Complete installation instructions for building Redox OS with Podman or native toolchains

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)

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:

Standard Installation

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, slirp4netns

Ubuntu/Debian: pkg-config, fuse3, libfuse3-dev

Fedora: fuse3, fuse3-devel

SUSE: 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

1. Build System Image

   make all
   

   Or without SELinux:

   make all USE_SELINUX=0
   
2. Launch in QEMU

   make qemu
   

Native Build

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

Interactive

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:

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

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