Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
45
docs/development.md
Normal file
45
docs/development.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue