Building Kirin¶

Two build roots¶

The repository has two valid CMake entry points, and picking the wrong one is the most common source of confusion:

The superbuild at the repository root composes everything — engine, hardware layer, CLI, tests and the Qt/QML touch GUI. This is what a board runs.
The engine subproject under kirin/ builds the engine, hardware layer, CLI and tests only. It remains independently buildable on purpose, so the engine can be worked on (and tested) without a Qt toolchain present.

Whole system (engine + hardware + CLI + tests + GUI)¶

git clone git@github.com:strvdr/kirin-autonomous-chess.git
cd kirin-autonomous-chess
cmake -S . -B build-system
cmake --build build-system -j

This produces two binaries: kirin (the CLI and UCI engine) and kirin-gui (the touch application). The GUI links kirin_engine and kirin_hardware in-process — there is no IPC and no engine daemon (decision D-50, in the application part, explains why).

Superbuild switches, all ON by default:

Option	Effect
`-DKIRIN_BUILD_GUI`	build the Qt/QML touch application
`-DKIRIN_BUILD_CLI`	build the `kirin` command-line binary
`-DKIRIN_BUILD_TESTS`	build the CTest suites
`-DKIRIN_ENABLE_GPIOD`	Raspberry Pi GPIO — off by default

Engine subproject only¶

cmake -S kirin -B build      # defaults to Release: -O3 -march=native -flto
cmake --build build
ctest --test-dir build       # full suite, no hardware required

Note

-march=native bakes in the build machine’s instruction set. That is right for a development bench and wrong for a distributable artifact — the OTA pipeline deliberately targets -mcpu=cortex-a76 instead, so a bundle built by CI runs on every Pi 5 in the fleet. See the fleet part.

GPIO support¶

GPIO is off by default. Without it the sensor scanner and operator buttons work only in simulation, which is what makes the whole suite runnable on a laptop:

cmake -S kirin -B build -DKIRIN_ENABLE_GPIOD=ON   # Pi only; needs libgpiod v2

Warning

There are several pre-existing kirin/build-* directories (build-bench, build-tc, build-codex) used for benchmarking and SPRT runs. They are not stale copies of the canonical build/ — don’t delete them and don’t confuse them for it.

Running the engine¶

The kirin binary has four run modes; kirin --help lists every flag.

Mode	Flag	Use
UCI	(default)	standard UCI engine for GUIs and testing
Physical	`--physical PORT` / `--boot`	live game on real hardware
Simulation	`--simulate`	interactive, no hardware
Dry run	`--dryrun [MOVES [DEPTH]]`	engine-vs-engine, prints every G-code command

--boot is the headless variant of physical mode, used by the systemd unit on the Pi. Hardware diagnostics live behind --oled-test, --sensor-diag, --gpio-led and --led-test.

Using Kirin as a UCI engine¶

Kirin speaks standard UCI, so it drops into any compatible GUI or automated harness. A minimal hand-driven session:

user  >> uci
kirin >> id name Kirin
kirin >> id author Strydr Silverberg
kirin >> option name Skill Level type spin default 2 min 0 max 2
          ... (see Appendix C for the full option surface)
kirin >> uciok

user  >> ucinewgame
user  >> isready
kirin >> readyok

user  >> position startpos moves e2e4 e7e5
user  >> go depth 12

The engine supports go depth, go nodes, go movetime, and the managed clock form go wtime/btime/winc/binc. Which one you choose matters for testing: Ch. Measuring Strength explains why go nodes is the reproducible choice for A/B comparison and why --tc is the only way to exercise the time-management path.