P8. The wheels, four platforms and a free threaded one
- Dominant language
- Mojo
- Stars
- 1
- Forks
- 0
- PR merge metrics
- PR metrics pending
Description
Specification: [`07-python-bindings.md`](../blob/main/docs/specs/07-python-bindings.md) sections 2 and 7, [`12-the-python-front-door-measured.md`](../blob/main/docs/specs/12-the-python-front-door-measured.md) sections 2 and 6.
Four wheels plus a free threaded one, built by `cibuildwheel`, each self contained.
Platforms: manylinux x86-64, manylinux aarch64, macOS arm64, macOS x86-64. No Windows, because Mojo has no native Windows support and WSL users install the Linux wheel.
### What is known
macOS arm64 works by hand. The extension links two Mojo runtime libraries which pull in two more, none of it links libpython, the four copied beside the extension come to 2.72 MB, one absolute rpath is rewritten to `@loader_path`, and the result imports on a stock Homebrew CPython 3.14 started with `env -i` and a `PATH` that has no Mojo on it.
### What is not known, and is most of this issue
**Linux.** The runtime libraries are `.so` rather than `.dylib`, the rpath tool is `patchelf` rather than `install_name_tool`, the token is `$ORIGIN` rather than `@loader_path`, and `auditwheel` will want either to bundle the vendored Mojo libraries or to be told to exclude them. None of that is hard and none of it is done. The one item in it that could become a real constraint is the glibc version the Mojo runtime requires, which is unmeasured and which decides which manylinux tag firepanda can claim.
**Free threaded.** There is no free threaded interpreter on the machine that produced these measurements, so nothing was tested against one. The reason for optimism is that the extension does not link libpython, so the usual ABI mismatch does not apply. The reason not to assume is `Py_mod_gil`: a single phase initialised extension that does not declare `Py_MOD_GIL_NOT_USED` makes a free threaded interpreter turn the GIL back on at import with a warning, which would pass a test suite while defeating the entire point, and nothing found in `PythonModuleBuilder` offers a way to declare it.
So the free threaded job asserts on `sys._is_gil_enabled()` being false and on the absence of that warning, not merely on the tests passing. A wheel that silently re-enables the GIL is worse than no wheel, because it makes a false claim.
### Scope
- [ ] `cibuildwheel` configuration, with the Mojo toolchain coming from the pixi environment inside the build container
- [ ] The vendoring and rpath step generalised across macOS and Linux
- [ ] `auditwheel` and `delocate` either repairing the wheel or being told why not to
- [ ] The glibc floor measured and the manylinux tag chosen from it rather than guessed
- [ ] A free threaded 3.14 wheel, with the `sys._is_gil_enabled()` assertion
- [ ] The full test suite run against the installed wheel, not against the source tree, on every platform
- [ ] Wheel size recorded in CI with a threshold. The measurements say a firepanda wheel has no business being much larger than the runtime it vendors, so the threshold should start near four megabytes and any increase should have to be argued for
- [ ] The build pinned to a Mojo version, declared in the wheel metadata, with a nightly job so a toolchain break is caught on the day it lands
### Depends on
The module skeleton issue, for the build script this generalises.
Contributor guide
Research direction
Start with docs/specs/07-python-bindings.md sections 2 and 7 and docs/specs/12-the-python-front-door-measured.md sections 2 and 6, then inspect the module skeleton issue and PythonModuleBuilder. Trace the existing build script before defining cibuildwheel, vendoring, rpath, auditwheel, and delocate steps. Done means tested installed wheels for the listed platforms, including free-threaded Python, with measured glibc compatibility, size, metadata, and CI coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, ci-cd
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100