Refresh installation and walkthrough documentation

This commit is contained in:
Jan Petykiewicz 2026-11-19 11:04:20 -08:00
commit 2b5b184dc6
5 changed files with 94 additions and 97 deletions

View file

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

View file

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

View file

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

View file

@ -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;

View file

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