specbolt: Instructions file for Claude Code

Build

Needs CMake 3.30+, Ninja, SDL2 and readline, and a compiler that suits the preset:

• the plain presets: clang 20+ or gcc 16+;
• the modules presets: clang 20+ with libc++, or gcc 16+ with libstdc++ (CI builds debug-modules with both, since gcc enforces module rules clang lets through);
• the reflection presets: gcc 16+, or a P2996 clang fork (see below);
• the wasm preset: clang with a WASI sysroot; see README.md.

Presets live in CMakePresets.json. The common ones:

cmake --preset debug            # Debug, no modules; works with clang or gcc
cmake --preset debug-modules    # Debug with C++ modules (needs clang + libc++)
cmake --preset release          # RelWithDebInfo, no modules (runs zexdoc tests)
cmake --preset debug-reflection # Debug with C++26 reflection (needs gcc 16+ or a P2996 clang)
cmake --preset release-reflection # RelWithDebInfo with reflection; runs zexdoc for v4 too
cmake --build --preset debug
ctest --preset debug

Pick the compiler with CC=… CXX=… or by setting CMAKE_CXX_COMPILER in a local CMakeUserPresets.json (gitignored) that inherits from one of the public presets.

The zexdoc regression tests are intentionally skipped in Debug (too slow); they run in RelWithDebInfo.

Run: ./build/debug/sdl/specbolt_sdl

C++26 reflection

Reflection (P2996) needs gcc 16+ or one of the P2996 clang forks; no clang release implements it, and the WASI build is on stock clang, so anything reflective must be optional. cmake/reflection.cmake probes for it, including the extra flags clang wants, and exposes:

• SPECBOLT_HAS_REFLECTION: true when the compiler can do it. Exclude reflective targets with if (SPECBOLT_HAS_REFLECTION), and guard reflective code on the SPECBOLT_REFLECTION macro.
• SPECBOLT_REFLECTION cache variable: AUTO (default, use if available), ON (require it; configure fails otherwise), OFF.

-freflection rides on opt::c++26 so it reaches every specbolt target uniformly. It's a dialect switch: gcc can't merge a module built without it into a TU built with it (importing one fails with conflicting declarations for types reachable both textually and through the module), and it needs -std=c++26, so applying it globally breaks third-party targets built at the default standard.