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   (type-check)
                         #    + cargo test --no-run         (link tests)
                         #    + cargo test --lib            (run headless lib tests)

It must exit 0 (GATE_OK) on a clean origin/main checkout before any PR is gated (issue #16: all open PRs were unverifiable because main itself did not build; review bounce: the gate previously also stopped at cargo check — compiled but never linked or ran tests).

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-tools/root/usr/lib/x86_64-linux-gnu — the shared-lib root of the SAME provisioned tree as the cmake/ninja above. Those binaries link against librhash.so.0, libuv.so.1, libjsoncpp.so.25 from this directory; without it on LD_LIBRARY_PATH cmake dies at exec time with error while loading shared libraries: librhash.so.0 (exit 127) and cmake-rs misreports it as is "cmake" not installed?. gate.sh adds this root (see the LLVM_BIN2 block), exactly like the other two roots.
• ~/.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.

What the gate runs, and why

Three steps, so a failure is attributable to exactly one phase:

1. cargo check --all-targets — type-checks every target including tests. This is the historical blocker phase (#16: num-traits SIGABRT under the old target-cpu=x86-64-v3).
2. cargo test --no-run — LINKS every test binary. A test that type-checks but cannot link is still a broken gate; cargo check alone never proves linkability. This answers the review question "the gate compiles the tests but never runs them" for the link half.
3. cargo test --lib — EXECUTES the library unit tests (headless: the netplay state-sync/rollback logic; no window or device needed). Test execution was deliberately NOT assumed: this step is wired in because it completes on the review box. main currently has 0 #[test] fns (measured in the #16 review; the inbound netplay PRs add ~38), so a clean run reports 0 passed — the mechanism, not the coverage, is what this gate guarantees until those PRs land.

Decision record: cargo test --no-run and cargo test --lib were both verified to complete here; running the full cargo test (which would also run windowed/bin tests) was not wired because it needs an interactive display and the review box's gate must stay headless-deterministic.

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).
• cmake: error while loading shared libraries: librhash.so.0 (exit 127), reported by cmake-rs as is "cmake" not installed? — the provisioned cmake/ninja need their OWN root (~/local-tools/root/usr/lib/x86_64-linux-gnu) on LD_LIBRARY_PATH; gate.sh's LLVM_BIN2 block does this. This was the issue #16 review bounce.