I guess using Go + Godot to build native & installable Android & iOS binaries (without any proprietary SDKs) was too easy. So it’s time for a real challenge…

Linux Binary Compatibility

(some background reading: https://jangafx.com/insights/linux-binary-compatibility)

For a while now, it’s been very easy to reliably ship command line software & servers for Linux, just run go build and out pops a single static binary that will run on any Linux distribution running kernel 3.2 or later (which was released in 2012, so there’s plenty of room for backwards compatibility).

The problems begin to creep in when you want access to hardware accelerated graphics. All the GPU drivers on Linux require accessing dynamic libraries via the C ABI. These C libraries are built against a particular libc, which is most commonly glibc but there are also a selection of musl-based distributions. If you compile a glibc library or executable, it won’t run on a musl system and vice-versa. That’s a big incompatibility right there!

In fact, I’ve directly experienced this, as I recently replaced the OS on my personal computer with the musl edition of Void Linux. Compiling the Zed editor with musl for example, was quite the challenge. It turns out that building graphics.gd projects on musl was also very broken. Go doesn’t properly support c-shared or c-archive when building against musl.

That’s a problem, firstly because this is my distro now, I need to be able to build graphics.gd projects! Secondly, in theory, musl has better support for static linking than glibc; so if there’s any solution to this Linux Binary Compatibility mess, it’s probably going to have something to do with musl.

Supporting musl

To work around these musl issues with Go, I had to patch the runtime with a build-overlay that applies when building for GOOS=musl. This is a new GOOS that I’ve introduced to graphics.gd, specifically to make musl builds possible.

Next up, I decided to ditch c-shared builds for musl, these were only convenient because you could easily plug and play Go into the official Godot binaries. The Godot Foundation doesn’t provide official musl builds, so instead, I’m linking the Go code directly with Godot c-archive to end up with a single binary. Amazing, graphics.gd supports musl now!

There’s just one issue, this means whenever somebody wants to release their project for Linux, they would have to create two builds, a Linux glibc build + a musl build and somehow communicate to their users, to pick the correct binary. Hell, before I installed Void Linux I didn’t even fully comprehend the differences between musl and glibc, this feels like I’m simply contributing to the problem!

Single Static Binaries + Graphics

Hold up! Earlier I reported that a key benefit of musl was better static library support. There should be a way to build a graphics.gd project into a single static binary. Well, here’s the thing. Yes, you can totally do this. Godot includes all of it’s dependencies on Linux, everything else is dynamically loaded at runtime, so just add the -static command and…

ERROR Dynamic loading not supported

Ouch, Godot wants to use dlopen to interface with X11, Wayland, OpenGL, Vulkan etc. As it turns out, musl refuses to implement dlopen for static binaries. They don’t want anyone to load a glibc library from musl because there are fundamental incompatibilities between how they implement TLS (thread-local-storage).

Don’t worry though! As dlopen is compiled as a weak symbol, this means, that as long as graphics.gd implements it, there’s still a chance to get a single static binary that can execute on any Linux system 3.2 onwards.

The Holy Grail

There’s some precedent for this, there’s the detour technique in C which will let you dlopen SDL and show graphics when running without a standard library. There’s also Cosmopolitan’s dlopen which uses a similar technique. So the solution here is to extend this for musl.

The way this works, is by including (or compiling) a small C program for the target machine. We load the program and execute into it from the same process. This program brings in the host’s dynamic linker so that we can steal the system’s dlopen and longjmp back into graphics.gd. We wrap any dynamically loaded functions with an assembly trampoline that switches to the system’s libc TLS for the duration of the call. It all starts looking a lot like cgo.

So after much hair pulling and LLM wrangling, it turns out that musl + dlopen is all we need to produce single static binaries + graphics for Linux. Everyone can now enjoy the Go single-static-binary experience on Linux with full support for hardware accelerated graphics.

Try it!

Here’s a build of the graphics.gd Dodge The Creeps sample project that should execute (and hopefully render graphics) on any Linux system with gcc installed (we don’t embed the helper binaries yet).

https://release.graphics.gd/dodge_the_creeps.static

You can also cross-compile your own project (on any supported platform)

GOOS=musl GOARCH=amd64 gd build

Note you may need to delete your export_presets.cfg so that the new musl export preset is added to your project