From 29bf99727f610ed6a66b64ad088ffc2171e57c18 Mon Sep 17 00:00:00 2001
From: jing <3030349106@qq.com>
Date: Sun, 1 Mar 2026 00:10:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(doc):=20=E5=AE=8C=E5=96=84Lab1=E5=AE=9E?=
 =?UTF-8?q?=E9=AA=8C=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...ab1-ANTLR词法语法分析实验说明.md | 117 ++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 doc/Lab1-ANTLR词法语法分析实验说明.md

diff --git a/doc/Lab1-ANTLR词法语法分析实验说明.md b/doc/Lab1-ANTLR词法语法分析实验说明.md
new file mode 100644
index 0000000..a4cd9af
--- /dev/null
+++ b/doc/Lab1-ANTLR词法语法分析实验说明.md
@@ -0,0 +1,117 @@
+# Lab1：用 ANTLR 实现 SysY 词法/语法分析器
+
+## 1. 本实验定位
+
+本仓库是一个“最小可运行编译器框架”，当前仅实现 SysY 的极小子集（示例级功能，主要用于演示完整构建流程）。  
+课程目标不是停留在这个最小子集，而是让同学们在该框架上逐步补全完整 SysY，并最终完成完整编译器（前端、中端、后端）。
+
+## 2. Lab1 要求
+
+Lab1 聚焦前端第一步：词法/语法分析。
+需要同学完成：
+
+1. 依据 SysY 规范扩展文法 `src/antlr4/SysY.g4`。
+2. 通过构建流程让 ANTLR 重新生成 Lexer/Parser。
+3. 让更多合法 SysY 程序可以被解析通过（不再仅限当前最小样例）。
+
+## 3. Lab1 需要补充的内容
+
+1. 必须修改的文件
+   - `src/antlr4/SysY.g4`：补全文法规则。
+   - `src/frontend/AstBuilder.cpp`：同步扩展 parse tree 到 AST 的构建逻辑。
+   - `src/ast/AstNodes.h`、`src/ast/AstNodes.cpp`：按新增语法补充或调整 AST 节点定义。
+
+2. 建议同步修改的文件
+   - `src/ast/AstPrinter.cpp`：为新增节点补充文本 AST 输出（`--ast-dot` 仅调试辅助，不是必做要求）。
+
+
+
+## 4. 当前示例实现说明
+
+当前仓库仅实现最小子集：
+
+1. 主要覆盖 `int main() { ... }` 这一固定函数形态。
+2. 只包含少量声明/返回/表达式能力（用于演示完整流程）。
+3. 示例用例位于 `test/test_case/simple_add.sy`。
+
+## 5. 构建与生成流程
+
+典型构建命令：
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j "$(nproc)"
+```
+
+ANTLR 生成文件统一位于：
+
+- `build/generated/antlr4/`
+
+如需手动触发 ANTLR 生成：
+
+```bash
+mkdir -p build/generated/antlr4
+java -jar third_party/antlr-4.13.2-complete.jar \
+  -Dlanguage=Cpp \
+  -visitor -no-listener \
+  -Xexact-output-dir \
+  -o build/generated/antlr4 \
+  src/antlr4/SysY.g4
+```
+
+## 6. Lab1 测试建议
+
+
+按提供的测试输入回归验证：
+
+1. 运行 `./build/bin/compiler <case.sy>` 检查解析是否成功。
+2. 出现报错时优先回查 `SysY.g4` 与对应 AST 构建逻辑。
+
+可选输出控制命令：
+
+```bash
+# 仅输出 AST 文本
+./build/bin/compiler --emit-ast test/test_case/simple_add.sy
+
+# 仅输出 IR
+./build/bin/compiler --emit-ir test/test_case/simple_add.sy
+
+# 同时输出 AST 与 IR（默认行为）
+./build/bin/compiler --emit-ast --emit-ir test/test_case/simple_add.sy
+```
+
+## 7. AST 输出相关说明（辅助）
+
+AST 输出是调试手段，可以根据 AST 结果检查语法/词法实现逻辑问题。  
+**此功能完善与否不会影响整个流程的功能，可以选择性的实现**。
+
+当前仓库中的 AST 文本输出与 `AST -> dot` 导出仅覆盖“已实现的最小语法子集”，并非完整 SysY 通用版本。 后续每新增语法/节点类型时，需要在 `src/ast/AstPrinter.cpp` 中同步补充文本输出与 dot 导出逻辑。
+
+1. 基础文本 AST 输出（默认）
+
+```bash
+./build/bin/compiler test/test_case/simple_add.sy
+```
+
+2. 图形化 AST 输出（可选）
+
+依赖安装（Ubuntu/WSL）：
+
+```bash
+sudo apt update
+sudo apt install -y graphviz
+```
+
+生成 DOT 与 PNG：
+
+```bash
+mkdir -p test/test_result/ast
+./build/bin/compiler --emit-ast --ast-dot test/test_result/ast/simple_add.ast.dot test/test_case/simple_add.sy
+dot -Tpng test/test_result/ast/simple_add.ast.dot -o test/test_result/ast/simple_add.ast.png
+```
+
+WSL 查看图片：
+
+```bash
+explorer.exe "$(wslpath -w test/test_result/ast/simple_add.ast.png)"
+```