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