pheon/docs/cli.md

151 lines
6.5 KiB
Markdown

# Command-line tools
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
The CLI recognizes gzip-compressed GDSII by its file header. Reported byte offsets
refer to the decompressed layout. The CLI runs independently of Python.
## Install
Install the CLI [from crates.io](https://crates.io/crates/pheon) with Rust 1.88
or newer.
```sh
cargo install pheon --locked
pheon --help
```
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
```sh
pheon dump chip.gds
pheon dump chip.gds --records
pheon hierarchy chip.gds --format ascii --depth 4
pheon hierarchy chip.gds --format mermaid --top CHIP
```
`dump` lists objects by cell. A prefix such as `3x` counts copies of the same
normalized object within a cell. Coordinates are in database units. Rectangles
show two corners, and longer vertex lists wrap across lines. References show
the target and any array dimensions before the coordinates. Add `--records`
to inspect the original record sequence, including timestamps. In color
output, the object dump highlights cell headings and layer numbers, and the
record dump highlights record names.
`hierarchy` shows direct placement counts on references. `[subtree elided]`
marks a repeated cell whose children were skipped. Repeated leaves show
each parent's placement count without the marker. At the depth limit,
`[children omitted]` marks a cell with further descendants. Mermaid
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 small_rect.gds big_rect.gds
```
The example exits with code 1 and shows one changed rectangle in `TOP`.
```text
Different
Cells:
* TOP
2/0: 1 rectangle changed
```
| Exit code | Meaning |
| --- | --- |
| 0 | Equal under the comparison rules and selected scope. |
| 1 | Differences found in a complete comparison. |
| 2 | Invalid input, a command error, or an incomplete comparison. |
A code of 1 is an expected comparison result. A code of 2 can accompany definite
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
pheon diff before.gds after.gds --top CHIP --layer 1/0
pheon diff before.gds after.gds --cell RESONATOR
```
| Option | Compared content |
| --- | --- |
| `--top NAME` | The named cell and its reachable descendants in each revision. |
| `--cell NAME` | One cell, including its references, without its descendants. |
| `--layer L/T\|NAME` | Objects on the selected layer/type pair, plus references leading to that layer. |
Selectors combine: `--top CHIP --cell RESONATOR` selects that cell within CHIP's
subtree. A name absent from both revisions is an error; presence on only one
side is an addition or deletion. Layer selection omits cells irrelevant to that
layer, but library fields and metadata-version diagnostics remain relevant.
The complete input is parsed before scope selection, so malformed records
outside the scope still fail the command.
Both `--layer` and `--show-layer` accept exact, case-sensitive names from the
embedded metadata in either revision. If a name refers to several numeric pairs,
Pheon lists the choices. A valid numeric pair always selects that pair directly.
## Control report detail
```sh
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer WG
pheon diff before.gds after.gds --show-cell RESONATOR --details --max-changes 20
pheon diff before.gds after.gds --hierarchy mermaid --depth 4
```
`--show-cell` and `--show-layer` filter displayed changes without changing the
comparison, totals, or exit status. In text reports, `--show-layer` filters
object changes within modified cells and hides references without a numeric
layer. Added and removed cells appear as name-only entries outside the object
budget. Use `--show-cell` to filter those entries.
`--max-changes N` limits displayed object occurrences after filtering. Text
defaults to 100 occurrences and shows a replacement only when both objects fit
within the limit. Grouped rows count each object toward the limit. When a
layer filter selects one side of a layer-only replacement, that side appears as
an addition or removal. The omission line lists changes hidden by filters or the
limit. JSON has no default object limit and records omissions in
`report_selection`. See the [JSON reference](diff-reports.md) for the selection
counters.
`--details` shows individual object evidence inside modified cells in text
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 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