Skip to main content

​
Overview

The Redox OS build system uses GNU Make with multiple modular configuration files in the mk/ directory. This reference documents all available make targets organized by category.

​
Primary Build Targets

​
all

Build the default hard drive image. 
make all
This is the default target when running make without arguments. It builds $(BUILD)/harddrive.img.

​
image

Clean and rebuild the hard drive image from scratch. 
make image
This target:
  • Unmounts any mounted filesystems
  • Removes existing harddrive.img and redox-live.iso
  • Builds a fresh image

​
rebuild

Rebuild the image, clearing the repo tag. 
make rebuild
Cleans $(BUILD)/repo.tag and rebuilds the entire system.

​
Live ISO Targets

​
live

Build a bootable live ISO image. 
make live
Creates $(BUILD)/redox-live.iso that can be booted without installation.

​
popsicle

Open the Popsicle USB flasher GUI with the live ISO. 
make popsicle
Requires popsicle-gtk to be installed on the host system.

​
Repository Management Targets

​
repo

Build all packages specified in the filesystem configuration. 
make repo
Builds $(BUILD)/repo.tag which triggers package compilation.

​
repo_clean

Clean all recipe build artifacts. 
make repo_clean
Equivalent to make c.--all.

​
fetch_clean

Delete all recipe source downloads. 
make fetch_clean
Equivalent to make u.--all.

​
repo-tree

Display the build dependency tree for recipes. 
make repo-tree
Shows which recipes need to be built and in what order.

​
image-tree

Display the package installation tree. 
make image-tree
Shows the estimated image size and package dependencies.

​
repo_clean_target

Clean target-specific artifacts for all recipes. 
make repo_clean_target
Removes only the architecture-specific build artifacts.

​
Recipe-Specific Targets

These targets operate on individual recipes or comma-separated lists.

​
f.RECIPE

Fetch source for one or more recipes. 
make f.coreutils
make f.coreutils,bash,gcc
​
RECIPE
string
required
Recipe name(s), comma-separated for multiple recipes

​
r.RECIPE

Cook (build) one or more recipes. 
make r.kernel
make r.kernel,drivers,init
​
RECIPE
string
required
Recipe name(s) to build

​
c.RECIPE

Clean build artifacts for one or more recipes. 
make c.gcc
make c.--all  # Clean all recipes
​
RECIPE
string
required
Recipe name(s) to clean, or --all for everything

​
u.RECIPE

Unfetch (delete source) for one or more recipes. 
make u.rust
make u.--all  # Delete all sources
​
RECIPE
string
required
Recipe name(s) to unfetch

​
p.RECIPE

Push (install) compiled package into mounted filesystem. 
make p.orbital
Do not run this while QEMU is running, as it may corrupt the disk image.
​
RECIPE
string
required
Recipe name(s) to push

​
pp.RECIPE

Push package with its package dependencies. 
make pp.netsurf

​
cr.RECIPE

Clean and rebuild recipes. 
make cr.relibc
Equivalent to make c.RECIPE && make r.RECIPE.

​
ucr.RECIPE

Unfetch, clean, and rebuild recipes. 
make ucr.gcc

​
uc.RECIPE

Unfetch and clean recipes. 
make uc.llvm

​
ucf.RECIPE

Unfetch, clean, and fetch recipes. 
make ucf.rust

​
rp.RECIPE

Build and push recipes. 
make rp.cosmic-term

​
crp.RECIPE

Clean, rebuild, and push recipes. 
make crp.installer

​
ucrp.RECIPE

Unfetch, clean, rebuild, and push recipes. 
make ucrp.kernel

​
rt.RECIPE

Show build tree for recipes. 
make rt.gcc

​
pt.RECIPE

Show push tree for recipes. 
make pt.coreutils

​
ppt.RECIPE

Show push tree with package dependencies. 
make ppt.orbital

​
find.RECIPE

Find the path to recipe directories. 
make find.kernel
make find.gcc,rust,llvm

​
debug.RECIPE

Open gdbgui debugger for a recipe binary. 
make debug.kernel
make debug.pcid DEBUG_BIN=pcid
​
DEBUG_BIN
string
Specific binary name to debug (optional)
Start QEMU with make qemu kvm=no QEMU_SMP=1 gdb=yes before debugging.

​
Clean Targets

​
clean

Remove all build artifacts. 
make clean
Removes:
  • repo/ directory
  • $(BUILD) directory
  • $(PREFIX) directory
  • Filesystem tools

​
distclean

Complete clean including source downloads. 
make distclean
Performs clean plus recipe source cleanup.

​
fstools_clean

Clean filesystem tools only. 
make fstools_clean

​
prefix_clean

Remove cross-compiler prefix builds. 
make prefix_clean

​
static_clean

Remove relibc and statically linked recipes. 
make static_clean

​
container_clean

Remove Podman container and cached files. 
make container_clean

​
Emulation Targets

​
qemu

Run Redox OS in QEMU. 
make qemu
​
kvm
yes|no
default:"auto"
Enable KVM acceleration
​
gpu
vga|virtio|ramfb|no
default:"vga"
Graphics adapter type
​
net
e1000|rtl8139|virtio|redir|no
default:"e1000"
Network adapter type
​
disk
nvme|ata|usb|virtio|sdcard
default:"nvme"
Disk controller type
​
audio
hda|ac97|no
default:"hda"
Audio device type
​
serial
yes|no
default:"yes"
Enable serial console
​
gdb
yes|no
default:"no"
Wait for GDB connection on port 1234
​
live
yes|no
default:"no"
Boot from live ISO instead of hard drive
​
uefi
yes|no
default:"yes"
Use UEFI boot (x86_64/aarch64)
​
QEMU_SMP
number
default:"4"
Number of CPU cores
​
QEMU_MEM
number
default:"2048"
Memory in MB

​
Examples

# Run with KVM disabled
make qemu kvm=no

# Run with virtio GPU and 4GB RAM
make qemu gpu=virtio QEMU_MEM=4096

# Run with GDB support
make qemu gdb=yes QEMU_SMP=1

# Boot live ISO with no network
make qemu live=yes net=no

​
virtualbox

Create and run VirtualBox VM. 
make virtualbox
Creates a new VirtualBox VM named “Redox” with the built hard drive image.

​
Filesystem Targets

​
mount

Mount the hard drive image. 
make mount
Mounts $(BUILD)/harddrive.img to $(BUILD)/filesystem/.

​
mount_extra

Mount the extra disk image. 
make mount_extra

​
mount_live

Mount the live ISO image. 
make mount_live

​
unmount

Unmount the currently mounted filesystem. 
make unmount

​
Cross-Compiler Targets

​
prefix

Build the cross-compiler toolchain. 
make prefix
Builds GCC, Rust, Clang, and relibc for cross-compilation.
With PREFIX_BINARY=1 (default), downloads prebuilt toolchains instead of building from source.

​
Podman Container Targets

​
container_shell

Open a shell in the Podman build container. 
make container_shell
​
PODMAN_BUILD
0|1
required
Must be set to 1 in .config or mk/config.mk

​
container_touch

Mark the container as built without rebuilding. 
make container_touch

​
container_kill

Kill the running Podman container. 
make container_kill

​
container_push

Push the container image to registry. 
make container_push

​
Development Targets

​
env

Open a shell with build environment variables set. 
make env
Provides an interactive shell with PATH and compiler variables configured.

​
setenv

Print environment variables for manual export. 
make setenv
Outputs: 
export ARCH='x86_64'
export BOARD=''
export CONFIG_NAME='desktop'
export BUILD='build/x86_64/desktop'

​
pull

Update the repository and filesystem tools. 
make pull
Runs git pull and removes the fstools tag to trigger rebuild.

​
gdb

Connect GDB to debug the kernel. 
make gdb
Connects to QEMU’s GDB stub on port 1234.
Start QEMU with gdb=yes first.

​
gdb-userspace

Debug userspace applications without gdbserver. 
make gdb-userspace GDB_APP_FILE=path/to/binary
This is a fallback method. Prefer using gdbserver inside the VM when possible.

​
kernel_debugger

Launch gdbgui in container for kernel debugging. 
make kernel_debugger
Opens gdbgui on http://localhost:5000 for kernel debugging.

​
wireshark

Open Wireshark to analyze network traffic. 
make wireshark
Opens $(BUILD)/network.pcap captured during QEMU execution.

​
cargo-fetch

Fetch Cargo dependencies for offline builds. 
make cargo-fetch
Required before building with REPO_OFFLINE=1.

​
CI Targets

​
ci-img

Build standard images for CI/release. 
make ci-img IMG_TAG=0.9.0
​
IMG_TAG
string
Version tag for image names (default: git describe)
​
IMG_DIR
string
default:"build/img/$(ARCH)"
Output directory for images
Builds server, desktop, and demo configurations.

​
ci-pkg

Build packages for CI. 
make ci-pkg

​
ci-toolchain

Build toolchain archives for distribution. 
make ci-toolchain
Creates compressed toolchain archives in build/toolchain/.

​
ci-os-test

Run OS tests and collect results. 
make ci-os-test

​
Special Targets

​
FORCE

Empty target used to force execution of other targets.
This is an internal target used by the build system.

​
Configuration-Specific Targets

​
server, desktop, demo

Build named configuration images. 
make server
make desktop
make demo
Each builds both hard drive and live ISO for the specified configuration.

​
See Also

Repo Tool

Command-line tool for recipe management

Configuration Options

Build system configuration variables

Build docs developers (and LLMs) love

Get started for freeTalk to us