划定 CMake 模块目录并补充各层 README。

固定 isa/compiler/vm/host 的职责边界，样例与测试单独成目录。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-18 16:32:07 +08:00
parent 368877ae34
commit 2eb2468119
11 changed files with 217 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 子集 ST + 寄存器 VM
+
+IEC 风格的子集 ST：用 `project.toml` 组织多个 `.st`，编译成单一映像，由寄存器虚拟机按扫描周期执行。
+
+方案见 [`Doc/初步计划.md`](Doc/初步计划.md)。
+
+```text
+多个 .st
+    ↑ project.toml 列出
+    ↓
+compiler（词法 / 语法 → 符号表 → 类型检查 → 寄存器码 → 链接）
+    ↓
+单一映像（函数字节码 + 全局 / FB 数据槽 + 工程哈希）
+    ↓
+vm 按扫描周期执行；host 喂 I、收 Q、给 Δt、回放
+```
+
+## 目录
+
+```text
+.
+├── CMakeLists.txt          # 顶层工程：加入四个目标，并启用测试
+├── cmake/                  # CMake 辅助（警告、C++ 标准等），不是业务模块
+├── isa/                    # 共享契约：指令、映像、定宽类型
+├── compiler/               # ST / toml 编译器
+├── vm/                     # 寄存器虚拟机
+├── host/                   # 可执行入口：编译并跑扫描周期
+├── examples/               # 样例工程（给人看、跑通最小闭环）
+│   └── line1/              # MAIN + Motor FB + I/O
+│       ├── project.toml
+│       ├── globals.st
+│       ├── motor.st
+│       └── main.st
+├── tests/                  # 自动化用例（语法、链接、指令、回放）
+├── third_party/            # 第三方（如 toml 解析），compiler 私有链接
+└── Doc/                    # 设计文档
+```
+
+样例和测试是数据，不做成 CMake 库。每个用例是一份 toml + 若干 `.st`，按工程子目录存放。
+
+## 模块与 CMake 目标
+
+四个链接目标，与目录一一对应。`compiler` 与 `vm` 不互相链接，合同放在 `isa`。
+
+| 目录 | 目标 | 类型 | 依赖 | 职责 |
+|---|---|---|---|---|
+| `isa/` | `isa` | `STATIC` 或 `INTERFACE` | 无 | 约 20 条指令编码、映像头、工程哈希、`BOOL` / `INT` / `TIME` 宽度 |
+| `compiler/` | `compiler` | `STATIC` | `isa` | 读 toml、收齐 `.st`、解析、链接、定址、类型检查、编寄存器码、写映像 |
+| `vm/` | `vm` | `STATIC` | `isa` | 一台 VM、一个入口、一份映像；扫描周期、寄存器、FB、有界 `CALL` / `RET` |
+| `host/` | `host` | `EXECUTABLE` | `compiler`、`vm` | 读工程、编译、按 toml 的 io 采样 I、执行 `PROGRAM MAIN`、写回 Q、用 Δt 推进定时器 / 计数器、回放 |
+
+词法、语法、符号表、检查、codegen、链接都留在 `compiler` 一个库里，不再拆 CMake 子库。
+
+### `isa`
+
+编译器写映像、虚拟机读映像，两边共用同一套编码。放这里避免循环依赖。
+
+### `compiler`
+
+toml **不声明变量**，只列出源文件、指定唯一 GVL、可选地把已有全局接到硬件。`VAR_GLOBAL` 第一版只允许出现在 `gvl.file`（如 `globals.st`）。
+
+### `vm`
+
+每个扫描周期：采样 I → 从 `PROGRAM MAIN` 的 `pc=0` 执行到 `RET` → 写回 Q → 用本周期 Δt 推进 `TON` / `TOF` / `CTU`。无 GC、无堆、无线程；变量编译期分配。
+
+### `host`
+
+第一版做成一条命令：编译 + 跑周期。不必再拆独立的编译器可执行文件。
+
+### `examples/` 与 `tests/`
+
+| 目录 | 用途 |
+|---|---|
+| `examples/line1/` | 计划中的最小样例：全局、`MotorStarter` FB、`PROGRAM MAIN` |
+| `tests/` | 冻关键字、指令、符号表、链接错误（重复 `VAR_GLOBAL`、`io.var` 未声明等） |
+
+`tests/` 通过 `add_test` 调用 `host` 或直接链接 `compiler` + `vm`。