can1357/pon

# pon `pon` 是一个用于 Python 3.14 的 JIT 和 AoT 原生编译器及 runtime，使用 Rust 编写。这里没有解释器，也没有 bytecode：每个模块都通过 ruff parser 进行解析，降低到一个共享的 IR，并通过 Cranelift 编译为机器码——可以是在进程内即时编译（`pon run`），也可以是提前编译为独立的原生可执行文件（`pon build`）。内存由 Green Tea 垃圾回收器管理，而不是通过引用计数，并且通过与 CPython v3.14.0 的字节级精确差异测试工具来确保正确性。 最终目标是成为 Python 界的 bun/v8：一个能通过 CPython 测试套件，运行多层 JIT 远超 CPython，提供单二进制可执行文件，并自带全套电池（包管理器、工具链）的 runtime。该项目正在大力积极开发中——请参阅[状态](#status)，了解目前的实际情况以及未来的发展方向。 ## 快速开始 ``` # JIT：解析 → IR → Cranelift → 运行，进程内 printf 'def add(a, b):\n return a + b\n\nprint("hello, world")\nprint(add(2, 3))\n' > hello.py cargo run -p pon -- run hello.py # AoT：相同的 IR 通过 cranelift-object，链接到原生可执行文件 cargo run -p pon -- build hello.py -o hello ./hello ``` 这两种路径都会打印出与 CPython 相同的字节。这一特性并非奢望——它是 conformance 测试套件的输出关卡（参见 [Conformance](#conformance--testing)）。 ``` pon run [args] pon build -o [--allow-dynamic] [--opt] [--target ] pon repl pon -c 'print(40 + 2)' pon - < script.py ``` ## 架构

一个 IR，两个后端，一个 runtime ABI。每一层——baseline JIT、optimizing JIT 和 AoT——都会降低相同的 IR，并调用相同的 `pon_*` 辅助函数： ``` source.py │ ruff parser (pinned 0.14.0, PythonVersion::PY314) AST ──> PON IR (pon-ir, one IR for every tier) │ ├── pon run: pon-codegen ──> cranelift-jit ──> native code in process │ tier-0 baseline (all boxed) │ tier-1 typed: inline caches, OSR, background compile │ └── pon build: pon-codegen ──> cranelift-object ──> object file ──> linked executable │ pon-runtime (object model, builtins, NULL-sentinel pon_* ABI) pon-gc (Green Tea garbage collector) ``` **对象模型：** CPython 的堆对象布局，减去了 refcount header。错误以 NULL 哨兵的形式跨越 ABI 传递，而不是通过堆栈展开。整数是任意精度的（`PyLong` 背后的 `num-bigint`）；一条带标记的小整数（tagged small-int）快速路径正在 typed 层中实现。 **分层：** tier-0 在没有类型反馈的情况下编译所有装箱（boxed）内容，并且是正确性的 baseline（`PON_TIER0_ONLY=1` 强制开启此项）。Runtime 辅助函数从第一次执行开始就为 `FeedbackCell` 类型配置提供反馈；热点函数会在后台线程上重新编译，正在运行的循环通过 on-stack replacement 进入优化后的代码。 **GC：** Green Tea 回收器拥有所有 Python 对象的所有权。Tier-0 在 safepoints 处使用带有 register-flush trampoline 的保守栈扫描；typed 层则升级为精确的 Cranelift 用户栈映射。 ## Workspace | Crate | 作用 | | --- | --- | | `pon-ir` | 基于 ruff 的前端：解析 Python 3.14，降低到共享的 PON IR | | `pon-codegen` | IR → Cranelift CLIF，由所有后端和层级共享 | | `pon-jit` | 进程内编译、分层、inline caches、OSR、后台编译 | | `pon-aot` | `cranelift-object` 后端：目标文件和链接后的原生可执行文件 | | `pon-runtime` | 对象模型、builtins、stdlib 原生模块、`pon_*` 辅助 ABI | | `pon-gc` | Green Tea 垃圾回收器 | | `pon-abi` | codegen 和 runtime 之间共享的 ABI 类型 | | `pon` | `pon` 二进制程序：`run`/`build`/`repl` 入口点 + 包管理器（索引客户端、解析器、wheel/sdist 安装） | | `pon-conformance` | 差异 conformance 套件、fuzzing、基准测试、下限棘轮 | 所有依赖都在根目录的 `Cargo.toml` 中的 `[workspace.dependencies]` 下声明一次；成员 crate 只进行继承（参见 [`AGENTS.md`](AGENTS.md)）。 ## Conformance 与测试 正确性契约是差异化的：只有当 `pon` 产生与 CPython v3.14.0（`TZ=UTC`，`PYTHONHASHSEED=0`）**字节完全相同**的输出时，语料库模块才算通过。通过的集合会被棘轮式地锁定到已提交的下限文件中，如果 CI 低于下限出现任何回归都会导致失败。 | 套件 | 测量内容 | 已提交下限 | | --- | --- | --- | | `cpython` | 语料库模块，JIT，与 CPython 3.14 字节级精确对比 | 244 个模块（[`conformance-floor.json`](conformance-floor.json)） | | `cpython-aot-subset` | 同样编译为 AoT 并作为原生二进制文件执行的语料库 | 206 个模块（[`aot-parity-floor.json`](aot-parity-floor.json)） | | `cpython-full` | CPython 自己的测试套件（`Lib/test`），在 pon 下运行 | 正在推进中（[`conformance-full-floor.json`](conformance-full-floor.json)） | | `fuzz` | 针对 CPython 的差异化 fuzzing；必须保持在零偏差 | — | | `ft-stress` | 默认 runtime 下的 no-GIL/多线程压力测试 | — | 常态化的关卡是 `scripts/gate.sh`；只有它的输出才会被算作关卡达成声明： ``` bash scripts/gate.sh fast # build + workspace tests + conformance floor + AoT floor + ft-stress bash scripts/gate.sh full # + cpython-full, bench, tier0-only diff, fuzz, package-manager E2E # 单独的 meters cargo run -q -p pon-conformance -- --suite cpython --check-floor cargo run -q -p pon-conformance -- --mode aot --suite cpython-aot-subset --check-floor cargo run -q -p pon-conformance -- --suite cpython --modules # one module, differential cargo run -q -p pon-conformance -- --suite fuzz --seed 42 --count 200 --jobs 8 ``` 语料库文件一旦落地即不可变：新的覆盖范围就是一个新的模块，在它进入清单之前，必须验证其与 `python3.14` 的输出是字节一致的。如果偏差是 CPython 本身的问题（而不是 pon 的问题），则会被记录在 [`pon-conformance/divergence-ledger.toml`](pon-conformance/divergence-ledger.toml) 中，而不是被掩盖过去。 ## 包管理器 `pon` 包含一个 uv 风格的包管理器，基于 `pubgrub` 解析和标准的 `pyproject.toml` 构建，目标是支持 PyPI 简单索引、wheels、sdists、可编辑安装和 VCS 依赖。它的 `run` 命令通过与直接脚本调度相同的 runtime 路径执行，同时增加了受管理的导入根。它正在积极开发中，尚未集成到 runtime 关卡中。 ``` pon init | add | remove | install | lock | run | list | freeze | show | download | check | cache | env ``` ## 固定的工具链 这些锁定是在整个 workspace 范围内确定的，并由 `Cargo.lock` / `rust-toolchain.toml` 强制执行；请勿随意更改。 | 组件 | 锁定版本 | | --- | --- | | 工具链 | `nightly-2026-04-29` (`rust-toolchain.toml`) | | MSRV | `rust-version = "1.94.0"`，edition 2024 | | Parser | ruff git tag `0.14.0`，`PythonVersion::PY314` | | 后端 | 所有 `cranelift-*` crates `=0.133.1`，同步锁定 | | 大整数 | `PyLong` 背后的 `num-bigint 0.4.6` | | CLIF 标志 | `preserve_frame_pointers=true`；JIT 为 `is_pic=false` / AoT 为 `is_pic=true` | | 参考实现 | CPython v3.14.0，固定在 `pon-conformance/vendor/cpython-3.14/REVISION` | ## 状态 目前已验证的内容（全部位于受棘轮控制、受 CI 检查的下限之后）： - `pon run` 和 `pon build` 实现了端到端的运行；上面的快速开始就是一个经过冒烟测试的例子。 - JIT 下有 209 个差异语料库模块与 CPython 3.14 字节一致；其中 172 个在编译为 AoT 时也能通过。 - 性能基础设施已就位：后台编译、OSR、inline caches、类型反馈。 目前明确**尚未**完成的内容——这是正在进行的路线图，按优先级排序： 1. **CPython 测试套件**（`cpython-full`）：持续的攻坚工作；故障被分簇并按波次消除。 2. **Stdlib 扩展**：`_io`/`os`，`math`/`struct`/`random`，`collections`/`itertools`/`json`，`datetime`，`importlib` 对齐——每一个都作为一个原生模块加上一个差异语料库模块落地。 3. **性能棘轮**：tagged small-int 翻转、TLAB 分配、dict 快速路径、float 拆箱、call/attribute 特化、generator 分层——朝着 ≥5× CPython 几何平均数目标（数值计算 ≥20×）迈进。 4. **AoT 一致性增长**，朝着完整的语料库迈进，外加单二进制产品的完善。 5. **No-GIL/free-threaded runtime 强化**：线程/GC/信号压力测试现在处于默认的 runtime 路径上，剩余的缺口由棘轮化的套件进行跟踪。 语言层面上已知的缺口正通过上述棘轮化的下限被逐步消除——已提交的下限文件，而不是此 README，才是权威的兼容性 baseline。

标签：Cranelift, JIT, Python, Rust, SOC Prime, 可视化界面, 开发工具, 无后门, 编译器, 网络流量审计, 运行时, 逆向工具, 通知系统