diff --git a/doc/lab1-handout.md b/doc/lab1-handout.md new file mode 100644 index 0000000..69a1531 --- /dev/null +++ b/doc/lab1-handout.md @@ -0,0 +1,86 @@ +# Lab1 Handout:ANTLR 接入与构建指令 + +本文档说明如何在本工程中使用 ANTLR(C++ 目标)生成解析器代码,并完成编译构建。 + +## 1. 目录约定(与 doc/目录结构设计.md 一致) + +- 文法文件(提交到仓库): + - `src/antlr4/SysY.g4` +- ANTLR 自动生成文件(不提交到仓库): + - 统一输出到构建目录:`/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 节生成命令。