Metadata-Version: 2.4
Name: alloconda
Version: 0.0.1a1
Summary: Zig-powered build backend and CLI for Python extension modules
Keywords: zig,python,extension,build,wheel,pep-517
Author: Matt Robenolt
Author-email: Matt Robenolt <m@robenolt.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/mattrobenolt/alloconda
Project-URL: Issues, https://github.com/mattrobenolt/alloconda/issues
Project-URL: Repository, https://github.com/mattrobenolt/alloconda
Description-Content-Type: text/markdown

# 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.

```bash
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.

```bash
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.

```bash
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`).

```bash
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.

```bash
alloconda init --alloconda-path ../../
```

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 point at a local alloconda checkout
- `--force` to overwrite existing files

### `alloconda inspect`

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

```bash
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.

```bash
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:

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

## Configuration

Alloconda reads optional defaults from `pyproject.toml`:

```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.
