Build system

Make → Cargo → Zig. The three-step pipeline that produces rockboxd.

Rockbox Zig is built by three tools in series:

1. Make — compiles the Rockbox C firmware into static libraries.
2. Cargo — compiles the Rust crates into static libraries (crate-type = ["staticlib"]).
3. Zig — links everything (plus CPAL) into a single executable.

Dependencies

Ubuntu / Debian

sudo apt-get install \
  libasound2-dev libfreetype6-dev libdbus-1-dev libunwind-dev \
  zip protobuf-compiler cmake

Fedora

sudo dnf install \
  alsa-lib-devel freetype-devel libunwind-devel \
  zip protobuf-compiler cmake

macOS (Homebrew)

brew install tsirysndr/tap/rockbox

This installs the pre-built binary. If you want to build from source, install the toolchain dependencies instead:

brew install freetype cmake protobuf

You’ll also need:

• Zig ≥ 0.16 — ziglang.org/download
• Rust stable — rustup update stable
• Deno — for the web UI build

Full build

# 1. Clone with submodules
git clone https://github.com/tsirysndr/rockbox-zig.git
cd rockbox-zig
git submodule update --init --recursive

# 2. Build the web UI (embedded into the binary)
cd webui/rockbox
deno install
deno run build
cd ../..

# 3. Configure and build the C firmware (one-time setup)
mkdir -p build-lib && cd build-lib
../tools/configure --target=sdlapp --type=N \
  --lcdwidth=320 --lcdheight=240 --prefix=/usr/local
cp ../autoconf/autoconf.h .
make lib
cd ..

# 4. Build Rust crates
cargo build --release -p rockbox-cli -p rockbox-server

# 5. Link everything with Zig
cd zig && zig build

The binary lands at zig/zig-out/bin/rockboxd.

Iterating on changes

Zig only re-links when the static libraries are newer than the binary. After editing C, run make lib first. After editing Rust, run cargo build --release first.

# C change
cd build-lib && make lib && cd .. && cd zig && zig build

# Rust change
cargo build --release -p rockbox-cli -p rockbox-server && cd zig && zig build

Stale binary pitfall. If behaviour doesn’t match the source, check mtimes:

ls -la zig/zig-out/bin/rockboxd \
       build-lib/libfirmware.a \
       target/release/librockbox_cli.a

If rockboxd is newer than every .a file, Zig considered the link up-to-date and your change wasn’t picked up.

Verifying symbols

nm zig/zig-out/bin/rockboxd | grep pcm_airplay
nm zig/zig-out/bin/rockboxd | grep pcm_squeezelite
ar t target/release/librockbox_cli.a | grep airplay
ar t target/release/librockbox_cli.a | grep slim

Headless build (CPAL / no SDL)

The recommended build path for desktop use is the headless target, which uses CPAL for audio instead of SDL. A convenience script handles all three steps:

bash scripts/build-headless.sh

This configures and builds the firmware against build-headless/, compiles the Rust crates with the cpal feature, and links the result with Zig.

Embeddable library (librockboxd.a)

zig build lib produces zig/zig-out/lib/librockboxd.a — a fat archive that desktop GUIs (GPUI, macOS Swift, Qt, …) can link against to boot the Rockbox daemon in-process. The public C header is include/rockboxd.h.

# After the headless firmware + Rust embed crate:
cd zig && zig build lib
# → zig/zig-out/lib/librockboxd.a

Don’t re-run tools/configure

build-lib/ is pre-configured for the sdlapp target; build-headless/ is pre-configured for the headless target. Re-running tools/configure regenerates the Makefile and overwrites local edits. If you really need to reconfigure, do it knowingly and review the resulting diff.