800495c912
Some checks failed
Rust / build-linux (linux-x86_64, X64, ubuntu-24.04, x86_64-unknown-linux-gnu) (pull_request) Failing after 8s
Rust / build-android (29.0.14206865, ubuntu-24.04, 33) (pull_request) Failing after 5s
Rust-lint / lint-linux (pull_request) Failing after 21s
Rust / build-linux (linux-aarch64, ARM64, ubuntu-24.04-arm, aarch64-unknown-linux-gnu) (pull_request) Has been cancelled
Rust / build-windows (windows-aarch64, woa64, windows-11-arm, aarch64-pc-windows-msvc) (pull_request) Has been cancelled
Rust / build-windows (windows-x86_64, win64, windows-2025, x86_64-pc-windows-msvc) (pull_request) Has been cancelled
Rust / build-macos (macos-aarch64, ARM64, aarch64-apple-darwin) (pull_request) Has been cancelled
Rust / Collect release artifacts (pull_request) Has been cancelled
Review findings addressed (PR #17 bounce): 1. gate.sh put the provisioned cmake/ninja on PATH but never added their OWN lib root to LD_LIBRARY_PATH, so cmake died with exit 127 (librhash.so.0 / libuv.so.1 / libjsoncpp.so.25 not found) and cmake-rs misreported 'is cmake not installed?'. The LLVM_BIN2 block now exports LD_LIBRARY_PATH=~/local-tools/root/usr/lib/x86_64-linux-gnu (same append pattern as the other two roots; final value carries all three). 2. The gate was compile-only. It now runs three steps: cargo check --all-targets (type-check), cargo test --no-run (LINK every test binary), cargo test --lib (EXECUTE headless lib unit tests). 3. docs/build-gate.md: prerequisites list the provisioned cmake's shared-lib root, the test-execution decision record, and the new troubleshooting entry. Verified on the review box: cold full gate exits 0 (GATE_OK), step 1 check then 11m52s test-link codegen then 'running 0 tests / ok' (main has no #[test] fns yet; the inbound netplay PRs add ~38); warm re-run 5.6s.
123 lines
6.5 KiB
Markdown
123 lines
6.5 KiB
Markdown
# 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.
|