Skip to content

feat: add musl (Alpine Linux) support and packaging - #2539

Closed
clemperorpenguin wants to merge 4 commits into
lemonade-sdk:mainfrom
clemperorpenguin:main
Closed

feat: add musl (Alpine Linux) support and packaging#2539
clemperorpenguin wants to merge 4 commits into
lemonade-sdk:mainfrom
clemperorpenguin:main

Conversation

@clemperorpenguin

Copy link
Copy Markdown
Collaborator

This PR adds support for building and running lemonade on musl-based Linux (Alpine), covering both the C++ server and native packaging. llama.cpp (CPU + Vulkan) is verified working on Alpine; the remaining backends are in progress.

What's included:

  • Compile-time libc detection (platform.h): defines LEMON_LINUX_MUSL on linux && !GLIBC, which drives backend asset selection.
  • Per-backend musl asset selection (llama.cpp, stable-diffusion.cpp, whisper.cpp, Kokoro, moonshine): musl builds fetch dedicated …-musl-… assets, never a glibc binary.
  • Alpine packaging (packaging/alpine/): APKBUILD (OpenRC instead of systemd), install scripts, build-apk.sh; adds onnxruntime runtime dep for the ONNX audio backends.
  • CI (alpine_apk_build.yml): builds + smoke-tests the .apk for x86_64 and aarch64.
  • setup.sh: apk branches at each package-manager choke point.
  • Dockerfile.alpine and a LEMONADE_BACKEND_REPO_OWNER testing hook (no-op when unset).

Depends on:
Companion changes to the backend release repos publish the …-musl-… assets (separate PRs). backend_versions.json intentionally unchanged.

Status:
llama.cpp CPU + Vulkan verified on Alpine; sd.cpp / whisper / Kokoro / moonshine in progress.

Cross-platform safety:
All C++ changes are #ifdef LEMON_LINUX_MUSL-guarded; shell changes are apk-only. glibc / Windows / macOS unchanged.

@clemperorpenguin

Copy link
Copy Markdown
Collaborator Author

PR depends on merges:
lemonade-sdk/llama.cpp#22
lemonade-sdk/stable-diffusion.cpp#16
lemonade-sdk/whisper.cpp-rocm#7
lemonade-sdk/moonshine-server-rocm#1
lemonade-sdk/Kokoros#5

Set LEMONADE_BACKEND_REPO_OWNER=clemperorpenguin for testing :)

Note: I can't get the whisper CI to pass, not sure why. Windows NPU builds for a day and then cancels the job.

@clemperorpenguin
clemperorpenguin marked this pull request as ready for review July 5, 2026 00:17
@clemperorpenguin clemperorpenguin self-assigned this Jul 5, 2026

@fl0rianr fl0rianr left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for pushing Alpine/musl support — the APK/Docker direction is good and the llama.cpp CPU/Vulkan smoke coverage is useful. I don’t think this is merge-ready yet.

Blocking issues:

  • Dockerfile.alpine bakes LEMONADE_BACKEND_REPO_OWNER=clemperorpenguin into the runtime image. That makes official images fetch backend binaries from a personal fork by default. Please default this to empty and only pass it explicitly in temporary CI/testing, or remove it once the companion asset PRs have landed.

  • The OpenRC service does not export XDG_RUNTIME_DIR or RUNTIME_DIRECTORY, while the Linux runtime-dir resolver requires one of them. The APK CI only tests direct lemond startup with a manually exported XDG_RUNTIME_DIR, so it does not cover the documented rc-service lemonade-server start path.

  • musl hosts can still select/download glibc Linux assets for some backends, especially llamacpp CUDA/ROCm and whispercpp ROCm. Please either mark those variants unsupported on musl or remap them consistently, and add install-param tests that assert musl never resolves Ubuntu/glibc asset names.

  • The PR depends on several unmerged backend release PRs for the musl assets. Please merge/release those first or keep this PR non-mergeable until the assets are available from official repos.

Also please reconcile the aarch64 descriptor support with the newly added aarch64 asset names and update the Dockerfile/README wording around Moonshine.

@fl0rianr fl0rianr left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the updates — the main blockers from my previous review are addressed now.

Remaining open points:

  • The companion backend asset PRs still need to land I guess you have this in plan
  • Please remove the temporary fork build-arg from the Alpine Docker smoke workflow once the companion assets are upstream.

After those move forward, I’m approving this.

clemperorpenguin and others added 4 commits August 8, 2026 22:56
Add compile-time libc detection in platform.h (LEMON_LINUX_MUSL) and a
musl asset resolver so backend downloads select musl builds on Alpine.
Backend descriptors omit recipes that ship glibc-only assets (llama.cpp
cuda/rocm, sd.cpp cuda/rocm, whisper.cpp rocm) on musl, so a musl host
never offers a backend it cannot download.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Add an APKBUILD with build/install scripts, an OpenRC init script, and a
Dockerfile.alpine for musl builds. setup.sh learns apk package mappings;
libsystemd is skipped since Alpine has no systemd.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Assert a musl host never resolves a glibc ("ubuntu") asset and that
backends with no musl build throw. Arch is a parameter, so the test runs
on any libc. Registered with add_cpp_ci_test(... CI ON) so it runs under
the cpp-ci CTest label.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Build and smoke-test the APK on x86_64 and aarch64, exercising both the
installed package and the OpenRC service path. The APK job follows the
deferred-CI convention: it is gated behind ci:distros on pull requests
and reports through an "Alpine APK builds" aggregate check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@clemperorpenguin

Copy link
Copy Markdown
Collaborator Author

I've thought about this more, it will either add tech debt to lemonade or to ggml, and I do not know that there is much demand for an Alpine package at this point - ROCm is not even fully packaged on Alpine yet afaik. Further, with custom backends being discussed/upcoming, and recent development of https://github.com/pg83/solo , I'm not sure if native musl support makes sense at this time without a way to run the glibc binaries (like with solo). Closing for now to refocus on other priorities.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area::installer Windows MSI / macOS DMG / Debian / RPM packaging enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants