Skip to content

Latest commit

 

History

History
65 lines (45 loc) · 3.87 KB

README.md

File metadata and controls

65 lines (45 loc) · 3.87 KB

Development notes

These pages are for someone changing the compiler. User-facing docs live in docs/, the design overview is ARCHITECTURE.md, and the published site is at https://pyscriptc.pages.dev.

Preview the internal notes with mise run docs:internal (a docmd dev server over this directory, no build step).

Core notes

  • Invariants — rules a change has to keep
  • Debug mode — compile --debug, PYSC_DEBUG, --debug-dir artifacts
  • PYSC_MIR escape hatch: switching the opt-in MIR lane, per-function behavior, comparing lanes
  • Compiler progress trend — reading the --markdown trend table and what moves it
  • Audit logging — the JSONL audit log and its directives
  • Map — which file owns a fence, a runtime call, or a test
  • Toolchain — C compiler driver resolution, Zig preference, and ziglang
  • Benchmark audit — what the benchmark suite measures and what it does not
  • Compat site — the data file, the builder and the deploy

Specs

Design notes

FFI

Benchmarks

Release

Generated support data

The two pages below are generated from the compiler by scripts/gen_support_table.py (data in scripts/support_data.toml); tests/test_support_docs.py fails when they drift. Do not hand-edit them.

These files are the in-repo snapshot of the data the compat site publishes.

The pipeline that feeds the site is in scripts/build_compat_json.py and scripts/compat_schema.py; it reads the same support_data.toml through the same evaluate function, so the tree keeps one definition of "supported". Its output is compat/data/compat.json, rebuilt by the nightly workflow and landed through a bot PR. The design is in Compat site.

The site itself is one Cloudflare Pages project at https://pyscriptc.pages.dev, with the compat page at /compat (linked from the docs through the PYSC_COMPAT_URL placeholder, default https://pyscriptc.pages.dev/compat). Until it is deployed, these two generated pages and compat/data/compat.json are the machine-readable status in the tree.