# Lab1 运行说明

## 1. 环境要求

建议环境中具备以下工具：

- `java`
- `cmake`
- `g++` / `clang++`
- `make` 或 `ninja`

可先检查：

```bash
java -version
cmake --version
g++ --version
```

## 2. 手动生成 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
```

## 3. 手动配置与编译

在仓库根目录执行：

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j "$(nproc)"
```

编译成功后，可执行文件位于：

```bash
./build/bin/compiler
```

## 4. 单个样例运行

### 4.1 仅输出语法树

```bash
./build/bin/compiler --emit-parse-tree test/test_case/functional/simple_add.sy
```

### 4.2 验证最小 IR 仍可工作

```bash
./build/bin/compiler --emit-ir test/test_case/functional/simple_add.sy
```

## 5. 批量测试

我提供了一个批量测试脚本：

```bash
./solution/run_lab1_batch.sh
```

该脚本默认使用 **parse-only 构建模式**：

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCOMPILER_PARSE_ONLY=ON
```

这样即使 `sem` / `irgen` / `mir` 还没有完成，Lab1 的语法树验证也不会被后续实验模块阻塞。

如果希望在批量测试时把每个样例的语法树保存到 `test_tree/` 目录，可以加可选项：

```bash
./solution/run_lab1_batch.sh --save-tree
```

该脚本会自动完成：

1. 重新生成 `build/generated/antlr4` 下的 ANTLR 文件
2. 执行 `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCOMPILER_PARSE_ONLY=ON`
3. 执行 `cmake --build build -j "$(nproc)"`
4. 批量测试 `test/test_case/functional/*.sy`
5. 批量测试 `test/test_case/performance/*.sy`
6. 批量测试 `test/test_case/negative/*.sy`，确认非法输入会触发 `parse` 报错

若使用 `--save-tree`，还会额外：

7. 在仓库根目录下创建 `test_tree/`
8. 将语法树按测试集目录结构保存，例如：

```bash
test_tree/functional/simple_add.tree
test_tree/performance/fft0.tree
```

脚本结束时会输出：

- 正例总数 / 通过数 / 失败数
- 反例总数 / 通过数 / 失败数
- 总覆盖样例数与整体通过情况
- 失败样例列表

若某个用例失败，脚本会打印失败用例名并返回非零退出码。

## 6. 反例测试说明

新增了负例目录：

```bash
test/test_case/negative
```

当前提供了 3 个非法样例：

- `missing_semicolon.sy`
- `missing_rparen.sy`
- `unexpected_else.sy`

这些样例用于验证：

- 合法输入能够成功输出语法树
- 非法输入能够触发 `parse` 报错
- 报错信息带有位置，便于定位问题

## 7. 常用附加命令

### 7.1 查看帮助

```bash
./build/bin/compiler --help
```

### 7.2 指定单个样例文件

```bash
./build/bin/compiler --emit-parse-tree <your_case.sy>
```

### 7.3 重新从零开始构建

```bash
rm -rf build
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
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j "$(nproc)"
```

## 8. 结果判定

Lab1 主要检查点是：

- 合法 SysY 程序可以被 `SysY.g4` 成功解析
- `--emit-parse-tree` 能输出语法树
- `test/test_case` 下正例可以批量通过语法树模式
- `test/test_case/negative` 下反例会稳定触发 `parse` 报错

本项目当前实现中，Lab1 的重点是“语法分析与语法树构建”，不是完整语义分析和完整 IR/汇编支持。