Building zaya (C++ / ROCm)

This document covers building zaya — a pure C++ inference server with optional GPU decoding support, one entry point of the single binary build/1bit (run via 1bit zaya). No Rust, no Python at runtime. The host CPU is AMD Strix Halo (Ryzen AI Max+ 395) and GPU acceleration uses TheRock 7.15.0a targeting gfx1151.

zaya_server is no longer a standalone CMake build target — its full source list is compiled into onebin/build/1bit only (see CMakeLists.txt). Build onebin and run the server via ./build/1bit zaya [flags]. Packaged installs (tarball/deb) do still ship a zaya_server symlink to that same binary for convenience, but there is no separate zaya_server binary to build from source.

Prerequisites

Install system dependencies:

sudo apt update
sudo apt install -y cmake ninja-build build-essential git

TheRock 7.15.0a

# Install TheRock HIP SDK for gfx1151 (Strix Halo)
pip install --index-url https://rocm.nightlies.amd.com/whl-multi-arch/ \
  "rocm[libraries,devel,device-gfx1151]"
export THEROCK_PIP_ROOT="$HOME/.cache/pip/therock"

# Verify
which amdclang++

The CMake build system auto-discovers TheRock (see CMakeLists.txt): /opt/rocm-therock → $THEROCK_PIP_ROOT → ~/.cache/lemonade/bin/therock.

Set CMAKE_HIP_ARCHITECTURES so that HIP kernels are compiled for Strix Halo:

export CMAKE_HIP_ARCHITECTURES=gfx1151

It is convenient to add this to your shell profile:

echo 'export CMAKE_HIP_ARCHITECTURES=gfx1151' >> ~/.bashrc

Build: zaya (required)

Clone the repository and build the main server binary:

# Clone (adjust URL to match your remote)
cd ~
git clone <your-repo-url> zaya
cd zaya

# Configure — TheRock is auto-detected (see CMakeLists.txt); never point
# CMAKE_PREFIX_PATH at system ROCm (/opt/rocm).
cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_HIP_ARCHITECTURES=gfx1151

# Build the single binary (zaya, unified, jarvis, vision, and the CLI all
# live in this one target — there is no standalone `zaya_server` target)
cmake --build build --target onebin

The resulting binary is build/1bit. Run the zaya server via ./build/1bit zaya [flags] (the packaged tarball/deb also installs a zaya_server symlink to the same binary for backward compatibility, dispatched by argv[0]).

NPU backend: FastFlowLM (flm)

The NPU backend spawns the flm binary (FastFlowLM, now an official AMD/ROCm project). CMake finds it in this order — no source build needed for the first two:

1. TheRock dist (<therock-root>/bin/flm) — FLM ships built into TheRock 7.14/7.15a
2. FastFlowLM .deb (/opt/fastflowlm/bin/flm) — the prebuilt release package from FastFlowLM releases, the same binary Lemonade Server tracks and stays in sync with
3. flm on PATH (/usr/bin/flm — the .deb symlink, also how Lemonade finds it)
4. Submodule build (third_party/FastFlowLM) — last resort

# Preferred: install the prebuilt package instead of building the submodule
sudo apt install ./fastflowlm_0.9.46_ubuntu26.04_amd64.deb

Build: zaya_gpu_decode (optional)

If your model uses the Q4NX quantisation format, you can build zaya_gpu_decode to offload the dequantisation and matmul steps to the GPU:

cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_HIP_ARCHITECTURES=gfx1151 \
  -DZAYA_ENABLE_GPU_DECODE=ON

cmake --build build --target zaya_gpu_decode

The resulting shared library (or object) is build/libzaya_gpu_decode.so.

Note: zaya_server will auto-detect the presence of this library at startup and use it when loading Q4NX models. Building without ZAYA_ENABLE_GPU_DECODE disables GPU decode; the server still runs, but inference stays entirely on CPU.

Build: llama.cpp with ROCm backend (optional)

If the server depends on llama.cpp and you want its inference to use the same ROCm device:

# Either bundled in the zaya repo or standalone
cd path/to/llama.cpp

cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_HIP_ARCHITECTURES=gfx1151 \
  -DGGML_HIP=ON

cmake --build build --target llama

Then ensure zaya_server's CMake configuration points to this build (e.g. via -DLLAMA_DIR=/path/to/llama.cpp/build during the zaya configure step).

CMake option summary

Running

./build/1bit zaya --model /path/to/model

If libzaya_gpu_decode.so was built and is findable, the server will print a message at startup confirming GPU decode is active.

Troubleshooting

hipErrorNoBinaryForGPU

The CMAKE_HIP_ARCHITECTURES variable was not set, or was set to the wrong target. Ensure it is gfx1151 and that TheRock 7.15.0a is installed (older ROCm releases may not include code-objects for gfx1151).

cannot find -lamdhip64

ROCm is not on the linker path. Make sure TheRock is installed at /opt/rocm-therock (or set THEROCK_PIP_ROOT) — CMakeLists.txt auto-detects it; never point CMAKE_PREFIX_PATH at system ROCm (/opt/rocm).

No GPU decode even though zaya_gpu_decode was built

Check that the shared library is in the library search path:

export LD_LIBRARY_PATH=/path/to/zaya/build:$LD_LIBRARY_PATH

Also verify the model file is actually Q4NX (check the file header or extension).

Kernel hang on first inference on Strix Halo (issue #1)

Strix Halo (gfx1151) systems may hit an amdgpu OPTC hang on the first GPU kernel launch after cold boot. The hang is intermittent (~1 in 5 boots).

Symptoms: first inference call hangs; dmesg shows OPTC lockup messages; reboot required.

Mitigation:

export HSA_ENABLE_SDMA=0   # avoids the triggering OPTC code path

See issue #1 for details.