Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
94
docs/cli.md
Normal file
94
docs/cli.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# Command-line tools
|
||||
|
||||
Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references.
|
||||
The CLI runs independently of Python.
|
||||
|
||||
## Install
|
||||
|
||||
From a source checkout, with 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
|
||||
```
|
||||
|
||||
Reports identify changed objects and their fields, plus affected ancestors in
|
||||
the hierarchy. Objects that can be paired unambiguously receive a replacement
|
||||
explanation; ambiguous changes remain removals and additions.
|
||||
|
||||
| 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).
|
||||
Loading…
Reference in a new issue