Add free-threaded Python 3.14 support and build matrix printing to CI workflow [full-build]

[Copilot]

Overview

Updates the build workflow to explicitly support free-threaded Python 3.14 wheels alongside existing abi3 wheels, adds build matrix visibility, and clarifies musllinux configuration.

Changes

1. Free-Threaded Python 3.14 Support

All platforms now explicitly build both:

• abi3 wheels (cp311-*) - compatible with Python 3.11+
• Free-threaded wheels (cp314t-*) - for Python 3.14 with GIL disabled

Windows:

$env:CIBW_BUILD = 'cp311-* cp314t-*'

Linux/macOS:

CIBW_BUILD: "cp311-* cp314t-*"

This ensures consistent behavior across platforms and makes free-threaded support explicit rather than accidental.

2. Build Matrix Visibility

Added --print-build-identifiers step on all platforms before building wheels. This will print exactly which wheel identifiers will be built (e.g., cp311-manylinux_x86_64, cp314t-win_amd64), making CI logs more transparent and easier to debug.

3. Explicit Musl Target Configuration

Enhanced CIBW_BEFORE_ALL_LINUX to explicitly add musl rust targets for clarity:

rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu \
  ppc64le-unknown-linux-gnu i686-unknown-linux-gnu \
  x86_64-unknown-linux-musl aarch64-unknown-linux-musl

This makes musllinux support explicit and ensures the necessary Rust toolchains are available.

4. Preserved Existing Behavior

• musllinux wheels continue to be built for x86_64 and aarch64
• musllinux i686 remains skipped (CIBW_SKIP: "*-musllinux_i686")
• Windows architectures remain x86 and AMD64 (no ARM64)
• All manylinux and musllinux image configurations unchanged
• No changes to test.yml or publish.yml workflows

Expected Build Output

After this change, wheels will be built for:

Windows:

• cp311-win_amd64, cp311-win32 (abi3)
• cp314t-win_amd64, cp314t-win32 (free-threaded, if interpreter available)

Linux:

• cp311-manylinux_* for x86_64, aarch64, ppc64le, i686 (abi3)
• cp311-musllinux_* for x86_64, aarch64 (abi3)
• cp314t-manylinux_* and cp314t-musllinux_* (free-threaded, if interpreter available)

macOS:

• cp311-macosx_* for x86_64 and arm64 (abi3)
• cp314t-macosx_* for x86_64 and arm64 (free-threaded, if interpreter available)

Benefits

✅ Consistent free-threaded Python 3.14 support across all platforms
✅ Better CI visibility with build matrix printing
✅ Explicit musl configuration for maintainability
✅ Maintains all existing wheel builds including musllinux

Original prompt

Please update the build workflow to (1) keep musllinux support, (2) normalize Windows builds so they explicitly include free-threaded (cp314t) wheels in addition to the abi3 wheel, and (3) print the cibuildwheel build matrix (identifiers) prior to building on all OSes.

Context from current repo config (commit d6bce0b):

• .github/workflows/build.yml runs cibuildwheel v2.23.2 on Linux/macOS with CIBW_BUILD set to "cp311-*" (abi3 via pyo3/abi3-py311), and uses a manual step on Windows without specifying CIBW_BUILD (which led to a cp314t Windows wheel getting built in 0.8.0). Linux/macOS currently have musllinux images available and produced musllinux wheels in 0.8.0. We want to keep musllinux.
• pyproject.toml uses maturin with pyo3/abi3-py311.

Requested changes:

1. Keep musllinux builds on Linux and make rustup musl targets explicit for clarity.

   • In the Linux/macOS cibuildwheel environment, keep the existing manylinux/musllinux images.
   • In CIBW_BEFORE_ALL_LINUX, after installing rustup, add explicit targets including GNU and musl:
     rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu ppc64le-unknown-linux-gnu i686-unknown-linux-gnu x86_64-unknown-linux-musl aarch64-unknown-linux-musl
   • Keep skipping musllinux i686 if that is intentional (currently CIBW_SKIP: "*-musllinux_i686").

2. Normalize Windows builds and include free-threaded wheels explicitly.

   • In the Windows step, set environment variables:
     • CIBW_BUILD = 'cp311-* cp314t-*' (keeps abi3 wheel and also builds free-threaded 3.14 if available)
     • Keep CIBW_ARCHS_WINDOWS = 'auto' (x86, AMD64). Do NOT add ARM64 unless specifically requested later.
     • Keep CIBW_BUILD_VERBOSITY = 3.
   • Insert a matrix print step by running: python -m pip install cibuildwheel && python -m cibuildwheel --print-build-identifiers before calling cibuildwheel to build.

3. Print the cibuildwheel matrix (build identifiers) on Linux and macOS too.

   • Add a step before the pypa/cibuildwheel action that installs cibuildwheel and calls --print-build-identifiers, using the same env that will be used by the action so the output matches the actual planned builds.

4. Also on Linux/macOS, expand CIBW_BUILD to include free-threaded builds explicitly:

   • CIBW_BUILD: "cp311-* cp314t-*"
     This will still build a single abi3 wheel per arch for CPython 3.11+ and add one free-threaded wheel per arch if an interpreter is available in the environment.

5. Do not alter publish or test workflows in this PR.

Acceptance criteria:

• CI logs on Windows, macOS, and Linux display the lines from cibuildwheel --print-build-identifiers that include cp311-* plus cp314t-* where available.
• Windows job explicitly sets CIBW_BUILD as described and still builds AMD64 and x86 wheels.
• Linux/macOS jobs build the same abi3 wheels as before plus free-threaded wheels (if interpreters exist), and keep producing musllinux wheels; musl rust targets are configured explicitly.
• No change to release triggers or publish/test workflows.

*This pull request was created as a result of the following prompt from Copilot chat.* > Please update the build workflow to (1) keep musllinux support, (2) normalize Windows builds so they explicitly include free-threaded (cp314t) wheels in addition to the abi3 wheel, and (3) print the cibuildwheel build matrix (identifiers) prior to building on all OSes. > > Context from current repo config (commit d6bce0b): > - .github/workflows/build.yml runs cibuildwheel v2.23.2 on Linux/macOS with CIBW_BUILD set to "cp311-*" (abi3 via pyo3/abi3-py311), and uses a manual step on Windows without specifying CIBW_BUILD (which led to a cp314t Windows wheel getting built in 0.8.0). Linux/macOS currently have musllinux images available and produced musllinux wheels in 0.8.0. We want to keep musllinux. > - pyproject.toml uses maturin with pyo3/abi3-py311. > > Requested changes: > 1) Keep musllinux builds on Linux and make rustup musl targets explicit for clarity. > - In the Linux/macOS cibuildwheel environment, keep the existing manylinux/musllinux images. > - In CIBW_BEFORE_ALL_LINUX, after installing rustup, add explicit targets including GNU and musl: > rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu ppc64le-unknown-linux-gnu i686-unknown-linux-gnu x86_64-unknown-linux-musl aarch64-unknown-linux-musl > - Keep skipping musllinux i686 if that is intentional (currently CIBW_SKIP: "*-musllinux_i686"). > > 2) Normalize Windows builds and include free-threaded wheels explicitly. > - In the Windows step, set environment variables: > - CIBW_BUILD = 'cp311-* cp314t-*' (keeps abi3 wheel and also builds free-threaded 3.14 if available) > - Keep CIBW_ARCHS_WINDOWS = 'auto' (x86, AMD64). Do NOT add ARM64 unless specifically requested later. > - Keep CIBW_BUILD_VERBOSITY = 3. > - Insert a matrix print step by running: python -m pip install cibuildwheel && python -m cibuildwheel --print-build-identifiers before calling cibuildwheel to build. > > 3) Print the cibuildwheel matrix (build identifiers) on Linux and macOS too. > - Add a step before the pypa/cibuildwheel action that installs cibuildwheel and calls --print-build-identifiers, using the same env that will be used by the action so the output matches the actual planned builds. > > 4) Also on Linux/macOS, expand CIBW_BUILD to include free-threaded builds explicitly: > - CIBW_BUILD: "cp311-* cp314t-*" > This will still build a single abi3 wheel per arch for CPython 3.11+ and add one free-threaded wheel per arch if an interpreter is available in the environment. > > 5) Do not alter publish or test workflows in this PR. > > Acceptance criteria: > - CI logs on Windows, macOS, and Linux display the lines from `cibuildwheel --print-build-identifiers` that include cp311-* plus cp314t-* where available. > - Windows job explicitly sets CIBW_BUILD as described and still builds AMD64 and x86 wheels. > - Linux/macOS jobs build the same abi3 wheels as before plus free-threaded wheels (if interpreters exist), and keep producing musllinux wheels; musl rust targets are configured explicitly. > - No change to release triggers or publish/test workflows.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[scott-griffiths]

This didn't include the correct tag in the commit message to make the wheels actually be built.