gopher64-netplay/docs/build-gate.md

Build gate (review box)

The project's review gate is a single documented command — see scripts/gate.sh:

./scripts/gate.sh        # == git submodule update --init --recursive
                         #    + cargo check --all-targets

It must exit 0 on a clean origin/main checkout before any PR is gated (issue #16: all open PRs were unverifiable because main itself did not build).

Why the defaults were changed (.cargo/config.toml)

The fork's original config had two problems on older / non-LLVM hosts:

1. -C target-cpu=x86-64-v3 for x86_64 — requires AVX2/BMI2 (Intel Haswell, 2013+). On a pre-AVX2 host (the review box is Sandy Bridge, x86-64-v2) cargo applies the target rustflags to build scripts, which then miscompile: num-traits's build script aborted with memory allocation of 648518346341351440 bytes failed (0x0900000000000010 — garbage from executing AVX2 instructions, not real OOM). The default build is now portable; the optimised target is opt-in: RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --release (RUSTFLAGS replaces config rustflags — carry other flags across).
2. [env] AR=llvm-ar forced an LLVM archiver that is not installed in the provisioned root — dropped; the platform ar (GNU binutils) archives clang objects fine. CC=clang/CXX=clang++ are retained because build.rs compiles the parallel-rdp / retroachievements C sources with clang-only flags (-flto=thin); cc-rs resolves clang via PATH, so a host simply needs clang on PATH (the review box gets it from the user-local LLVM root via gate.sh). CMAKE_POLICY_VERSION_MINIMUM=3.5 is retained (cmake >= 4 needs it for freetype); SDKROOT is retained for macOS SDK discovery.

Host prerequisites (Linux)

• cargo/rustc (toolchain pinned in rust-toolchain.toml)
• clang/clang++ on PATH (build.rs, see above)
• cmake (SDL3, freetype), ar, a real pkg-config
• fontconfig dev (the GUI text stack pulls yeslogic-fontconfig-sys through slint → parley → fontique) and X11 dev (SDL3's video backend; the fork's own src/ui.rs uses sdl3_sys::video directly)
• libclang (LIBCLANG_PATH) for the bindgen build-dependency's clang-sys probe

The review box has no system packages for any of these and no sudo, so user-local roots extracted from Ubuntu .debs are provisioned:

• ~/local-tools/root/usr/lib/llvm-18/bin — clang/clang++/clang-18 (plus cmake, ninja, pkgconf, wayland-scanner in ~/local-tools/root/usr/bin), libclang-18.so in ~/local-tools/root/usr/lib/llvm-18/lib
• ~/.local/bin-fc/pkg-config — wrapper that execs the real pkgconf (the pypi pkg-config/pkgconf-pypi shims on ~/.local/bin wrongly report exit 0 for missing packages, which makes cmake enable optional SDL backends)
• ~/.local/fcroot/usr/lib/x86_64-linux-gnu/pkgconfig — fontconfig.pc, freetype2.pc, zlib.pc, expat.pc, libpng16.pc, X11 pc files, with matching headers and shared libs in the same root

scripts/gate.sh wires all of these onto PATH/env when present; on hosts with system toolchains the provisioning blocks are no-ops.

Troubleshooting

• memory allocation of 648518346341351440 bytes failed (SIGABRT in a dependency build script) — an x86-64-v3 (or other AVX2-only) flag is being applied on a pre-AVX2 CPU. Remove the flag / use the portable default.
• cc1: error: unrecognized argument to '-flto=' option: 'thin' — build.rs requires clang; gcc rejects -flto=thin. Put clang on PATH (or run via scripts/gate.sh on the review box).
• failed to find tool "clang" inside ring's build — clang is missing from PATH.
• Package 'fontconfig' not found — PKG_CONFIG_PATH is not pointing at a fontconfig dev root (or the pypi pkg-config shim is intercepting).
• SDL cmake: SDL could not find X11 or Wayland development libraries — CMake's FindX11 needs CMAKE_INCLUDE_PATH/CMAKE_LIBRARY_PATH pointed at the X11 dev root (pkg-config alone is not consulted for X11).