Docker 대신 호스트에 직접 올릴 때도 절차는 짧다. 엔진도 도구도 빌드도 C++·CMake·셸로만 이루어져 있어서 Python이 전혀 필요 없다. 이 글은 docs/GUIDE.md §1(Install)을 따른다.

요구 사항

구분	내용
필수	Linux, C++20 컴파일러, CMake 3.21+, Ninja, pthreads
선택	ROCm(hipcc) — AMD 장치 커널용. 없으면 호스트 백엔드만 빌드된다. /opt/rocm이 아니면 ROCM_PATH 설정
카드 사용 시	Resizable BAR (펌웨어의 Above 4G Decoding + Re-Size BAR). 꺼두면 디스패치 인자가 고정 호스트 메모리에 머물러 카드가 링크로 매번 읽는다 — R9700에서 Qwen3.8-27B fp8 디코딩이 0.4~1.8% 늘어난다. P2P도 큰 BAR 필요
카드 사용 시	amdgpu.cwsr_enable=1 (기본값). 꺼지면 드라이버가 선점 못 해 카드가 멈춘다. radiance는 그런 카드에서 시작을 거부하고 고칠 것을 알려준다
선택	OpenMP(호스트 커널), ffmpeg 6+ 개발 라이브러리(이미지·비디오·오디오 입력), curl·jq(셸 하네스)

HTTP 서버, JSON 라이브러리, llama.cpp 관련 부분은 vendor/에 벤더링되어 있다. ROCm 10.1로는 VOPD 페어링을 꺼서 빌드한다(같은 소스를 두 번 컴파일해 다른 코드를 내는 컴파일러 문제). Docker 이미지는 패치된 컴파일러로 페어링을 켜고, 같은 수정이 들어간 컴파일러는 -DRAD_HIP_VOPD_REPEATABLE=ON로 선언한다. ROCm 7.2는 해당 없다.

빌드: build.sh 한 번

git clone https://codeberg.org/StillDeadcode/radiance.git radiance && cd radiance
./build.sh

build.sh는 구성 → 빌드 → 빠른 테스트 실행까지 한다. hipcc가 있고 카드를 열거할 수 있으면 그 카드 아키텍처로 장치 커널을 컴파일하고, 아니면 호스트 백엔드가 된다. 기본 플래그:

./build.sh -c          # 빌드 디렉터리 비우고 시작
./build.sh --no-hip    # hipcc가 있어도 호스트 백엔드 강제
./build.sh --debug     # Debug 빌드
./build.sh --asan      # AddressSanitizer+UBSan, build-asan/
./build.sh --tsan      # ThreadSanitizer, build-tsan/
./build.sh -b mybuild  # build/ 대신 다른 디렉터리

CMake를 직접 쓰거나 프리셋을 써도 된다.

cmake -S . -B build -G Ninja
cmake --build build -j
ctest --test-dir build -L fast -j8 --output-on-failure
# 또는: cmake --preset default / asan / tsan

ROCm이 /opt/rocm 밖(가상환경 안의 사용자 공간 SDK 등)에 있으면 ROCM_PATH만으로는 모자라고 hipcc·HIP 컴파일러·device-lib·--gcc-install-dir를 직접 짚어줘야 한다. GUIDE §1.2에 전체 configure 명령이 나와 있고, 결국 Docker 이미지가 이 문제를 피하는 가장 손쉬운 길이기도 하다.

카드가 없다면: 호스트 백엔드

GPU 없는 머신은 1급 지원 대상이다. 호스트 백엔드는 완전하다 — 코어, 스케줄러, 플래너, 토크나이저, 서버가 그대로 돌아가고, libavx(AVX-512/AVX2, 로드 시 CPU 기능으로 선택)가 동봉 모든 모델의 모든 op를 서빙하며, 테스트 전체가 통과한다. 작은 모델은 데스크톱 CPU에서 대화 가능 속도, 27B 이상은 카드보다 훨씬 느리게 돈다. ROCm 빌드나 컨테이너 이미지도 카드가 안 보이는 머신에서는 자동으로 모든 op를 호스트 커널로 돌린다.

테스트 계층

테스트는 레이블로 계층이 나뉜다. build.sh가 도는 것은 fast뿐이다.

실행	선택하는 것	시간(16코어 기준)
ctest --preset fast	인너 루프. build.sh가 도는 것	약 10초
ctest --preset host	카드 없이 도는 전부	약 1.5분
ctest --preset gpu	카드가 필요한 것(하나씩, 카드 독점)	분 단위
ctest --preset perf	월클록 단언 테스트(각각 단독)	초 단위
ctest --preset asan	build-asan/에서 fast 계층	약 4분

커널을 검사하는 테스트도 별도로 있다. rad-kbench(레이블 kbench)는 기록된 픽스처로 라이브러리별 커널을 libref의 기준 답과 비교하고, r4d_selftest는 libr4d의 퓨전이 대체하는 unfused 커널과 바이트 단위로 결과가 같은지 본다. 커널 점검을 손으로:

build/bin/rad-kbench --home build/radiance_home --max-cases 1

각 테스트 바이너리는 --list, 패턴 필터, --shard 1/4 같은 공통 인자를 받고, CPU 예산을 넘기면 실패로 처리된다.

설치와 RADIANCE_HOME

설치는 빌드 디렉터리를 처음 구성할 때 prefix를 정해야 한다. 기본 플러그인 경로 <prefix>/share/radiance가 첫 configure에 컴파일해 박히기 때문에, 나중에 cmake --install build --prefix DIR만 하면 플러그인을 딴 곳에서 찾는 트리가 생긴다.

cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/opt/radiance
cmake --build build -j
cmake --install build

prefix에는 bin/(radiance, rad-convert, rad-info, rad-kbench, rad-tune, rad-schemas, rad-tokcheck), include/radiance/(ABI 헤더), lib/cmake/radiance/, libexec/radiance/(다운로더), share/radiance/가 들어간다.

$RADIANCE_HOME은 엔진과 모든 도기가 시작할 때 훑는 디렉터리다.

$RADIANCE_HOME/
  kernels/         커널 라이브러리     libr4d.so, libref.so, libavx.so, yours.so
  architectures/   아키텍처 플러그인   qwen4exp_fp8.so, llama_fp8.so, ...
  quantizers/      양자화기 플러그인   libquant.so
  kernels.rkb      rad-kbench가 재생하는 커널 픽스처
  tune/            rad-tune의 기종별 튜닝 캐시

RADIANCE_HOME 또는 --radiance-home으로 :로 구분된 검색 경로를 줄 수 있고 앞의 것이 이긴다. 자기 플러그인 디렉터리를 설치본 앞에 둘 수 있다는 뜻이다. 빌드 트리에서 작업할 때는 build/radiance_home이 home이다.

export RADIANCE_HOME=$PWD/build/radiance_home
build/bin/radiance --model m.rad --port 8000
RADIANCE_HOME=$HOME/my-plugins:/opt/radiance/share/radiance rad-info --plugins

없는 카드용 빌드

장치 커널은 머신이 보고하는 아키텍처로 컴파일되지만, 없는 카드를 목표로 삼을 수도 있다.

cmake -S . -B build -G Ninja -DRAD_GPU_TARGETS='gfx1201;gfx1200'

각 커널 라이브러리는 자기가 서빙하는 아키텍처를 선언하고, 대상에 없는 빌드에서는 빠진다. 엔진 자체의 장치 코드는 모든 families의 generic target로 항상 빌드된다 — 새 카드를 지원하는 일은 엔진 포크가 아니라 kernels/에 .so 하나 넣는 일이다(PLUGIN.md §10). 이 주제의 플러그인 작성에서 이어서 다룬다.