Refresh installation and walkthrough documentation
This commit is contained in:
parent
623de2e585
commit
2b5b184dc6
1 changed files with 94 additions and 97 deletions
98
docs/cli.md
98
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue