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

# Build system

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

Rockbox Daemon 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

<Tabs>
  <Tab title="Ubuntu / Debian">
    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    sudo apt-get install \
      libasound2-dev libfreetype6-dev libdbus-1-dev libunwind-dev \
      zip protobuf-compiler cmake
    ```
  </Tab>

  <Tab title="Fedora">
    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    sudo dnf install \
      alsa-lib-devel freetype-devel libunwind-devel \
      zip protobuf-compiler cmake
    ```
  </Tab>

  <Tab title="macOS (Homebrew)">
    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    brew install tsirysndr/tap/rockbox
    ```

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

    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    brew install freetype cmake protobuf
    ```
  </Tab>
</Tabs>

You'll also need:

* **Zig** ≥ 0.16 — [ziglang.org/download](https://ziglang.org/download/)
* **Rust stable** — `rustup update stable`
* **Deno** — for the web UI build

## Full build

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# 1. Clone with submodules
git clone https://github.com/tsirysndr/rockboxd.git
cd rockboxd
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.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# 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
```

<Warning>
  **Stale binary pitfall.** If behaviour doesn't match the source, check
  mtimes:

  ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
  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.
</Warning>

## Verifying symbols

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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`.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
# 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.