2026-08-06 22:43:59 +00:00
1 changed files with 182 additions and 0 deletions
@@ -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)