Solo: a .so loader for static Linux binaries

Solely from the provided source material, this account details <SoLo>, a unique loader for static Linux binaries that enables them to utilize host-supplied GPU drivers. At runtime, SoLo seamlessly loads a user's glibc-linked GPU driver without requiring a separate container or duplication of the libc library within the process.

Developed with IX, a source-first build system, SoLo consists of a statically linked executable capable of dynamically loading necessary GPU drivers as shared objects previously built against glibc. By providing a dlfcn-style source API supported by its own ELF loader and a glibc ABI bridge, SoLo allows static binaries to access the GPU drivers already installed on the machine.

The repository includes a comprehensive Vulkan proof, showcasing a fully static executable that successfully loads the host's unmodified Vulkan driver, runs a compute shader, and writes the resulting image to a PNG format. This proof has been tested across various GPU vendors such as AMD radv, radeonsi, Intel, NVIDIA, and Apple M1 using Asahi Linux, all under Linux with an installed Vulkan driver.

To ensure the reliability of SoLo, a continuous integration (CI) system performs rigorous testing by loading the shared libraries of the 1,000 most-installed Debian packages through SoLo, on both x86-64 and aarch64 architectures. The prebuilt binary can be easily obtained without the need for cloning or installing additional toolchains, requiring only a Linux system with a Vulkan driver installed, such as meson-vulkan-drivers.

SoLo also allows developers to specify a particular GPU driver by providing the ICD manifest name, which may vary slightly between different distributions. If no --driver option is provided, SoLo will automatically discover the host's installed Vulkan ICD. The executable itself is not dynamically linked, as demonstrated by the command provided in the source material.

To build the demo, a Python 3 environment with C/C++ compilers in the PATH is sufficient. The complete example can be found in the bin/vulkan directory, with the Vulkan program located in main.cpp. The elf_loader.cpp file handles ELF segment mapping, DT_NEEDED resolution, versioned symbol resolution, and various ELF-specific features such as relocation processing, TLS support, IFUNCs, and RELRO application. The loader recursively loads any dependencies that are themselves ELF DSOs.

Notably, SoLo does not load glibc and instead provides ABI-correct adapters for glibc functions via the glibc_shim.cpp file. Unsupported glibc functions are replaced by unique stubs that loudly fail if called, ensuring the process does not silently corrupt due to missing symbols. By leveraging musl's ABI-specific synchronization objects, SoLo maintains a single lock for both the loaded DSO and the static executable that may share it, while adopting glibc's static recursive and error-check initializers on first use.

SoLo's architecture allows for selective dependency satisfaction using functions already linked into the executable, such as the Wayland dependency. LD_LIBRARY_PATH and DL_ELF_LIBRARY_PATH environment variables are honored for libraries outside the standard system directories. All the critical components of SoLo are compact enough to be read and understood within the source material.

The default target builds a standalone archive, with the resulting libdlfcn.a accessible through the ./dlfcn symlink. This allows developers to include lib/dlfcn.h and link the archive into their musl-static application, redirecting ordinary dlopen()/dlsym() calls to SoLo. The source tree is intentionally self-contained, making it suitable for inclusion in other static build graphs.

The CI process performs native builds and tests using Alpine/musl with GCC, Fedora with GCC, and Ubuntu with Clang. The Vulkan test installs each distribution's respective Lavapipe package and runs the demo without using the driver from an Arch sysroot. Every build input for the standalone Vulkan executable is vendored under the bin/vulkan directory, and build.py directly compiles those sources without invoking upstream CMake, Meson, configure, or Make build systems.

Extensive licensing files are retained alongside the corresponding sources, and the shader.inc file contains the checked-in SPIR-V form of shader.comp, eliminating the need for a separate shader compiler. In general, SoLo enables static applications to communicate with the dynamic loader, instructing it to use the symbols already linked into the application's executable for specific system dependencies.

This innovative approach effectively bridges the hard wall between "fully static" and "uses the system GPU," providing a finite, testable compatibility layer.