Skip to content

Contributing to SPy

Thanks for helping improve SPy! There are many ways to contribute: trying SPy and reporting issues, improving the documentation, adding tests or examples, and working on the compiler itself.

Talk to us

Contributing code

The contribution workflow (fork, branch, pre-commit hooks, pull request) is described in CONTRIBUTING.md.

Development setup

SPy needs Python dependencies (managed by pip, uv or Pixi) and a native library, bdw-gc. The most up-to-date requirements are in the tests workflow. Run all the commands below from the root of the repository, without an active virtual environment.

To install bdw-gc yourself (the uv and pip methods):

  • Debian/Ubuntu: sudo apt install libgc-dev
  • macOS, with Homebrew: brew install bdw-gc

Prerequisite: bdw-gc (see above).

uv sync
. .venv/bin/activate
make -C spy/libspy

Prerequisites: Python 3.12, pip >= 25.1 (for PEP 735 dependency groups) and bdw-gc (see above).

python3 -m venv .venv
. .venv/bin/activate
pip install -e . --group dev
make -C spy/libspy

No prerequisite: Pixi also installs bdw-gc.

pixi run make-libspy
pixi shell

Other useful commands: pixi run ruff-format, pixi run ruff-check, pixi run doc-serve, pixi run test-xdist.

Optional build dependencies

spy build compiles the generated C code to a native or WebAssembly binary. Depending on the target:

  • Native (--target native): a system C compiler such as gcc or clang (build-essential on Debian/Ubuntu).
  • Emscripten (--target emscripten): the Emscripten SDK, with the latest toolchain activated so that emcc is on your PATH.
  • WASI (--target wasi): uses Zig, which is installed automatically with SPy.

The interpreter and redshift work without any of these.

Running the tests

pytest
pytest -n auto -v -x

To understand how the compiler is organized, read The compilation pipeline.

Contributing to the documentation

See Contributing to the documentation.