Make Commands Reference

Complete reference for all Makefile targets in the Redox OS build system

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

QEMU Configuration Variables

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