Update BUILD.md: gplan.so can't be built from source on Bullseye

Document GLIBC/GLIBCXX version constraints and Python 3.5 compat notes.
Recommend using official release gplan.so instead.

.pi/BUILD.md

@@ -54,7 +54,23 @@ ELF 32-bit LSB shared object, ARM, EABI5  (linked against libpython3.5m.so.1.0)
 ```
 If you see `ELF 64-bit LSB shared object, ARM aarch64` or `libpython3.9` — wrong.
 
-**Option A: Build from source (recommended)**
+**Option A: From official release (recommended)**
+
+```bash
+curl -sL https://github.com/OneFinityCNC/onefinity-firmware/releases/download/v1.6.6/onefinity-1.6.6.tar.bz2 \
+  | tar xjf - --include='*/gplan.so' -O > src/py/camotics/gplan.so
+```
+
+The gplan.so is pure G-code planning with no version-specific code — safe to
+reuse across firmware versions.
+
+**Option B: From a working Pi**
+
+```bash
+scp bbmc@10.1.10.55:/usr/local/lib/python3.5/dist-packages/bbctrl-*.egg/camotics/gplan.so src/py/camotics/
+```
+
+**Option C: Build from source (broken — documented for reference)**
 
 Uses Docker's armv7 QEMU emulation on Apple Silicon. Requires a one-time
 copy of Python 3.5 headers from the Pi (~1.7MB):
@@ -119,24 +135,23 @@ docker run --rm --platform linux/arm/v7 \
   '
 ```
 
-Why the relink step: SCons compiles `.o` files that are Python-version-agnostic
+**Why this doesn't actually work:** The `.o` files compile fine and the
-(they only use `#include <Python.h>` which is ABI-compatible between 3.5-3.9
+Python relink works, but the compiled objects use GLIBC_2.29+ symbols
-for the subset camotics uses). The only version-specific part is the final
+(from Bullseye's glibc 2.31) and GLIBCXX_3.4.26+ (from GCC 10). The Pi's
-`-lpython3.X` link. So we let SCons build with 3.9 (since it ignores overrides)
+Stretch has GLIBC_2.24 / GLIBCXX_3.4.22 max. Even with `-static-libstdc++
-then relink the same objects against 3.5m.
+-static-libgcc`, glibc symbols like `GLIBC_2.29` leak through the object
+files compiled against Bullseye headers.
 
-**Option B: From official release**
+To truly build from source you'd need a Stretch armhf container — but
+Stretch's archived repos have broken package metadata that prevents
+installing build-essential + scons. The official gplan.so was built
+in a Raspbian Stretch chroot (see `scripts/gplan-init-build.sh`).
 
-```bash
+**Key Pi constraints for native code:**
-curl -L https://github.com/OneFinityCNC/onefinity-firmware/releases/download/v1.6.6/onefinity-1.6.6.tar.bz2 \
+- GLIBC ≤ 2.24 (Stretch)
-  | tar xjf - --include='*/gplan.so' --strip-components=3 -C src/py/camotics/
+- GLIBCXX ≤ 3.4.22 (GCC 6)
-```
+- Python 3.5m (`libpython3.5m.so.1.0`)
-
+- ELF 32-bit ARM EABI5
-**Option C: From a working Pi**
-
-```bash
-scp bbmc@10.1.10.55:/usr/local/lib/python3.5/dist-packages/bbctrl-*.egg/camotics/gplan.so src/py/camotics/
-```
 
 ### bbserial.ko — kernel module
 
@@ -230,6 +245,16 @@ Open http://localhost:8765 — full UI with emulated AVR.
 
 See `backup/onefinity-backup.sh` for details. Environment variables: `ONEFINITY_HOST` (default 10.1.10.55), `ONEFINITY_USER` (bbmc), `ONEFINITY_PASS` (onefinity).
 
+## Python 3.5 Compatibility
+
+The Pi runs Python 3.5.3. Watch out for features added in later versions:
+- No `f"strings"` (use `"%s" % var` or `"{}".format(var)`)
+- No `subprocess.run(capture_output=True)` (use `stdout=PIPE, stderr=PIPE`)
+- No `subprocess.run(text=True)` (use `.decode('utf-8')` on stdout/stderr)
+- No `dataclasses`, no `:=` walrus operator
+- No `asyncio.run()` (use `loop.run_until_complete()`)
+- No `typing` generics like `dict[str, int]` (use `Dict[str, int]` from typing)
+
 ## Pi Details
 
 | | |