docs(doc): 补充 lab1 ANTLR 生成与构建说明

doc/lab1-handout.md

@@ -0,0 +1,86 @@
+# Lab1 Handout：ANTLR 接入与构建指令
+
+本文档说明如何在本工程中使用 ANTLR（C++ 目标）生成解析器代码，并完成编译构建。
+
+## 1. 目录约定（与 doc/目录结构设计.md 一致）
+
+- 文法文件（提交到仓库）：
+  - `src/antlr4/SysY.g4`
+- ANTLR 自动生成文件（不提交到仓库）：
+  - 统一输出到构建目录：`<build_dir>/generated/antlr4/`
+  - 典型文件：`SysYLexer.*`、`SysYParser.*`、`SysYBaseVisitor.*`、`SysYVisitor.*`、`*.tokens`、`*.interp`
+- ANTLR4 C++ runtime（提交到仓库）：
+  - `third_party/antlr4-runtime-4.13.2/`
+  - 工程通过 CMake 直接构建并链接该 runtime（无需系统安装 antlr4-runtime）
+
+## 2. 生成代码（启用 -visitor）
+
+说明：
+- 本实验不提供脚本，请手动执行以下命令。
+- 生成时启用 `-visitor`，并关闭 listener（`-no-listener`）。
+
+### 2.1 前置依赖
+
+- Java（用于运行 `antlr-*.jar`）
+- ANTLR4 完整 jar（本仓库已内置 4.13.2）
+
+本仓库内置 jar 路径：
+- `third_party/antlr-4.13.2-complete.jar`
+
+### 2.2 生成命令
+
+假设构建目录为 `build/`（可自行替换为 `build-debug/`、`out/` 等）：
+
+```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
+```
+
+生成完成后，请确认目录 `build/generated/antlr4/` 中出现：
+- `SysYLexer.cpp/.h`
+- `SysYParser.cpp/.h`
+- `SysYBaseVisitor.cpp/.h`、`SysYVisitor.cpp/.h`
+
+## 3. 编译构建（CMake）
+
+本工程默认使用：
+- `third_party/antlr4-runtime-4.13.2` 提供的 C++ runtime（无需额外安装）
+- `build/generated/antlr4/*.cpp` 作为前端解析器实现的编译输入（需要先完成第 2 节的生成）
+
+### 3.1 配置
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+```
+
+### 3.2 构建
+
+```bash
+cmake --build build -j "$(nproc)"
+```
+
+成功后应当生成：
+- 可执行文件目标：`compiler`
+
+## 4. 常见问题
+
+### 4.1 找不到 SysYParser.h / SysYLexer.h
+
+原因：没有先生成，或生成目录不匹配。
+
+排查：
+- 确认 `build/generated/antlr4/` 下存在生成的 `.h/.cpp`
+- 如果你使用的是非 `build/` 的构建目录（例如 `out/`），则生成输出也要改为 `out/generated/antlr4/`
+
+### 4.2 修改 SysY.g4 后编译行为未变化
+
+原因：生成文件未更新。
+
+解决：
+- 每次修改 `src/antlr4/SysY.g4` 后都要重新执行第 2 节生成命令。