docs: README 随改名同步（ViperC/viperc.exe/__vpcbuild__）并纠正过时内容

- 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\ 对齐
2026-10-12 14:48:47 +08:00
1 parent 023a22af08
commit 9b93586eec
@@ -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
 ```

-产物位置 = `<工程目录>\<build_dir>\output\<linker.output>`，即默认 `<工程>\.tpv_build\output\app.exe`；
-TransPyV 自身因 `linker.output` 为 `TransPyV.exe`，产物是 `TransPyV\.tpv_build\output\TransPyV.exe`。
+产物位置 = `<工程目录>\<build_dir>\output\<linker.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 <bat>` | 不执行 `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 `<project dir>\<build_dir>\output\<linker.output>` — by default
-`<project>\.tpv_build\output\app.exe`. TransPyV itself sets `linker.output` to `TransPyV.exe`,
-so its own product is `TransPyV\.tpv_build\output\TransPyV.exe`.
+`<project>\__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 <bat>` | 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