Linux wheels¶
libstdc++ is never bundled — and must never be¶
The single most important rule for the Linux wheels: the gcc runtime
(libstdc++.so.6, libgcc_s.so.1) must come from the host or the active
conda/pixi env, never from the wheel. auditwheel never bundles it (manylinux
policy), and the test_python_ver action (.github/actions/test_python_ver),
which wheels.yml runs in the build jobs and test-artifacts, asserts the
installed wheel ships no copy.
Why (gh-119 forensics, 2026-06-10)¶
Wheels ≤ 0.35.0.4 bundled the conda env's gcc-14 libstdc++.so.6 (the
ldd-closure copied everything outside /usr/lib, and the conda prefix carries
its own gcc runtime). Our libraries resolved it via $ORIGIN rpath while
numpy/scipy — manylinux wheels that never vendor libstdc++ — loaded the system
copy. Result: two libstdc++ copies in every numpy-importing process.
That dual-copy state corrupts the heap: gcc emits template statics (the
std::locale facet registries that std::regex depends on) as
STB_GNU_UNIQUE symbols, which the dynamic loader unifies across the two
copies — so code inlined against one copy operates on the other copy's
internal state. Concretely, Environment.init → PropertyTree::
rebuildAutoValidators → isSequenceType → std::regex compile ends up calling
free() on a stack address (valgrind shows the wrong-vtable-slot callee
codecvt::do_unshift inside _BracketMatcher::_M_ready()).
Key experimental facts (seven rounds of no-build CI experiments against released PyPI wheels; results emitted as check-run annotations):
- Every released Linux wheel since at least 0.35.0.3 crashes, both arches — the bug predates the conda-deps migration and the GH #35 preload.
- Import order is irrelevant (numpy-first and tesseract-first both crash).
- Any single active copy is clean:
LD_PRELOADing either the system or the bundled copy fixes it, as does not importing numpy, as does deleting the bundled copy so the RPATH falls through to the system one. - glibc's
double free or corruption (top)abort is detection, not occurrence:free(stack-address)is UB that glibc only catches when the fake chunk trips its heuristics. In allocation-rich processes (the pytest suite) the same free corrupts silently — the suite was never protected, only undetected. - With the bundled copy removed,
env.init+ kinematics run clean and the process then hits the second latent bug: the gh-72 teardown crash (Environment destroyed before plugin-backed objects → plugin.sos dlclosed → destructors virtual-call unmapped pages), fixed bynb::keep_alive<0, 1>on the Environment getters.
The GH #35 preload is gone¶
__init__.py used to RTLD_GLOBAL-preload the bundled copy so it would win
the SONAME race against numpy on old distros. Its premise — "two copies
coexist safely, the newer one wins" — is exactly what the forensics falsified,
and it could never help numpy-first processes anyway (it ran too late). Do not
reintroduce it.
Supported libstdc++ floor¶
The wheels are built on Ubuntu 24.04 with its gcc 13 and tagged
manylinux_2_39, so pip installs them only where glibc is 2.39 or newer
(Ubuntu 24.04+, Debian 13+), which also carry a gcc-13 era libstdc++.
Plugin bundling¶
Plugin factory libraries are dlopen'd by boost_plugin_loader, so the linker
would never see them. The collision, kinematics and task composer modules link
them anyway and register them through their anchors (see
binaries), so auditwheel bundles them with the
rest of the closure. Objects created by those plugins carry vtables that live
in the plugin .sos; binding-level nb::keep_alive<0, 1> on every
Environment getter returning plugin-backed objects keeps the Environment (and
so the loader and the mapped plugins) alive as long as any such object exists.
Wheel/development dependency drift¶
pixi run check-wheel-sources compares dependencies.rosinstall with the
tesseract, tesseract_planning, and trajopt development submodule revisions.
The wheel jobs run it before building dependencies. Update the source manifest
when those submodules change; this check does not certify the provenance of an
externally built conda package.
The wheel dependency set uses vcpkg release 2026.10.16, the release used by
PR #394's successful build, instead of following the latest release. Overlays
remain checked into this repository and the selected upstream sources. The
release is declared in scripts/native_stack.toml, and scripts/native_stack.py
checks vcpkg out at that tag.
Until the development env moved onto the same native build, the conda and vcpkg dependency versions differed: the reviewed build used Boost 1.92 / 1.88, yaml-cpp 0.9 / 0.8 and KDL 1.5.3 / 1.5.4 respectively (wheel / development). Source alignment is not third-party ABI parity; the fresh-runner artifact tests exercise the shipped stack independently.
The Linux -include stdexcept workaround is tracked in
tesseract_planning#802.
Remove it only after an updated upstream source passes the wheel build without it.