Repolode
Submit
pg83

pg83/solo

A dlfcn-style .so loader that lets a fully static musl Linux binary load the host's glibc-linked GPU drivers, such as Vulkan ICDs.

View on GitHub
Stars
643
Forks
15
Open issues
15
Last commit
23 days ago

What is it?

SoLo solves a specific deployment problem: a fully static musl-linked executable cannot normally dlopen() the GPU driver shared objects installed on a host, which are usually built against glibc. SoLo provides a dlfcn-style API backed by its own ELF loader for x86-64 and aarch64, plus a glibc ABI bridge implemented on top of the process's musl runtime. The result is still a single static executable that can use the driver already on the machine.

The repository includes an end-to-end Vulkan demo that loads the host's unmodified Vulkan ICD, runs a checked-in compute shader, and writes the output to a PNG. Glibc is never loaded as a second libc; its imports are mapped to adapters over musl, and unimplemented functions are stubs that abort with the symbol and version name. C++ exceptions, the four TLS models, and symbol versioning are handled across the boundary.

The project is Linux-only and load-once: dlclose succeeds but does not unload an image. Coverage is tested in CI by loading the shared libraries of the 1000 most-installed Debian library packages on both architectures.

Key features

  • 01Provides a dlfcn-style dlopen/dlsym API for fully static musl binaries.
  • 02Includes its own ELF loader for x86-64 and aarch64.
  • 03Bridges glibc ABI imports onto the process's existing musl runtime.
  • 04Loads host Vulkan ICD drivers without a container or AppImage.
  • 05Ships a prebuilt Vulkan demo binary that writes a PNG via a compute shader.

Use cases

  • Shipping a single static Linux binary that needs the host's Vulkan or OpenGL driver.
  • Running GPU compute or graphics workloads from a static musl application.
  • Loading glibc-built shared libraries from a musl-static program without bundling a distro.
  • Studying how a userspace ELF loader and glibc-to-musl ABI bridge are implemented.

Quick start

  1. 1

    Download the prebuilt Vulkan demo binary from the releases page

    curl -LO https://github.com/pg83/solo/releases/latest/download/vulkan-x86_64
  2. 2

    Make the binary executable

    chmod +x vulkan-x86_64
  3. 3

    Run the demo to write a 512x512 PNG using the host's Vulkan driver

    ./vulkan-x86_64 hello.png

Things to know

  • Linux only, on x86-64 and aarch64 architectures.
  • Requires a host Vulkan driver installed for the GPU demo to work.
  • Still a niche, experimental approach to loading glibc-linked host libraries.

Topics

#elf-loader#dynamic-linking#static-linking#vulkan#musl#glibc#linux#cpp#abi#dlopen

FAQ

What is solo?
A dlfcn-style .so loader that lets a fully static musl Linux binary load the host's glibc-linked GPU drivers, such as Vulkan ICDs. SoLo solves a specific deployment problem: a fully static musl-linked executable cannot normally dlopen() the GPU driver shared objects installed on a host, which are usually built against glibc. SoLo provides a dlfcn-style API backed by its own ELF loader for x86-64 and aarch64, plus a glibc ABI bridge implemented on top of the process's musl runtime. The result is still a single static executable that can use the driver already on the machine.
Is solo free to use? What license does it have?
solo is open source under the MIT license. Check the license terms before using it in commercial products.
Is solo still maintained?
Actively maintained. The last commit to solo was on Sep 29, 2026.
What can I use solo for?
Shipping a single static Linux binary that needs the host's Vulkan or OpenGL driver. Running GPU compute or graphics workloads from a static musl application. Loading glibc-built shared libraries from a musl-static program without bundling a distro. Studying how a userspace ELF loader and glibc-to-musl ABI bridge are implemented.
How do I install solo?
Download the prebuilt Vulkan demo binary from the releases page: curl -LO https://github.com/pg83/solo/releases/latest/download/vulkan-x86_64 Make the binary executable: chmod +x vulkan-x86_64 Run the demo to write a 512x512 PNG using the host's Vulkan driver: ./vulkan-x86_64 hello.png
Where can I get solo?
The source code and installation instructions are on GitHub: https://github.com/pg83/solo

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects