finalize lab1

Author: yuk1i

docs/assets/labs/w1-intro/antlr-codegen-make.png

@@ -20,15 +20,11 @@ Lab 课大致安排：
 
 参考 [环境配置](../env/index.md)
 
-## 什么是编译器
-
-TODO
-
 ## 什么是 ANTLR
 
 ChatGPT said:
 
-ANTLR（ANother Tool for Language Recognition）是一个功能强大的 语法解析器生成工具，常用于构建编译器、解释器、DSL（领域特定语言）、代码分析工具等。它的主要作用是将 **文法规则** 转换成可以在目标语言（如 Java、C#, Python, JavaScript 等）中运行的 **词法分析器（Lexer）** 和 **语法分析器（Parser）**。
+ANTLR（ANother Tool for Language Recognition）是一个功能强大的 **语法解析器生成工具**，常用于构建编译器、解释器、DSL（领域特定语言）、代码分析工具等。它的主要作用是将 **文法规则** 转换成可以在目标语言（如 Java、C#, Python, JavaScript 等）中运行的 **词法分析器（Lexer）** 和 **语法分析器（Parser）**。
 
 ### 什么是文法规则
 
@@ -58,127 +54,78 @@ ANTLR（ANother Tool for Language Recognition）是一个功能强大的 语法
 
 Project Zero is released!
 
+## ANTLR 配置
 
-以下删除。
-
-### 1. 先把 Java 装好
+首先，从 https://github.com/sqlab-sustech/CS323-Compilers-2025F-Projects/ clone 代码，并切换到 project0-fake1 分支：
 
-ANTLR 是用 Java 写的，运行时也需要 JVM，所以第一步就是装 Java。  
-- 如果你已经装过 JDK 8 或以上版本，在终端/命令行里敲  
-  ```
-  java -version
-  ```
-  能出现类似 `openjdk 17.0.x` 的字样，就跳过这一步。  
-- 如果提示找不到命令，先去 [Oracle 官网](https://www.oracle.com/cn/java/technologies/downloads/)下载对应系统的 JDK。安装完记得把 `JAVA_HOME` 配好，并把 `%JAVA_HOME%/bin`（Windows）或 `$JAVA_HOME/bin`（macOS/Linux）加到系统 PATH 里。  
-  Windows 用户可以在“系统属性 → 高级 → 环境变量”里弄；mac/Linux 在 `~/.bashrc` 或 `~/.zshrc` 里加个  
-  ```
-  export JAVA_HOME="你放置java的目录"
-  export PATH=$JAVA_HOME/bin:$PATH
-  ```
-  然后 `source ~/.zshrc`或者`source ~/.bashrc`让它生效。
-
----
+```shell
+$ git clone https://github.com/sqlab-sustech/CS323-Compilers-2025F-Projects/
+$ cd CS323-Compilers-2025F-Projects
+$ git checkout project0-fake1
+```
 
-### 2. 准备 IntelliJ IDEA 和 Maven
+随后，在 IDEA 中打开这个文件夹，你应该看到如下目录结构：
 
-IDEA 推荐用 **IntelliJ IDEA Community**（免费）或 **Ultimate**（学生免费）。去 [JetBrains 官网](https://www.jetbrains.com/idea/download) 下载安装即可。  
-Maven 可以选两条路：  
-- 懒人做法：什么都不用管，IDEA 自带 Maven 了。  
-- 手痒做法：去 [Maven 官网](https://maven.apache.org/download.cgi) 下载二进制包，解压后把 `bin` 目录加到 PATH，同样在终端里 `mvn -v` 能出信息即可。
+![alt text](../assets/labs/w1-intro/idea-dir.png)
 
----
+设置 Java SDK 版本为 21。
 
-### 3. 安装 ANTLR 插件
+### 使用 Makefile 编译 ANTLR 语法文件
 
-1. 打开 IDEA → 左上角 **File → Settings**（macOS 是 **IntelliJ IDEA → Preferences**）。  
-2. 左侧找到 **Plugins → Marketplace**，搜索框里敲 **ANTLR v4**。  
-![](../assets/antlr/plugin.png)
-3. 看到作者是 “ANTLR” 的那个，点 **Install**，装完后重启 IDEA。  
-4. 重启完，随便打开一个 `.g4` 文件，如果左侧项目树里文件名左边出现一只小“A”图标，就说明插件安装成功。
----
+我们之前说，ANTLR 是一套 **语法解析器生成工具**，它可以针对某个给定的语法文件，生成一些可以处理该语法的代码。
 
-### 4. 新建 Maven 项目并放好语法文件
+项目根目录中有一个 `Calc1.g4` 文件，它是一个 ANTLR 的语法文件，在项目根目录下执行 `make`，我们可以注意到在 `src/main/java` 下面多了 `generated.Calc1` 这个包，里面有若干 `.java` 文件。这些代码就是 ANTLR 工具针对 `Calc1.g4` 这个语法生成的代码。
 
-1. **File → New → Project → Maven**，直接 **Next**。   
-2. IDEA 会自动帮你生成 `src/main/java`、`src/main/resources` 等目录。（如果没有可以自己新建，在对应的目录下右击新建文件夹，应该会有提示）
-3. 在 `src/main` 上右键 → **New → Directory**，起名 `grammar`。  
-4. 把我们提供的 `Calculator.g4`拖进去。  
-   此时如果插件生效，`Calculator.g4` 左侧会出现一个红色小“A”图标。
+![alt text](../assets/labs/w1-intro/antlr-codegen-make.png)
 
----
+再执行 `make clean` 我们会发现 `generated/` 目录被删除了。
 
-### 5. 配置 ANTLR 代码生成路径
+### 安装 IDEA 的 ANTLR 插件
 
-1. 在 `Calculator.g4` 上右键 → **Configure ANTLR...**。  
-   弹出的窗口里填：  
-   - **Output directory...** 选到项目根目录下的 `src/main/java`（点右侧文件夹图标，一路点进去）。  
-   - **Package/namespace** 填 `antlr`。  
-   - **Language** 选 `Java`。  
-   其他保持默认 → **OK**。  
-   ![](../assets/antlr/menu2.png)
-2. 再右键 `Calculator.g4` → **Generate ANTLR Recognizer**。  
-   几秒后，你会看到 `src/main/java/antlr` 下面蹦出 `CalculatorLexer.java`、`CalculatorParser.java` 等文件。
+打开 Settings，找到 Plugin，在 Marketplace 里搜索 **ANTLR v4**，安装开发者为 "Terence Parr" 的那个插件。
 
----
+![alt text](../assets/labs/w1-intro/antlr-plugin.png)
 
-### 6. 引入 ANTLR 运行时依赖
+在 `Calc1.g4` 文件上点右键，在菜单栏中点 "Configure ANTLR"，打开配置框，并按照如下配置：
 
-这时候 `*.java` 文件会一片红，因为缺antlr运行时所需要的jar包。  
-打开项目根目录下的 `pom.xml`，把光标放在 `<dependencies>` 标签里（如果没有就自己建一个），粘贴：
+![alt text](../assets/labs/w1-intro/antlr-plugin-configure.png)
 
-```xml
-<dependency>
-    <groupId>org.antlr</groupId>
-    <artifactId>antlr4</artifactId>
-    <version>4.13.2</version>
-</dependency>
-```
+在 `Calc1.g4` 文件上点右键，在菜单栏中点 "Generate ANTLR Recognizer"，我们会注意到在 `src/main/java/generated/Calc1` 下面出现了同样的文件。
 
-保存后，IDEA 右上角会出现一个小 Maven 图标，点它或者按 **Ctrl+Shift+O**（mac 是 ⌘+⇧+O）刷新。  
-等进度条跑完，红色波浪线会全部消失。
-![](../assets/antlr/reload.png)
----
+### 调用 ANTLR
 
-### 7. 写个 Main 类跑起来
-
-1. 在 `src/main/java` 上右键 → **New → Java Class**，起名 `Main`。  
-2. 把下面代码粘进去：
+将 `Main.java` 覆盖为如下内容，如果遇到了依赖问题，使用 Maven 解决依赖问题。
 
 ```java
-package com.example.antlr_demo;
-
-import antlr.CalculatorLexer;
-import antlr.CalculatorParser;
+import generated.Calc1.Calc1Lexer;
+import generated.Calc1.Calc1Parser;
 import org.antlr.v4.runtime.*;
+import org.antlr.v4.runtime.tree.*;
 
 public class Main {
     public static void main(String[] args) {
         // 把要解析的字符串喂给 ANTLR
         CharStream input = CharStreams.fromString("1 + 2");
         // 词法分析器
-        CalculatorLexer lexer = new CalculatorLexer(input);
+        Calc1Lexer lexer = new Calc1Lexer(input);
         // Token 流
         CommonTokenStream tokens = new CommonTokenStream(lexer);
         // 语法分析器
-        CalculatorParser parser = new CalculatorParser(tokens);
+        Calc1Parser parser = new Calc1Parser(tokens);
         // 从规则 'expression' 开始解析
-        ParseTree tree = parser.expression();
+        ParseTree tree = parser.expr();
         // 把树打印出来看看
         System.out.println(tree.toStringTree(parser));
     }
 }
 ```
 
-3. 右键 `Main.java` → **Run 'Main.main()'**。  
-   控制台会输出：
+然后，运行该 Main 类，Console 会输出：
 
 ```
 (expression (term 1) + (term 2))
 ```
 
-这就表示 ANTLR 成功把 `1 + 2` 拆成了一棵语法树。  
-暂时看不懂树长什么样没关系，后面我们会慢慢讲到它背后的含义。
+这就表示 ANTLR 成功把 `1 + 2` 拆成了一棵语法树。
 
----
-
-跟着做完这几步，你就拥有了能跑起来的 ANTLR 环境。接下来我们就可以开始写真正的语法规则了。
+暂时看不懂树长什么样没关系，后面我们会慢慢讲到它背后的含义。