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
|
||||
|
||||
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
|
||||
cargo install --path . --locked --bin pheon
|
||||
cargo install pheon --locked
|
||||
pheon dump chip.gds
|
||||
pheon diff before.gds after.gds
|
||||
pheon hierarchy chip.gds --format mermaid
|
||||
|
|
@ -29,13 +30,13 @@ comparisons. Start with the [CLI guide][cli], then set up
|
|||
|
||||
## 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
|
||||
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
|
||||
from pheon import arrow
|
||||
|
|
@ -44,9 +45,8 @@ layout = arrow.read_path("chip.gds")
|
|||
print(layout.field("lib_name")[0].as_py())
|
||||
```
|
||||
|
||||
Source installation needs Rust; prebuilt Python wheels bundle the native library.
|
||||
The [Python guide][python] covers installation, selected reads, and integer
|
||||
packing. The [Arrow reference][arrow] describes the returned data.
|
||||
The Python package installs PyArrow. See the [Python guide][python] for source
|
||||
installs and selected reads, and the [Arrow reference][arrow] for the returned data.
|
||||
|
||||
## 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
|
||||
[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
|
||||
[crate]: https://crates.io/crates/pheon
|
||||
[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
|
||||
[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
|
||||
|
|
|
|||
98
docs/cli.md
98
docs/cli.md
|
|
@ -6,18 +6,17 @@ 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:
|
||||
Install the CLI [from crates.io](https://crates.io/crates/pheon) with Rust 1.88
|
||||
or newer.
|
||||
|
||||
```sh
|
||||
cargo install --path . --locked --bin pheon
|
||||
cargo install pheon --locked
|
||||
pheon --help
|
||||
```
|
||||
|
||||
You can also build locally with `cargo build --release --locked --bin pheon`
|
||||
and run `target/release/pheon` (`pheon.exe` on Windows).
|
||||
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
|
||||
|
||||
|
|
@ -44,44 +43,22 @@ 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 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
|
||||
pheon diff small_rect.gds big_rect.gds
|
||||
```
|
||||
|
||||
Text reports start with the result. The headline includes cell counts for
|
||||
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`.
|
||||
The example exits with code 1 and shows one changed rectangle in `TOP`.
|
||||
|
||||
An unchanged layer name appears inline when the layer occurs on one displayed
|
||||
row, as in `1/0 (WG): rectangle moved by (20, -5) dbu`. A layer on several
|
||||
displayed rows gets one legend entry. Object details use `-` for removals, `+` for additions,
|
||||
and `~` for likely replacements. Identical unmatched objects share a row
|
||||
with a count such as `+ 12× 1/0: path …`. Unmatched paths with five or more
|
||||
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.
|
||||
```text
|
||||
Different
|
||||
Cells:
|
||||
* TOP
|
||||
2/0: 1 rectangle changed
|
||||
```
|
||||
|
||||
| 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
|
||||
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
|
||||
|
|
@ -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,
|
||||
retained fields, and properties.
|
||||
|
||||
The diff hierarchy shows directly changed cells, affected ancestors, and targets
|
||||
of modified references. It includes references from both revisions so removed
|
||||
branches remain visible. Counts represent direct placements, with symbolic
|
||||
counts for arrays. ASCII uses the cell list's change markers and marks
|
||||
reference changes whose placement count stays the same. When the cell list
|
||||
shows all edits to an unchanged target on a single branch, ASCII can omit
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,35 +1,42 @@
|
|||
# Development
|
||||
|
||||
This guide is for contributors building and checking Pheon. For usage, start
|
||||
with the [CLI](cli.md) or [Python](python.md) guide.
|
||||
The checkout selects stable Rust. The minimum supported compiler is 1.88.
|
||||
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
|
||||
is 1.88. Python bindings require Python 3.11 or newer. Source builds require
|
||||
the tracked `Cargo.lock`; update dependencies explicitly with Cargo.
|
||||
| Area | Start here | First check |
|
||||
| --- | --- | --- |
|
||||
| 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
|
||||
cargo test --locked
|
||||
cargo test --release --locked
|
||||
cargo build --release --locked
|
||||
python3 -m venv .venv
|
||||
. .venv/bin/activate
|
||||
python -m pip install .
|
||||
python -I tools/check_installed.py
|
||||
```
|
||||
|
||||
Use `RUSTUP_TOOLCHAIN=1.88.0` to check source builds against the minimum compiler.
|
||||
The Python package bundles its native library during installation and reads its
|
||||
version from installed package metadata. After installation, to test a newly
|
||||
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`.
|
||||
To test a newly built shared library, set `PHEON_LIBRARY` to its absolute path
|
||||
and run `python -m unittest discover -s tests/python` from the checkout. Clear
|
||||
the override when checking the bundled library with `check_installed.py`.
|
||||
|
||||
## Check upstream layouts
|
||||
|
||||
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
|
||||
cargo build --release --locked --bin pheon
|
||||
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
|
||||
|
||||
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
|
||||
[Arrow layout version](arrow-schema.md) are independent of package releases and
|
||||
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
|
||||
```
|
||||
|
||||
Inspect the resulting diff. Goldens normalize the producer version to `test`;
|
||||
a package version change alone should not alter them. JSON Schema checks verify
|
||||
structure, while semantic tests verify links, totals, and result/exit agreement.
|
||||
Inspect the resulting diff. Goldens normalize the producer version to `test`.
|
||||
Use the [JSON Schema](diff-report-v1.schema.json) to check structure. Rust tests
|
||||
verify links, totals, and agreement between the result and exit status.
|
||||
|
||||
See [building releases](releases.md) for source archives, wheels, and standalone
|
||||
CLI artifacts.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,13 @@ returned data layout, see the [Arrow reference](arrow-schema.md).
|
|||
|
||||
## 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
|
||||
use pheon::library::read_library;
|
||||
|
|
|
|||
|
|
@ -1,22 +1,24 @@
|
|||
# Python
|
||||
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
To install a PyPI release:
|
||||
Install Pheon from [PyPI](https://pypi.org/project/pheon/).
|
||||
|
||||
```sh
|
||||
python -m pip install pheon
|
||||
```
|
||||
|
||||
The package installs PyArrow for layout reads. Existing `pheon[arrow]`
|
||||
requirements still work. Prebuilt wheels bundle the native library. From a
|
||||
source checkout, use `python -m pip install .` with Rust 1.88 or newer.
|
||||
requirements still work. [Prebuilt wheels](https://pypi.org/project/pheon/#files)
|
||||
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
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
Python, or the [native API guide](native-api.md) to call the library directly.
|
||||
|
|
|
|||
Loading…
Reference in a new issue