diff --git a/README.md b/README.md index 10f3fc5..eaf6d3c 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,11 @@ other object details. They compare object fields and coordinates exactly; see th ## Try the command-line tools -From a source checkout, install the CLI with Rust 1.88 or newer: +Install the CLI [from crates.io][crate] with Rust 1.88 or newer. +Use your own GDSII paths in the examples. ```sh -cargo install --path . --locked --bin pheon +cargo install pheon --locked pheon dump chip.gds pheon diff before.gds after.gds pheon hierarchy chip.gds --format mermaid @@ -29,13 +30,13 @@ comparisons. Start with the [CLI guide][cli], then set up ## Read layouts in Python -Python 3.11 or newer is required. From a source checkout: +Install the Python package [from PyPI][pypi] with Python 3.11 or newer. ```sh -python -m pip install . +python -m pip install pheon ``` -Run Python outside the source checkout to use the installed package: +Run this example from a directory containing `chip.gds`. ```python from pheon import arrow @@ -44,9 +45,8 @@ layout = arrow.read_path("chip.gds") print(layout.field("lib_name")[0].as_py()) ``` -Source installation needs Rust; prebuilt Python wheels bundle the native library. -The [Python guide][python] covers installation, selected reads, and integer -packing. The [Arrow reference][arrow] describes the returned data. +The Python package installs PyArrow. See the [Python guide][python] for source +installs and selected reads, and the [Arrow reference][arrow] for the returned data. ## Learn more @@ -59,7 +59,9 @@ Licensed under [GPL-3.0-only][license]. [arrow]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/arrow-schema.md [cli]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/cli.md [comparison]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/comparison.md +[crate]: https://crates.io/crates/pheon [docs]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/index.md [git]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/git.md [license]: https://mpxd.net/code/jan/pheon/src/branch/master/LICENSE.md +[pypi]: https://pypi.org/project/pheon/ [python]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/python.md diff --git a/docs/cli.md b/docs/cli.md index fb56827..2d66ea6 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,18 +6,17 @@ refer to the decompressed layout. The CLI runs independently of Python. ## Install -If you downloaded a CLI archive, extract it and add the directory containing -`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it. - -To install from a source checkout, use Rust 1.88 or newer: +Install the CLI [from crates.io](https://crates.io/crates/pheon) with Rust 1.88 +or newer. ```sh -cargo install --path . --locked --bin pheon +cargo install pheon --locked pheon --help ``` -You can also build locally with `cargo build --release --locked --bin pheon` -and run `target/release/pheon` (`pheon.exe` on Windows). +From a source checkout, install with `cargo install --path . --locked --bin pheon` +or build with `cargo build --release --locked --bin pheon` and run +`target/release/pheon` (`pheon.exe` on Windows). ## Inspect a layout @@ -44,44 +43,22 @@ output is diagram source for a Mermaid renderer. ## Compare revisions +Run `pheon diff before.gds after.gds` with your own files, or download these +small layouts from the pinned test corpus to try a comparison. +[small_rect.gds][small] · [big_rect.gds][big] + ```sh -pheon diff before.gds after.gds -pheon diff before.gds after.gds --hierarchy ascii --max-changes 20 -pheon diff before.gds after.gds --format json > report.json +pheon diff small_rect.gds big_rect.gds ``` -Text reports start with the result. The headline includes cell counts for -reports with more than three changed cells, incomplete comparisons, or omitted -changes. The `Cells:` section lists removals with `-`, additions with `+`, and -modifications with `*`. Modified cells show counts of rectangles, polygons, and -boxes changed, moved, added, or removed on each layer. When the only displayed -shape change on a layer is a move, the row shows its displacement in database -units. Repeated reference additions or removals to the same target appear as a -count. When both occur for one target, they share a row. A complete set of edits -to a target also shows -the total direct placements when there are unchanged placements, for example -`leaf · -3 refs, +6 refs · placements 10 -> 13`. +The example exits with code 1 and shows one changed rectangle in `TOP`. -An unchanged layer name appears inline when the layer occurs on one displayed -row, as in `1/0 (WG): rectangle moved by (20, -5) dbu`. A layer on several -displayed rows gets one legend entry. Object details use `-` for removals, `+` for additions, -and `~` for likely replacements. Identical unmatched objects share a row -with a count such as `+ 12× 1/0: path …`. Unmatched paths with five or more -vertices show their width, vertex count, and vertex bounds in one line. -A unique polygon, box, or path replacement that differs only in layer or -datatype appears on one row, for example `~ 1/0 (WG) → 2/0 (CORE) · rectangle`. - -Use `--format json` for details of individual objects and `--hierarchy` to see -which parent cells are affected. - -`diff` and `dump` use `--color auto` by default. Colors appear on supported -terminals and are disabled when `NO_COLOR` is set or `TERM=dumb`. Use -`--color=always` to keep colors in a pipe, for example -`pheon diff before.gds after.gds --color=always | less -R`. Use -`--color=never` for plain text. JSON reports and Mermaid diagram source stay plain. - -For large unscoped diffs with substantial byte overlap, Pheon reuses parsed -contents of matching cells. Cell timestamps and file offsets can differ. +```text +Different +Cells: +* TOP + 2/0: 1 rectangle changed +``` | Exit code | Meaning | | --- | --- | @@ -94,6 +71,21 @@ differences, but equality cannot be established. Read the [comparison rules](comparison.md) before relying on results in automation, and the [JSON reference](diff-reports.md) to consume reports programmatically. +### Read the text report + +The cell list marks additions with `+`, removals with `-`, and modifications +with `*`. Modified cells summarize shape changes by layer and repeated +references by target. A single move can show its displacement in database units. +Layer names appear inline or in a legend. Object rows use `~` for likely +replacements and `+` or `-` for unmatched additions and removals. + +Use `--details` for individual objects, `--hierarchy ascii` for affected +parents, or `--format json` for machine-readable evidence. + +`diff` and `dump` color supported terminals by default. Set `NO_COLOR`, use +`TERM=dumb`, or pass `--color=never` for plain text. Pass `--color=always` when +piping into `less -R`. JSON and Mermaid diagram source stay plain. + ## Choose the comparison scope ```sh @@ -146,20 +138,14 @@ reports. Replacement rows include a nested `-` row for the old object and a `+` row for the new object, with cell-local coordinates in database units, retained fields, and properties. -The diff hierarchy shows directly changed cells, affected ancestors, and targets -of modified references. It includes references from both revisions so removed -branches remain visible. Counts represent direct placements, with symbolic -counts for arrays. ASCII uses the cell list's change markers and marks -reference changes whose placement count stays the same. When the cell list -shows all edits to an unchanged target on a single branch, ASCII can omit -that terminal edge. The hierarchy retains ancestor paths, shared branches, -and edges with edits hidden by display filters or limits. ASCII appears when -there are relationships to show. ASCII diffs fold chains of three or more cells -along unchanged single-placement edges, for example `CHIP → block → * leaf`. -Branch points and changed edges keep their own rows. `--depth` counts the -original edges. -For the complete graph within the comparison scope, use -`--format json --hierarchy graph` without `--depth`. Display filters leave the -graph intact. +The diff hierarchy shows changed cells, affected ancestors, and modified +references from both revisions. Counts are direct placements, including +symbolic array counts. ASCII folds straight chains of unchanged edges and can +omit terminal edges already explained by the cell list. `--depth` counts the +original edges. For the full graph within the comparison scope, use +`--format json --hierarchy graph` without `--depth`. Next: configure [Git integration](git.md) or add [layer names](layer-names.md). + +[small]: https://raw.githubusercontent.com/gdsfactory/gdsfactory/7407836dd5d872c704fc06f38562a2ffc88049dc/tests/gds/small_rect.gds +[big]: https://raw.githubusercontent.com/gdsfactory/gdsfactory/7407836dd5d872c704fc06f38562a2ffc88049dc/tests/gds/big_rect.gds diff --git a/docs/development.md b/docs/development.md index e884456..1d960d7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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. diff --git a/docs/native-api.md b/docs/native-api.md index 7e0a020..01ddcf4 100644 --- a/docs/native-api.md +++ b/docs/native-api.md @@ -5,7 +5,13 @@ returned data layout, see the [Arrow reference](arrow-schema.md). ## Rust -Add `pheon` as a dependency. The library readers accept GDSII byte slices: +Add [pheon](https://crates.io/crates/pheon) from your Rust project. + +```sh +cargo add pheon +``` + +The library readers accept GDSII byte slices. ```rust use pheon::library::read_library; diff --git a/docs/python.md b/docs/python.md index bc03060..f02fffb 100644 --- a/docs/python.md +++ b/docs/python.md @@ -1,22 +1,24 @@ # Python Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read -only selected cells. The base `pheon` package also provides integer packing. +only selected cells. The package also provides integer packing. Python 3.11 or newer is required. ## Install -To install a PyPI release: +Install Pheon from [PyPI](https://pypi.org/project/pheon/). ```sh python -m pip install pheon ``` The package installs PyArrow for layout reads. Existing `pheon[arrow]` -requirements still work. Prebuilt wheels bundle the native library. From a -source checkout, use `python -m pip install .` with Rust 1.88 or newer. +requirements still work. [Prebuilt wheels](https://pypi.org/project/pheon/#files) +bundle the native library. On platforms without a compatible wheel, pip builds +the library from source and needs Rust 1.88 or newer and a native linker. -Run Python outside the source checkout to use the installed package. +From a source checkout, install with `python -m pip install .`, then run Python +outside the checkout to import the installed package. ## Read a layout @@ -85,11 +87,5 @@ Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`. Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access errors use Python's normal I/O exceptions. -## Use from Klamath or Masque - -Klamath's `native` extra installs Pheon's packing helpers. Masque's `arrow` extra -installs Pheon for layout reads. Use the same Python environment as the -companion package. - See [development](development.md) to test a locally built native library from Python, or the [native API guide](native-api.md) to call the library directly.