Refresh installation and walkthrough documentation

This commit is contained in:
Jan Petykiewicz 2026-11-19 11:04:20 -08:00
commit 2b5b184dc6

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