Refresh installation and walkthrough documentation
This commit is contained in:
parent
623de2e585
commit
2b5b184dc6
1 changed files with 94 additions and 97 deletions
|
|
@ -1,35 +1,42 @@
|
|||
# Development
|
||||
|
||||
This guide is for contributors building and checking Pheon. For usage, start
|
||||
with the [CLI](cli.md) or [Python](python.md) guide.
|
||||
The checkout selects stable Rust. The minimum supported compiler is 1.88.
|
||||
Use the checked-in `Cargo.lock` and update dependencies explicitly with Cargo.
|
||||
|
||||
## Build and test
|
||||
## Check a change
|
||||
|
||||
The checkout selects the stable Rust toolchain; the minimum supported compiler
|
||||
is 1.88. Python bindings require Python 3.11 or newer. Source builds require
|
||||
the tracked `Cargo.lock`; update dependencies explicitly with Cargo.
|
||||
| Area | Start here | First check |
|
||||
| --- | --- | --- |
|
||||
| GDSII parsing and Arrow reads | [`src/record.rs`](../src/record.rs), [`src/library.rs`](../src/library.rs) | `cargo test --locked --test parser_errors --test selective_reads` |
|
||||
| Comparisons and CLI | [`src/review.rs`](../src/review.rs), [`src/review/`](../src/review/), [`src/bin/pheon.rs`](../src/bin/pheon.rs) | `cargo test --locked --test review` |
|
||||
| Python and CFFI | [`pheon/`](../pheon/), [`src/lib.rs`](../src/lib.rs) | `python -I tools/check_installed.py` after installation |
|
||||
|
||||
Run `cargo test --locked` for the full Rust suite or `cargo test --release --locked`
|
||||
for release builds. Set `RUSTUP_TOOLCHAIN=1.88.0` to check the minimum compiler.
|
||||
|
||||
## Test the Python package
|
||||
|
||||
Use Python 3.11 or newer and install into a virtual environment.
|
||||
|
||||
```sh
|
||||
cargo test --locked
|
||||
cargo test --release --locked
|
||||
cargo build --release --locked
|
||||
python3 -m venv .venv
|
||||
. .venv/bin/activate
|
||||
python -m pip install .
|
||||
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 and reads its
|
||||
version from installed package metadata. After 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`.
|
||||
To test a newly built shared library, set `PHEON_LIBRARY` to its absolute path
|
||||
and run `python -m unittest discover -s tests/python` from the checkout. Clear
|
||||
the override when checking the bundled library with `check_installed.py`.
|
||||
|
||||
## Check upstream layouts
|
||||
|
||||
The [GDSII corpus](../contrib/gds-corpus.toml) pins open-source fixtures and cell
|
||||
libraries. After installing Pheon and building the release CLI, run:
|
||||
libraries. Install Pheon in the virtual environment before running the corpus
|
||||
check.
|
||||
|
||||
```sh
|
||||
cargo build --release --locked --bin pheon
|
||||
python -I tools/check_gds_corpus.py --fetch
|
||||
```
|
||||
|
||||
|
|
@ -40,7 +47,7 @@ to `.cache/gds-corpus/report.json` and exits with status 1 if a check fails.
|
|||
|
||||
## Interfaces and reports
|
||||
|
||||
The CFFI declarations live in [pheon/_ffi.h](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h). Keep them aligned
|
||||
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).
|
||||
|
|
@ -53,9 +60,9 @@ changing their contract:
|
|||
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.
|
||||
Inspect the resulting diff. Goldens normalize the producer version to `test`.
|
||||
Use the [JSON Schema](diff-report-v1.schema.json) to check structure. Rust tests
|
||||
verify links, totals, and agreement between the result and exit status.
|
||||
|
||||
See [building releases](releases.md) for source archives, wheels, and standalone
|
||||
CLI artifacts.
|
||||
|
|
|
|||
Loading…
Reference in a new issue