| name | bundled-native-soname-conflict |
| description | A native library you bundle with a desktop app drags its own copy of a general-purpose base library along, that copy claims the shared-object name for the whole process the moment your native loads, and an unrelated platform API then fails with a missing-symbol message naming a third library. Use when a feature that opens links or system dialogs works on your machine but silently does nothing on users' machines, when a platform API reports itself unsupported at runtime, when deciding what a native bundle may contain, or when a merged fix for exactly this bug does not seem to have changed anything for users. |
A bundled base library claims a system library name
Ship a native library with your app and you ship its whole dependency closure. If that closure
contains a general-purpose base library the host desktop also has — a utility/collections
library, a compression library, a crypto library — then the first copy loaded wins the
shared-object name (on Linux, the soname recorded in the library's dynamic section) for the rest of the
process. Your native loads early, so your copy wins.
Nothing fails at that moment. It fails later, in code that has nothing to do with your native:
a platform API opens the system counterpart of that same family, the system copy needs a
symbol the older bundled copy does not export, the load fails, and the platform marks the whole
API unsupported for the remainder of the process.
Worked example (Linux): a bundled media library carried a utility library built on an older
distribution. The JDK's desktop-integration API (java.awt.Desktop) probes its native backing
on first use; on a host with a newer system copy of that family the probe died with an
undefined-symbol message naming a third library in the same family. From then on the JDK
reported the desktop API unsupported, and all external-link call sites broke at once.
The two fixes, in order
Cure — exclude base-system libraries when staging the bundle:
