|
|
# 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 节生成命令。
|
