Contributing and Building

Contributing and Building

The generator is a C++23 project. Generated C++ targets C++17. The top-level CMakeLists.txt requires CMake 4.5.0-rc1; lower CMake versions cannot compile the project. Dependencies are declared in vcpkg.json. Linux builds use Clang with libc++; Windows builds use MSVC. GCC generator builds are not supported.

Linux

Set your compiler and point CMake at your vcpkg checkout:

export CC=clang-20 CXX=clang++-20
export CFLAGS=-stdlib=libc++
export CXXFLAGS=-stdlib=libc++
export LDFLAGS=-stdlib=libc++
cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE="$PWD/cmake/toolchains/clang-libcxx.cmake" \
  -DVCPKG_TARGET_TRIPLET=x64-linux-libcxx \
  -DVCPKG_OVERLAY_TRIPLETS="$PWD/cmake/triplets"
cmake --build cmake-build-release

Choose a Clang installation available on your system. The toolchain file is named clang-libcxx.cmake (with two x's).

Windows

Use an MSVC Developer Command Prompt with CMake, Ninja, and vcpkg:

cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="%VCPKG_INSTALLATION_ROOT%/scripts/buildsystems/vcpkg.cmake"
cmake --build cmake-build-release

Tests and architecture

The C++ tests live in tests/; Python package tests use tests/test_ispa_pkg.py. src/ holds the generator frontend, DFA, semantics, diagnostics, and UAST; lib/algorithm/ holds LL/LR plugins; lib/converter/ holds C++ and Python emitters. parser/ contains bootstrapped grammar parsers and the target runtime. See parser/README.md, lib/algorithm/README.md, and docs/LR_STATUS.md before changing those parts.

The generator loads algorithm and converter plugins beside the executable. Plugin binaries must match the host's API, compiler, and standard library. Incremental cache records are versioned and fall back to a cold build when incompatible.