pheon/docs/cli.md

148 lines
6.9 KiB
Markdown
Raw Normal View History

# 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
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:
```sh
cargo install --path . --locked --bin pheon
pheon --help
```
You can also build locally 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
```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
```
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`.
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.
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.
| 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.
## 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` | Objects on a numeric 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.
## Control report detail
```sh
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer 1/0
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. A layer display filter hides references
without a numeric layer. `--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. A single omission line lists changes hidden by filters or the
limit. JSON has no default object limit and reports
omissions from both display filters and any explicit limit in `report_selection`.
See the [JSON reference](diff-reports.md) for the selection counters.
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
2026-11-18 23:04:24 -08:00
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.
Next: configure [Git integration](git.md) or add [layer names](layer-names.md).