python-wheels: add a development guide

[threexc]

This is the first draft of a new development guide containing information about how we structure our workflows and handle some quirks of building for riscv64. Please review the sections for clarity and functional utility - it's not very long, but it is dense, so I may have missed some important details.

[gounthar]

Really useful to have this written down. I've been building the same set of wheels on my side (the 34 in packages.json), so most of this matches what I ended up doing. A few edge cases from that experience that might be worth folding in:

suggestion: separate setup-uv from cibuildwheel's own build frontend. The uv section covers replacing setup-python, which works well. The different trap I keep hitting: when you copy an upstream workflow that runs cibuildwheel, cibuildwheel can pick uv as its build frontend (build[uv]), and that fails on riscv64 because it can't find uv inside the manylinux container (which uv). Setting CIBW_BUILD_FRONTEND: build (or pip) fixes it. I hit this on msgspec. Might be worth a line, since anyone copying a cibuildwheel-based workflow will run into it.

suggestion: a note on the compiler. A few packages need GCC 14 on riscv64, not 13: abseil trips a subword-atomics static_assert under GCC 13 (bit me on sentencepiece), and anything pulling _Float16/zvfh intrinsics needs 14 too. The manylinux_2_39_riscv64 image ships GCC 14, so cibuildwheel-in-container builds are fine, but a workflow that compiles directly on the runner gets the runner's GCC 13. A short "if your build needs GCC 14..." note would save the next person a confusing failure.

question: the Python matrix. The section reads "four latest released" (3.11-3.14 + 3.14t) and then narrows to 3.12/3.13/3.14/3.14t via the NumPy precedent. My own releases are cp312/313/314 (I dropped 3.11 and haven't added 3.14t yet). Is the intended standard matrix 3.12 through 3.14t, with 3.11 excluded? Might help to state the one canonical matrix outright so it doesn't drift per-package.

thought (non-blocking): runner ISA. Around early June the RISE runner pool briefly lost the V extension and some vector binaries started hitting SIGILL. Probably out of scope for a dev guide, but for wheels that build or exercise RVV code, a green test depends on what the runner actually supports that day. Maybe just worth being aware of.

nitpick (non-blocking): a couple of small prose things while you're in there: "riscv64 wheel should be built" could be "wheels"; "critieria" -> "criteria"; and the first Licensing sentence ("Since RISE is the distributor..., ensuring that...") reads like it's missing its main verb.

Happy to open PRs for any of these rather than leaving them as review comments.

[threexc]

Really useful to have this written down. I've been building the same set of wheels on my side (the 34 in packages.json), so most of this matches what I ended up doing. A few edge cases from that experience that might be worth folding in:

suggestion: separate setup-uv from cibuildwheel's own build frontend. The uv section covers replacing setup-python, which works well. The different trap I keep hitting: when you copy an upstream workflow that runs cibuildwheel, cibuildwheel can pick uv as its build frontend (build[uv]), and that fails on riscv64 because it can't find uv inside the manylinux container (which uv). Setting CIBW_BUILD_FRONTEND: build (or pip) fixes it. I hit this on msgspec. Might be worth a line, since anyone copying a cibuildwheel-based workflow will run into it.

suggestion: a note on the compiler. A few packages need GCC 14 on riscv64, not 13: abseil trips a subword-atomics static_assert under GCC 13 (bit me on sentencepiece), and anything pulling _Float16/zvfh intrinsics needs 14 too. The manylinux_2_39_riscv64 image ships GCC 14, so cibuildwheel-in-container builds are fine, but a workflow that compiles directly on the runner gets the runner's GCC 13. A short "if your build needs GCC 14..." note would save the next person a confusing failure.

question: the Python matrix. The section reads "four latest released" (3.11-3.14 + 3.14t) and then narrows to 3.12/3.13/3.14/3.14t via the NumPy precedent. My own releases are cp312/313/314 (I dropped 3.11 and haven't added 3.14t yet). Is the intended standard matrix 3.12 through 3.14t, with 3.11 excluded? Might help to state the one canonical matrix outright so it doesn't drift per-package.

thought (non-blocking): runner ISA. Around early June the RISE runner pool briefly lost the V extension and some vector binaries started hitting SIGILL. Probably out of scope for a dev guide, but for wheels that build or exercise RVV code, a green test depends on what the runner actually supports that day. Maybe just worth being aware of.

nitpick (non-blocking): a couple of small prose things while you're in there: "riscv64 wheel should be built" could be "wheels"; "critieria" -> "criteria"; and the first Licensing sentence ("Since RISE is the distributor..., ensuring that...") reads like it's missing its main verb.

Happy to open PRs for any of these rather than leaving them as review comments.

Thanks for the review. Since this is still a draft and the doc isn't merged yet, I'll just address your comments directly. On the setup-uv side, which manylinux container image did you use? I can see uv inside one I just pulled:

tgamblin@alchemist ~ $ docker run --rm -it quay.io/pypa/manylinux_2_39_riscv64
WARNING: The requested image's platform (linux/riscv64) does not match the detected host platform (linux/amd64/v3) and no specific platform was requested
[root@c7c0206645ed /]# uv --version
uv 0.11.28 (riscv64gc-unknown-linux-gnu)
[root@c7c0206645ed /]#

[threexc]

@gounthar I've addressed your other issues/comments. Would you like me to add Suggested-by tags to those commits? If so, which email do I use for you?

Side note: we could open issues in the runner repo for the GCC and ISA points, so they can be tracked.

[gounthar]

You're right that the current manylinux_2_39_riscv64 ships uv. That lines up: uv has had riscv64 builds since around 0.7.13 last year, so my "uv isn't in the image" framing is stale.

My failure was on cibuildwheel 3.2.1 a while back, paired with skipping musllinux, so I can't cleanly say now whether it was the older cibuildwheel not provisioning uv into the container or the musllinux image rather than manylinux. Either way, with the image as it is today build[uv] may just work, and I don't want you writing down a workaround that isn't needed anymore.

Let me re-test on a current image before you fold anything in. I've got a zstandard build PR open (#161) that hit exactly this choice, so I'll flip it to upstream's build[uv] and let the RISE runner settle it, then report back.

On your other note: no need for Suggested-by on the commits; the review credit is plenty, but thanks for offering.

As for tracking the GCC and ISA points in the runner repo, please go ahead and open them. The vector/ISA one overlaps riscv-runner#49 (the RVV drop I filed), though that one is closed now, so it may be worth reopening or checking whether it has been resolved rather than starting fresh. The GCC-13-vs-14 default looks like a clean new issue.
I'm happy to add repro details on either once they are up.

[gounthar]

Reporting back with a result: build[uv] works fine on riscv64 now, so scratch my first suggestion.

I dropped the frontend override on the zstandard PR (#161) and let upstream's build[uv] run on the RISE runner. All four wheels (cp312/313/314 + cp314t) built and the test suite passed natively, using uv the whole way:

build_frontend: build[uv]
+ python -m build /project --wheel --installer=uv
+ uv pip install .../zstandard-0.25.0-cp313-cp313-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl
224 passed, 68 skipped

So the dev guide doesn't need a build-frontend workaround. My old failure was cibuildwheel 3.x era and it's moot on the current image. If any note is worth keeping, it's the opposite of what I first said: on a current manylinux_2_39_riscv64, build[uv] just works.

[threexc]

@gounthar I've opened this for the GCC version mismatch: riseproject-dev/riscv-runner#65

Please add any extra info you may find helpful there.

[luhenry]

riscv64 workflows using it will generally fail

This is not true. As long as the workflow keeps to major.minor (e.g. 3.12, 3.13) then it will work since there is already these versions installed on the runner. There is also already the free threaded versions for 3.13 and 3.14

[threexc]

Ah right, I forgot about that. I'm inclined to still keep using uv since it doesn't add much extra to the workflows, and it is a bit more "predictable". What do you think?

[luhenry]

Happy with using uv. I just want to be careful in the documentation we write.

[luhenry]

I don't believe you need to checkout the repository to have access to it. You can simply specify uses: riseproject-dev/python-wheels/actions/publish-to-gitlab@main. You can also just use a composite action in the same repository: https://docs.github.com/en/actions/tutorials/create-actions/create-a-composite-action#creating-a-composite-action-within-the-same-repository

[threexc]

I've got a NumPy upgrade running now, I'll test the first suggestion out on that and if it works I'll adjust the docs. Expect a push covering that and the setup-python/setup-uv thing soonish.

[luhenry]

thought (non-blocking): runner ISA. Around early June the RISE runner pool briefly lost the V extension and some vector binaries started hitting SIGILL. Probably out of scope for a dev guide, but for wheels that build or exercise RVV code, a green test depends on what the runner actually supports that day. Maybe just worth being aware of.

Again, that's not true. @gounthar please when using AI, make sure it's accurate.