build: scripts/sccache.sh wraps rustc when sccache is installed, and the gates source it

A build cache serves a dependency rebuild after a branch switch or a `git clean` instead of
recompiling it, which is most of what the in-loop verify spends. It stays a convenience and
never a requirement: with nothing on `PATH` nothing is exported and a clone needs only stable
Rust and a C compiler, exactly as before.

`check.sh`, `gates.sh` and `smoke.sh` source it, so the loops pick it up without being asked
and a machine that would rather not have it sets `BENILLA_NO_SCCACHE=1`. An existing
`RUSTC_WRAPPER` wins. Only rustc is wrapped — the vendored Lua build wants its own
`CC="sccache cc"`, so it is not cached by this.

docs/CONTRIBUTING.md

@@ -59,6 +59,13 @@ out of scope is closed with the reason.
   compiler, because the client's Lua is vendored and built from source. On macOS the Xcode
   command line tools, which also supply libclang for the audio bindings; on Linux the ALSA and
   udev development packages and pkg-config. `python3` runs two of the gates.
+- **A build cache (optional).** [`sccache`](https://github.com/mozilla/sccache) serves a dependency
+  rebuild after a branch switch or a `git clean` from cache instead of recompiling it.
+  `scripts/check.sh`, `scripts/gates.sh` and `scripts/smoke.sh` use it automatically when it is on
+  `PATH`; for the play loop, `. scripts/sccache.sh && cargo play`, or `scripts/sccache.sh cargo
+  play`, wraps one command. Without it a clone builds exactly as before; an existing `RUSTC_WRAPPER`
+  wins and `BENILLA_NO_SCCACHE=1` skips it. It does not wrap the C compiler, so the vendored Lua
+  build is not cached by it.
 - **A 1.12.1 install of your own.** `WOW_DATA=<its Data folder>`, or a `WoW` link at the repo
   root, which only a dev build sees: the player build looks for `Data/` or `WoW/Data/` beside
   the binary. benilla reads the install and never writes into it. `WOW_DATA=` (set, empty)

scripts/check.sh

@@ -15,6 +15,9 @@ root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$root" ] && [ -f "$root/scripts/check.sh" ] || root="$here"
 cd "$root" || exit 1
 
+# sccache, when installed, caches the builds below; opt out with BENILLA_NO_SCCACHE=1.
+. "$root/scripts/sccache.sh"
+
 if [ "${CHECK_FULL:-}" = "1" ]; then
     exec "$root/scripts/gates.sh"
 fi

scripts/gates.sh

@@ -18,6 +18,9 @@ here="$(cd "$(dirname "$0")/.." && pwd)"
 root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$root" ] && [ -f "$root/scripts/gates.sh" ] || root="$here"
 cd "$root" || exit 1
+
+# sccache, when installed, caches the builds below; opt out with BENILLA_NO_SCCACHE=1.
+. "$root/scripts/sccache.sh"
 echo "gating: $root"
 
 # ── Green-stamp memoization ──────────────────────────────────────────────────────────────────────

scripts/sccache.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Use sccache for rustc when it is installed. It is a developer convenience, never a requirement:
+# without it nothing is exported and a clone needs only stable Rust and a C compiler.
+#
+# Sourced, it exports RUSTC_WRAPPER into the current shell for later cargo commands; run with a
+# command, it wraps just that command. The verify, land and smoke scripts source it themselves.
+#
+#   . scripts/sccache.sh && cargo play
+#   scripts/sccache.sh cargo play
+#
+# An existing RUSTC_WRAPPER wins, BENILLA_NO_SCCACHE=1 skips this, and SCCACHE_DISABLE=1 turns
+# sccache itself off. Only rustc is wrapped: the vendored Lua build wants its own `CC="sccache cc"`.
+# Sourced, it must not change the caller's shell options.
+enable() {
+    [ -n "${RUSTC_WRAPPER:-}" ] && return 0
+    [ -n "${BENILLA_NO_SCCACHE:-}" ] && return 0
+    command -v sccache >/dev/null 2>&1 || return 0
+    export RUSTC_WRAPPER=sccache
+}
+
+enable
+# Executed with a command: run it wrapped. Sourced: leave the caller's positionals alone.
+if [ "${BASH_SOURCE[0]}" = "$0" ] && [ "$#" -gt 0 ]; then
+    exec "$@"
+fi

scripts/smoke.sh

@@ -16,6 +16,9 @@ if [ -z "$root" ] || [ ! -f "$root/scripts/smoke.sh" ]; then
     root="$(cd "$(dirname "$0")/.." && pwd)"
 fi
 cd "$root" || exit 1
+
+# sccache, when installed, caches the client build below; opt out with BENILLA_NO_SCCACHE=1.
+. "$root/scripts/sccache.sh"
 echo "smoke: $root"
 
 # Resolve the account first, then unset every inherited WOW_* the case below does not keep, so