Linux loader-assist: install the .so without sudo (spike)

[SethMorrowSoftware]

Goal

Let Linux users run Box2Dxt without sudo — and ideally without any per-user setup at all — by making "drop box2dxt.so next to the stack" work on Linux the way it already does on Windows/macOS.

The problem

On Linux the OXT/LiveCode engine hands the bare name box2dxt.so to dlopen and never searches the stack's folder, so today the library must sit on a system search path — typically sudo cp box2dxt.so /usr/lib/ && sudo ldconfig.

The approach (this spike)

Preload the shim by absolute path before the first physics call. Once it's in the process, the engine's later bare-name dlopen("box2dxt.so") resolves to the already-resident copy. glibc matches an already-loaded object by soname, not filename, so this only works if the soname is exactly box2dxt.so.

• src/box2dxt.lcb — bind the platform dlopen/dlerror (resolved from the host process, so callable before box2dxt.so is loadable) and expose b2LoadNativeLib(path) / b2LoadNativeLibError(). No new C ABI symbol, so b2Version() stays 4.
• CMakeLists.txt — opt-in -DBOX2DXT_BARE_SONAME=ON builds the library under its bare deploy name so its soname is box2dxt.so. Default OFF keeps the historical libbox2dxt.* artifact, so nothing in the existing build/CI/docs changes yet.

Verified locally (build half)

Build	Artifact	soname
default (flag off)	libbox2dxt.so	libbox2dxt.so
-DBOX2DXT_BARE_SONAME=ON	box2dxt.so	box2dxt.so

The default-build control proves why a plain file rename can't work: renamed to box2dxt.so, the soname is still libbox2dxt.so.

Needs an OXT pass (the spike question)

Two things can only be confirmed in OXT:

1. Does c:>dlopen bind? (Fallback tokens for libc/libdl are noted in the .lcb.)
2. Does the engine honor the preloaded copy — i.e. after b2LoadNativeLib("/abs/path/box2dxt.so") returns 1, does b2Version() return 4 with the .so on no search path?

If yes, the follow-up is to wire the Kit to call b2LoadNativeLib automatically (Linux-gated) at startup, flip the soname default on, and update docs/CI. If no, fall back to the per-user ~/.local/lib self-installer.

https://claude.ai/code/session_01EVV5fGeXqtWs8WDrmgWNku

---

Generated by Claude Code