pheon/docs/development.md
Jan Petykiewicz d95c378690 Add a reproducible upstream GDSII corpus check
Pin 30 layouts from five upstream repositories and verify downloads and license
files by SHA-256. Exercise full reads, scans, selected reads, and CLI
self-comparisons with a per-layout JSON report. Cache the inputs locally for
offline reruns.

The baseline exposes a CLI rejection of KLayout's padded-name fixture. The
gzip fixture passes directly through the CLI.
2026-11-17 16:15:05 -08:00

2.5 KiB

Development

This guide is for contributors building and checking Pheon. For usage, start with the CLI or Python 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. Source builds require the tracked Cargo.lock; update dependencies explicitly with Cargo.

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 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.

Check upstream layouts

The GDSII corpus pins open-source fixtures and cell libraries. After installing .[arrow] and building the release CLI, run:

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; 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 for source archives, wheels, and standalone CLI artifacts.