GitHub Actions CI: explain Zig usage in Python wheel release

[jayaddison]

The Zig toolchain functionality enabled here originates from a build workflow in the uap-rust repository; as far as I can tell, Zig is not required when building and releasing the Python wheels.

My understanding is that the maturin-action that installs the Zig dependencies would proceed even if they cannot be installed, so I don't think that their failure would block the release process here.

Even so, I think that software build processes should usually try to limit their build requirements to only what is necessary, so I'm offering this as a cleanup.

Update: Zig is used during the relevant GitHub Actions workflow to cross-build manylinux wheels; this PR has been repurposed to add an explanatory comment, instead of removing the flag to enable Zig as initial suggested.

Resolves #312.

[jayaddison]

@masklinn hm. re-reading the maturin-action link I posted -- I noticed that containerisation gets turned off as a side-effect of the --zig argument.

It looks like the CI job assigns various native build runners from a matrix of options -- so I don't know whether we need the overhead (and extra surface area) of a Docker build.

One idea would be to explicitly configure container: off for these builds, to retain equivalence with the side-effect that the --zig arg had.

[masklinn]

hm. re-reading the maturin-action link I posted -- I noticed that containerisation gets turned off as a side-effect of the --zig argument.

That was never intended, so doesn't matter.

It looks like the CI job assigns various native build runners from a matrix of options -- so I don't know whether we need the overhead (and extra surface area) of a Docker build.

The question is less whether we need the overhead and more whether we need to avoid it.

The wheels workflow doesn't run normally, only when the PR is flagged to run it or when cutting a release, so it doesn't matter.

[masklinn]

Although it does look like the dockerised maturin is not happy: https://github.com/ua-parser/uap-python/actions/runs/25629265798/job/75229894764#step:5:262

[jayaddison]

Hm. OK.

There is a note in the maturin-action readme that building wheels should use docker containers or zig: https://github.com/PyO3/maturin/blob/1f7e7527f23b88a3a3a22be5dda927ca8fe32ea3/README.md?plain=1#L205-L207

For portability reasons, native python modules on linux must only dynamically link a set of very few libraries which are installed basically everywhere, hence the name manylinux.
The pypa offers special docker images and a tool called auditwheel to ensure compliance with the manylinux rules.
If you want to publish widely usable wheels for linux pypi, you need to use a manylinux docker image or build with zig.

...and some of that text originates from: PyO3/maturin#2457

I might ask there about how/why Zig helps here.

One other thing I noticed is a couple of the warnings in the failed build:

⚠️ Warning: Failed to determine python platform

Naively inspecting the code those led me to the Rust detect_arch_from_python function in maturin -- it looks like it can detect macos and win Python versions, but that Linux wouldn't be handled. Seemingly that's somewhat-intentional but again I'm not exactly sure why.

If Zig really is required for wheel builds, as per the README, then I expect we'd find a different form of build failure if we attempt to configure container: off explicitly.

[jayaddison]

Self-quoting re: Zig requirement:

...and some of that text originates from: PyO3/maturin#2457

I might ask there about how/why Zig helps here.

I was sagely pointed towards the documentation, and the answer I get from there is that maturin uses the (library) linking functionality from Zig's (cross-compile enabled) C compiler:

• https://www.maturin.rs/distribution.html#cross-compile-to-linuxmacos
• https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html

So, roughly speaking, this is a route to build manylinux-compliant wheels (wheels that only reference a limited number of system libraries from native code) without invoking a Docker containerised environment to do that.

---

Self-quoting re: Python detection:

One other thing I noticed is a couple of the warnings in the failed build:

⚠️ Warning: Failed to determine python platform

Naively inspecting the code those led me to the Rust detect_arch_from_python function in maturin -- it looks like it can detect macos and win Python versions, but that Linux wouldn't be handled. Seemingly that's somewhat-intentional but again I'm not exactly sure why.

Perhaps uap-python's assignment of a fixed python name for the wheel-build Python interpreter executable is relevant to this; ref the -i arg at:

uap-python/.github/workflows/release-wheels.yml

Line 106 in 2179269

args: --release --out dist -m ua-parser-rs/Cargo.toml -i python ${{ matrix.args }}

Edit: use permalink for code reference.

[jayaddison]

@masklinn roughly speaking: I think I now understand that --zig is valid, and that it's used to allow cross-compilation of uap-python's wheels without Docker.

So: I think we can close this.

If it would be worthwhile to get the Docker build back into a usable state as an alternative/comparison build (it wouldn't produce identical binaries, I'd guess, because the toolchain is different -- but having diverse available build options is good), I could try exploring this further, probably on the OpenCulinary fork of the repo.

[masklinn]

@jayaddison would you mind repurposing this PR just to add a comment to the zig option, in case someone else notices the same thing you did heads down the same rabbit hole? Something along the lines of

cross-builds used for manylinux, see comments on #315

or something along those lines?

I'd do it myself, but your branch is under an org repository and AFAIK github still does not support maintainer pushes to such.