62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# Public API catalog
|
|
|
|
`public-api.json` is the authoritative compiled-metadata inventory for the 13
|
|
LibreMetaverse library assemblies at the pinned upstream commit. It contains:
|
|
|
|
- stable C# documentation IDs and complete public type/member metadata;
|
|
- nullability, constraints, bases, interfaces, overload parameters, accessors,
|
|
constants, events, delegates, enum values, and public attributes;
|
|
- assembly identities and independent reflection/ECMA-335 count checks;
|
|
- hashes for the outputs of all six upstream source generators;
|
|
- `external_types`, the non-LibreMetaverse types used by public signatures and
|
|
every LibreMetaverse API that uses them.
|
|
|
|
External entries are replacement obligations, not copied dependency APIs.
|
|
`RUST-TYPES.tsv` resolves every entry to Rust core/std, an adopted
|
|
cross-platform crate, or a native MetaCrate type. Third-party API objects use
|
|
project-owned boundary types so their eventual backend can be replaced without
|
|
exposing SkiaSharp, SIPSorcery, MessagePack, CoreJ2K, or another foreign member
|
|
surface. `RUST-MAPPING.tsv` records one reviewed destination and full Rust
|
|
signature for every catalog member. `MAPPING-COVERAGE.md` is the readable gate
|
|
summary.
|
|
|
|
Regenerate from the clean pinned upstream checkout:
|
|
|
|
```sh
|
|
python3 tools/extract_public_api.py
|
|
```
|
|
|
|
The command builds the upstream libraries into a temporary directory, runs the
|
|
extractor twice against the same compiled metadata, rejects count mismatches or
|
|
duplicate documentation IDs, and writes the result only when both outputs are
|
|
byte-identical. The extractor is development-only and is absent from every
|
|
Cargo manifest and published Rust dependency graph.
|
|
|
|
Regenerate or validate the Rust mapping with only Python's standard library:
|
|
|
|
```sh
|
|
python3 tools/generate_rust_mapping.py
|
|
python3 tools/generate_rust_mapping.py --check
|
|
python3 tools/generate_api_shims.py
|
|
python3 tools/generate_api_shims.py --check
|
|
python3 tools/check_api_coverage.py
|
|
```
|
|
|
|
The checker rejects duplicate C# IDs, duplicate Rust destinations, invalid
|
|
statuses, stale or missing catalog entries, unresolved signature types,
|
|
assemblies without representative mappings, and platform-specific API targets.
|
|
It also rejects generated `Default` shims, plausible false/zero/empty/nil
|
|
fallbacks, and generated function bodies that do not use the standardized
|
|
`Error::NotImplemented` result or `unimplemented_api!` panic.
|
|
The two support traits in `RUST-TYPES.tsv` are included because compiled public
|
|
inheritance records reference them even though they are absent from the public
|
|
type table.
|
|
|
|
`generate_api_shims.py` consumes the catalog and reviewed mapping ledger,
|
|
formats all 13 generated Rust assemblies deterministically, and generates the
|
|
standalone `tests/api-compile` downstream fixture. `check_api_coverage.py`
|
|
compares catalog IDs, mapping rows, exported shim IDs, and fixture probes;
|
|
rejects stale, missing, duplicate, or erased entries; and verifies
|
|
`API-COVERAGE.md`. Regenerate that report with
|
|
`python3 tools/check_api_coverage.py --write`.
|