Overview

When deploying shared object (.so) files to Linux-based hardware systems, binaries built on newer Linux distributions may fail at runtime on older systems. This can occur even when CPU architecture and operating system family are the same.

Failures may appear as loader errors, unresolved symbols, or crashes during library initialization.

C++ ABI Compatibility on Linux

On Linux, C++ binaries dynamically link against libstdc++, which provides a defined set of C++ ABI symbols. Newer Linux distributions ship versions of libstdc++ that expose additional ABI symbols (for example, CXXABI_1.3.8).

Older Linux systems may only provide earlier ABI versions, such as CXXABI_1.3.7. If a shared library is built on a system whose libstdc++ exports newer ABI symbols than are available on the target system, the binary may fail to load or execute at runtime.

This mismatch may not be detected during compilation.

Inspecting ABI Versions

The ABI symbols provided by libstdc++ on a given system can be inspected using:

strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep CXXABI_1.3

This output can be used to compare ABI support between build and runtime environments.

Build Environment

Shared libraries were rebuilt using an older Linux distribution whose default libstdc++ did not expose newer ABI symbols.

The build environment was created using Docker, and Linux binaries were built inside that environment

SSH Configuration in the Build Environment

When using the older Linux distribution in the build environment, additional steps were required to enable SSH access.

A password was first set for the root account, and SSH was configured to allow password-based login. The following changes were made inside the container:

docker exec -it <container-name> bash
 passwd

sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config
sed -i 's/PermitRootLogin without-password/PermitRootLogin yes/' /etc/ssh/sshd_config
sed -i 's/PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

echo "PasswordAuthentication yes" >> /etc/ssh/sshd_config
echo "PermitRootLogin yes" >> /etc/ssh/sshd_config

mkdir -p /var/run/sshd
service ssh restart

After these steps, SSH access to the container was available.

Building the Shared Libraries

In this container, the .so files were rebuilt and no longer depended on newer ABI symbols.

Summary

• Linux shared library compatibility can be affected by C++ ABI differences.
• ABI requirements are determined by the build environment’s libstdc++.
• Newer Linux systems may introduce ABI symbols not present on older systems.
• Rebuilding shared libraries in an environment aligned with the target system can resolve runtime compatibility issues.

This case reflects JNBridge’s ongoing work supporting customers with specialized deployment requirements.