alloconda 0.0.1a2

Zig-powered build backend and CLI for Python extension modules

alloconda CLI

Alloconda ships a small CLI for building and packaging Zig-based Python extensions. It also provides a PEP 517 build backend for pyproject.toml projects.

Commands

alloconda build

Build the extension via zig build, detect the PyInit_* symbol, and copy the compiled library into the Python package directory.

alloconda build

Options:

• --release: use -Doptimize=ReleaseFast
• --module: override the PyInit_* module name
• --lib: path to a prebuilt library
• --package-dir: where to install the extension
• --ext-suffix: override the extension suffix (useful for cross builds)
• --zig-target: Zig target triple for cross builds
• --python-include: cross-build Python include path
• --no-init / --force-init: control __init__.py generation

alloconda wheel

Build a wheel by staging the package, copying the compiled extension, and writing dist-info metadata. This is intentionally lightweight and targets the common PEP 427 path.

alloconda wheel --python-tag cp312 --abi-tag cp312 --manylinux 2_28 --arch x86_64

Options:

• Tag selection: --python-tag, --abi-tag, --platform-tag
• Manylinux/musllinux helpers: --manylinux, --musllinux, --arch
• --python-version / --pbs-target: use cached python-build-standalone headers
• --ext-suffix: override the extension suffix for cross builds
• --out-dir: wheel output directory (default: dist/)
• --skip-build: skip zig build if you already built the library

When using --python-version, run alloconda python fetch first to populate the cache. If --python-tag is omitted, it defaults from --python-version (e.g. cp314).

alloconda wheel-all

Build a full wheel matrix across common platforms and Python versions.

alloconda wheel-all --python-version 3.14 --include-musllinux

Options:

• --python-version (repeatable) or --all for every available version
• --target to override the default platform list
• --include-windows to add Windows targets (experimental)
• --fetch to auto-download missing headers
• --dry-run to print the matrix

alloconda develop

Build and install the project in editable mode via pip install -e . (or uv pip).

alloconda develop

Options:

• --release: use -Doptimize=ReleaseFast
• --module: override the PyInit_* module name
• --lib: path to a prebuilt library
• --package-dir: where to install the extension
• --ext-suffix: override the extension suffix
• --zig-target: Zig target triple for cross builds
• --python-include: cross-build Python include path
• --skip-build: skip the zig build step (requires existing output)
• --no-init / --force-init: control __init__.py generation
• --pip-arg: extra args passed through to pip (repeatable)
• --uv: use uv pip (auto-selected if pip is missing)

alloconda init

Scaffold a Zig project for an alloconda Python extension module.

alloconda init

This creates build.zig, build.zig.zon, src/root.zig, and a default package directory at src/<project_name>/__init__.py.

Options:

• --name to override the project name
• --module-name to override the Python extension module name
• --dir to choose a target directory
• --alloconda-path to use a local checkout or git+https URL
• --force to overwrite existing files

If --alloconda-path is omitted, alloconda is fetched from GitHub and pinned in build.zig.zon.

If pyproject.toml exists, the build backend stanza is added automatically.

alloconda inspect

Inspect a built library or wheel and print derived metadata. Useful for quick sanity checks in scripts.

alloconda inspect --lib zig-out/lib/libzigadd.dylib
alloconda inspect --wheel dist/zigadd-0.1.0-*.whl --verify

alloconda python fetch

Fetch and cache python-build-standalone headers for cross builds.

alloconda python fetch --version 3.14 --manylinux 2_28 --arch x86_64

The cache location can be overridden with ALLOCONDA_PBS_CACHE or --cache-dir.

Build backend

Add this to pyproject.toml to use alloconda as a build backend:

[build-system]
requires = ["alloconda"]
build-backend = "alloconda.build_backend"

Configuration

Alloconda reads optional defaults from pyproject.toml:

[tool.alloconda]
module-name = "_zigadd"
package-dir = "zigadd"
python-version = "3.14"
python-tag = "cp314"
abi-tag = "cp314"
manylinux = "2_28"
arch = "x86_64"
include = ["*.pyi"]
exclude = ["tests/*"]

CLI flags and PEP 517 --config-settings override these values.