docs/research/godot-musl-alpine.md

@@ -0,0 +1,212 @@
+# Do official Godot Linux binaries run on Alpine/musl?
+
+Research date: 2026-08-06. Scope: official binaries from
+`downloads.tuxfamily.org` / `github.com/godotengine/godot-builds`
+(the same source `abarichello/godot-ci` downloads from) — not
+self-compiled or third-party (e.g. Alpine's own package) builds.
+
+## VERDICT
+
+**(a) Editor binary (headless export, `godot --headless --export-release ...`)**
+**Works with gcompat** *at best, unverified/likely-partial* — more precisely:
+**Does not work out of the box; requires gcompat, and even gcompat is not
+confirmed sufficient.**
+
+- The official Linux editor/export-template binaries are built in a
+  Fedora-based container and dynamically linked against **glibc 2.34**
+  (see Sources: `godotengine/build-containers`). They are not static and
+  not musl-native.
+- Godot's own source will not even *compile* on musl without patches
+  (undefined `backtrace`/`backtrace_symbols`, `PTHREAD_MUTEX_RECURSIVE_NP`,
+  `isnanf` differences) — this doesn't affect running a prebuilt glibc
+  binary directly, but it confirms the codebase has known musl-specific
+  assumptions that could also bite at runtime.
+- Multiple Godot maintainers/contributors state plainly: **"Godot
+  currently only runs on Linux distributions with glibc as libc
+  implementation. On distros with musl libc, it won't compile."**
+  (godot-proposals#2439). No official statement confirms gcompat works
+  for the editor.
+- A related, unresolved report (godot/godot#21282) describes the Godot
+  **editor segfaulting on launch on musl-libc distros (Alpine, Gentoo)**,
+  with the reporter speculating about musl stack-size differences. It was
+  closed/archived as stale, not fixed — so the risk of a crash isn't
+  hypothetical, it has a filed report, even though the report predates
+  gcompat's now-common usage and doesn't test it explicitly.
+- No GitHub issue, forum post, or doc page found in this research
+  confirms someone successfully ran the *official* headless editor via
+  `gcompat` for exports. Community Docker images for headless Godot CI
+  (e.g. `robpc/docker-godot-headless`, `barichello/godot-ci` itself) are
+  all Debian/Ubuntu-based, not Alpine — which is itself weak circumstantial
+  evidence that the ecosystem defaults to glibc bases rather than having
+  solved this on Alpine.
+
+**(b) Do export templates care about the host libc?**
+**No — the concern is purely about the editor binary, not the templates.**
+
+- Export templates are per-*target-platform* binaries/build artifacts
+  (Windows .exe, macOS .app, Android .apk components, Linux
+  `.x86_64`, etc.) that the editor copies/embeds into the exported
+  project. The editor process doing the exporting does not execute the
+  Linux export template as a subprocess as part of a normal export — it
+  reads/writes template files and packs the PCK. The host libc constrains
+  only whether the **editor binary itself** can run on the CI host; it has
+  no bearing on which libc the *exported game* (or its Linux export
+  template) targets. That's a separate, independent concern for whoever
+  runs the exported game later.
+- Caveat: this reasoning is architectural inference from how the export
+  pipeline works, not from an explicit Godot doc sentence that says "host
+  libc does not affect templates" — no such explicit statement was found
+  in `docs.godotengine.org`. Treat sub-question (b)'s verdict as
+  **high-confidence but not directly quoted from an official source.**
+
+## Static / musl-native build question
+
+**No official static or musl-native Linux build exists.**
+
+- A GitHub Discussion on `quaadgras/graphics.gd` (a Godot GDExtension/Go
+  binding project) states directly: **"The Godot Foundation doesn't
+  provide official musl builds."** The same discussion explains *why*
+  a static musl build is hard even in principle: Godot needs `dlopen` at
+  runtime to load X11/Wayland/OpenGL/Vulkan drivers, and **musl refuses to
+  implement `dlopen` for statically-linked binaries** (by design, to avoid
+  loading glibc-ABI shared objects into a musl process). The project's
+  workaround is a hand-written assembly TLS trampoline, not something
+  Godot upstream does.
+- Separately, `godot/godot#111876` shows even Godot's *static library*
+  build mode (`LibGodot`) is currently broken/unsupported on Linux, for
+  unrelated build-system reasons — reinforcing that "just statically link
+  it" is not a solved path upstream.
+- Alpine Linux itself packages a **musl-native `godot` build** compiled
+  from source (`pkgs.alpinelinux.org`, package `godot` version `4.6-r2`,
+  in the `edge/testing` repo, linked against `so:libc.musl-x86.so.1`).
+  This is a real, working musl-native Godot editor — but it is an
+  Alpine/community-maintained rebuild from source, **not** the official
+  Godot Foundation binary, is in the `testing` repo (not stable/main), and
+  its version lag/coverage relative to the official releases used by
+  `godot-ci` was not verified.
+- Godot's own compiling-for-Linux docs list Alpine `apk` build
+  dependencies (implying compiling *from source* on Alpine is a supported,
+  documented path — see Sources), which is consistent with "build your
+  own musl-native binary" being viable, while "run the official prebuilt
+  binary on musl" is not.
+
+## Sub-question 1 detail — editor binary and host libc
+
+- **Build environment**: `godotengine/build-containers` README states the
+  Linux build container's *base image is Fedora 44*, and its Linux SDK
+  toolchain is "GCC 15.2.0 built against **glibc 2.34**, binutils
+  2.46.0." This is the container that produces the official
+  editor/export-template binaries godot-ci and this repo download. Fedora
+  and its glibc toolchain confirm the binaries are dynamically linked
+  against glibc, not statically linked and not musl.
+- **Compiling docs list Alpine packages, but for source builds only**:
+  `docs.godotengine.org`'s "Compiling for Linux, *BSD" page lists an
+  Alpine `apk add` package list (`scons pkgconf gcc g++ libx11-dev ...`)
+  for people who want to *compile Godot themselves* on Alpine. It does
+  **not** discuss musl vs glibc, gcompat, or static linking, and it does
+  not say the official prebuilt binaries work on Alpine. A companion doc
+  bug (`godotengine/godot-docs#9180`, filed 2024-04-03, still open in this
+  research) flags that the Alpine package list is stale (`libexecinfo-dev`
+  removed from Alpine since 3.17) and that musl builds should instead pass
+  `execinfo=no` to SCons — again, this is guidance for *compiling from
+  source on Alpine*, not for running the official downloaded binary.
+- **Known runtime failure report**: `godot/godot#21282`, "Segmentation
+  fault on opening a project on musl libc" — reproduced on Gentoo and
+  Alpine, editor crashes immediately when opening a project. Root cause
+  undetermined by the reporter ("might be ... musl stack size"); issue
+  closed/archived without resolution. This predates widespread gcompat
+  adoption and doesn't test it, so it neither confirms nor rules out
+  gcompat as a fix — but it is documented evidence that musl-adjacent
+  environments have triggered editor crashes.
+- **Compile-time musl blockers (indirect evidence of glibc coupling)**:
+  - `godot/godot#63978` — Alpine 3.16 compile fails: undefined references
+    to `backtrace`/`backtrace_symbols` (musl's `execinfo.h` handling
+    differs from glibc's). Closed as "not planned."
+  - `godot/godot#31555` — VHACD third-party module fails to compile on
+    musl due to `PTHREAD_MUTEX_RECURSIVE_NP`, a glibc-specific macro.
+  - `godot/godot-proposals#2439` — proposal to `#ifdef __GLIBC__`-guard
+    glibc-specific code and support musl properly; states plainly Godot
+    "currently only runs on Linux distributions with glibc." Closed,
+    linked to PR #63983 (partial follow-up on the `basename` difference,
+    not full musl support).
+  - `godot/godot#20037` — long-running "[TRACKER] musl libc support in
+    Godot," opened by someone building an Alpine-based Godot Docker image,
+    covering `execinfo.h`, `isnanf` vs `isnan`, and the segfault above.
+    Closed without musl becoming an official target.
+- **gcompat's actual capability**: Alpine's gcompat package/mirror
+  (`Stantheman/gcompat` on GitHub, description corroborated via search
+  results; the canonical `wiki.alpinelinux.org/wiki/Running_glibc_programs`
+  page returned HTTP 403 to automated fetch in this research and could not
+  be quoted directly) is described consistently across secondary sources
+  as: a small compatibility shim providing glibc-ABI-compatible symbols
+  and dynamic-linker paths so *some* glibc-linked binaries run on musl —
+  explicitly **not a full glibc reimplementation**, and known to fail for
+  more complex binaries (a commonly cited example in search results:
+  Godot-Jolt, a Godot GDExtension, reportedly does **not** work on Alpine
+  even with gcompat or `alpine-pkg-glibc` installed — secondary evidence,
+  a search-result summary rather than a page this research fetched and
+  quoted directly). This is consistent with an engine-sized C++ binary
+  like the Godot editor being a poor gcompat candidate, but there is no
+  first-party confirmation either way for the Godot editor specifically.
+
+## Sub-question 2 detail — export templates and libc
+
+- Godot's Linux export docs (`docs.godotengine.org/en/stable/tutorials/export/exporting_for_linux.html`)
+  discuss export architecture options (x86_64/x86_32/arm) but say nothing
+  about host libc or export-template libc requirements — no relevant text
+  found on that page in this research.
+- By Godot's export architecture: the editor process reads template
+  binaries (downloaded/bundled per target platform) and assembles the
+  exported project; it does not need to *execute* a Linux export template
+  as part of exporting *to* Linux (self-hosted export execution isn't part
+  of the pipeline the way, say, code-signing tools might be for other
+  platforms). This means:
+  - The **editor's** ability to run on the CI host is gated by the host's
+    libc (glibc vs musl+gcompat), per sub-question 1.
+  - The **export templates'** relevant libc/ABI concerns are about the
+    *target* platform the exported game will run on later (e.g. does the
+    Linux export template embedded into the exported game work on the
+    end-user's glibc or musl system) — a wholly separate question from
+    whether the CI host running the editor is Alpine or Debian.
+  - No official doc text was found stating this explicitly; it is inferred
+    from the documented shape of the export pipeline rather than a quoted
+    source, so treat with the caveat noted in the VERDICT section.
+
+## Sources
+
+| URL | What it established |
+|---|---|
+| https://github.com/godotengine/build-containers | Official Linux build container base image is Fedora 44, toolchain built against glibc 2.34 — official binaries are glibc-linked, not static/musl. (README fetched via WebFetch) |
+| https://github.com/godotengine/godot-proposals/issues/2439 | Explicit maintainer/contributor statement: "Godot currently only runs on Linux distributions with glibc... On distros with musl libc, it won't compile." Proposal to add `__GLIBC__` guards; closed, partially addressed by PR #63983. |
+| https://github.com/godotengine/godot/issues/20037 | Long-running musl-support tracker opened by an Alpine-Docker-image author; covers execinfo.h, isnanf/isnan, segfaults; closed without musl becoming an official target. |
+| https://github.com/godotengine/godot/issues/21282 | Reported editor segfault on project-open specifically on musl (Alpine, Gentoo); root cause undetermined; closed/archived unresolved. |
+| https://github.com/godotengine/godot/issues/63978 | Alpine 3.16 compile failure: undefined `backtrace`/`backtrace_symbols` due to musl's execinfo handling; closed "not planned." |
+| https://github.com/godotengine/godot/issues/31555 | VHACD third-party module uses glibc-specific `PTHREAD_MUTEX_RECURSIVE_NP`, breaking musl compiles. |
+| https://github.com/godotengine/godot/issues/111876 | Godot's static-library (LibGodot) build mode is currently broken on Linux — static linking isn't a solved path upstream even outside the musl question. |
+| https://github.com/godotengine/godot-docs/issues/9180 | Docs bug: Alpine `apk` package list in the compiling guide is stale (`libexecinfo-dev` gone since Alpine 3.17); recommends `execinfo=no` for musl source builds. Still open at research time. |
+| https://docs.godotengine.org/en/4.4/contributing/development/compiling/compiling_for_linuxbsd.html | Official compiling-for-Linux doc; lists an Alpine `apk add` package list for *source* builds; does not mention musl, glibc, gcompat, or static linking explicitly. |
+| https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_linux.html | Official Linux export doc; covers export architecture options; contains no host-libc or template-libc guidance either way. |
+| https://github.com/quaadgras/graphics.gd/discussions/242 | Direct statement "The Godot Foundation doesn't provide official musl builds"; explains musl's `dlopen`-refusal-on-static-binaries as the core technical obstacle to a static/musl-native Godot; describes a custom TLS-trampoline workaround used by that (unrelated, third-party) project — not something Godot upstream ships. |
+| https://pkgs.alpinelinux.org/package/edge/testing/x86/godot | Confirms Alpine ships its own musl-native `godot` package (v4.6-r2, `edge/testing` repo, linked against `so:libc.musl-x86.so.1`) — a real musl-native build, but Alpine/community-maintained, not the official Godot Foundation binary, and in the testing (not stable) repo. |
+| https://github.com/godotengine/godot-build-scripts | Confirms official release build scripts use containers from `godotengine/build-containers`; did not itself surface Dockerfile content (fetch returned only the repo overview). |
+| G:\_DEV\repos\godot-ci\Dockerfile (this repo, local file) | Confirms this repo's current image is built `FROM barichello/godot-ci:${GODOT_VERSION}` using `apt-get` (Debian/Ubuntu-based, glibc) — i.e., the status quo this research is evaluating an Alpine alternative against. |
+
+### Secondary evidence only (not proof, not fetched/quoted directly — flagged per task instructions)
+
+- Search-result summaries (not independently fetched and verified page-by-page in this research) reported: a Godot Jolt GDExtension addon reportedly does not work on Alpine even with `gcompat` or `alpine-pkg-glibc` installed. Cited as a data point that gcompat compatibility for glibc-linked Godot-adjacent binaries is inconsistent, not as proof about the core editor binary.
+- `wiki.alpinelinux.org/wiki/Running_glibc_programs` returned HTTP 403 to this research's fetch tool and could not be quoted directly; gcompat's description above is reconstructed from consistent secondary summaries (Medium post, Alpine aports mirror descriptions, HN discussion) rather than the primary wiki text itself. Treat the general characterization of gcompat as reliable (it matches gcompat's well-known public description) but not as a verbatim-cited primary source in this research.
+- `aronand/godot-alpine` (GitHub repo, "Godot on Alpine Linux") appeared in search results as a potentially relevant project but was not fetched/read in this research; flagging its existence only, not its content, as an unverified pointer for follow-up.
+- `godotforums.org` thread "Help with exporting games for alpine and musl based systems" — returned only a loading-error page to this research's fetch tool; could not be summarized or cited despite being a promising-looking thread title. Flagging as an unresolved follow-up, not evidence.
+
+## Bottom line for godot-ci's purposes
+
+Given the official Linux editor is a glibc 2.34 binary from a Fedora-based
+build container, and there is no official statement or found report of
+successfully running it under Alpine+gcompat for headless exports (only an
+unresolved musl-segfault report and general "gcompat doesn't fix everything"
+signals), switching this repo's base image to Alpine is **not a low-risk
+change** without first prototyping it end-to-end (pull the real
+downloads.tuxfamily.org editor zip, `apk add gcompat`, and run a real
+`--headless --export-release` in a throwaway Alpine container) to see
+whether it actually works, rather than assuming gcompat is sufficient.
+Export templates themselves are not a blocker for this decision either way.