pheon/docs/development.md

2.8 KiB

Development

The checkout selects stable Rust. The minimum supported compiler is 1.88. Use the checked-in Cargo.lock and update dependencies explicitly with Cargo.

Check a change

Area Start here First check
GDSII parsing and Arrow reads src/record.rs, src/library.rs cargo test --locked --test parser_errors --test selective_reads
Comparisons and CLI src/review.rs, src/review/, src/bin/pheon.rs cargo test --locked --test review
Python and CFFI pheon/, 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.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
python -I tools/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 pins open-source fixtures and cell libraries. Install Pheon in the virtual environment before running the corpus check.

cargo build --release --locked --bin pheon
python -I tools/check_gds_corpus.py --fetch

The checker uses curl to cache layouts and license files in .cache/gds-corpus/ and verifies their SHA-256 digests. Omit --fetch to rerun offline. It checks full reads, scans, selected reads, and CLI self-comparisons. It writes diagnostics 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. Keep them aligned with the exported native functions. The C API version and Arrow layout version are independent of package releases and the JSON report schema.

Review tests cover comparison semantics, CLI behavior, symbolic array counts, and versioned report goldens. To regenerate JSON goldens after deliberately 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. Use the JSON Schema to check structure. Rust tests verify links, totals, and agreement between the result and exit status.

See building releases for source archives, wheels, and standalone CLI artifacts.