Open-source project
pg83/solo avatar
pg83/solo

SoLo tags its releases 9, 10, 11, and its CI claims 1,000 packages but 2,100 objects

Portable Linux binaries, solved

652 stars14 forksC++MIT

At a glance

What is it?
A dlfcn-style API and ELF loader that lets one fully static musl binary load the host's glibc-built GPU driver, with no second libc in the process. The engineering is careful; the release naming and the CI arithmetic are loose.
Who is it for?
SoLo is worth a look if you ship static binaries and have hit the wall of a driver you cannot link. The library model is the part to copy: no startup call, ordinary dlopen redirected through a linked archive, and generated stubs that name the symbol they could not implement.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 47 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pg83/solo652 ★ · +16
Star history
Repository2026-09-212026-11-15
pg83/solo636652

16 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Release tags are the integers 9, 10 and 11

Three release tags are visible and none of them is a version in any conventional sense. They are `9`, `10` and `11`, dated 2026-08-22, 2026-09-03 and 2026-09-07. No `v` prefix, no major, no minor, no patch.

That is workable and it is unpinnable. The documented download is an asset name with no version in it, pulled from the latest release:

sh
curl -LO https://github.com/pg83/solo/releases/latest/download/vulkan-x86_64
chmod +x vulkan-x86_64
./vulkan-x86_64 hello.png

Every user who runs that gets whatever the newest tag happens to be, and the filename gives no way to record which. Two people running the same command a week apart may have different binaries, and nothing in the artefact distinguishes them.

The assets are also architecture-named rather than version-named, with `vulkan-x86_64` for Intel and AMD machines and `vulkan-aarch64` as the same demo for arm64. That is a clean naming scheme for the file and the wrong place to have versioned it.

The repository itself is not idle. The last push to the default branch is 2026-09-29, three days before this was written, so the branch is ahead of every published tag.

If you need reproducibility, the commit is the only handle in this setup.

1,000 Debian packages, over 2,100 host objects

The claim that replaces a demo is on every commit of CI: the shared libraries of the 1,000 most-installed Debian packages are loaded through SoLo, more than 2,100 host objects, on both x86-64 and aarch64.

The arithmetic is what makes this worth reading. 2,100 objects for 1,000 packages is a little over two per package. A typical shared-library closure on Debian carries more than that, so either the set is filtered to objects that actually need mapping, or the packages are being counted for their own library rather than their full dependency tree.

Either reading is fine, but the two numbers do not tell you which one you are getting. What it does establish is breadth of host coverage across both architectures on every push, which is a stronger commitment than a matrix of platforms tested once.

That matters because the project's entire premise is that an unknown host driver, built by someone else against a libc you did not ship, has to load and run correctly. A curated list of friendly drivers proves nothing; 2,100 objects from the most-installed packages is a reasonable proxy for the messy middle.

The local equivalent is a single command, `./build test`, described as loading an Arch glibc DSO closure.

glibc is never loaded, and the missing functions name themselves

The design decision that makes this possible is that no second libc ever enters the process. The host's Vulkan driver may import `malloc@GLIBC_2.2.5`, and that symbol does not resolve to a real glibc. It resolves, through `lib/glibc_shim.cpp`, to an ABI-correct adapter implemented on top of the musl runtime already in the executable.

What happens when an adapter does not exist is the part worth copying. Unsupported glibc functions get unique generated stubs that fail loudly, naming the exact symbol and the version, instead of silently corrupting the process. A driver that calls into something unimplemented produces a diagnostic naming `malloc@GLIBC_2.2.5` rather than memory corruption three layers later. `lib/glibc_stubs.cpp` holds those fallbacks separately from the implemented adapters in `lib/glibc_shim.cpp`.

Locking is handled by not shadowing anything. musl sizes its synchronisation objects to the glibc ABI of each architecture, so a `pthread_mutex_t` a driver creates is the same object the static executable uses. One lock, shared, rather than two that both believe they own it. glibc's static recursive and error-checking initialisers are adopted on first use rather than at startup.

The loader underneath is in `lib/elf_loader.cpp` and is a full job: it maps ELF segments, walks `DT_NEEDED`, resolves versioned symbols, applies x86-64 relocations, supports ELF TLS and TLSDESC, materialises IFUNCs, applies RELRO and runs initialisers. Dependencies that are themselves DSOs load recursively.

There is no startup call, and initial-exec TLS comes from a linked pad

Using SoLo as a library is unusually cheap, and the reason is unusual.

The default build target produces a standalone archive, and the published `./dlfcn` symlink points to the resulting `libdlfcn.a`. You include `lib/dlfcn.h`, link the archive into a musl-static application, and ordinary `dlopen()` and `dlsym()` calls are redirected to SoLo. There is no initialisation function to call and no order to respect.

The subtlety is thread-local storage. A guest driver can demand static TLS, including the initial-exec model, and SoLo supplies it from a `thread_local` pad the library links into the application. musl sizes every thread's TLS with that pad from process birth, and the loader hands pieces of guests to it as they load.

That is why there is no startup call. The work that a conventional dynamic loader would do at startup is done at link time instead, and the runtime cost is paid per load.

The stated intent is that the source tree is deliberately self-contained and suitable for copying into another static build graph, which is a real constraint to check before you vendor it: four library files, one header, and a build system that is a Python script.

`lib/dlfcn.cpp` is the public surface, holding dlopen, dlsym, error handling and the static provider registry.

AT_SECURE is honoured, and the ldd report names objects with no mapping

Two environment behaviours are documented precisely enough to be worth quoting.

`LD_LIBRARY_PATH` is honoured for libraries outside the standard system directories, with one exception: in secure-execution mode, signalled by `AT_SECURE`, the environment is ignored the way `ld.so` ignores it. A setuid or otherwise privileged binary does not get a search path it did not have any right to.

`LD_TRACE_LOADED_OBJECTS=1` prints every object in `ldd`'s format as it loads. The interesting part is the last clause: the listing includes names that were never mapped, because they were satisfied by an ABI bridge or by a provider already linked into the executable. So the report is a dependency list in the broad sense rather than a mapping list, which is closer to what you want when debugging than what `ldd` gives you.

That second behaviour is enabled by the static provider registry. Before loading a DSO from disk, SoLo checks whether the dependency is already satisfied by something in the executable. The example given is Wayland, and the effect is that a driver can be linked against an interface the application already provides instead of carrying its own copy.

Both features share one property: they make the loader aware of what is already in the process, which is the difference between a `dlopen` replacement and a second one.

The demo runs a real pipeline, on six hardware and platform combinations

The proof is a compute shader, not a version string check. The static executable enters the statically linked Khronos Vulkan loader, then loads the host's Vulkan ICD together with its non-glibc dependencies through SoLo. It creates a device, a storage buffer, a descriptor set and a compute pipeline, dispatches a shader that is checked into the repository, maps the result and writes it out through statically linked libpng. The output is a 512 by 512 RGBA PNG.

The platforms behind that are a list worth reading, because each one breaks a different assumption: AMD radv, radeonsi, Intel and NVIDIA on Linux, Apple M1 hardware under Asahi Linux, Android under Termux, and WSL with Mesa's dzn driver running over Direct3D 12.

The demo is also a build tool rather than a test fixture. The same binary is how the release binaries for a terminal emulator are produced, which means the loader is on the critical path of somebody else's release.

Driver selection is a flag rather than a guess. `--driver` takes an explicit ICD manifest path, and the documentation warns that manifest names vary slightly between distributions. Passing nothing lets the embedded Khronos loader do its normal discovery, which is the correct default and the reason the demo works on a machine you have never seen.

You can confirm the binary really is static yourself, by checking that an interpreter segment is absent and that there is no dynamic section.

No standard build file, two style documents, and a script named build

The problem being solved is stated plainly at the top. Static binaries are a boring way to deploy on Linux until the application needs a GPU, because Vulkan and OpenGL drivers arrive as shared objects built against glibc, and a fully static musl binary cannot normally `dlopen` them.

The repository has 15 top-level entries and no conventional build file among them. There is no CMake list, no Cargo manifest and no package manifest. What there is: a `build.py`, an executable named `build` that takes a target argument, a `build` entry that also appears in the tree listing, and a dependency on IX, a separate source-first build system for static Linux binaries.

The `build` name is the awkward part. The README invokes it as `./build`, `./build vulkan` and `./build test`, so it is an executable. Having both a script and a conventional output-directory name at the top level makes `rm -rf build` a genuinely ambiguous thought for anyone who has not read the source.

Documentation is thin and split. There are two style documents, `STYLE.md` and `STYLE_PRJ.md`, plus a contributing guide and a formatting configuration for clang. The README itself is the primary reference, and it is unusually good on the parts that matter: which symbols are shimmed, which are stubbed, and what happens when a guest asks for something neither covers.

The licence is MIT with a licence file at the top level.

Editorial conclusion

SoLo is worth a look if you ship static binaries and have hit the wall of a driver you cannot link. The library model is the part to copy: no startup call, ordinary dlopen redirected through a linked archive, and generated stubs that name the symbol they could not implement. Before you depend on it, accept that release assets are unversioned and tagged with integers, so pin by commit rather than by tag, and that its CI coverage figure is objects loaded rather than closure depth, so a package whose dependencies are mostly already linked will not stress the loader.

Frequently asked questions

What problem does SoLo actually solve?

A fully static musl binary cannot normally dlopen a host shared library built against glibc, which blocks Vulkan and OpenGL drivers. SoLo provides a dlfcn-style API backed by its own ELF loader for x86-64 and aarch64 plus a glibc ABI bridge over musl, so one static executable can use the graphics driver already on the machine.

How do I run the SoLo Vulkan demo without a toolchain?

Download the prebuilt binary from the latest release, make it executable and run it with an output path. The command discovers the distro-installed Vulkan ICD the usual way and writes a 512 by 512 RGBA image. mesa-vulkan-drivers is enough to install, and there is an arm64 build of the same demo.

How do I use SoLo as a library in a static binary?

Build the standalone archive, include lib/dlfcn.h and link it into a musl-static application; ordinary dlopen and dlsym calls are then redirected. There is no startup call. Static TLS that guests need, including initial-exec, comes from a thread_local pad the library links into your application.

What happens when SoLo meets a glibc function it does not implement?

It does not load glibc. Implemented symbols resolve through lib/glibc_shim.cpp to ABI-correct adapters over musl, and everything else gets a unique generated stub in lib/glibc_stubs.cpp that fails loudly with the exact symbol and version rather than corrupting the process silently.

How do I pin a SoLo version for a build?

By commit rather than by tag. The visible release tags are the bare integers 9, 10 and 11, and the documented download pulls an unversioned asset from the latest release, so neither the tag nor the filename records what you actually ran.

Official sources

  1. Issues
  2. License: MIT
  3. pg83/solo on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pg83-solo.svg)](https://hysenlabs.com/projects/pg83-solo)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pg83-solo.svg)](https://hysenlabs.com/projects/pg83-solo)

Was this useful?