新增 STCompiler 使用说明文档。
- 构建 / 用法（-o 产出 .stb）/ 退出码 / line1 示例 - project.toml 字段表、ST 子集支持范围与 v1 限制清单 - 编译管线五类错误前缀与示例；样例与测试索引；当前状态 - compiler/README 与 Doc/索引 登记
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# STCompiler 使用说明
|
||||
|
||||
把 ST 工程（`project.toml` + 若干 `.st`）编译成单一映像 `.stb`。执行由 `BytecodeExecutor`（12.9/12.10 实现）负责。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
cmake --preset gcc-debug # 配置
|
||||
cmake --build --preset gcc-debug # 编译
|
||||
ctest --test-dir build/gcc-debug # 测试（当前 9 个用例）
|
||||
```
|
||||
|
||||
可执行文件：`build/gcc-debug/compiler/STCompiler`
|
||||
|
||||
## 用法
|
||||
|
||||
```text
|
||||
STCompiler <project.toml> [-o <name>.stb]
|
||||
```
|
||||
|
||||
| 参数 | 作用 |
|
||||
|---|---|
|
||||
| `<project.toml>` | 工程文件（必填） |
|
||||
| `-o <name>.stb` | 编译并写出映像文件；**缺省时只打印文件集合与工程哈希**（12.3 阶段行为） |
|
||||
| `--help` | 打印帮助 |
|
||||
|
||||
退出码：`0` 成功；`1` 编译失败（错误信息打到 stderr）。
|
||||
|
||||
## 示例（line1）
|
||||
|
||||
```bash
|
||||
$ STCompiler examples/line1/project.toml
|
||||
project: line1
|
||||
files:
|
||||
globals.st
|
||||
motor.st
|
||||
main.st
|
||||
hash: 0xc3fe4ae74ad45900
|
||||
|
||||
$ STCompiler examples/line1/project.toml -o line1.stb
|
||||
compiled: line1.stb (184 bytes, 2 functions, 4 globals)
|
||||
```
|
||||
|
||||
产物 `line1.stb`：魔数 `STSC` + 版本 1 的单一映像（指令见 `Doc/isa/指令与映像.md`）。
|
||||
|
||||
## 工程文件（project.toml）
|
||||
|
||||
只做三件事：**列出源文件、指定唯一 GVL、可选地把已声明全局接到硬件**。不声明变量。
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `project.name` | 是 | 工程名 |
|
||||
| `project.entry` | 是 | 第一版必须 `"program MAIN"` |
|
||||
| `project.cycle_limit` | 是 | 每周期指令上限（>0） |
|
||||
| `project.dt_ms` | 是 | 本周期 Δt 毫秒（>0），给 TON/TOF/CTU |
|
||||
| `files.st` | 是 | 源文件列表（非空数组） |
|
||||
| `gvl.file` | 否 | 唯一允许 `VAR_GLOBAL` 的文件；已在 `files.st` 则不重复收录 |
|
||||
| `[[io.input]]` / `[[io.output]]` | 否 | `var` + `channel` + `bit`；`var` 必须已在 GVL 声明 |
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "line1"
|
||||
entry = "program MAIN"
|
||||
cycle_limit = 100000
|
||||
dt_ms = 10
|
||||
|
||||
[files]
|
||||
st = ["globals.st", "motor.st", "main.st"]
|
||||
|
||||
[gvl]
|
||||
file = "globals.st"
|
||||
|
||||
[[io.input]]
|
||||
var = "EmergencyStop"
|
||||
channel = 0
|
||||
bit = 2
|
||||
```
|
||||
|
||||
## ST 子集（第一版）
|
||||
|
||||
**POU**：`PROGRAM` / `FUNCTION` / `FUNCTION_BLOCK`（含对应 `END_*`）。
|
||||
|
||||
**变量段**：`VAR` / `VAR_INPUT` / `VAR_OUTPUT` / `VAR_GLOBAL`（仅 `gvl.file` 顶层）/ `VAR_EXTERNAL`。
|
||||
|
||||
**类型**：`BOOL` / `INT` / `TIME`；内建 FB 类型 `TON` / `TOF` / `CTU`（关键字，不可作变量名）。
|
||||
|
||||
**语句**：赋值 `:=`、`IF / ELSIF / ELSE / END_IF`、`WHILE / END_WHILE`、FB 调用 `fb(in := ..., ...);`、字段读 `fb.Q`。
|
||||
|
||||
**表达式**：字面量（`TRUE`/`FALSE`、整数、`T#10ms` 式 TIME）、`NOT`、`AND`/`OR`（**短路**）、比较 `= <> < <= > >=`（不连锁）、算术 `+ - * /`、一元负号、函数调用 `Add(3, 4)`。
|
||||
|
||||
**函数**：结果 = 函数名赋值（`Add := a + b;`）；返回类型 `FUNCTION Add : INT`；调用约定：结果 r0、参数 r1..r7（最多 7 个输入，函数内只读）、变量与临时从 r8 起（见 `Doc/compiler/寄存器码.md`）。
|
||||
|
||||
**限制（v1 明确不做）**：指针 / `REF` / `CLASS` / `ANY` / `VAR_IN_OUT`（语法层直接拒绝）、链式比较、FB 字段赋值、`REAL`、字符串、用户类型套娃、隐式类型转换、函数循环调用（链接层拒绝）、`FUNCTION` 写全局（类型检查层拒绝，含经 `VAR_EXTERNAL`）。
|
||||
|
||||
## 编译管线与错误类别
|
||||
|
||||
```
|
||||
project.toml + .st
|
||||
→ 词法（lex error）→ 语法（syntax error）→ 链接（link error）
|
||||
→ 类型检查（type error）→ 寄存器码（codegen error）→ .stb
|
||||
```
|
||||
|
||||
错误消息前缀即阶段：`lex error` / `syntax error` / `link error` / `type error` / `codegen error`，均带文件与行列（`type error` 仅带文件）。
|
||||
|
||||
| 类别 | 示例 |
|
||||
|---|---|
|
||||
| `lex error` | 非法字符、未闭合注释、坏 `T#` 字面量 |
|
||||
| `syntax error` | 缺 `END_*`、`VAR_IN_OUT` 等保留名、链式比较 |
|
||||
| `link error` | 非 GVL 文件写 `VAR_GLOBAL`、同名全局、io.var 未在 GVL、未声明实例、循环调用 |
|
||||
| `type error` | `FUNCTION` 写全局、AND 吃 INT、赋值类型不匹配、FB 输入类型不匹配 |
|
||||
| `codegen error` | 寄存器溢出、写 io.input、写函数输入 |
|
||||
|
||||
## 样例与测试
|
||||
|
||||
- `examples/line1/`：最小闭环（MAIN + MotorStarter FB + I/O + 全局），给人看
|
||||
- `tests/cases/01~20/`：20 个用例（每份 `project.toml` + `.st` + `EXPECTED.md`），编译结果按表
|
||||
- `tests/`：CTest（`isa_roundtrip` / `compiler_toml` / `lexer_tokens` / `parser_syntax` / `linker_links` / `typecheck_types` / `codegen_slice1`）
|
||||
|
||||
## 当前状态
|
||||
|
||||
- ✅ 可编译：14 个正例用例全部产出 `.stb`；6 个负例按期望拒绝
|
||||
- ⏳ 执行：`BytecodeExecutor`（加载 `.stb` 跑扫描周期）在 12.9/12.10
|
||||
- ⏳ sidecar（`<name>.runtime.toml`，I/O 绑定）在 12.10 随执行器一起接线
|
||||
@@ -8,6 +8,7 @@ doc/
|
||||
初步计划.md
|
||||
isa/指令与映像.md
|
||||
compiler/编译管线.md
|
||||
compiler/STCompiler使用说明.md
|
||||
compiler/词法.md
|
||||
compiler/语法.md
|
||||
compiler/符号表与链接.md
|
||||
@@ -22,6 +23,7 @@ doc/
|
||||
| [`初步计划.md`](初步计划.md) | 全工程定案：子集 ST、toml、执行模型、第 12 节阶段 |
|
||||
| [`isa/指令与映像.md`](isa/指令与映像.md) | 指令、映像、定宽类型、饱和；**规范以此为准** |
|
||||
| [`compiler/编译管线.md`](compiler/编译管线.md) | 编译器边界与管线 |
|
||||
| [`compiler/STCompiler使用说明.md`](compiler/STCompiler使用说明.md) | 构建、用法、工程文件、ST 子集、错误类别 |
|
||||
| [`compiler/词法.md`](compiler/词法.md) | 12.4 词法：关键字表、token、大小写、TIME 字面量 |
|
||||
| [`compiler/语法.md`](compiler/语法.md) | 12.5 语法：AST 结构、文法、拒绝清单 |
|
||||
| [`compiler/符号表与链接.md`](compiler/符号表与链接.md) | 12.6 符号表与链接：数据区定址、FB 布局、错误类别 |
|
||||
|
||||
Reference in New Issue
Block a user