haylan/godot-ci
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'docs(research): investigate Blender on Alpine/musl' (#18) from research/blender-musl-alpine into main

Browse Source
This commit was merged in pull request #18.
This commit is contained in:
haylan
2026-08-06 22:43:59 +00:00
parent 0c3a55a8cf a6645add28
commit f0307c6558
1 changed files with 182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/research/blender-musl-alpine.md
+182
View File
@@ -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)