pheon/docs/cli.md
Jan Petykiewicz 15e8a3b7b5 Share GDSII reader logic and simplify review output
Share record framing, name decoding, payload validation, array reference
decoding, and Arrow cell-header parsing. Accept trailing NUL padding in
names and retain located diagnostics for malformed records.

Summarize text diffs by cell, layer, and reference target. Show comparison
and omission counts before detail. Compact canonical dumps while
preserving exact fields and duplicate counts for Git textconv. Simplify
hierarchy output and retain per-object evidence in JSON.
2026-11-17 21:49:26 -08:00

109 lines
4.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
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.
`hierarchy` shows direct placement counts on references. Shared cells are
marked where their contents appear earlier in the tree. 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 and group changes by cell. Added and removed
cell headings give the object count within the comparison scope. Each layer
lists counts of rectangles, polygons, and boxes changed, moved, added, or removed.
Added or removed cells also count references by target.
Other objects use `-` for removals, `+` for additions, and `~` for likely
replacements. Use `--format json` for details of individual objects and
`--hierarchy` to see which parent cells are affected.
| 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.
A paired replacement uses two occurrences. The text report counts omissions
from filters and limits before listing cell changes. JSON includes all changed
objects unless the limit is explicit.
The diff hierarchy marks directly changed cells, affected ancestors, and
unchanged targets of modified references. It includes references from both
revisions so removed branches remain visible. Counts represent direct placements;
arrays remain symbolic. `--depth` limits text diagrams. For a complete graph in
JSON, use `--format json --hierarchy graph`; text depth and display filters do
not trim that graph.
Next: configure [Git integration](git.md) or add [layer names](layer-names.md).