Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
11 changed files with 798 additions and 681 deletions
133
docs/arrow-schema.md
Normal file
133
docs/arrow-schema.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
# Arrow layout reference
|
||||
|
||||
This reference is for consumers of Pheon's Arrow readers. Each result is a
|
||||
one-row `StructArray` representing a GDSII library. The
|
||||
[Python guide](python.md) shows how to obtain and access it.
|
||||
|
||||
Geometry fields named `layer` are **indices into the result's `layers` table**.
|
||||
Reference `target` and cell `id` values index its `cell_names` table. Resolve IDs
|
||||
using tables from the same result; a selected read can assign different IDs.
|
||||
|
||||
`pheon_arrow_schema_version()` currently returns 1 for all layouts below.
|
||||
Consumers of the [C API](native-api.md) must check both this application schema
|
||||
version and the separate C API version.
|
||||
|
||||
## Full library
|
||||
|
||||
| Field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `meters_per_db_unit` | Float64 | Database unit size in meters. |
|
||||
| `user_units_per_db_unit` | Float64 | User units per database unit. |
|
||||
| `lib_name` | Utf8 | Library name. |
|
||||
| `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. |
|
||||
| `cells` | List(Cell) | Cell records. |
|
||||
| `cell_names` | List(Utf8) | Names indexed by cell ID. |
|
||||
| `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. |
|
||||
|
||||
### Cell
|
||||
|
||||
| Field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `id` | UInt32 | Index into `cell_names`. |
|
||||
| `file_offset` | UInt64 | Byte offset immediately after STRNAME, before the first element or ENDSTR. |
|
||||
| `srefs`, `arefs` | List(SRef), List(ARef) | References without properties. |
|
||||
| `sref_props`, `aref_props` | List(SRefProp), List(ARefProp) | References with properties. |
|
||||
| `rect_batches` | List(RectBatch) | Optimized rectangular boundaries. |
|
||||
| `boundary_batches` | List(BoundaryBatch) | Other boundaries without properties. |
|
||||
| `boundary_props` | List(BoundaryProp) | Boundaries with properties. |
|
||||
| `paths` | List(Path) | Paths. |
|
||||
| `nodes`, `boxes` | List(BoxNode) | Node and box elements. |
|
||||
| `texts` | List(Text) | Text labels. |
|
||||
|
||||
## Hierarchy scan and selected reads
|
||||
|
||||
Scans return the same metadata and `cell_names`, omit `layers`, and replace
|
||||
`cells` with these records:
|
||||
|
||||
| Field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `id` | UInt32 | Index into this result's `cell_names`. |
|
||||
| `struct_start_offset` | UInt64 | Inclusive offset of BGNSTR. |
|
||||
| `struct_end_offset` | UInt64 | Exclusive offset after ENDSTR. |
|
||||
| `refs` | List(ScanRef) | References sorted by target ID, with properties omitted. |
|
||||
|
||||
ScanRef has ARef's fields below. An SREF uses zero basis vectors and counts
|
||||
`(1, 1)`. Geometry and text are skipped without decoding.
|
||||
|
||||
Pass complete half-open cell ranges to `read_selected_library` in Rust or
|
||||
`read_cells_bytes` in Python/C. The result uses the full library layout, with
|
||||
cells in requested order. An empty selection returns metadata and empty lists.
|
||||
Offsets always refer to the original uncompressed input. The Rust selected
|
||||
reader returns the original input slice as its remainder.
|
||||
|
||||
## Packed values
|
||||
|
||||
| Value | Storage | Decoding |
|
||||
| --- | --- | --- |
|
||||
| Layer/type pair in `layers` | UInt32 | Layer in high 16 bits; datatype/texttype/boxtype/nodetype in low 16 bits. |
|
||||
| Point or vector | UInt64 | Signed Int32 x in high 32 bits, signed Int32 y in low 32 bits. |
|
||||
| Array counts | UInt32 | Columns in high 16 bits, rows in low 16 bits. |
|
||||
|
||||
Layer halves preserve the original 16-bit patterns; reinterpret them as signed
|
||||
Int16 where an integration uses signed GDS layer values. Array counts originate
|
||||
from positive Int16 values. Flattened coordinate lists below use `[x, y, ...]`
|
||||
in integer database units.
|
||||
|
||||
## References
|
||||
|
||||
| SRef field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `target` | UInt32 | Target cell ID. |
|
||||
| `invert_y` | Boolean | Reflection flag. |
|
||||
| `scale` | Float64 | Magnification. |
|
||||
| `angle_rad` | Float64 | Rotation in radians. |
|
||||
| `xy` | UInt64 | Packed origin. |
|
||||
|
||||
ARef adds `xy0` and `xy1` (UInt64 packed column/row increments) and `counts`
|
||||
(UInt32). SRefProp and ARefProp add `properties: List(Property)`.
|
||||
|
||||
Array increments must be exact signed 32-bit integers. All Arrow readers reject
|
||||
fractional or out-of-range endpoint/count division rather than rounding it.
|
||||
One-placement AREFs can be normalized to SREFs. The review CLI retains original
|
||||
endpoints and distinguishes SREF from AREF independently of this representation.
|
||||
|
||||
## Geometry and text
|
||||
|
||||
Every `layer` below is a UInt32 **table index**, not a packed pair.
|
||||
|
||||
| Type | Fields beyond `layer` |
|
||||
| --- | --- |
|
||||
| RectBatch | `rects: List(Int32)`, flattened `[min_x, min_y, max_x, max_y]` rectangles. |
|
||||
| BoundaryBatch | `vertices: List(Int32)`; `vertex_offsets: List(UInt32)` gives each boundary's start in points, not scalar coordinates. |
|
||||
| BoundaryProp | `vertices: List(Int32)`; `properties: List(Property)`. |
|
||||
| BoxNode | `xy: List(Int32)`; `properties: List(Property)`. |
|
||||
| Path | Fields below. |
|
||||
| Text | Fields below. |
|
||||
|
||||
| Path field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `path_type` | Int16, nullable | Stored path type. |
|
||||
| `extension_start`, `extension_end` | Int32, nullable | End extensions. |
|
||||
| `width` | Int32, nullable | Null when WIDTH is absent. |
|
||||
| `xy` | List(Int32) | Centerline coordinates. |
|
||||
| `properties` | List(Property) | Element properties. |
|
||||
|
||||
| Text field | Arrow type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `presentation_horiz`, `presentation_vert`, `presentation_font` | UInt8, nullable | Presentation attributes. |
|
||||
| `path_type` | Int16, nullable | Stored path type. |
|
||||
| `width` | Int32, nullable | Stored width. |
|
||||
| `invert_y` | Boolean, nullable | Reflection flag. |
|
||||
| `mag` | Float64, nullable | Magnification. |
|
||||
| `angle_deg` | Float64, nullable | Rotation in degrees. |
|
||||
| `xy` | UInt64 | Packed position. |
|
||||
| `string` | Utf8 | Label text. |
|
||||
| `properties` | List(Property) | Element properties. |
|
||||
|
||||
Property contains `key: Int16` and `value: Utf8`. The reader preserves property
|
||||
order and duplicates. Property-list fields are nullable in the schema; the
|
||||
reader normally emits valid lists, including empty ones.
|
||||
|
||||
Geometry batching and reference normalization mean this layout is not a verbatim
|
||||
record stream; use the [CLI's record dump](cli.md#inspect-a-layout) when original
|
||||
records matter.
|
||||
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).
|
||||
58
docs/comparison.md
Normal file
58
docs/comparison.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
# Comparison rules
|
||||
|
||||
Pheon compares GDSII objects using the `klamath-object-v2` profile. Use it to
|
||||
review exact layout changes while ignoring incidental ordering and timestamps.
|
||||
The [CLI guide](cli.md) explains how to choose cells and layers.
|
||||
|
||||
## What counts as equal
|
||||
|
||||
Cells match by name and layers by numeric layer/type pair. By default, the
|
||||
comparison includes the entire library.
|
||||
|
||||
Pheon ignores library and cell timestamps, cell order, element order, and
|
||||
property order. Boundary and box rings are normalized for their starting vertex
|
||||
and winding direction. Other vertices remain significant. Repeated objects and
|
||||
properties are compared as multisets, so duplicates still count.
|
||||
|
||||
Other retained details compare exactly: paths, labels, reference transforms,
|
||||
array endpoints and counts, properties, and flags. An explicitly stored default
|
||||
is distinct from an omitted field. An SREF is distinct from a one-element AREF.
|
||||
REAL8 encodings are retained, so differently encoded values can compare as
|
||||
changed even when their decoded values agree.
|
||||
|
||||
Library fields, including UNITS, compare separately. Coordinates are not
|
||||
rescaled to a shared grid. Cell renames are additions and deletions; Pheon does
|
||||
not infer identity from similar content. It does not perform geometric Boolean
|
||||
operations, XOR, or tolerance-based matching.
|
||||
|
||||
## Read change explanations
|
||||
|
||||
Unmatched objects can be paired to explain a replacement when the pairing is
|
||||
unique by kind, layer, and bounds, then by kind and layer. References also use
|
||||
their target cell. Ambiguous candidates remain independent removals and
|
||||
additions. Pairing helps explain the report; it does not establish persistent
|
||||
object identity or change the underlying counts.
|
||||
|
||||
Reported bounds are envelopes of stored coordinates in cell-local database
|
||||
units. They exclude path width, rendered text size, and recursively transformed
|
||||
reference geometry. Account for UNITS before interpreting a physical dimension
|
||||
or movement.
|
||||
|
||||
Recognized [layer-name annotations](layer-names.md) are removed from ordinary
|
||||
object comparison. Their name mapping compares separately, so a layer rename
|
||||
appears once.
|
||||
|
||||
## Know when a result is incomplete
|
||||
|
||||
Unsupported records, future metadata versions, unresolved references, and
|
||||
hierarchy cycles prevent a complete comparison. Pheon reports known differences
|
||||
but returns 2 rather than claiming equality.
|
||||
|
||||
Scope can exclude a record known to belong to another layer. Unsupported
|
||||
records whose layer is unknown can still make a layer-scoped comparison
|
||||
incomplete. Library fields and future metadata diagnostics remain visible.
|
||||
Malformed input fails before scope is applied.
|
||||
|
||||
For automation, check completeness as well as differences. The
|
||||
[JSON report reference](diff-reports.md) describes the status fields and retained
|
||||
evidence.
|
||||
45
docs/development.md
Normal file
45
docs/development.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Development
|
||||
|
||||
This guide is for contributors building and checking Pheon. For usage, start
|
||||
with the [CLI](cli.md) or [Python](python.md) guide.
|
||||
|
||||
## Build and test
|
||||
|
||||
The checkout selects the stable Rust toolchain; the minimum supported compiler
|
||||
is 1.88. Python bindings require Python 3.11 or newer.
|
||||
|
||||
```sh
|
||||
cargo test --locked
|
||||
cargo test --release --locked
|
||||
cargo build --release --locked
|
||||
python -m pip install '.[arrow]'
|
||||
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. 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`.
|
||||
|
||||
## Interfaces and reports
|
||||
|
||||
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).
|
||||
|
||||
Review tests cover comparison semantics, CLI behavior, symbolic array counts,
|
||||
and versioned report goldens. To regenerate JSON goldens after deliberately
|
||||
changing their contract:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
See [building releases](releases.md) for source archives, wheels, and standalone
|
||||
CLI artifacts.
|
||||
|
|
@ -1,4 +1,9 @@
|
|||
# Machine-readable diff reports
|
||||
# JSON diff reports
|
||||
|
||||
Use JSON reports to automate layout review while retaining the evidence behind
|
||||
a result. The [comparison rules](comparison.md) define equality; the
|
||||
[version 1 JSON Schema](diff-report-v1.schema.json) defines every field.
|
||||
A [complete example](../tests/golden/report-geometry.json) shows geometry changes.
|
||||
|
||||
```sh
|
||||
pheon diff before.gds after.gds --format json > report.json
|
||||
|
|
@ -6,184 +11,116 @@ pheon diff before.gds after.gds --format json --hierarchy graph
|
|||
pheon diff before.gds after.gds --format json --top CHIP --layer 1/0
|
||||
```
|
||||
|
||||
The command writes one UTF-8 JSON document followed by a newline to stdout.
|
||||
Comparison diagnostics belong to that document. Output write failures are
|
||||
reported on stderr and return 2; interrupted output is not a valid report.
|
||||
JSON output currently belongs to `diff`; `dump`, `hierarchy`, and the Git
|
||||
external driver retain their existing text interfaces. No external process is
|
||||
used to produce a report.
|
||||
`diff` writes one UTF-8 JSON document and a newline to stdout, including comparison
|
||||
diagnostics. Output write failures go to stderr and return 2; interrupted output
|
||||
is invalid. Other CLI commands retain text output.
|
||||
|
||||
The [version 1 JSON Schema](diff-report-v1.schema.json) defines the structure.
|
||||
[Golden reports](../tests/golden/report-geometry.json) illustrate complete
|
||||
evidence; other `report-*.json` goldens cover equality, metadata, incomplete
|
||||
comparison, and failure. Their producer version is replaced with `test` so
|
||||
package version changes do not alter the fixtures.
|
||||
## Check the result first
|
||||
|
||||
## Versions and determinism
|
||||
|
||||
Pheon emits schema version 1 with producer name `pheon`. This schema has not
|
||||
had a public release. The comparison profile remains `klamath-object-v2`, and
|
||||
the `KLAMATH_LAYER_NAMES_V1` GDS marker retains its existing meaning.
|
||||
|
||||
`schema_version` describes the report structure. `comparison_profile` names the
|
||||
equality rules, currently `klamath-object-v2`. `producer.version` identifies the
|
||||
implementation. These versions are independent. Consumers interpreting equality
|
||||
must understand the comparison profile as well as the schema.
|
||||
|
||||
Compatible additions may introduce optional fields. Consumers should ignore
|
||||
unfamiliar additional fields and handle unfamiliar diagnostic codes and matching
|
||||
rules without treating them as equality. Removed fields or changed meanings
|
||||
require a new schema version. The schema intentionally permits additional fields.
|
||||
|
||||
For the same inputs, paths, options, and producer version, serialization is
|
||||
deterministic. Cells, layer pairs, fields, properties, and graph edges are sorted.
|
||||
Duplicate objects and properties remain separate occurrences. Reports contain
|
||||
no generation timestamp or required content fingerprint.
|
||||
|
||||
## Result and exit status
|
||||
|
||||
| `status` | `result` | Exit code | Interpretation |
|
||||
| `status` | `result` | Exit code | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `complete` | `equal` | 0 | Equal under the recorded profile and scope. |
|
||||
| `complete` | `different` | 1 | Differences found. |
|
||||
| `incomplete` | `different` | 2 | Definite differences found, with comparison limitations. |
|
||||
| `incomplete` | `different` | 2 | Definite differences, with comparison limitations. |
|
||||
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
|
||||
| `failed` | `unknown` | 2 | No comparison result is available. |
|
||||
| `failed` | `unknown` | 2 | No comparison result. |
|
||||
|
||||
Unsupported records, future metadata versions, unresolved references, and
|
||||
hierarchy cycles make the comparison incomplete. Malformed input, read errors,
|
||||
invalid scopes, and invalid command arguments produce failed reports. CI must
|
||||
check completeness as well as differences. An exit code of 1 is a normal
|
||||
comparison outcome, including when stdout is redirected to a report file.
|
||||
A code of 1 is an expected result, including when saving a report. Unsupported
|
||||
records, future metadata, unresolved references, and cycles make a comparison
|
||||
incomplete. Malformed input, I/O errors, invalid scopes, and command errors fail.
|
||||
|
||||
Library and cell timestamps are excluded from the comparison profile. A valid,
|
||||
complete timestamp-only comparison returns 0. Raw record dumps remain available
|
||||
for examining those timestamps.
|
||||
`summary` covers the whole scoped comparison before display filters. Counts are
|
||||
`exact` for complete results and `observed` for incomplete ones. Failed reports
|
||||
have a null summary and empty change arrays. Replacement suggestions and affected
|
||||
ancestors do not add to change counts.
|
||||
|
||||
`summary` counts the entire scoped comparison, before display selection. Its
|
||||
`counts` is `exact` for a complete comparison and `observed` for an incomplete
|
||||
one. Failed reports have a null summary and empty change arrays. Replacement
|
||||
suggestions and affected ancestors never add to change counts.
|
||||
## Scope and evidence selection
|
||||
|
||||
## Scope, selection, and numbers
|
||||
`scope` records `top`, `cell`, and numeric `layer` selectors; null means
|
||||
unrestricted. The full input is parsed before scope selection.
|
||||
|
||||
`scope` records the actual `top`, `cell`, and numeric `layer` selectors. Null
|
||||
means unrestricted. The complete file is parsed before applying scope, so an
|
||||
invalid record outside the selected subtree still fails the command.
|
||||
`report_selection` records display-only cell/layer filters and `max_objects`.
|
||||
JSON is unbounded by default. Explicit `--max-changes N` limits total emitted
|
||||
removals plus additions, with removals first within each cell. Selection counters
|
||||
`filtered_cells`, `filtered_objects`, `limited_objects`, and `emitted_objects`
|
||||
explain omissions. `truncated` is true when filtering or limits omit evidence.
|
||||
Library changes, layer-name changes, diagnostics, summaries, and the optional
|
||||
graph remain. Replacement links appear only if both objects are emitted.
|
||||
|
||||
`report_selection` records display-only `cell`, `layer`, and `max_objects`.
|
||||
JSON has no default object limit. Explicit `--max-changes N` limits the total
|
||||
number of emitted object occurrences across both sides. Removals precede
|
||||
additions within each cell. `filtered_cells`, `filtered_objects`,
|
||||
`limited_objects`, and `emitted_objects` explain evidence selection. `truncated`
|
||||
is true if filtering or a limit omits any changed cell or object. Library and
|
||||
layer-name changes, diagnostics, summaries, and the optional graph are retained.
|
||||
A replacement is emitted only when both linked objects are included.
|
||||
## Read values safely
|
||||
|
||||
All aggregate counts, limits, and byte offsets are unsigned decimal **strings**.
|
||||
This avoids loss of precision in JSON consumers using binary64 numbers.
|
||||
Coordinates, numeric tags, layer/type pairs, widths, and array dimensions are
|
||||
bounded integers represented as JSON numbers. Null means absent or unavailable;
|
||||
zero and empty arrays do not imply absence.
|
||||
Aggregate counts, limits, and byte offsets are unsigned decimal **strings** to
|
||||
avoid JSON number precision loss. Coordinates, numeric tags, layer/type pairs,
|
||||
widths, and array dimensions are bounded JSON numbers. Null means absent or
|
||||
unavailable; zero and empty arrays remain meaningful values.
|
||||
|
||||
`inputs.old` and `inputs.new` contain input paths, presence, and UNITS fields.
|
||||
Presence is distinct from an empty library. The Rust API also supports absent
|
||||
Git revisions using `Document::empty_like`; no units are invented for absent
|
||||
inputs. Failed reports may have null presence and units. Argument failures can
|
||||
lack input/selection context because the command could not be parsed.
|
||||
`inputs.old` and `inputs.new` record paths, presence, and UNITS. An absent revision
|
||||
is distinct from an empty library. The Rust API supports absent Git revisions
|
||||
with `Document::empty_like`. Failed reports may lack presence, units, or argument
|
||||
context. Non-UTF-8 paths use null `path` and `path_encoded_hex`: `0x`-prefixed
|
||||
platform-native Rust path bytes, not a portable filename encoding.
|
||||
|
||||
Paths are UTF-8 when representable. Otherwise `path` is null and
|
||||
`path_encoded_hex` preserves Rust's platform-native encoded path bytes, prefixed
|
||||
with `0x`. This is platform-dependent evidence rather than a portable path name.
|
||||
## Interpret changes
|
||||
|
||||
## Change evidence
|
||||
| Section | Evidence |
|
||||
| --- | --- |
|
||||
| `library_changes` | Typed before/after header fields, including unscaled UNITS. Presence changes use a null tag and boolean values. |
|
||||
| `layer_name_changes` | Before/after names for numeric pairs `{ "number": 1, "purpose": 0 }`. |
|
||||
| `layer_legend` | Unchanged names available in scope. Annotation labels do not also appear as object changes. |
|
||||
| `cell_changes` | Name, nullable before/after cell records, attributes, removed/added objects, and replacement suggestions. A null side means absent; an existing empty cell still has a byte offset. |
|
||||
|
||||
`library_changes` records changed header fields as typed before/after arrays.
|
||||
Library presence changes use the special field `presence`, a null tag, and
|
||||
boolean before/after values. Units are not rescaled to a common grid.
|
||||
Objects retain kind, numeric tag, layer, target, bounds, source side and half-open
|
||||
byte range, typed fields, and a sorted property multiset including duplicates.
|
||||
Convenience fields include origin, width, and reference dimensions. SREF counts
|
||||
are `[1, 1]`; kind and retained fields still distinguish a one-element AREF.
|
||||
|
||||
`layer_name_changes` records numeric pairs with before/after names. A layer
|
||||
pair is `{ "number": 1, "purpose": 0 }`, where purpose is DATATYPE, TEXTTYPE,
|
||||
BOXTYPE, or NODETYPE according to the object kind. `layer_legend` contains
|
||||
unchanged names available in the scope. Embedded annotation labels are excluded
|
||||
from ordinary object changes. A metadata rename appears once.
|
||||
Coordinates are cell-local database units. Bounds are stored-coordinate
|
||||
envelopes, excluding stroke width, rendered text, and recursive target geometry.
|
||||
Consider UNITS before deriving physical dimensions.
|
||||
|
||||
Each `cell_changes` entry has its name, nullable before/after cell records,
|
||||
attribute evidence, removed and added objects, and replacement suggestions.
|
||||
A null cell side means the cell is absent in that scope. An existing empty
|
||||
cell has a byte offset and an empty attribute array.
|
||||
Fields contain `tag`, display `name`, `encoding`, decoded `value`, and
|
||||
`payload_hex`. Numeric tags are authoritative. XY values are lists of points;
|
||||
other numeric values are arrays. Unsupported encodings have null values and
|
||||
preserved bytes. Invalid UTF-8 strings/properties have null decoded values;
|
||||
hex preserves their bytes.
|
||||
|
||||
Each object retains:
|
||||
Evidence follows the comparison profile: boundary/box rings are canonicalized,
|
||||
string padding is removed, and fields/properties are sorted. REAL8 encodings and
|
||||
explicit defaults remain significant. Source offsets locate original records.
|
||||
|
||||
- Its kind and numeric tag, numeric layer pair, target cell, and coordinate envelope.
|
||||
- Its original source side and byte range `[byte_offset, end_offset)`.
|
||||
- Typed field records and the sorted property multiset, including duplicates.
|
||||
- Convenience fields for text/reference origin, path/text width, and reference
|
||||
array dimensions. SREF dimensions are `[1, 1]`; the kind and retained fields
|
||||
distinguish an SREF from a one-element AREF and explicit fields from omission.
|
||||
|
||||
Coordinates are cell-local integer database units. `bounds` contains
|
||||
`[xmin, ymin, xmax, ymax]` of stored coordinates. It excludes path stroke width,
|
||||
rendered text dimensions, and recursively transformed target geometry.
|
||||
Equal envelopes do not establish geometric equality. Unit changes must be
|
||||
considered before deriving physical movements or dimensions.
|
||||
|
||||
A retained field has a numeric `tag`, convenience `name`, `encoding`, decoded
|
||||
`value`, and `payload_hex`. The numeric tag is authoritative; names are display
|
||||
aids. XY values are arrays of `[x, y]` pairs. Other numeric fields are arrays
|
||||
of their declared type. Unsupported encodings retain bytes with a null value.
|
||||
String and property values are null if their bytes are not valid UTF-8;
|
||||
`payload_hex` always preserves them without replacement characters.
|
||||
|
||||
Payloads follow the comparison profile: boundary/box rings use canonical start
|
||||
and winding, string padding is removed, and fields/properties are sorted. They
|
||||
are comparison evidence, not a verbatim serialization of the source records.
|
||||
REAL8 payload encodings are retained exactly alongside their decoded values.
|
||||
Explicit defaults and omitted fields remain distinct. Source ranges allow raw
|
||||
record inspection when original encoding or order is needed.
|
||||
|
||||
Replacement suggestions link report-local removed/added IDs, with a `match_rule`,
|
||||
typed `field_changes`, and `properties_changed`. Their explanation is optional
|
||||
for consumers to display and must not be parsed. Current matching rules are
|
||||
`unique_kind_layer_bounds`, `unique_kind_layer`, and `unique_kind_target`.
|
||||
These are explanatory matches, not persistent identity or shape equivalence.
|
||||
Ambiguous candidates stay independent removals and additions. IDs are unique
|
||||
within a report and have no meaning across reports.
|
||||
Replacements link report-local removed/added IDs with `match_rule`,
|
||||
`field_changes`, and `properties_changed`. Rules are `unique_kind_layer_bounds`,
|
||||
`unique_kind_layer`, or `unique_kind_target`. IDs are not persistent identities;
|
||||
ambiguous candidates stay separate. Explanation text is for display only.
|
||||
|
||||
## Diagnostics and hierarchy
|
||||
|
||||
Diagnostics have `code`, `severity`, `message`, input `side`, original byte
|
||||
offset, cell, layer, and target context. Unknown context is null. Messages are
|
||||
for display; codes and context support automation. Current limitation codes are
|
||||
`unsupported_record`, `unsupported_metadata_version`, `unresolved_reference`,
|
||||
`hierarchy_cycle`, and `scope_mismatch`. Failure codes are `invalid_input`,
|
||||
`io_error`, `invalid_scope`, and `command_error`. Fatal parser errors currently
|
||||
retain their location in the human message; their structured byte offset is
|
||||
null. Consumers must not depend on message wording.
|
||||
Diagnostics provide `code`, `severity`, `message`, input side, byte offset, cell,
|
||||
layer, and target; unknown context is null. Use codes and context for automation.
|
||||
Fatal parser locations currently appear only in the human message, with null
|
||||
structured offsets. Do not parse message wording.
|
||||
|
||||
`--hierarchy graph` includes the full scoped union graph of both revisions.
|
||||
Otherwise `hierarchy` is null. Nodes are keyed by cell name, with per-side
|
||||
states `included`, `outside_scope`, `unresolved`, or `absent`. Their `change`
|
||||
is `direct`, `affected` through a descendant, or `unchanged`.
|
||||
Limitation codes are `unsupported_record`, `unsupported_metadata_version`,
|
||||
`unresolved_reference`, `hierarchy_cycle`, and `scope_mismatch`. Failure codes are
|
||||
`invalid_input`, `io_error`, `invalid_scope`, and `command_error`.
|
||||
|
||||
Edges record parent, target, before/after direct placement counts, and whether
|
||||
the underlying reference records changed. AREF columns times rows contribute
|
||||
symbolically; arrays are never expanded. Counts are direct edge multiplicities,
|
||||
not recursively accumulated placements. Shared cells occur once. Removed edges
|
||||
remain visible, and ancestors are computed over the union of both revisions.
|
||||
Graph content is independent of display filters and object limits. Text depth
|
||||
limits and ASCII/Mermaid choices do not apply to JSON graphs.
|
||||
`--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy`
|
||||
is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`,
|
||||
`unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`.
|
||||
Edges record parent, target, before/after direct placement counts, and changed
|
||||
reference records. Array multiplicities are symbolic, not expanded or recursively
|
||||
accumulated. Shared cells occur once and removed edges remain. Display filters,
|
||||
object limits, and text depth do not trim the graph.
|
||||
|
||||
## Development
|
||||
## Versions
|
||||
|
||||
`cargo test --test review` checks report semantics, CLI behavior, and versioned
|
||||
goldens. To intentionally regenerate report goldens after reviewing a contract
|
||||
change, run:
|
||||
`schema_version` is 1, `comparison_profile` is `klamath-object-v2`, and
|
||||
`producer.name` is `pheon`. Structure, equality rules, and producer version evolve
|
||||
independently. Understand the profile before interpreting equality. Consumers
|
||||
should tolerate additional optional fields and unknown codes/rules without
|
||||
assuming equality. Removed fields or changed meanings require a schema change.
|
||||
|
||||
```sh
|
||||
PHEON_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
|
||||
```
|
||||
|
||||
Schema validators can validate the goldens or actual CLI output against
|
||||
`diff-report-v1.schema.json`. Schema validation does not replace semantic checks
|
||||
such as replacement links, summary totals, or status/exit-code agreement.
|
||||
Serialization is deterministic for identical inputs, paths, options, and producer
|
||||
version. Sorted evidence retains duplicates. Reports have no generation timestamp
|
||||
or required content fingerprint. See [development](development.md) for contract
|
||||
tests and golden updates.
|
||||
|
|
|
|||
59
docs/git.md
Normal file
59
docs/git.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Git integration
|
||||
|
||||
Configure Git to show meaningful GDSII changes during review. Install the
|
||||
[Pheon CLI](cli.md#install) first, then choose one of the following drivers.
|
||||
Templates are also available in [contrib/git](../contrib/git/).
|
||||
|
||||
## Object comparison
|
||||
|
||||
Use the external driver for object-aware comparison and affected hierarchy.
|
||||
Add this to your repository's `.gitattributes`:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=pheon
|
||||
```
|
||||
|
||||
Add this to `.git/config`, or use the same section in your user Git config:
|
||||
|
||||
```gitconfig
|
||||
[diff "pheon"]
|
||||
command = pheon git-diff --hierarchy ascii --
|
||||
binary = true
|
||||
trustExitCode = false
|
||||
```
|
||||
|
||||
Then run `git diff` as usual. The driver reads Git's temporary old and new files
|
||||
and handles additions, deletions, and renames. Keep the final `--`: Git appends
|
||||
its path and revision arguments after it. Put Pheon options before that marker,
|
||||
for example `--top CHIP` or `--show-layer 1/0`.
|
||||
|
||||
For an existing `diff=layout` attribute, put the configuration under
|
||||
`[diff "layout"]` instead. Attribute names only select a Git driver.
|
||||
|
||||
The external driver returns 0 after rendering either an equal or different
|
||||
comparison, and nonzero for invalid or incomplete comparisons. For automation
|
||||
that needs equality status, run `pheon diff OLD NEW` directly; it returns
|
||||
0, 1, or 2 as described in the [CLI guide](cli.md).
|
||||
|
||||
## Normalized text comparison
|
||||
|
||||
Use text conversion when you want Git to compare normalized text dumps. Set
|
||||
`.gitattributes` to:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=pheon-text
|
||||
```
|
||||
|
||||
Configure the driver:
|
||||
|
||||
```gitconfig
|
||||
[diff "pheon-text"]
|
||||
textconv = pheon dump
|
||||
binary = true
|
||||
cachetextconv = true
|
||||
```
|
||||
|
||||
Git can cache converted text. Invalidate that cache when upgrading to a tool or
|
||||
comparison profile that changes the dump format, or disable `cachetextconv`.
|
||||
These diffs are for human review; they are not patches that can be applied to
|
||||
GDSII files. See the [comparison rules](comparison.md) for normalization details.
|
||||
19
docs/index.md
Normal file
19
docs/index.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Pheon documentation
|
||||
|
||||
Start with a guide for the task you want to perform.
|
||||
|
||||
| Task | Guide |
|
||||
| --- | --- |
|
||||
| Inspect layouts, compare revisions, or view hierarchy | [Command-line tools](cli.md) |
|
||||
| Load geometry or selected cells in Python | [Python](python.md) |
|
||||
| Review GDSII files with Git | [Git integration](git.md) |
|
||||
| Add readable names to numeric layers | [Layer names](layer-names.md) |
|
||||
| Understand what a comparison considers equal | [Comparison rules](comparison.md) |
|
||||
|
||||
For integrations, use the [Arrow layout reference](arrow-schema.md),
|
||||
[Rust and C API guide](native-api.md), or [JSON report reference](diff-reports.md).
|
||||
|
||||
For contributors and maintainers, see [development](development.md) and
|
||||
[building releases](releases.md).
|
||||
|
||||
Return to the [project introduction](../README.md).
|
||||
44
docs/layer-names.md
Normal file
44
docs/layer-names.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Layer names
|
||||
|
||||
Attach readable names to numeric GDSII layer/type pairs so Pheon can show a
|
||||
legend in comparison reports. Names are annotations; geometry keeps its numeric
|
||||
layer assignments.
|
||||
|
||||
## Add or update names
|
||||
|
||||
```sh
|
||||
pheon name-layers chip.gds named.gds --cell CHIP --carrier 900/7 \
|
||||
--name 1:0:WG --name 2:0:METAL
|
||||
```
|
||||
|
||||
Choose an existing cell and an otherwise unused `(layer, texttype)` pair in that
|
||||
cell as the carrier. The carrier must contain no ordinary design objects.
|
||||
The output path must be new; Pheon refuses to overwrite any existing file,
|
||||
including the input.
|
||||
|
||||
The command consolidates the legend into that cell. Existing mappings remain
|
||||
unless you override them with `--name`. It creates no cells or references, and
|
||||
copies other records, timestamps, unknown records, and trailing padding byte for
|
||||
byte. Input and annotation validation finish before the output is created.
|
||||
|
||||
## Annotation format
|
||||
|
||||
A text label whose exact string is `KLAMATH_LAYER_NAMES_V1` identifies a carrier
|
||||
pair in its cell. Every other text label on that pair in the same cell is a
|
||||
mapping of the form:
|
||||
|
||||
```text
|
||||
layer:datatype:name
|
||||
```
|
||||
|
||||
For example, `1:0:WG` names pair `(1, 0)` as WG. Numbers are unsigned 16-bit
|
||||
decimals. The name must be nonempty UTF-8 and may contain colons; only the first
|
||||
two colons separate fields. The legacy marker remains part of the format.
|
||||
|
||||
Mappings are collected across the library. Identical duplicates are accepted;
|
||||
conflicting names for the same pair are errors. Recognized annotation labels
|
||||
are excluded from ordinary object comparison. The name mapping compares
|
||||
separately, while unchanged names remain available in the report legend.
|
||||
|
||||
Pheon does not currently read LayoutEditor LayerNames metadata, extract layers,
|
||||
or remap geometry. See the [CLI guide](cli.md) for layer selection during review.
|
||||
68
docs/native-api.md
Normal file
68
docs/native-api.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Rust and C integration
|
||||
|
||||
Use the Rust library or C API to read GDSII into Arrow without Python. For the
|
||||
returned data layout, see the [Arrow reference](arrow-schema.md).
|
||||
|
||||
## Rust
|
||||
|
||||
Add `pheon` as a dependency. The library readers accept GDSII byte slices:
|
||||
|
||||
```rust
|
||||
use pheon::library::read_library;
|
||||
|
||||
let bytes = std::fs::read("chip.gds").expect("read layout");
|
||||
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
|
||||
println!("{layout:?}");
|
||||
```
|
||||
|
||||
`read_library` reads geometry; `scan_library` returns metadata, references, and
|
||||
cell ranges. Pass `(start, end)` ranges from a scan to `read_selected_library`
|
||||
to load only those cells. Each range must span one complete cell. Readers return
|
||||
`(remainder, StructArray)` on success. The selected reader returns the original
|
||||
input as its remainder, since selection is random access.
|
||||
|
||||
The `record`, `records`, and `basic` modules also provide low-level GDSII record
|
||||
writing. There is no high-level writer for the Arrow layout. REAL8 writing is
|
||||
exact for representable in-range `f64` values: magnitudes below `2^-260`
|
||||
underflow to zero; magnitudes at least `2^252` and nonfinite values are rejected.
|
||||
|
||||
## C API
|
||||
|
||||
Build the shared library with `cargo build --release --locked`. The
|
||||
[header](../pheon/_ffi.h) defines the functions and Arrow C Data structures.
|
||||
The library is `libpheon.so`, `libpheon.dylib`, or `pheon.dll` on Linux, macOS,
|
||||
or Windows respectively.
|
||||
|
||||
| Function | Input | Result |
|
||||
| --- | --- | --- |
|
||||
| `read_path` | NUL-terminated path | Full layout. |
|
||||
| `read_bytes` | Byte pointer and size | Full layout. |
|
||||
| `scan_bytes` | Byte pointer and size | Metadata, references, and cell ranges. |
|
||||
| `read_cells_bytes` | Bytes and cell ranges | Full layout for selected cells. |
|
||||
|
||||
`read_path` accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads
|
||||
uncompressed GDSII; Python's `read_path` adds gzip handling.
|
||||
|
||||
For `read_cells_bytes`, `ranges` points to alternating uint64 start/end offsets
|
||||
and `range_count` is the number of cells, not the number of offsets. Ranges are
|
||||
half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned,
|
||||
native-endian uint64 values. Input buffers must remain readable for the call.
|
||||
Null buffer pointers are allowed only when their corresponding length is zero.
|
||||
|
||||
### Status and ownership
|
||||
|
||||
Each reader returns 0 on success and -1 on failure. Call `last_error_message()`
|
||||
on the same thread after a failure. It returns a borrowed NUL-terminated message;
|
||||
copy it before the next parser call or thread exit. It returns null after a
|
||||
successful parser call.
|
||||
|
||||
Supply valid, writable, initialized `ArrowArray` and `ArrowSchema` structures
|
||||
without live allocations to overwrite. A failed call leaves them unchanged.
|
||||
Successful outputs own their storage independently of the input buffer. Transfer
|
||||
ownership to an Arrow importer, or call each non-null release callback exactly
|
||||
once. Do not release structures again after an importer takes ownership.
|
||||
|
||||
`pheon_abi_version()` and `pheon_arrow_schema_version()` both currently return 1.
|
||||
Check both before using the API. The C calling/ownership contract and Arrow
|
||||
layout have separate versions; neither is the package version or the
|
||||
[JSON report schema](diff-reports.md).
|
||||
97
docs/python.md
Normal file
97
docs/python.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
# 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.
|
||||
Python 3.11 or newer is required.
|
||||
|
||||
## Install
|
||||
|
||||
To install a published package with Arrow support:
|
||||
|
||||
```sh
|
||||
python -m pip install 'pheon[arrow]'
|
||||
```
|
||||
|
||||
From a source checkout, use `python -m pip install '.[arrow]'`. Source builds
|
||||
require Rust 1.88 or newer. Prebuilt wheels bundle the native library and need
|
||||
no Rust installation. Use `pheon` without the `arrow` extra if you only need
|
||||
integer packing; importing it does not import PyArrow.
|
||||
|
||||
Run Python outside the source checkout to use the installed package.
|
||||
|
||||
## Read a layout
|
||||
|
||||
```python
|
||||
from pheon import arrow
|
||||
|
||||
layout = arrow.read_path("chip.gds")
|
||||
print(layout.field("lib_name")[0].as_py())
|
||||
print(layout.field("cell_names")[0].as_py())
|
||||
cells = layout.field("cells")[0].values
|
||||
```
|
||||
|
||||
`read_path` accepts strings and path-like objects, expands `~`, and recognizes
|
||||
gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte
|
||||
buffer, such as `bytes`, `bytearray`, or a compatible memoryview.
|
||||
|
||||
Every reader returns a one-row `pyarrow.StructArray`. Geometry is grouped by
|
||||
cell and element kind; cell and layer IDs resolve through tables in the same
|
||||
result. See the [Arrow reference](arrow-schema.md) for fields and encodings.
|
||||
The returned arrays own their storage independently of the input buffer.
|
||||
|
||||
## Scan, then read selected cells
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
from pheon import arrow
|
||||
|
||||
content = Path("chip.gds").read_bytes() # Uncompressed GDSII bytes.
|
||||
scan = arrow.scan_bytes(content)
|
||||
cells = scan.field("cells")[0].values
|
||||
ranges = list(zip(
|
||||
cells.field("struct_start_offset").to_pylist(),
|
||||
cells.field("struct_end_offset").to_pylist(),
|
||||
))
|
||||
selected = arrow.read_cells_bytes(content, ranges[:2])
|
||||
```
|
||||
|
||||
Scanning returns library metadata, cell names, references, and complete cell byte
|
||||
ranges without decoding geometry or text. Selected reads return the full layout
|
||||
schema for the requested cells, in the requested order. Use the selected result's
|
||||
own name and layer tables: IDs may differ between reads.
|
||||
|
||||
Ranges must have shape `(N, 2)` with nonnegative integer offsets. Each half-open
|
||||
range must span exactly one complete cell, from BGNSTR through ENDSTR. An empty
|
||||
list returns metadata without cells. For compressed files, decompress the bytes
|
||||
before scanning or selecting ranges.
|
||||
|
||||
## Pack integers
|
||||
|
||||
```python
|
||||
import pheon
|
||||
|
||||
int2_bytes = pheon.pack_int2([1, 2, 3])
|
||||
int4_bytes = pheon.pack_int4([100, 200])
|
||||
```
|
||||
|
||||
These helpers return big-endian GDSII integer bytes. They accept NumPy arrays,
|
||||
Python sequences, or scalars and preserve the caller's data, including for
|
||||
noncontiguous or differently ordered arrays. Pheon currently has no high-level
|
||||
Python layout writer.
|
||||
|
||||
## Errors and native library selection
|
||||
|
||||
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.
|
||||
|
||||
Python loads its bundled native library. Set `PHEON_LIBRARY` to an explicit
|
||||
library path before importing Pheon to override it during development. The
|
||||
loader checks C API and Arrow schema compatibility. It does not discover a
|
||||
Cargo-installed executable or search PATH for a library.
|
||||
|
||||
Klamath's `native` extra installs Pheon's packing helpers; Masque's `arrow` extra
|
||||
installs Pheon with Arrow support. Install these in the same Python environment
|
||||
as the companion package. A standalone CLI installation does not supply the
|
||||
Python bindings.
|
||||
For direct integration without Python, see the [native API guide](native-api.md).
|
||||
|
|
@ -1,51 +1,48 @@
|
|||
# Building and validating a release
|
||||
# Building releases
|
||||
|
||||
The source archive, Python wheels and standalone CLI are separate artifacts.
|
||||
Python wheels contain `pheon` and its shared library; Cargo installation contains
|
||||
the CLI. Neither installation searches for the other.
|
||||
This guide is for maintainers producing source archives, Python wheels, and
|
||||
standalone CLI artifacts. See [development](development.md) for local checks.
|
||||
|
||||
Build the source archive and then the wheel from that archive:
|
||||
## Build from the source archive
|
||||
|
||||
```sh
|
||||
python -m pip install build
|
||||
python -m build
|
||||
```
|
||||
|
||||
The default `build` invocation builds its wheel from the source archive. Both
|
||||
carry the Cargo version, license and locked dependency resolution. A source build
|
||||
requires Rust 1.88 or newer. The checkout selects current stable through
|
||||
`rust-toolchain.toml`; `RUSTUP_TOOLCHAIN=1.88.0` selects the minimum compiler
|
||||
explicitly for source-package builds. An installed wheel has no Rust runtime
|
||||
requirement.
|
||||
The default invocation builds the wheel from the source archive. Both use the
|
||||
Cargo version, license, and locked dependencies. Source builds require Rust 1.88
|
||||
or newer; the checkout selects stable. Use `RUSTUP_TOOLCHAIN=1.88.0` to check the
|
||||
minimum compiler explicitly.
|
||||
|
||||
The package workflow builds the archive once, then uses cibuildwheel to build
|
||||
from it and repair wheels for Linux x86-64/ARM64, macOS x86-64/ARM64 and Windows
|
||||
x86-64. Repair uses the platform tools supplied by cibuildwheel. Wheels must keep
|
||||
the `py3-none` interpreter/ABI tags and a platform tag, including an appropriate
|
||||
manylinux tag for Linux releases. Local unrepaired `linux_*` wheels are development
|
||||
artifacts, not portable Linux releases.
|
||||
Python wheels contain the package and shared library. Cargo installation
|
||||
provides the CLI. Neither installation discovers or depends on the other.
|
||||
|
||||
Each repaired wheel is tested on Python 3.11 through 3.14 without rebuilding it.
|
||||
Tests run in isolated mode against the installed package and bundled library,
|
||||
including an import that verifies integer packing does not import PyArrow. To
|
||||
repeat that check locally after installing a wheel and PyArrow:
|
||||
## Validate artifacts
|
||||
|
||||
The [package workflow](../.github/workflows/packages.yml) builds one source archive
|
||||
and uses cibuildwheel to build and repair wheels for Linux and macOS x86-64/ARM64,
|
||||
and Windows x86-64. Wheels use `py3-none` interpreter/ABI tags plus a platform tag.
|
||||
Linux releases need an appropriate manylinux tag; unrepaired local `linux_*`
|
||||
wheels are development artifacts.
|
||||
|
||||
The workflow tests each repaired wheel on Python 3.11–3.14 without rebuilding it.
|
||||
Tests run in isolated mode against the installed package and bundled library.
|
||||
To repeat the check after installing a wheel and PyArrow:
|
||||
|
||||
```sh
|
||||
python -I /path/to/pheon/tools/check_installed.py
|
||||
```
|
||||
|
||||
Unset `PHEON_LIBRARY` for artifact tests. It exists to select an explicit external
|
||||
library during development, and version checks apply equally to that library.
|
||||
The minimum Rust compiler and current stable compiler run native tests in both
|
||||
debug and release modes. CLI artifacts contain the executable, license, README
|
||||
and Git integration templates. They are tied to their build OS and architecture.
|
||||
Unset `PHEON_LIBRARY` for artifact checks. Native checks cover minimum and stable
|
||||
Rust in debug and release modes. Standalone CLI artifacts contain the executable,
|
||||
license, README, documentation, and Git templates; each targets one OS and
|
||||
architecture.
|
||||
|
||||
Workflows upload build artifacts only. They do not publish to PyPI, crates.io,
|
||||
or a hosted release. The repository URL and checkout directory can be renamed
|
||||
to `pheon` separately; no remote repository settings are changed by this work.
|
||||
## Publish separately
|
||||
|
||||
The project rename provides no Python import shim or old CLI alias. Companion
|
||||
releases must migrate their imports and dependencies together. The Python C API
|
||||
version and Arrow layout version are currently 1. CLI reports use schema version
|
||||
1 and retain the `klamath-object-v2` comparison profile and existing GDS layer-name
|
||||
metadata marker.
|
||||
Workflows upload artifacts; they do not publish to PyPI, crates.io, or a hosted
|
||||
release. Review the artifacts and test results before publishing them.
|
||||
Coordinate companion package dependencies when changing Python interfaces.
|
||||
C API, Arrow layout, JSON schema, and comparison-profile versions have separate
|
||||
contracts; see the [native API](native-api.md) and [report reference](diff-reports.md).
|
||||
|
|
|
|||
Loading…
Reference in a new issue