Skip to content

Building Wheels

Elzar includes a native Go library for sprite generation. This guide covers building platform-specific wheels.

Development build

For local development:

# Install dependencies
make env

# Build Go library
make lib

Building wheels

Local build

make wheels

This creates a platform-specific wheel in dist/:

map_style-0.1.0-py3-none-macosx_14_0_arm64.whl

Multi-architecture Linux builds

Use Docker to build wheels for multiple Linux architectures:

VERSION=0.1.0 ./wheel.sh

This builds:

  • map_style-0.1.0-py3-none-manylinux_*_x86_64.whl
  • map_style-0.1.0-py3-none-manylinux_*_aarch64.whl

Dockerfile

The multi-stage Dockerfile:

  1. Stage 1 (go-build): Compiles the Go sprite library
  2. Stage 2: Packages the Python wheel with the pre-built native library
# Stage 1: Build Go extension
FROM golang:1.24-bookworm AS go-build

COPY sprite/ sprite/

RUN cd sprite && go build -buildmode=c-shared \
    -o libpysprite.so ./pysprite

# Stage 2: Build Python wheel
FROM ghcr.io/astral-sh/uv:bookworm-slim

COPY --from=go-build /build/sprite/libpysprite.so generator/lib/
COPY . .

RUN uv build -w

Build caching

The Dockerfile uses BuildKit cache mounts for faster rebuilds:

RUN --mount=type=cache,target=/go/pkg/mod,id=gomod-${TARGETARCH} \
    --mount=type=cache,target=/root/.cache/go-build,id=gobuild-${TARGETARCH} \
    go build ...

Cache IDs include the target architecture to maintain separate caches for amd64 and arm64.

Wheel tags

The wheel uses the tag format: py3-none-{platform}

  • py3: Compatible with any Python 3.x (uses ctypes, not C extension)
  • none: No ABI dependency
  • {platform}: Platform-specific (contains native library)

Environment variables

Variable Description
VERSION Package version for wheel filename
SKIP_GO_BUILD Skip Go compilation (use pre-built library)
TARGET_GOOS Cross-compile target OS
TARGET_GOARCH Cross-compile target architecture

Cross-compilation

For cross-compiling the Go library:

# Build for Linux amd64 on macOS
TARGET_GOOS=linux TARGET_GOARCH=amd64 python setup.py build

Note

Cross-compilation requires appropriate C cross-compilers for CGO.

CI/CD integration

Example GitHub Actions workflow:

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'
      - uses: astral-sh/setup-uv@v4
      - run: uv build
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-${{ matrix.os }}
          path: dist/*.whl