Installation¶

postc is developed with uv. This page covers the recommended uv setup, the sibling-repo layout postc expects, a plain pip alternative, and the system prerequisites no Python package manager installs for you: a C compiler, and — per backend — the qbe binary or the WASM toolchain (llvmlite, for the LLVM backend, is pip-installable via the llvm extra).

Requirements¶

Repository layout¶

postc's dev dependencies are wired to its sibling repo through [tool.uv.sources] path deps, so check both repos out side by side:

compilers/
├── postc/         # this repo
└── postpython/    # sibling — provides postyp + postpyc

Two editable path deps point into that sibling:

• postyp — the shared POST Python type vocabulary, from ../postpython/postyp-dist. Single source of truth; the compiler depends on it at runtime (postyp>=0.3.0).
• postpyc — the POST Python reference implementation, from ../postpython. It is postc's benchmark baseline: postc's output is measured against it over time (see Benchmarking).

Both become versioned PyPI deps once published; until then the checkout is required.

git clone https://github.com/openteams-ai/postc
git clone https://github.com/openteams-ai/postpython
cd postc

Install with uv (recommended)¶

From the postc/ checkout, sync everything — all dependency groups and all extras:

uv sync --all-groups --all-extras
uv run postc --help

That installs the runtime dep (postyp), the dev group (pytest, ruff, mypy, nox, hypothesis, numpy, narwhals, and the postpyc baseline), the docs group (zensical), and every optional-dependency extra.

For a leaner environment, sync selectively:

uv sync                      # runtime deps only (postyp)
uv sync --group dev          # + the test/lint toolchain
uv sync --extra numpy        # + a single extra

Install with pip¶

pip works too. Because the type vocabulary is a path dep during development, install the sibling editable checkout alongside postc:

python -m pip install -e ../postpython/postyp-dist   # postyp
python -m pip install -e .                           # postc

Add extras in the usual way — pip install -e '.[numpy,narwhals]'.

Extras¶

Backend toolchains and their optional integrations opt in via extras, keeping the core dependency-light. The C and QBE backends need only a system C compiler (and the qbe tool); the LLVM backend needs the llvm extra:

System prerequisites¶

These are not pip-installable and must be present on your PATH.

C compiler¶

Both backends produce native code by compiling emitted source with a C compiler. Any of cc, clang, or gcc works.

cc --version            # macOS: ships with the Xcode command-line tools
# Debian/Ubuntu:  sudo apt install build-essential
# Fedora:         sudo dnf install gcc

qbe¶

The QBE backend lowers the IR to QBE IL, which the qbe tool assembles. Install it from c9x.me/compile:

qbe -h                  # confirm it is on your PATH
# macOS (Homebrew):  brew install qbe

Details of what each backend shells out to live in Toolchain.

Verify¶

uv run postc --help

Then work through Getting started, or see the full CLI reference. To run the test suite and doc build, see Testing:

make test       # pytest
make lint       # ruff (the enforced gate)
make docs       # zensical build --strict