From 9b93586eec0ac3927074dd2a7c652d144f7f5b6d Mon Sep 17 00:00:00 2001 From: TermiNexus Date: Mon, 12 Oct 2026 14:48:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E9=9A=8F=E6=94=B9=E5=90=8D?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=EF=BC=88ViperC/viperc.exe/=5F=5Fvpcbuild=5F?= =?UTF-8?q?=5F=EF=BC=89=E5=B9=B6=E7=BA=A0=E6=AD=A3=E8=BF=87=E6=97=B6?= =?UTF-8?q?=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - w32.* -> win32.*（中文前提条件/对比表、英文 Prerequisites/对比表 共 4 处） - 规模数字按实测刷新：App 82 文件 63,783 行；Gen 54 文件 47,297 行； Phase 6/5,339；Stub 9/6,207；Projectrans 3/712 - 自测套件位置纠正：不在本仓库，位于工作区根 Test\（独立仓库，97 工程 129 个 .vp）， 由 Test\SequentialRegressionTest.py 驱动；删除已不存在的 Test/{App,NegativeTest,Sha1Test} 描述 - 工作区布局补 Test\ 与 exe\，修正 ViperC\ 对齐 --- README.md | 135 +++++++++++++++++++++++++++--------------------------- 1 file changed, 68 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 6c02850..1756015 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# TransPyV +# ViperC [English](#english) | [中文](#中文) -The **Viper language compiler, written in Viper itself** — and it is **self-hosted**: TransPyV compiles its own source and produces `TransPyV.exe`. It translates Viper sources to LLVM IR, then drives `llc` + `clang++` to link a native Windows executable. The first-generation CPython compiler ([TransPyC](https://git.gvsds.com/GVSDS/TransPyC)) is now only kept as the bootstrapping **seed**. +The **Viper language compiler, written in Viper itself** — and it is **self-hosted**: ViperC compiles its own source and produces `viperc.exe`. It translates Viper sources to LLVM IR, then drives `llc` + `clang++` to link a native Windows executable. The first-generation CPython compiler ([TransPyC](https://git.gvsds.com/GVSDS/TransPyC)) is now only kept as the bootstrapping **seed**. -**用 Viper 语言编写的 Viper 编译器**，且**已完成自举**：TransPyV 能编译自身源码并产出 `TransPyV.exe`。它把 Viper 源码翻译为 LLVM IR，再调用 `llc` + `clang++` 链接为 Windows 原生可执行文件。第一代 CPython 编译器（[TransPyC](https://git.gvsds.com/GVSDS/TransPyC)）现在只作为自举**种子**保留。 +**用 Viper 语言编写的 Viper 编译器**，且**已完成自举**：ViperC 能编译自身源码并产出 `viperc.exe`。它把 Viper 源码翻译为 LLVM IR，再调用 `llc` + `clang++` 链接为 Windows 原生可执行文件。第一代 CPython 编译器（[TransPyC](https://git.gvsds.com/GVSDS/TransPyC)）现在只作为自举**种子**保留。 --- @@ -14,18 +14,18 @@ The **Viper language compiler, written in Viper itself** — and it is **self-ho ### 这是什么 -`TransPyV` 是 Viper 的第二代编译器：**用 Viper 自己写、也被 Viper 自己编译**。整条链路上没有任何 Python 运行时参与编译 —— 词法/语法分析走 `includes/ast`（自研解析器，9 个文件），IR 生成走 `App/lib/core/Gen/`，目标代码由 `llc` 与 `clang++` 产出。 +`ViperC` 是 Viper 的第二代编译器：**用 Viper 自己写、也被 Viper 自己编译**。整条链路上没有任何 Python 运行时参与编译 —— 词法/语法分析走 `includes/ast`（自研解析器，9 个文件），IR 生成走 `App/lib/core/Gen/`，目标代码由 `llc` 与 `clang++` 产出。 自举链路： ```text TransPyC（种子，CPython 实现） - │ 只做一次：把 TransPyV 源码编译成 TransPyV.exe + │ 只做一次：把 ViperC 源码编译成 viperc.exe ▼ -TransPyV.exe（第一阶段产物） - │ 自举：用这个 exe 再编译 TransPyV 自身 +viperc.exe（第一阶段产物） + │ 自举：用这个 exe 再编译 ViperC 自身 ▼ -TransPyV.exe（自举产物，当前仓库随包/随 exe\ 提供的那份） +viperc.exe（自举产物，当前仓库随包/随 exe\ 提供的那份） │ └─ 用它编译任意 Viper 工程（ViperApps\*、Test\* …） ``` @@ -34,20 +34,20 @@ TransPyV.exe（自举产物，当前仓库随包/随 exe\ 提供的那份） | 项 | 值 | | --- | --- | -| 编译器源码 | `App/` 下 **76 个 `.vp` 文件，64,656 行** | -| 其中翻译器核心 | `App/lib/core/Gen/` **52 个文件，49,978 行** | -| 阶段与合并 | `App/lib/Phase/` 6 文件 5,309 行；`App/lib/Stub/` 9 文件 6,877 行 | -| 工程与工具 | `App/lib/Projectrans/` 3 文件 1,008 行 | -| 自测用例 | `Test/` 下 **39 个 `.vp`**（`App/` 36 + `NegativeTest/` 2 + `Sha1Test/` 1） | -| 平台 | Windows x64（源码直接 `import w32.*`） | +| 编译器源码 | `App/` 下 **82 个 `.vp` 文件，63,783 行** | +| 其中翻译器核心 | `App/lib/core/Gen/` **54 个文件，47,297 行** | +| 阶段与合并 | `App/lib/Phase/` 6 文件 5,339 行；`App/lib/Stub/` 9 文件 6,207 行 | +| 工程与工具 | `App/lib/Projectrans/` 3 文件 712 行 | +| 自测/回归套件 | 工作区根 `Test\`（**独立仓库**）：**97 个工程，129 个 `.vp`**，由 `Test\SequentialRegressionTest.py` 驱动 | +| 平台 | Windows x64（源码直接 `import win32.*`） | > 自举可行性分析与历史数据见 [`wiki/13-bootstrapping.md`](https://git.gvsds.com/GVSDS/TransPyC/blob/main/wiki/13-bootstrapping.md)（该文标注：Phase A → Phase B/C 已跑通，编译器已脱离 Python 运行时）。 ### 目录结构 ```text -TransPyV/ -├── project.vpj # 工程配置（source_dir=./App, build_dir=./.tpv_build, 输出 TransPyV.exe） +ViperC/ +├── project.vpj # 工程配置（source_dir=./App, build_dir=./__vpcbuild__, 输出 viperc.exe） ├── App/ # 编译器源码（Viper） │ ├── main.vp # CLI 入口：内存池初始化、单例注入、参数解析、Phase 调度 │ └── lib/ @@ -75,18 +75,16 @@ TransPyV/ │ └── Stub/ │ ├── StubGen/ # .vpi 读取 + 声明转换 │ └── StubMerger/ # 多份 .stub.ll / .text.ll 依赖排序与合并 -└── Test/ # 编译器自测（Viper） - ├── project.vpj - ├── App/ # 36 个 .vp（多为 *_test.vp），入口 test_main.vp 聚合全部用例 - ├── NegativeTest/ # 负向测试（故意编译失败） - └── Sha1Test/ # SHA1 命名空间测试 ``` +> 自测/回归套件不在本仓库：位于工作区根 `Test\`（独立仓库，97 个工程 129 个 `.vp`）， +> 由 `Test\SequentialRegressionTest.py` 驱动（`--exe exe\viperc.exe`）。 + ### 前提条件 | 工具 | 说明 | | --- | --- | -| Windows 10/11 x64 | 编译器源码直接 `import w32.*`，当前仅 Windows | +| Windows 10/11 x64 | 编译器源码直接 `import win32.*`，当前仅 Windows | | `llc` | LLVM 静态编译器（本机 22.1.8），由 `project.vpj` 的 `compiler.cmd` 指定 | | `clang++` | mingw-w64 工具链，`-fuse-ld=lld` 链接（本机 `D:/msys64/mingw64/bin/clang++.exe`） | | ≥ 1.5 GiB 空闲内存 | 启动即 `malloc` 1 GiB 主池 + 512 MiB 常驻池 | @@ -97,7 +95,9 @@ TransPyV/ ```text TransPyC\ # 工作区根 ├── TransPyC\ # 第一代编译器（种子） -├── TransPyV\ # 本仓库 +├── ViperC\ # 本仓库 +├── Test\ # 回归套件（独立仓库） +├── exe\ # 随包提供的自举产物（viperc.exe） └── includes\ # Viper 标准库 + includes/ast 解析器 ``` @@ -105,22 +105,22 @@ TransPyC\ # 工作区根 ```bat :: 日常：直接用自举产物编译任意工程 -exe\TransPyV.exe --project ViperApps\ViperMNIST\project.vpj --clean +exe\viperc.exe --project ViperApps\ViperMNIST\project.vpj --clean :: 编译并立即运行 -exe\TransPyV.exe --project ViperApps\ViperMNIST\project.vpj --clean --run +exe\viperc.exe --project ViperApps\ViperMNIST\project.vpj --clean --run :: 只有在需要重建编译器本体（自举种子）时，才动用 TransPyC -python TransPyC\Projectrans.py --project TransPyV\project.vpj --clean +python TransPyC\Projectrans.py --project ViperC\project.vpj --clean ``` -产物位置 = `<工程目录>\\output\`，即默认 `<工程>\.tpv_build\output\app.exe`； -TransPyV 自身因 `linker.output` 为 `TransPyV.exe`，产物是 `TransPyV\.tpv_build\output\TransPyV.exe`。 +产物位置 = `<工程目录>\\output\`，即默认 `<工程>\__vpcbuild__\output\app.exe`； +ViperC 自身因 `linker.output` 为 `viperc.exe`，产物是 `ViperC\__vpcbuild__\output\viperc.exe`。 -跑编译器自测套件： +跑回归套件（工作区根 `Test\`，独立仓库）： ```bat -exe\TransPyV.exe --project TransPyV\Test\project.vpj --clean --run +python Test\SequentialRegressionTest.py --exe exe\viperc.exe ``` ### 命令行参数 @@ -138,14 +138,14 @@ exe\TransPyV.exe --project TransPyV\Test\project.vpj --clean --run | `--rebuild-includes` | 只删 includes 预编译缓存（`includes.binary`），强制重编 includes | | `--clear-cache` | 只清 temp 缓存（`.vpi` / `.stub.ll` / `.text.ll`），强制重生成 stub | | `--run` | 编译成功后立即执行产物 | -| `--repl` | 交互式 REPL（M1：表达式片段 → DLL → 调用回显）；未给 `--project` 时按 cwd → `TransPyV.exe` 同目录查找 `repl.vpj` 模板工程（找不到则报错并提示 `--project`）；与 `--asan` / `--phase2command` 互斥 | +| `--repl` | 交互式 REPL（M1：表达式片段 → DLL → 调用回显）；未给 `--project` 时按 cwd → `viperc.exe` 同目录查找 `repl.vpj` 模板工程（找不到则报错并提示 `--project`）；与 `--asan` / `--phase2command` 互斥 | | `--asan` | ASan 模式：先 `opt -passes=asan` 插桩；运行库须由 `project.vpj` 的 `linker.static_libs` 声明，否则 fail-fast | | `--phase2command ` | 不执行 `llc`/链接，只把命令写进指定 `.bat` | | `--nowarn-register` | 抑制 Phase A 依赖类 WARN（跨模块 `text.ll` 未生成，下遍收敛） | | `--no-llvmpeephole` | 关闭 FunctionPrint 的本地窥孔（T2 store/load 转发、T3 空 bitcast） | | `--detection` | 开启 MemBuddy 分配检测（`0xCDCD` 标记 + 记录表探针，查越界写） | | `--show-args` | 打印全部解析结果 | -| `--version`, `-v` | 打印 Viper / VRTE / TransPyV 版本、提交号、目标三元组与 LLVM 版本 | +| `--version`, `-v` | 打印 Viper / VRTE / ViperC 版本、提交号、目标三元组与 LLVM 版本 | | `--help`, `-h` | 打印帮助 | ### 架构 @@ -201,15 +201,15 @@ source_dir 下全部 .vp/.py（多文件模式：递归扫描所有源文件） ### 与 TransPyC 的关系 -| 维度 | TransPyC | TransPyV | +| 维度 | TransPyC | ViperC | | --- | --- | --- | | 实现语言 | CPython | Viper | -| 定位 | 自举**种子**（只用来生成稳定的 TransPyV） | **现行编译器** | +| 定位 | 自举**种子**（只用来生成稳定的 ViperC） | **现行编译器** | | 自举状态 | — | ✅ 已完成，能编译自身 | | 入口 | `TransPyC/Projectrans.py` | `App/main.vp` | | AST 解析 | Python `ast` / 自研 vast | `includes/ast` 自研（9 文件） | | 工程配置 | `project.json` | `project.vpj` | -| 平台 | Windows / Linux | Windows（`w32.*`） | +| 平台 | Windows / Linux | Windows（`win32.*`） | ### 进一步阅读 @@ -227,18 +227,18 @@ source_dir 下全部 .vp/.py（多文件模式：递归扫描所有源文件） ### What is this -`TransPyV` is the second-generation Viper compiler: **written in Viper and compiled by Viper**. No Python runtime takes part in the compilation path — lexing/parsing goes through `includes/ast` (a self-implemented parser, 9 files), IR generation through `App/lib/core/Gen/`, and machine code through `llc` + `clang++`. +`ViperC` is the second-generation Viper compiler: **written in Viper and compiled by Viper**. No Python runtime takes part in the compilation path — lexing/parsing goes through `includes/ast` (a self-implemented parser, 9 files), IR generation through `App/lib/core/Gen/`, and machine code through `llc` + `clang++`. The bootstrap chain: ```text TransPyC (seed, implemented in CPython) - │ one-time only: compile TransPyV sources into TransPyV.exe + │ one-time only: compile ViperC sources into viperc.exe ▼ -TransPyV.exe (stage-one artifact) - │ bootstrap: this exe compiles TransPyV itself +viperc.exe (stage-one artifact) + │ bootstrap: this exe compiles ViperC itself ▼ -TransPyV.exe (self-hosted artifact — the one shipped in exe\) +viperc.exe (self-hosted artifact — the one shipped in exe\) │ └─ used to build any Viper project (ViperApps\*, Test\* …) ``` @@ -247,18 +247,18 @@ Current state and size (measured on the dev machine): | Item | Value | | --- | --- | -| Compiler sources | **76 `.vp` files, 64,656 lines** under `App/` | -| Translator core | `App/lib/core/Gen/` — **52 files, 49,978 lines** | -| Phases & merging | `App/lib/Phase/` 6 files 5,309 lines; `App/lib/Stub/` 9 files 6,877 lines | -| Project & utils | `App/lib/Projectrans/` 3 files 1,008 lines | -| Self-tests | **39 `.vp`** under `Test/` (`App/` 36 + `NegativeTest/` 2 + `Sha1Test/` 1) | -| Platform | Windows x64 (sources `import w32.*` directly) | +| Compiler sources | **82 `.vp` files, 63,783 lines** under `App/` | +| Translator core | `App/lib/core/Gen/` — **54 files, 47,297 lines** | +| Phases & merging | `App/lib/Phase/` 6 files 5,339 lines; `App/lib/Stub/` 9 files 6,207 lines | +| Project & utils | `App/lib/Projectrans/` 3 files 712 lines | +| Self-tests | workspace root `Test\` (**separate repo**): **97 projects, 129 `.vp`**, driven by `Test\SequentialRegressionTest.py` | +| Platform | Windows x64 (sources `import win32.*` directly) | ### Directory layout ```text -TransPyV/ -├── project.vpj # project config (source_dir=./App, build_dir=./.tpv_build, output TransPyV.exe) +ViperC/ +├── project.vpj # project config (source_dir=./App, build_dir=./__vpcbuild__, output viperc.exe) ├── App/ # compiler sources (Viper) │ ├── main.vp # CLI entry: pools, singleton injection, arg parsing, phase dispatch │ └── lib/ @@ -286,18 +286,17 @@ TransPyV/ │ └── Stub/ │ ├── StubGen/ # .vpi reader + declaration converter │ └── StubMerger/ # dependency-ordered merge of .stub.ll / .text.ll -└── Test/ # compiler self-tests (Viper) - ├── project.vpj - ├── App/ # 36 .vp (mostly *_test.vp); entry point test_main.vp aggregates them all - ├── NegativeTest/ # negative tests (must fail to compile) - └── Sha1Test/ # SHA1 namespace test ``` +> The self-test/regression suite is not in this repo: it lives at the workspace root `Test\` +> (a separate repo, 97 projects, 129 `.vp`), driven by `Test\SequentialRegressionTest.py` +> (`--exe exe\viperc.exe`). + ### Prerequisites | Tool | Notes | | --- | --- | -| Windows 10/11 x64 | sources `import w32.*`; Windows-only for now | +| Windows 10/11 x64 | sources `import win32.*`; Windows-only for now | | `llc` | LLVM static compiler (22.1.8 here), set by `compiler.cmd` in `project.vpj` | | `clang++` | mingw-w64 toolchain, `-fuse-ld=lld` (here `D:/msys64/mingw64/bin/clang++.exe`) | | ≥ 1.5 GiB free RAM | allocates a 1 GiB main pool + 512 MiB permanent pool at startup | @@ -308,7 +307,9 @@ Required layout (`project.vpj` refers to `../includes`): ```text TransPyC\ # workspace root ├── TransPyC\ # first-generation compiler (seed) -├── TransPyV\ # this repo +├── ViperC\ # this repo +├── Test\ # regression suite (separate repo) +├── exe\ # shipped self-hosted artifact (viperc.exe) └── includes\ # Viper standard library + includes/ast parser ``` @@ -316,23 +317,23 @@ TransPyC\ # workspace root ```bat :: everyday use: build any project with the self-hosted compiler -exe\TransPyV.exe --project ViperApps\ViperMNIST\project.vpj --clean +exe\viperc.exe --project ViperApps\ViperMNIST\project.vpj --clean :: build and run immediately -exe\TransPyV.exe --project ViperApps\ViperMNIST\project.vpj --clean --run +exe\viperc.exe --project ViperApps\ViperMNIST\project.vpj --clean --run :: only when rebuilding the compiler itself (bootstrap seed), use TransPyC -python TransPyC\Projectrans.py --project TransPyV\project.vpj --clean +python TransPyC\Projectrans.py --project ViperC\project.vpj --clean ``` Artifacts land in `\\output\` — by default -`\.tpv_build\output\app.exe`. TransPyV itself sets `linker.output` to `TransPyV.exe`, -so its own product is `TransPyV\.tpv_build\output\TransPyV.exe`. +`\__vpcbuild__\output\app.exe`. ViperC itself sets `linker.output` to `viperc.exe`, +so its own product is `ViperC\__vpcbuild__\output\viperc.exe`. -Run the compiler self-test suite: +Run the regression suite (workspace root `Test\`, a separate repo): ```bat -exe\TransPyV.exe --project TransPyV\Test\project.vpj --clean --run +python Test\SequentialRegressionTest.py --exe exe\viperc.exe ``` ### CLI flags @@ -350,14 +351,14 @@ exe\TransPyV.exe --project TransPyV\Test\project.vpj --clean --run | `--rebuild-includes` | delete only the includes cache (`includes.binary`), forcing a full includes rebuild | | `--clear-cache` | clear only temp (`.vpi` / `.stub.ll` / `.text.ll`), forcing stub regeneration | | `--run` | execute the produced binary on success | -| `--repl` | interactive REPL (M1: expression fragment → DLL → call and echo); without `--project` it looks for the `repl.vpj` template project in cwd, then next to `TransPyV.exe` (errors out with a `--project` hint if neither exists); mutually exclusive with `--asan` / `--phase2command` | +| `--repl` | interactive REPL (M1: expression fragment → DLL → call and echo); without `--project` it looks for the `repl.vpj` template project in cwd, then next to `viperc.exe` (errors out with a `--project` hint if neither exists); mutually exclusive with `--asan` / `--phase2command` | | `--asan` | ASan mode: `opt -passes=asan` first; runtimes must be declared in `project.vpj` `linker.static_libs`, else fail-fast | | `--phase2command ` | do not run `llc`/link; write the commands into the given `.bat` | | `--nowarn-register` | suppress Phase A dependency WARNs (cross-module `text.ll` not yet emitted, converges next pass) | | `--no-llvmpeephole` | disable FunctionPrint local peepholes (T2 store/load forwarding, T3 no-op bitcast) | | `--detection` | enable MemBuddy allocation detection (`0xCDCD` fill + record-table probe for out-of-bounds writes) | | `--show-args` | dump all parsed arguments | -| `--version`, `-v` | print Viper / VRTE / TransPyV versions, commit ids, target triple and LLVM version | +| `--version`, `-v` | print Viper / VRTE / ViperC versions, commit ids, target triple and LLVM version | | `--help`, `-h` | print help | ### Architecture @@ -415,15 +416,15 @@ out-of-bounds writes. ### Relation to TransPyC -| Dimension | TransPyC | TransPyV | +| Dimension | TransPyC | ViperC | | --- | --- | --- | | Implementation | CPython | Viper | -| Role | bootstrap **seed** (only used to produce a stable TransPyV) | **the current compiler** | +| Role | bootstrap **seed** (only used to produce a stable ViperC) | **the current compiler** | | Self-hosted? | — | ✅ yes, it compiles itself | | Entry | `TransPyC/Projectrans.py` | `App/main.vp` | | AST parsing | Python `ast` / in-house vast | `includes/ast` (9 files, in-house) | | Project config | `project.json` | `project.vpj` | -| Platform | Windows / Linux | Windows (`w32.*`) | +| Platform | Windows / Linux | Windows (`win32.*`) | ### Further reading