Detect gzip headers on every CLI input and decode all members before parsing. Keep report offsets relative to the decompressed stream and report corrupt archives as invalid input. Recognize OASIS headers and explain how to provide GDSII data. Cover mixed compressed and plain comparisons, corrupt trailers, and layer-name output from compressed input.
99 lines
3.9 KiB
Markdown
99 lines
3.9 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` shows a normalized layout description. Add `--records` to inspect raw
|
|
records, including timestamps. `hierarchy` shows cell references without
|
|
expanding array placements. Shared cells are marked rather than repeated
|
|
indefinitely. 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 group changes by cell. A `-` line shows an object from the old file
|
|
and a `+` line shows one from the new file. A `~` line explains a likely
|
|
replacement when Pheon can pair the two uniquely. Request a hierarchy view 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;
|
|
JSON includes all changed objects unless this 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).
|