just keep up, idk how to use git

arcsysu · Feb 28, 2024 · 6f8fd77 · 6f8fd77
2 parents 15fc4bc + 34cefef
commit 6f8fd77
Show file tree

Hide file tree

Showing 8 changed files with 147 additions and 38 deletions.
diff --git a/docs/QA.md b/docs/QA.md
@@ -0,0 +1,2 @@
+# 常见问题与答案
+我们编译原理助教众多，希望同学们踊跃提问。同时我们会挑选一些比较有代表性或者提问次数较多的问题放到这里供同学们查阅。
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,13 +2,14 @@
 * 前言
   * [环境配置](introduction/environment.md)
   * [实验框架使用方法](introduction/howtouse.md) 
-  * [帮助我们改进文档](introduction/helptoimprove.md)
+  * [帮助我们改进实验](introduction/helptoimprove.md)
 * Task0
   * [实验内容](task0_doc/task0.md) 
 * Task1
   * [实验介绍](task1_doc/overview.md) 
   * [使用 flex 完成 Task1](task1_doc/flex.md)
   * [使用 antlr 完成 Task1](task1_doc/antlr.md)
+  * [API 速查](task1_doc/apidoc.md)
 * Task2
   * [实验介绍](task2_doc/overview.md) 
   * [公用代码介绍](task2_doc/share.md) 
@@ -18,3 +19,6 @@
   * [待续](README.md)
 * Task4
   * [待续](README.md)
+* Q&A
+  * [常见问题与答案](QA.md)
+
diff --git a/docs/images/debugtest11.jpg b/docs/images/debugtest11.jpg
diff --git a/docs/images/debugtest22.jpg b/docs/images/debugtest22.jpg
diff --git a/docs/introduction/environment.md b/docs/introduction/environment.md
@@ -4,30 +4,32 @@
 
 
 ## 软件安装
-由于大部分同学都是使用 `Windows` 电脑进行开发，所以这里采用windows11系统进行演示。首先需要同学们下载并安装以下三种软件。由于 `Windows` 系统下 `docker` 的正常使用需要 `wsl` 环境，所以请同学们在安装 `docker` 之前先安装 `wsl`。(对于 `linux` 系统和  `mac` 系统的同学而言，只需要跳过 `wsl` 的安装即可)。
+由于大部分同学都是使用 `Windows` 电脑进行开发，所以这里采用windows11系统进行演示。首先需要同学们下载并安装以下三种软件。由于 `Windows` 系统下 `docker` 的正常使用需要 `WSL` 环境，所以请同学们在安装 `docker` 之前先安装 `WSL`。(对于 `linux` 系统和  `mac` 系统的同学而言，只需要跳过 `WSL` 的安装即可)。
 
 需要安装的软件如下：
 
-- wsl
+- WSL2
 - docker
+- git
 - vscode
 
-首先是WSL，WSL是Windows Subsystem for Linux的简称，它是微软在Windows操作系统上提供的一个功能，允许用户在Windows环境下运行Linux应用程序和命令行工具。简单来说，它让你可以在Windows系统中享受到Linux的强大功能。首先同学们需要打开 `控制面板-程序-启动或关闭 Windows 功能`，开启`容器`、`适用于 Linux 的 Windows 子系统`、`虚拟机平台`三个功能。
+首先是WSL，WSL是Windows Subsystem for Linux的简称，它是微软在Windows操作系统上提供的一个功能，允许用户在Windows环境下运行Linux应用程序和命令行工具。简单来说，它让你可以在Windows系统中享受到Linux的强大功能。首先同学们需要打开 `控制面板-程序-启动或关闭 Windows 功能`，开启`容器`（Windows11特有）、`适用于 Linux 的 Windows 子系统`、`虚拟机平台`三个功能。
 ![Windows系统功能开启](../images/systemconfigure.png)
 
 
-同学们需要打开自己的终端命令行，在其中输入以下代码，等待其安装即可。
+同学们需要打开自己的终端命令行，在其中输入以下代码，等待其安装即可。已安装 WSL 的同学请检查安装的 WSL 版本是否为2，使用 WSL1 的同学需自行将版本升级，或创建一个新的 WSL2 系统。
 ```shell
-wsl -l -v                       # 列举所有可安装的 Linux 系统
+wsl -l -v                       # 列举所有已安装的 Linux 系统
 wsl --set-default-version 2     # 设置 WSL 默认版本号为2
 wsl -d Ubuntu --install         # 安装 Ubuntu 系统
 ```
 ![WSL安装示意](../images/wsl1.png)
 
-然后是 docker 的安装，Docker 可以将代码、运行所需的运行时、系统工具和库进行打包。这可以使得同学进行实验代码开发的环境和我们助教开发实验时一模一样，减少了同学们环境配置的繁琐操作。
-同学们直接在[官方网站](https://www.docker.com/products/docker-desktop/)下载，并进行图形界面的安装即可.
+然后是 docker 的安装（注意 Windows 系统上 docker 安装的前置条件是 WSL2 已经安装好），Docker 可以将代码、运行所需的运行时、系统工具和库进行打包。这可以使得同学进行实验代码开发的环境和我们助教开发实验时一模一样，减少了同学们环境配置的繁琐操作。同学们直接在[官方网站](https://www.docker.com/products/docker-desktop/)下载，并进行图形界面的安装即可。
 
-最后是vscode的安装，vscode是一款可以安装多种强大插件的开源代码编辑器，如果同学们选择vscode作为本次实验的代码编辑器，助教提前设计好的工作流将大幅提升你的开发效率。如果同学们选择其他代码编辑器将不能享受到这样的福利。vscode直接在[官方网站](https://code.visualstudio.com/)下载，并进行图形界面的安装即可.
+其次是 git 的安装，git 是一个开源的分布式版本控制系统，用于有效地处理从小到大的项目版本管理。同学们直接在[官方网站](https://git-scm.com/downloads)下载，并进行图形界面的安装即可。
+
+最后是 vscode 的安装，vscode 是一款可以安装多种强大插件的开源代码编辑器，如果同学们选择 vscode 作为本次实验的代码编辑器，助教提前设计好的工作流将大幅提升你的开发效率。如果同学们选择其他代码编辑器将不能享受到这样的福利，需要自行探索相关功能。vscode 直接在[官方网站](https://code.visualstudio.com/)下载，并进行图形界面的安装即可。
 
 ## (可选方案 1)dev containers 自动配置
 同学们打开vscode之后需要点击下图红色三角形所示的按钮，进入到插件管理界面进行dev containers插件的安装。
@@ -101,16 +103,16 @@ systemctl start docker   #启动 docker 服务
 
 ### 注意事项
 
-1. 在配置Dev Container环境时，请勿在Windows/Mac Terminal环境下直接克隆仓库或使用网站下载仓库代码，并在 vscode 中选择`Dev Containers: Reopen in Container`选项进行搭建。这种做法会导致Dev Container和代码文件处于不同的操作系统中，在执行命令时产生巨大的性能开销。搭建Dev Container环境时建议使用如上文所述的`Dev Containers: Clone Repository in Container Volume`选项，让 vscode 帮助我们自动下载仓库代码并安装容器。
-2. 在搭建Dev Container时若出现网络问题，请检查本机（包括WSL2）代理是否开启以及git代理是否配置，并尝试在打开/关闭代理后重新搭建。
+1. 在配置 dev container 环境时，请勿在Windows/Mac Terminal环境下直接克隆仓库或使用网站下载仓库代码，并在 vscode 中选择`Dev Containers: Reopen in Container`选项进行搭建。这种做法会导致 dev container 和代码文件处于不同的操作系统中，在执行命令时产生巨大的性能开销。搭建 dev container 环境时建议使用如上文所述的`Dev Containers: Clone Repository in Container Volume`选项，让 vscode 帮助我们自动下载仓库代码并安装容器。
+2. 在搭建 dev container时若出现网络问题，请检查本机（包括WSL2）代理是否开启以及git代理是否配置，并尝试在打开/关闭代理后重新搭建。
 
 <!-- ![showlog](../images/envok.png) -->
 ## (可选方案 2)命令行手动配置（使用docker）
 首先请同学们启动 vscode 软件，点击下图所示的按钮新建一个命令行窗口。
 
 ![新建命令行窗口](../images/openterminal.png)
 
-如果同学们使用的是 windows 系统，在这里需要输入以下命令进入 wsl，如果使用的是 mac 系统或者是 Linux 系统可以直接进行后续步骤。
+如果同学们使用的是 Windows 系统，在这里需要输入以下命令进入 WSL，如果使用的是 Mac 系统或者是 Linux 系统可以直接进行后续步骤。
 
 ```bash
 wsl
@@ -145,23 +147,36 @@ systemctl start docker   #启动 docker 服务
 ![确认 docker 服务成功启动](../images/checkdocker.jpg)
 你也可以通过docker desktop来确认docker服务的启动状态
 ![确认 docker 服务成功启动(gui)](../images/dockergui.png)
-如果确认 docker 已经是运行状态则可以进行下一步操作。在命令行窗口输入以下命令进行ubuntu 镜像的拉取。
-```
+如果确认 docker 已经是运行状态则可以进行下一步操作。在命令行窗口输入以下命令进行 ubuntu 镜像的拉取。
+```bash
 docker pull ubuntu:22.04
 ```
-出现以下输出字样则代表镜像拉取已经完成，
+出现以下输出字样则代表镜像拉取已经完成：
 
 ![镜像拉取完成](../images/ubuntuimage.jpg)
 
 我们需要将拉取下来的 ubuntu 镜像实例化为一个容器，并在容器内进行实验环境的配置。但是在将镜像实例化为容器之前，
 在我此时的例子中，我的代码文件所在文件夹为`/Users/nickchen/SYsU-lang2`。有了这个文件路径之后就可以开始将前面拉取的镜像实例化为一个容器了。请大家在命令行输入如下命令  
 注意⚠️：将里面的`/Users/nickchen/SYsU-lang2`改为你先前设置的仓库的路径（即上文`pwd`命令得到的路径）
 ```bash
-docker run -it --name labdemo -v /Users/nickchen/SYsU-lang2:/workspace   ubuntu:22.04
+git clone https://mirror.ghproxy.com/https://github.com/arcsysu/SYsU-lang2
+```
+![仓库拉取示意](../images/gitrepclone.jpg)
+
+请同学们输入以下代码进入实验代码文件夹，并且进行实验代码文件夹路径的输出查看。
+```bash
+cd SYsU-lang  #进入文件夹
+pwd           #查看当前路径
+```
+![仓库拉取示意](../images/getloc.jpg)
+
+在我此时的例子中，我的代码文件所在文件夹为`/home/zwshan/SYsU-lang`。有了这个文件路径之后就可以开始将前面拉取的镜像实例化为一个容器了。请大家在命令行输入如下命令，
+```bash
+docker run -it --name labdemo -v /home/zwshan/SYsU-lang:/workspace   ubuntu:22.04
 # docker run是运行 Docker 容器的命令
 # -it 是两个选项的结合。-i 表示交互式操作，允许用户与容器进行交互，-t 表示分配一个伪终端（pseudo-TTY）。这使得用户可以在容器内执行命令，并且能够与命令行进行交互。
 # --name labdemo表示将运行的容器命名为 labdemo
-# -v /Users/nickchen/SYsU-lang2:/workspace 代表将宿主机的 /Users/nickchen/SYsU-lang2 路径映射到 docker 容器内的 /workspace 路径
+# -v /your/path/to/SYsU-lang2:/workspace 代表将宿主机的 /your/path/to/SYsU-lang2 路径映射到 docker 容器内的 /workspace 路径
 ```
 当同学们在命令行看到`root@xx`等字样时意味着成功将镜像实例化为了容器，此时输入`cd workspace`即可成功进入实验代码文件夹。
 
@@ -183,8 +198,8 @@ apt-get install -y ninja-build clang-14 wget cmake xz-utils g++ lld flex bison #
 | unzip | 正如其名 |
 | g++  | 实验必需的编译器 |
 | lld  | 实验必需的链接器 |
-| flex    | 你将很快接触到它 |
-| bison   | 你将没那么快但也很快接触到它 |
+| flex    | 词法分析器构造工具 |
+| bison   | 文法分析器构造工具 |
 
 
 在上述软件成功安装之后，请大家输入以下命令进行另外两个特殊软件的安装,两种软件在对应文件夹下都有助教提前写好的自动化编译安装脚本。  
@@ -194,17 +209,19 @@ apt-get install -y ninja-build clang-14 wget cmake xz-utils g++ lld flex bison #
 ```bash
 cd /workspace/llvm && bash install.sh
 ```
-成功编译安装后的界面如下图所示(就是无事发生)
+成功安装后的界面如下图所示（就是无事发生）  
+
 ![alt text](../images/llvm_success.png)
 
-接下来是antlr 软件的安装，请大家在命令行输入如下命令。
+
+接下来是 antlr 软件的安装，请大家在命令行输入如下命令。
 ```bash
 cd /workspace/antlr && bash install.sh
 ```
 成功编译安装后的界面如下图所示(也就是无事发生)
 ![alt text](../images/antlr_success.png)
 
-<!-- ![antlr成功安装图片（图片待施工，开发机网络崩溃）](../images/) -->
+
 注意⚠️：因为编译是计算密集型任务，此步骤耗时可能较长，如果你不能成功编译，你可以尝试以下的方法：
 1. 重新编译  
 ```bash

diff --git a/docs/introduction/howtouse.md b/docs/introduction/howtouse.md
@@ -7,8 +7,6 @@
 在上一小节环境构造时，不管同学们采用的是 `dev containers` 自动构建的方法还是手动构建的方法，打开项目的方式都是一样的。同学们首先需要点击下图中左侧箭头所示的像一台电脑一样的按钮 `remote explorer`（一个 vscode 插件，需手动安装） ，然后点击`REMOTE EXPLORER`**后**的选择框，按下向下的类三角形按钮，选择红色箭头所示的`Dev Containers`选项，之后同学们便会在下图所示的界面，将鼠标放到 `SYsU-lang2`（如果是手动配置的环境，容器名称可能不同）的位置，点击鼠标右键，再点击`Open Container in xx Window`，即可成功打开我们的实验项目环境。
 
 
-
-
 ![showlog](../images/howtoreopendev.jpg)
 
 
@@ -62,15 +60,23 @@ set(TASK4_REVIVE OFF)
 
 
 ## 如何调试代码
-前面提到了同学们可以通过肉眼比对自己的输出和标准输出来进行debug，但也可能会存在肉眼比对找不到bug的情况。由于助教在设计实验的过程中已经把调试配置文件编写完成，所以同学们可以直接进行图形界面的调试。
+在这里首先介绍如何通过肉眼比对的方式来进行 debug，在上一小节中我们介绍了如何获得当前正在做的实验的标准答案，通过对比某个测试样例下标准答案和自己的输出的 debug 方式就是肉眼比对 debug 。以`000_main.sysu.c`这个测试样例为例子，同学们可以在
+`/workspaces/SYsU-lang2/build/test/task1/functional-0/`找到`000_main.sysu.c`这个文件夹，查看文件夹中的内容可以发现存在以下三个文件夹，通过查看以下三个文件夹中的内容即可进行 debug 。
+```
+|-- answer.txt
+|-- output.txt
+`-- score.txt
+```
+
+在某些情况下可能会存在肉眼 debug 无法找到错误的情况，由于助教在设计实验的过程中已经把调试配置文件编写完成，所以同学们可以直接进行图形界面的调试。
 我以实验一的flex版本实现为例进行介绍。首先我在`main.cpp`如图所示位置打了断点。
 
 ![showlog](../images/maindebug.png)
 
-然后在`PROJECT STATUS`处将`DEBUG`配置为`task1`
+然后在`PROJECT STATUS`处将`Debug`和`Build`配置为`task1`
 
-![showlog](../images/debugtest1.png)
+![showlog](../images/debugtest11.jpg)
 
-然后点击左侧插件菜单栏中的量杯按钮`TESTING`。这里假设我实验一的第一个测试样例就没能正常通过，点击如下图所示的debug按钮即可进入调试的图形界面。
+然后点击左侧插件菜单栏中的量杯按钮`TESTING`。在对应测试样例的后面点击如下图所示的debug按钮即可进入调试的图形界面。
 
-![showlog](../images/debuganniu.png)
+![showlog](../images/debugtest22.jpg)
diff --git a/docs/task1_doc/antlr.md b/docs/task1_doc/antlr.md
@@ -99,13 +99,5 @@ for (auto&& token : tokens.getTokens())
     }
 ```
 
-接下来的这段代码对`Loc`信息进行提取，这里已经实现了简单的`token`行号以及列号的提取。但是还需要同学们进行进阶的实现，以便正确提取出`token`所在的文件名。
-
-```c++
-    std::string locInfo = " Loc=<" + std::to_string(token->getLine()) + ":" +
-                          std::to_string(token->getCharPositionInLine() + 1) +
-                          ">";
-```
-
-`for`循环中剩下的代码用于判断是否输出`[StartOfLine]`和`[LeadingSpace]`以及输出最终结果，这些代码不用同学们进行修改，所以不做更多的介绍。
+`for`循环中剩下的代码用于判断是否输出`[StartOfLine]`和`[LeadingSpace]`以及输出最终结果，这些代码不用同学们进行修改，所以不做更多的介绍。但对`Loc`信息进行提取，包括简单的`token`行号以及列号，`token`所在的文件名的提取需要同学们自己实现。
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# 常见问题与答案
		我们编译原理助教众多，希望同学们踊跃提问。同时我们会挑选一些比较有代表性或者提问次数较多的问题放到这里供同学们查阅。