[ENHANCEMENT] Publish musllinux wheels (Alpine / musl libc)

[Kelketek]

Bug Description

Summary: Compilation fails with "cc: error: unrecognized command-line option '--rtlib=compiler-rt'" on Alpine in an arm64 environment.

Expected Behavior:
Autobahn installs as normal, compiling if it must.

Actual Behavior:
Compilation is induced upon install rather than using a prebuilt wheel, and fails.

Reproduction Steps

On an Arm64 system with docker, create a directory, change to it, and put in it this Dockerfile:

FROM alpine
RUN apk add uv gcc
RUN uv init /app
WORKDIR /app
RUN uv add autobahn

Then run docker build .

Environment

• Package: autobahn-python
• Version: 26.6.1
• Python Version: CPython 3.14.4
• Operating System: Raspberry Pi OS based on Debian GNU/Linux 12 (bookworm)
• Framework: Happens even installing alone, but getting it as a transitive dependency of Django channels/Daphne

Additional Context

Error Messages:

  × Failed to build `autobahn==26.6.1`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `hatchling.build.build_wheel` failed (exit status: 1)
      [stdout]
      ======================================================================
      Capturing FlatBuffers git version from deps/flatbuffers
      ======================================================================
        -> deps/flatbuffers not found or not a git repo
        -> Using existing version in _git_version.py
      Building for Python with extension suffix:
      .cpython-314-aarch64-linux-musl.so
      Building CFFI module:
      /root/.cache/uv/sdists-v9/pypi/autobahn/26.6.1/ke1VdRcg1EUd1NkdWNLjb/src/src/autobahn/nvx/_utf8validator.py
      generating ./_nvx_utf8validator.c
      the current directory is
      '/root/.cache/uv/sdists-v9/pypi/autobahn/26.6.1/ke1VdRcg1EUd1NkdWNLjb/src/src/autobahn/nvx'
      Building CFFI module:
      /root/.cache/uv/sdists-v9/pypi/autobahn/26.6.1/ke1VdRcg1EUd1NkdWNLjb/src/src/autobahn/nvx/_xormasker.py
      generating ./_nvx_xormasker.c
      the current directory is
      '/root/.cache/uv/sdists-v9/pypi/autobahn/26.6.1/ke1VdRcg1EUd1NkdWNLjb/src/src/autobahn/nvx'
      [stderr]
      cc: error: unrecognized command-line option '--rtlib=compiler-rt'
      warning: build_ext: building extension "_nvx_utf8validator" failed:
      command '/usr/bin/cc' failed with exit code 1
      cc: error: unrecognized command-line option '--rtlib=compiler-rt'
      warning: build_ext: building extension "_nvx_xormasker" failed: command
      '/usr/bin/cc' failed with exit code 1
      Traceback (most recent call last):
        File "<string>", line 11, in <module>
          wheel_filename =
      backend.build_wheel("/root/.cache/uv/builds-v0/.tmp8L16Vi", {}, None)
        File
      "/root/.cache/uv/builds-v0/.tmpblVrse/lib/python3.14/site-packages/hatchling/build.py",
      line 58, in build_wheel
          return os.path.basename(next(builder.build(directory=wheel_directory,
      versions=["standard"])))
      
      ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/root/.cache/uv/builds-v0/.tmpblVrse/lib/python3.14/site-packages/hatchling/builders/plugin/interface.py",
      line 149, in build
          build_hook.initialize(version, build_data)
          ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
        File
      "/root/.cache/uv/sdists-v9/pypi/autobahn/26.6.1/ke1VdRcg1EUd1NkdWNLjb/src/hatch_build.py",
      line 73, in initialize
          raise RuntimeError(
          ...<5 lines>...
          )
      RuntimeError: NVX CFFI extension was requested (AUTOBAHN_USE_NVX) but
      was not built - refusing to emit a pure-Python (py3-none-any) autobahn
      wheel. See the build log above for the underlying compile failure. Set
      AUTOBAHN_USE_NVX=0 to intentionally build a pure-Python wheel.
      hint: This usually indicates a problem with the package or the build
      environment.
  help: `autobahn` (v26.6.1) was included because `artconomy` (v3.2.0) depends
        on `channels[daphne]` (v4.3.2) which depends on `daphne` (v4.2.2)
        which depends on `autobahn`

Checklist

• I have searched existing issues to avoid duplicates
• I have provided a minimal reproducible example
• I have included version information
• I have included error messages/logs

[oberstet]

Thanks for the detailed report — the key detail is the toolchain, not autobahn itself.

What's actually happening

--rtlib=compiler-rt is not a flag autobahn adds (it appears nowhere in our
build). It comes from the Python interpreter you're building against:

• uv add autobahn builds against uv's managed CPython 3.14, which is a
  python-build-standalone
  build compiled with clang. It bakes clang-specific flags
  (--rtlib=compiler-rt, usually also -fuse-ld=lld) into its sysconfig
CFLAGS/LDSHARED.
• When autobahn's NVX C extension is compiled, cffi/setuptools reuse those exact
  sysconfig flags — but you installed gcc, and gcc rejects the clang-only
  --rtlib= option.

You can confirm it's coming from the interpreter:

python -c "import sysconfig; print(sysconfig.get_config_var('LDSHARED')); print(sysconfig.get_config_var('CFLAGS'))"

Two things make it surface on Alpine specifically:

1. Alpine is musl, and autobahn currently ships manylinux (glibc) wheels,
   not musllinux — so there's no binary wheel for cp314/musl/aarch64 and uv
   must build from the sdist.
2. autobahn 26.6.1 builds the NVX extension by default and now fails loudly
   instead of silently shipping a pure-Python wheel (this was an intentional fix
   so broken-toolchain builds don't go unnoticed).

Re: apk add compiler-rt

That alone won't fix it. --rtlib= is a clang option; Alpine's cc is
gcc, which doesn't understand it whether or not the compiler-rt runtime
package is installed. compiler-rt only helps if you also compile with clang.

How to fix it (pick one)

Option A — skip the native extension (simplest, works anywhere).
NVX is an optional SIMD-accelerated WebSocket UTF-8 validator / XOR masker; the
pure-Python fallback is fully functional, just a bit slower. Build with:

FROM alpine
RUN apk add uv gcc musl-dev
RUN uv init /app
WORKDIR /app
ENV AUTOBAHN_USE_NVX=0
RUN uv add autobahn

Option B — use Alpine's own Python toolchain (recommended if you want NVX).
Alpine's CPython is built with gcc/musl, so its sysconfig flags match the gcc
you install and NVX compiles cleanly:

FROM alpine
RUN apk add uv gcc musl-dev python3 python3-dev
RUN uv init /app
WORKDIR /app
ENV UV_PYTHON_PREFERENCE=only-system
RUN uv add autobahn

(Equivalently, point uv at the system interpreter, e.g.
uv venv --python /usr/bin/python3, instead of using uv's managed CPython.)

Option C — match the clang toolchain python-build-standalone expects.
Keep uv's managed CPython, but compile with clang + compiler-rt (+ lld) so the
embedded flags are understood — this is the only case where compiler-rt is
actually relevant:

FROM alpine
RUN apk add uv clang compiler-rt lld musl-dev
RUN uv init /app
WORKDIR /app
ENV CC=clang
RUN uv add autobahn

On the autobahn side

• We may add musllinux wheels so Alpine users get a prebuilt binary and don't
  need a compiler at all — tracking that as a possible enhancement.
• The build error message already points to AUTOBAHN_USE_NVX=0 as the explicit
  opt-out, which is Option A.

If Option A or B unblocks you, that's the quickest path; let us know how it goes.

---

references:

• https://pkgs.alpinelinux.org/package/edge/main/x86/compiler-rt
• https://pkgs.alpinelinux.org/package/edge/main/aarch64/compiler-rt
• https://pkgs.alpinelinux.org/package/edge/main/x86/llvm-runtimes
• https://pkgs.alpinelinux.org/package/edge/main/aarch64/llvm-runtimes

[oberstet]

there is no bug, but a potential enhancement, hence I renamed the issue. here are the details:

---

Problem

autobahn ships manylinux (glibc), macOS and Windows wheels, but no
musllinux wheels. So on Alpine / musl systems there is no installable binary
wheel — pip/uv fall back to building the sdist, which compiles the NVX CFFI
extension and breaks on toolchain mismatches (e.g. #1877: uv's clang-built
managed CPython injects --rtlib=compiler-rt, which Alpine's gcc rejects).

Shipping musllinux wheels lets musl users install a prebuilt binary with no
compiler at all, eliminating this whole class of report.

Proposal

Mirror the existing manylinux container matrix with musllinux (PEP 656):

• wheels-docker.yml (x86_64): add a job on quay.io/pypa/musllinux_1_2_x86_64
  alongside the current manylinux_2_28_x86_64.
• wheels-arm64.yml (aarch64): add jobs on quay.io/pypa/musllinux_1_2_aarch64
  alongside manylinux_2_28_aarch64 (QEMU, same as today).
• Same interpreter set: cp311, cp312, cp313, cp314, pypy311.
• auditwheel repair with the musllinux policy to tag/validate the wheels.
• Wire the new artifacts into release.yml (download-artifact-verified +
  check-release-fileset targets), as we did for the cp312/cp314 aarch64 wheels
  in [BUG] PyPI missing cp312 and cpy314 wheels for manylinux aarch64 #1848.

NVX itself compiles fine under musl — the musllinux container toolchain is gcc,
so the #1877 clang-flag problem does not apply to the wheels we build here.

Notes / scope

• This is a CI-matrix expansion (roughly doubles the Linux wheel jobs, incl. the
  slow QEMU aarch64 ones) — could land x86_64 musllinux first and add aarch64
  after, if we want to bound cost.
• Until then, the [ENHANCEMENT] Publish musllinux wheels (Alpine / musl libc) #1877 workaround stands: AUTOBAHN_USE_NVX=0 for a pure-Python
  build, or use Alpine's native python3 toolchain.
• We need to figure out the situation: PyPy on ARM64 with musl libc

Refs: #1877.

---

This analysis was produced with AI assistance (Claude Code) and requires human review before filing. Which I did.

[Kelketek]

@oberstet I got option c working, with a few adjustments. I had to use the package clang21 instead of clang, since apparently Alpine expects you to care about the version. clang22 claims to be available on their website, but it didn't pull for me. clang21 did and autobahn then built.

I think none of my other packages currently require a build or if they do, they weren't bothered by the switch to clang from gcc, so I'm able to move forward now, thanks! Looking forward to the prebuilts. :)