151 lines
6.5 KiB
Markdown
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
|