pheon/docs/development.md

45 lines
1.7 KiB
Markdown

# Development
This guide is for contributors building and checking Pheon. For usage, start
with the [CLI](cli.md) or [Python](python.md) guide.
## Build and test
The checkout selects the stable Rust toolchain; the minimum supported compiler
is 1.88. Python bindings require Python 3.11 or newer.
```sh
cargo test --locked
cargo test --release --locked
cargo build --release --locked
python -m pip install '.[arrow]'
python -I tools/check_installed.py
```
Use `RUSTUP_TOOLCHAIN=1.88.0` to check source builds against the minimum compiler.
The Python package bundles its native library during installation. To test a
newly built library without reinstalling, set `PHEON_LIBRARY` to its absolute
path and run `python -m unittest discover -s tests/python` from the checkout.
Unset this override when checking installed artifacts with `check_installed.py`.
## Interfaces and reports
The CFFI declarations live in [pheon/_ffi.h](../pheon/_ffi.h). Keep them aligned
with the exported native functions. The C API version and
[Arrow layout version](arrow-schema.md) are independent of package releases and
the [JSON report schema](diff-reports.md).
Review tests cover comparison semantics, CLI behavior, symbolic array counts,
and versioned report goldens. To regenerate JSON goldens after deliberately
changing their contract:
```sh
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
```
Inspect the resulting diff. Goldens normalize the producer version to `test`;
a package version change alone should not alter them. JSON Schema checks verify
structure, while semantic tests verify links, totals, and result/exit agreement.
See [building releases](releases.md) for source archives, wheels, and standalone
CLI artifacts.