diff --git a/docs/research/blender-musl-alpine.md b/docs/research/blender-musl-alpine.md new file mode 100644 index 0000000..eea294d --- /dev/null +++ b/docs/research/blender-musl-alpine.md @@ -0,0 +1,182 @@ +# Does official Blender run under Alpine/musl? + +Research for [wayfinder ticket #5](https://git.arthurerlich.de/haylan/godot-ci/issues/5). +Scope: this repo currently downloads the **official glibc Linux tarball** from +`download.blender.org/release/` (see `Dockerfile`, `scripts/resolve-blender-url.sh`) +onto a `barichello/godot-ci` (Ubuntu/glibc) base, and uses it for headless +`.blend` → asset import in the Godot CI pipeline. This doc asks whether that +same tarball, or any Blender build, works on an Alpine/musl base. + +## Verdict + +- **Official tarball on Alpine as-is: does not work.** It is a glibc build + (Blender requires glibc ≥ 2.28 per Blender's own requirements page) and + Alpine ships musl instead of glibc, with no glibc present at all. +- **Official tarball via `gcompat`: unproven / likely does not work reliably.** + `gcompat` is explicitly a shim for *pre-built* glibc binaries and is + documented by Alpine as not fully compatible — "some [binaries] will still + not work with this patch." The one concrete community attempt found (a PR + against `ikester/blender-docker`) tried exactly this — official binary + + Alpine + presumably gcompat/manual lib shims — and failed with missing + libraries (`libGLU.so.1`, `libXrender.so.1`) and unresolved glibc-only + symbols (`__sched_cpualloc`, `qsort_r`, `backtrace`). The image never ran. + This is a single secondary data point, not exhaustive, but it's the only + real-world attempt this research turned up and it failed outright. +- **musl-native alternative exists: yes.** Alpine's `community` repository + packages Blender from source against musl — `blender`, `blender-headless`, + `blender-shared`, `blender-doc`, `py3-blender` — currently at **5.2.0-r0** + for `x86_64`. `blender-headless` is specifically the no-GUI server/CLI + build, i.e. exactly the shape needed for a Godot import pipeline + (`blender --background --python ...`). +- **Caveat on the alternative:** as of this research, the Alpine package + index shows these packages **only in the `edge` branch**, not in a + released stable branch (e.g. `v3.20`/`v3.21`). Edge is Alpine's rolling/ + unstable branch — usable, but it means pinning to a moving target rather + than a versioned stable release, which cuts against the reproducibility + this pipeline wants from a pinned Blender version. +- **Headless `.blend` import specifically:** not separately verified beyond + the existence of `blender-headless` and its description ("headless build" + for server/automation use). No primary Blender-side documentation or + Alpine changelog was found confirming Python-scripted `--background` + import/export works flawlessly on the musl build; this is inferred from + the package's stated purpose, not confirmed by a run. + +**Net:** there is a plausible musl-native path (Alpine `community/edge` +`blender-headless`), but it is edge-only today, and the "just run the +official tarball via gcompat" path has a real failure report against it. +Either the pipeline pins to Alpine `edge` (accepting rolling-release churn) +or Alpine is not a good fit for this image's need for a stable, pinned +Blender version. + +## Details and sources + +### Official Blender's own requirement (primary) + +Blender's official download requirements page (blender.org) states Linux +support requires **glibc 2.28 or newer**; for older glibc (e.g. glibc 2.17 / +RHEL 7) Blender recommends staying on the old Blender 3.4 release instead. +This is a hard glibc dependency stated by Blender itself — nothing on that +page mentions musl or Alpine as a supported target. +(https://www.blender.org/download/requirements/, https://www.blender.org/download/) + +Blender's Linux build documentation +(https://developer.blender.org/docs/handbook/building_blender/linux/) +returned HTTP 403 to automated fetch during this research and could not be +quoted directly; it is generally understood (and consistent with the glibc +requirement above) to target mainstream glibc distros for both building and +running Blender, with no documented musl/Alpine build target. + +### Alpine's gcompat (primary — Alpine wiki/GitHub) + +- Alpine's own wiki page on running glibc programs + (`https://wiki.alpinelinux.org/wiki/Running_glibc_programs`) describes + `gcompat` as the mechanism for running *already-compiled* glibc binaries + on musl by intercepting the glibc dynamic linker path and redirecting to + musl plus a set of compatibility shims. (Fetched via search-engine summary + — the wiki itself returned HTTP 403 to direct fetch during this research.) +- The `gcompat` project itself (https://github.com/rs--/gcompat, mirrored at + https://github.com/Stantheman/gcompat) states plainly: it works for + binaries **already compiled against glibc**, has **no headers**, and + **cannot be used to build software that requires glibc**. It explicitly + warns that "some [glibc binaries] will still not work with this patch," + and recommends fixing/porting software to be libc-portable instead of + relying on gcompat for anything beyond simple/small binaries. +- Alpine's `gcompat` package on `pkgs.alpinelinux.org` is present in the + `main` repo, version `1.1.0-r4` (checked build date 2023-07-31) — small + and simple, consistent with its stated scope (a shim, not a glibc + reimplementation). (https://pkgs.alpinelinux.org/packages?name=gcompat) + +Blender is a large, complex application (OpenGL/Vulkan, audio via +PulseAudio/PipeWire, X11, dozens of bundled C/C++ libraries, a bundled +Python). This is exactly the profile gcompat's own documentation flags as +likely to fail — and the one concrete attempt found (below) did fail. + +### Alpine's musl-native Blender package (primary — pkgs.alpinelinux.org) + +`pkgs.alpinelinux.org` package index, checked directly: + +| package | branch | repo | arch | version | purpose | +|---|---|---|---|---|---| +| `blender` | edge | community | x86_64 | 5.2.0-r0 | full GUI build | +| `blender-headless` | edge | community | x86_64 | 5.2.0-r0 | **no-GUI build for server/automation** | +| `blender-shared` | edge | community | x86_64 | 5.2.0-r0 | shared libs subpackage | +| `blender-doc` | edge | community | x86_64 | 5.2.0-r0 | docs | +| `py3-blender` | edge | community | x86_64 | 5.2.0-r0 | Python bindings subpackage | + +(https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender, +https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender-headless) + +Since Alpine's `community`/`main` repos are built from source +(`aports`) against musl, these are **native musl builds**, not the glibc +tarball run through a shim — this is the actual "musl-friendly alternative" +the ticket asks about. `blender-headless`'s description ("headless build", +no GUI deps) matches the "background import for a CI asset pipeline" use +case directly. + +The important caveat, also confirmed directly against the package index: +these packages appear to exist **only under the `edge` branch** at the time +of this research (no stable-branch listing, e.g. `v3.20`/`v3.21`, was found +for `blender`/`blender-headless`). Alpine's `edge` is the rolling +development branch — using it means tracking a moving target rather than a +pinned stable Alpine release, which works against the kind of reproducible, +version-pinned build this repo's `resolve-blender-url.sh` / +`resolve-godot-version.sh` scripts are designed around. + +### Community corroboration (secondary) + +- `ikester/blender-docker` PR #1 ("Change to use alpine linux, much smaller + base image size", https://github.com/ikester/blender-docker/pull/1): + contributor tried moving that Dockerfile to Alpine using the official + Blender binary. Result reported by the repo owner: **it did not run** — + missing `libGLU.so.1`, `libXrender.so.1`, and unresolved glibc-only + symbols (`__sched_cpualloc`, `qsort_r`, `backtrace`). The owner asked the + contributor to "sort out dependencies"; the PR was never updated further + and was not merged. This is a single, non-exhaustive report (no gcompat + usage confirmed explicitly), but it's concrete evidence that the naive + "official tarball + Alpine" path fails in practice, consistent with + gcompat's own documented limitations. +- Other headless-Blender Docker projects found in this search + (`BlenderKit/headless-blender-container`, `HaiyiMei/blender-docker-headless`, + LinuxServer.io's `docker-blender`) all use glibc-based bases (Ubuntu/Debian), + not Alpine — i.e. nobody surveyed here ships a working Alpine+official-tarball + image. This absence is itself weak corroborating evidence that the + glibc-tarball-on-Alpine path isn't a well-trodden, working setup. + +## Implication for this repo + +If Alpine is being considered as a smaller/leaner base for the CI image: + +1. The current approach (download official glibc tarball from + `download.blender.org`, per `Dockerfile` / `scripts/resolve-blender-url.sh`) + **cannot be ported to Alpine as-is** — no glibc, and gcompat is not a + credible fix for something as large/complex as Blender (per gcompat's own + docs, and per the one real attempt found, which failed). +2. The only musl-native path found, Alpine's `blender-headless` package, + exists **only on `edge`** — adopting Alpine would mean giving up the + pinned/reproducible-version approach this repo currently uses for both + Godot and Blender, in favor of tracking Alpine's rolling branch, or + manually backporting/building the aport for a stable branch (extra + maintenance burden not costed here). +3. No evidence was found either way (positive or negative) on whether the + Alpine `blender-headless` package's Python/`--background` scripting + behaves identically to the official build for `.blend` import — only + that the package is described as built for that use case. + +**This is a real argument against Alpine** for this image unless the team +is willing to (a) pin to Alpine `edge` and accept its churn, or (b) take on +maintaining a backport of the `blender`/`blender-headless` aport for a +stable Alpine branch themselves. + +## Sources + +- https://www.blender.org/download/requirements/ +- https://www.blender.org/download/ +- https://developer.blender.org/docs/handbook/building_blender/linux/ (403 on direct fetch; referenced via search summary) +- https://wiki.alpinelinux.org/wiki/Running_glibc_programs (403 on direct fetch; referenced via search summary) +- https://github.com/rs--/gcompat +- https://github.com/Stantheman/gcompat +- https://pkgs.alpinelinux.org/packages?name=gcompat +- https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender +- https://pkgs.alpinelinux.org/package/edge/community/x86_64/blender-headless +- https://github.com/ikester/blender-docker/pull/1 (secondary/community) +- https://github.com/BlenderKit/headless-blender-container (secondary, uses Ubuntu — corroborates absence of a working Alpine setup)