Refresh installation and walkthrough documentation
This commit is contained in:
parent
623de2e585
commit
2b5b184dc6
5 changed files with 94 additions and 97 deletions
18
README.md
18
README.md
|
|
@ -14,10 +14,11 @@ other object details. They compare object fields and coordinates exactly; see th
|
||||||
|
|
||||||
## Try the command-line tools
|
## Try the command-line tools
|
||||||
|
|
||||||
From a source checkout, install the CLI with Rust 1.88 or newer:
|
Install the CLI [from crates.io][crate] with Rust 1.88 or newer.
|
||||||
|
Use your own GDSII paths in the examples.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
cargo install --path . --locked --bin pheon
|
cargo install pheon --locked
|
||||||
pheon dump chip.gds
|
pheon dump chip.gds
|
||||||
pheon diff before.gds after.gds
|
pheon diff before.gds after.gds
|
||||||
pheon hierarchy chip.gds --format mermaid
|
pheon hierarchy chip.gds --format mermaid
|
||||||
|
|
@ -29,13 +30,13 @@ comparisons. Start with the [CLI guide][cli], then set up
|
||||||
|
|
||||||
## Read layouts in Python
|
## Read layouts in Python
|
||||||
|
|
||||||
Python 3.11 or newer is required. From a source checkout:
|
Install the Python package [from PyPI][pypi] with Python 3.11 or newer.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python -m pip install .
|
python -m pip install pheon
|
||||||
```
|
```
|
||||||
|
|
||||||
Run Python outside the source checkout to use the installed package:
|
Run this example from a directory containing `chip.gds`.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from pheon import arrow
|
from pheon import arrow
|
||||||
|
|
@ -44,9 +45,8 @@ layout = arrow.read_path("chip.gds")
|
||||||
print(layout.field("lib_name")[0].as_py())
|
print(layout.field("lib_name")[0].as_py())
|
||||||
```
|
```
|
||||||
|
|
||||||
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
The Python package installs PyArrow. See the [Python guide][python] for source
|
||||||
The [Python guide][python] covers installation, selected reads, and integer
|
installs and selected reads, and the [Arrow reference][arrow] for the returned data.
|
||||||
packing. The [Arrow reference][arrow] describes the returned data.
|
|
||||||
|
|
||||||
## Learn more
|
## Learn more
|
||||||
|
|
||||||
|
|
@ -59,7 +59,9 @@ Licensed under [GPL-3.0-only][license].
|
||||||
[arrow]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/arrow-schema.md
|
[arrow]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/arrow-schema.md
|
||||||
[cli]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/cli.md
|
[cli]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/cli.md
|
||||||
[comparison]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/comparison.md
|
[comparison]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/comparison.md
|
||||||
|
[crate]: https://crates.io/crates/pheon
|
||||||
[docs]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/index.md
|
[docs]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/index.md
|
||||||
[git]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/git.md
|
[git]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/git.md
|
||||||
[license]: https://mpxd.net/code/jan/pheon/src/branch/master/LICENSE.md
|
[license]: https://mpxd.net/code/jan/pheon/src/branch/master/LICENSE.md
|
||||||
|
[pypi]: https://pypi.org/project/pheon/
|
||||||
[python]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/python.md
|
[python]: https://mpxd.net/code/jan/pheon/src/branch/master/docs/python.md
|
||||||
|
|
|
||||||
98
docs/cli.md
98
docs/cli.md
|
|
@ -6,18 +6,17 @@ refer to the decompressed layout. The CLI runs independently of Python.
|
||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
If you downloaded a CLI archive, extract it and add the directory containing
|
Install the CLI [from crates.io](https://crates.io/crates/pheon) with Rust 1.88
|
||||||
`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it.
|
or newer.
|
||||||
|
|
||||||
To install from a source checkout, use Rust 1.88 or newer:
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
cargo install --path . --locked --bin pheon
|
cargo install pheon --locked
|
||||||
pheon --help
|
pheon --help
|
||||||
```
|
```
|
||||||
|
|
||||||
You can also build locally with `cargo build --release --locked --bin pheon`
|
From a source checkout, install with `cargo install --path . --locked --bin pheon`
|
||||||
and run `target/release/pheon` (`pheon.exe` on Windows).
|
or build with `cargo build --release --locked --bin pheon` and run
|
||||||
|
`target/release/pheon` (`pheon.exe` on Windows).
|
||||||
|
|
||||||
## Inspect a layout
|
## Inspect a layout
|
||||||
|
|
||||||
|
|
@ -44,44 +43,22 @@ output is diagram source for a Mermaid renderer.
|
||||||
|
|
||||||
## Compare revisions
|
## 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
|
```sh
|
||||||
pheon diff before.gds after.gds
|
pheon diff small_rect.gds big_rect.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
|
The example exits with code 1 and shows one changed rectangle in `TOP`.
|
||||||
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
|
```text
|
||||||
row, as in `1/0 (WG): rectangle moved by (20, -5) dbu`. A layer on several
|
Different
|
||||||
displayed rows gets one legend entry. Object details use `-` for removals, `+` for additions,
|
Cells:
|
||||||
and `~` for likely replacements. Identical unmatched objects share a row
|
* TOP
|
||||||
with a count such as `+ 12× 1/0: path …`. Unmatched paths with five or more
|
2/0: 1 rectangle changed
|
||||||
vertices show their width, vertex count, and vertex bounds in one line.
|
```
|
||||||
A unique polygon, box, or path replacement that differs only in layer or
|
|
||||||
datatype appears on one row, for example `~ 1/0 (WG) → 2/0 (CORE) · rectangle`.
|
|
||||||
|
|
||||||
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 |
|
| Exit code | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
|
|
@ -94,6 +71,21 @@ differences, but equality cannot be established. Read the
|
||||||
[comparison rules](comparison.md) before relying on results in automation, and
|
[comparison rules](comparison.md) before relying on results in automation, and
|
||||||
the [JSON reference](diff-reports.md) to consume reports programmatically.
|
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
|
## Choose the comparison scope
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
|
@ -146,20 +138,14 @@ 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,
|
`+` row for the new object, with cell-local coordinates in database units,
|
||||||
retained fields, and properties.
|
retained fields, and properties.
|
||||||
|
|
||||||
The diff hierarchy shows directly changed cells, affected ancestors, and targets
|
The diff hierarchy shows changed cells, affected ancestors, and modified
|
||||||
of modified references. It includes references from both revisions so removed
|
references from both revisions. Counts are direct placements, including
|
||||||
branches remain visible. Counts represent direct placements, with symbolic
|
symbolic array counts. ASCII folds straight chains of unchanged edges and can
|
||||||
counts for arrays. ASCII uses the cell list's change markers and marks
|
omit terminal edges already explained by the cell list. `--depth` counts the
|
||||||
reference changes whose placement count stays the same. When the cell list
|
original edges. For the full graph within the comparison scope, use
|
||||||
shows all edits to an unchanged target on a single branch, ASCII can omit
|
`--format json --hierarchy graph` without `--depth`.
|
||||||
that terminal edge. The hierarchy retains ancestor paths, shared branches,
|
|
||||||
and edges with edits hidden by display filters or limits. ASCII appears when
|
|
||||||
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).
|
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
|
||||||
|
|
|
||||||
|
|
@ -1,35 +1,42 @@
|
||||||
# Development
|
# Development
|
||||||
|
|
||||||
This guide is for contributors building and checking Pheon. For usage, start
|
The checkout selects stable Rust. The minimum supported compiler is 1.88.
|
||||||
with the [CLI](cli.md) or [Python](python.md) guide.
|
Use the checked-in `Cargo.lock` and update dependencies explicitly with Cargo.
|
||||||
|
|
||||||
## Build and test
|
## Check a change
|
||||||
|
|
||||||
The checkout selects the stable Rust toolchain; the minimum supported compiler
|
| Area | Start here | First check |
|
||||||
is 1.88. Python bindings require Python 3.11 or newer. Source builds require
|
| --- | --- | --- |
|
||||||
the tracked `Cargo.lock`; update dependencies explicitly with Cargo.
|
| GDSII parsing and Arrow reads | [`src/record.rs`](../src/record.rs), [`src/library.rs`](../src/library.rs) | `cargo test --locked --test parser_errors --test selective_reads` |
|
||||||
|
| Comparisons and CLI | [`src/review.rs`](../src/review.rs), [`src/review/`](../src/review/), [`src/bin/pheon.rs`](../src/bin/pheon.rs) | `cargo test --locked --test review` |
|
||||||
|
| Python and CFFI | [`pheon/`](../pheon/), [`src/lib.rs`](../src/lib.rs) | `python -I tools/check_installed.py` after installation |
|
||||||
|
|
||||||
|
Run `cargo test --locked` for the full Rust suite or `cargo test --release --locked`
|
||||||
|
for release builds. Set `RUSTUP_TOOLCHAIN=1.88.0` to check the minimum compiler.
|
||||||
|
|
||||||
|
## Test the Python package
|
||||||
|
|
||||||
|
Use Python 3.11 or newer and install into a virtual environment.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
cargo test --locked
|
python3 -m venv .venv
|
||||||
cargo test --release --locked
|
. .venv/bin/activate
|
||||||
cargo build --release --locked
|
|
||||||
python -m pip install .
|
python -m pip install .
|
||||||
python -I tools/check_installed.py
|
python -I tools/check_installed.py
|
||||||
```
|
```
|
||||||
|
|
||||||
Use `RUSTUP_TOOLCHAIN=1.88.0` to check source builds against the minimum compiler.
|
To test a newly built shared library, set `PHEON_LIBRARY` to its absolute path
|
||||||
The Python package bundles its native library during installation and reads its
|
and run `python -m unittest discover -s tests/python` from the checkout. Clear
|
||||||
version from installed package metadata. After installation, to test a newly
|
the override when checking the bundled library with `check_installed.py`.
|
||||||
built library without reinstalling, set `PHEON_LIBRARY` to its absolute
|
|
||||||
path and run `python -m unittest discover -s tests/python` from the checkout.
|
|
||||||
Unset this override when checking installed artifacts with `check_installed.py`.
|
|
||||||
|
|
||||||
## Check upstream layouts
|
## Check upstream layouts
|
||||||
|
|
||||||
The [GDSII corpus](../contrib/gds-corpus.toml) pins open-source fixtures and cell
|
The [GDSII corpus](../contrib/gds-corpus.toml) pins open-source fixtures and cell
|
||||||
libraries. After installing Pheon and building the release CLI, run:
|
libraries. Install Pheon in the virtual environment before running the corpus
|
||||||
|
check.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
cargo build --release --locked --bin pheon
|
||||||
python -I tools/check_gds_corpus.py --fetch
|
python -I tools/check_gds_corpus.py --fetch
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -40,7 +47,7 @@ to `.cache/gds-corpus/report.json` and exits with status 1 if a check fails.
|
||||||
|
|
||||||
## Interfaces and reports
|
## Interfaces and reports
|
||||||
|
|
||||||
The CFFI declarations live in [pheon/_ffi.h](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h). Keep them aligned
|
The CFFI declarations live in [`pheon/_ffi.h`](../pheon/_ffi.h). Keep them aligned
|
||||||
with the exported native functions. The C API version and
|
with the exported native functions. The C API version and
|
||||||
[Arrow layout version](arrow-schema.md) are independent of package releases and
|
[Arrow layout version](arrow-schema.md) are independent of package releases and
|
||||||
the [JSON report schema](diff-reports.md).
|
the [JSON report schema](diff-reports.md).
|
||||||
|
|
@ -53,9 +60,9 @@ changing their contract:
|
||||||
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
|
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
|
||||||
```
|
```
|
||||||
|
|
||||||
Inspect the resulting diff. Goldens normalize the producer version to `test`;
|
Inspect the resulting diff. Goldens normalize the producer version to `test`.
|
||||||
a package version change alone should not alter them. JSON Schema checks verify
|
Use the [JSON Schema](diff-report-v1.schema.json) to check structure. Rust tests
|
||||||
structure, while semantic tests verify links, totals, and result/exit agreement.
|
verify links, totals, and agreement between the result and exit status.
|
||||||
|
|
||||||
See [building releases](releases.md) for source archives, wheels, and standalone
|
See [building releases](releases.md) for source archives, wheels, and standalone
|
||||||
CLI artifacts.
|
CLI artifacts.
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,13 @@ returned data layout, see the [Arrow reference](arrow-schema.md).
|
||||||
|
|
||||||
## Rust
|
## Rust
|
||||||
|
|
||||||
Add `pheon` as a dependency. The library readers accept GDSII byte slices:
|
Add [pheon](https://crates.io/crates/pheon) from your Rust project.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cargo add pheon
|
||||||
|
```
|
||||||
|
|
||||||
|
The library readers accept GDSII byte slices.
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
use pheon::library::read_library;
|
use pheon::library::read_library;
|
||||||
|
|
|
||||||
|
|
@ -1,22 +1,24 @@
|
||||||
# Python
|
# Python
|
||||||
|
|
||||||
Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read
|
Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read
|
||||||
only selected cells. The base `pheon` package also provides integer packing.
|
only selected cells. The package also provides integer packing.
|
||||||
Python 3.11 or newer is required.
|
Python 3.11 or newer is required.
|
||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
To install a PyPI release:
|
Install Pheon from [PyPI](https://pypi.org/project/pheon/).
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python -m pip install pheon
|
python -m pip install pheon
|
||||||
```
|
```
|
||||||
|
|
||||||
The package installs PyArrow for layout reads. Existing `pheon[arrow]`
|
The package installs PyArrow for layout reads. Existing `pheon[arrow]`
|
||||||
requirements still work. Prebuilt wheels bundle the native library. From a
|
requirements still work. [Prebuilt wheels](https://pypi.org/project/pheon/#files)
|
||||||
source checkout, use `python -m pip install .` with Rust 1.88 or newer.
|
bundle the native library. On platforms without a compatible wheel, pip builds
|
||||||
|
the library from source and needs Rust 1.88 or newer and a native linker.
|
||||||
|
|
||||||
Run Python outside the source checkout to use the installed package.
|
From a source checkout, install with `python -m pip install .`, then run Python
|
||||||
|
outside the checkout to import the installed package.
|
||||||
|
|
||||||
## Read a layout
|
## Read a layout
|
||||||
|
|
||||||
|
|
@ -85,11 +87,5 @@ Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`.
|
||||||
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
|
Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access
|
||||||
errors use Python's normal I/O exceptions.
|
errors use Python's normal I/O exceptions.
|
||||||
|
|
||||||
## Use from Klamath or Masque
|
|
||||||
|
|
||||||
Klamath's `native` extra installs Pheon's packing helpers. Masque's `arrow` extra
|
|
||||||
installs Pheon for layout reads. Use the same Python environment as the
|
|
||||||
companion package.
|
|
||||||
|
|
||||||
See [development](development.md) to test a locally built native library from
|
See [development](development.md) to test a locally built native library from
|
||||||
Python, or the [native API guide](native-api.md) to call the library directly.
|
Python, or the [native API guide](native-api.md) to call the library directly.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue