# Build gate (review box)

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

```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.