Skip to content

Contributing

Dev setup

postc uses uv and expects its sibling repo ../postpython checked out alongside it (the source of the postyp type vocabulary and the postpyc benchmark baseline).

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

System prerequisites (not pip-installable): a C compiler (cc/clang/gcc) and the qbe binary for the QBE backend.

The enforced gate

Ruff and the differential test suite are the gate; the type-checkers are advisory (the lifted compiler internals carry pre-existing type debt).

make test       # pytest
make lint       # ruff check + format  (the enforced gate; also runs in pre-commit)
make typecheck  # mypy / ty / pyrefly  (advisory, never fails the build)
make docs       # zensical build --strict

Run a single tier with markers: uv run pytest -m unit (or integration, e2e).

Adding a golden program

The end-to-end corpus lives in tests/c_e2e/programs/. To add one:

  1. Drop a self-contained POST module (typed functions, no top-level executable code) into tests/c_e2e/programs/.
  2. Add its probes — (function, args) tuples — to PROBES in tests/c_e2e/test_programs.py. The differential oracle then runs it under CPython and every backend and asserts they agree.

The whole corpus is also compiled on every available backend by the compile ratchet. See the testing guide.

Adding a backend

Implement the Backend protocol, register it (in-tree or via a postc.backends entry point), and hold it to the differential suite. The full walkthrough is in Writing a backend.

Commit hygiene

pre-commit runs ruff (check + format) and a few generic hooks. Keep the diff scoped; the discipline is to lift proven code unchanged and rebuild only structure.