> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/redox-os/redox/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Build Guide

> Guide to building Redox OS directly on your host system without containers

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

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

## When to Use Native Builds

<CardGroup cols={2}>
  <Card title="Development" icon="code">
    Faster iteration when working on specific components
  </Card>

  <Card title="Debugging" icon="bug">
    Direct access to build artifacts and intermediate files
  </Card>

  <Card title="IDE Integration" icon="window">
    Better integration with development tools and IDEs
  </Card>

  <Card title="Low Memory" icon="memory">
    Lower memory overhead without container isolation
  </Card>
</CardGroup>

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

<Info>
  **macOS Users:** Native builds on macOS are **not recommended**. The toolchain relies on FUSE which requires kernel extensions. Use `podman_bootstrap.sh` instead.
</Info>

## Bootstrap Installation

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

### Using the Bootstrap Script

<Steps>
  <Step title="Download the Script">
    ```bash theme={null}
    curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/native_bootstrap.sh -o native_bootstrap.sh
    ```
  </Step>

  <Step title="Make it Executable">
    ```bash theme={null}
    chmod +x native_bootstrap.sh
    ```
  </Step>

  <Step title="Run the Bootstrap">
    For QEMU (recommended):

    ```bash theme={null}
    ./native_bootstrap.sh -e qemu
    ```

    For non-interactive installation:

    ```bash theme={null}
    ./native_bootstrap.sh -e qemu -y
    ```
  </Step>
</Steps>

### What the Bootstrap Does

<AccordionGroup>
  <Accordion title="Operating System Detection" icon="desktop">
    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
  </Accordion>

  <Accordion title="Build Dependencies" icon="toolbox">
    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
  </Accordion>

  <Accordion title="Rust Toolchain" icon="rust">
    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
  </Accordion>

  <Accordion title="Repository Setup" icon="code-branch">
    Prepares the build environment:

    * Clones Redox repository from GitLab
    * Creates `.config` with `PODMAN_BUILD=0`
    * Sets up directory structure
    * Checks Travis CI build status
  </Accordion>
</AccordionGroup>

## Manual Setup

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

### 1. Install Build Dependencies

<Tabs>
  <Tab title="Debian/Ubuntu">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Arch Linux">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    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
    ```

    <Warning>
      macOS native builds are experimental. Consider using Podman instead.
    </Warning>
  </Tab>
</Tabs>

### 2. Install Rust

```bash theme={null}
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
source $HOME/.cargo/env
```

### 3. Install Cargo Tools

```bash theme={null}
cargo install just --version 1.42.4
cargo install cbindgen --version 0.29.0
```

### 4. Clone Repository

```bash theme={null}
git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream
cd redox
```

### 5. Configure for Native Build

Create a `.config` file:

```bash .config theme={null}
PODMAN_BUILD?=0
```

Optional optimizations:

```bash .config theme={null}
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

```bash theme={null}
make all
```

The build process will:

<Steps>
  <Step title="Check Tools">
    Verify all required build tools are available
  </Step>

  <Step title="Build Filesystem Tools">
    Compile `redoxfs`, `redoxfs-mkfs`, and `redox_installer`
  </Step>

  <Step title="Build or Download Prefix">
    Either build the cross-compilation toolchain or download pre-built binaries
  </Step>

  <Step title="Build Recipes">
    Compile all packages specified in your configuration
  </Step>

  <Step title="Create Image">
    Generate the bootable disk image
  </Step>
</Steps>

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

<Tip>
  Use `REPO_BINARY=1` for your first build to save significant time.
</Tip>

## Build Configuration

### Environment Variables

Create or modify `.config` to customize the build:

```bash .config theme={null}
# 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/`:

<CardGroup cols={2}>
  <Card title="desktop" icon="desktop">
    Full desktop environment with GUI and applications
  </Card>

  <Card title="server" icon="server">
    Server configuration with networking utilities
  </Card>

  <Card title="minimal" icon="minimize">
    Bare minimum system (fastest to build)
  </Card>

  <Card title="dev" icon="code">
    Development tools and compilers
  </Card>
</CardGroup>

## Build Targets

### Image Targets

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Mount the disk image
make mount

# Unmount the disk image
make unmount

# Push packages to mounted image
make p.package_name
```

## Running Redox

### QEMU

```bash theme={null}
# 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

```bash theme={null}
make virtualbox
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing dependencies" icon="circle-exclamation">
    **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`
  </Accordion>

  <Accordion title="Toolchain build fails" icon="wrench">
    **Symptoms:** Errors during prefix build

    **Solutions:**

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

  <Accordion title="FUSE errors" icon="plug">
    **Symptoms:** Cannot mount filesystem

    **Solutions:**

    * 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`
  </Accordion>

  <Accordion title="Out of memory" icon="memory">
    **Symptoms:** Build killed, system freezes

    **Solutions:**

    * Reduce parallel jobs: `make all -j2`
    * Use swap space
    * Build with fewer packages (minimal config)
    * Close other applications
  </Accordion>

  <Accordion title="Recipe fails to build" icon="triangle-exclamation">
    **Symptoms:** Specific package build errors

    **Solutions:**

    * 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
  </Accordion>
</AccordionGroup>

## Advanced Usage

### Cross-Compilation

Native builds support cross-compilation for different architectures:

```bash theme={null}
# 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:

```bash .config theme={null}
PREFIX=/path/to/custom/prefix
PREFIX_BINARY=0
```

### Incremental Development

For fast iteration during development:

```bash theme={null}
# 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:

```bash .config theme={null}
REPO_DEBUG=1
```

This will:

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

## Performance Tips

<Steps>
  <Step title="Use Binary Packages">
    ```bash theme={null}
    echo 'REPO_BINARY=1' >> .config
    ```

    Reduces build time from hours to minutes
  </Step>

  <Step title="Use Binary Toolchain">
    ```bash theme={null}
    echo 'PREFIX_BINARY=1' >> .config
    ```

    Saves 30-60 minutes on first build
  </Step>

  <Step title="Use Minimal Config">
    ```bash theme={null}
    echo 'CONFIG_NAME=minimal' >> .config
    ```

    Builds only essential packages
  </Step>

  <Step title="Parallel Jobs">
    ```bash theme={null}
    make all -j$(nproc)
    ```

    Use all CPU cores
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/build-system/configuration">
    Learn about configuration options
  </Card>

  <Card title="Recipes" icon="book" href="/build-system/recipes">
    Understand the recipe system
  </Card>
</CardGroup>