开发环境配置¶
我们教学使用的参考环境为 GNU/Linux ，发行版为 Debian 13 trixie。
如果你使用的是 GNU/Linux，不管是哪种发行版，我们相信你有足够的能力自己配好环境。
对于 Windows / macOS (arm64, Apple Silicon) 用户，我们推荐你使用 VMware 配置虚拟机，配合 VSCode / IDEA IntelliJ 的 SSH 远程开发。
此外，我们还提供了以下方案，这些方案不需要安装虚拟机，更加轻量级。但是，我们并不为这些情况提供排错与技术支持。
- 使用 Windows WSL
- 使用 macOS 的原生环境
配置开发环境¶
使用 VMware 虚拟机¶
我们推荐使用 VMware 作为虚拟机软件，VMWare 的安装文件已经放在 https://dl.cra.moe/CS323-Compilers-2025Fall/ 下面。
Note
VMware Workstation (for Windows) 和 VMware Fusion (for macOS) 均已向个人用户免费授权，无需再使用所谓的破解版。
在安装完 VMware 后，你有两个选择：
-
你可以导入我们已经配置好的虚拟环境。
Windows 用户请下载 OVF 文件，解压后将 .ovf 文件拖至 VMware 中即可。
macOS 用户请选择包含 arm64 的压缩包，解压后将 .vmwarevm 拖入 VMware 的虚拟机列表中。你可以参照 https://yuk1i.github.io/os-next-docs/env/vm/macos/ 中的图片过程。
Note
预配置的 VMware 镜像中，root密码为 123456，普通用户 cs323 的密码为 123456。
-
你可以选择从零安装 Linux 虚拟机，请安装 Debian 13（安装镜像可从南科大镜像站上下载 https://mirrors.sustech.edu.cn/）。并安装以下软件包：
如果控制台显示 llvm-19 和 clang-19 找不到的错误，可以尝试以下命令：
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo add-apt-repository "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-19 main"
sudo apt update
sudo apt install clang-19 llvm-19
Windows WSL2 配置¶
macOS 原生开发环境配置¶
参考 macOS 原生配置
配置开发工具¶
我们建议大家提前配置好 VS Code / IntelliJ IDEA 的 SSH 远程开发环境，或者使用 WSL 进行开发。
本节提供两种 VS Code 配置方式：
- 远程开发（推荐）：使用 VS Code Remote SSH 连接课程虚拟机，适合使用 VMware 的同学。
- 前期本地开发（临时方案）：如果暂时无法安装或启动虚拟机，可以先直接在 Windows 或 macOS 本机完成前期实验。
前期实验只需要 Git、JDK 21 和 Make，不需要先配好完整的编译器开发环境。后续实验需要 LLVM 等工具时，仍建议迁移到课程虚拟机。
使用 VS Code 远程开发¶
下面以 VS Code + Remote SSH 为例，带大家完成远程开发环境配置。
给 VS Code 安装 SSH 插件¶
按照上图完成插件安装：
- 点击左侧边栏的 Extensions（扩展） 按钮。
- 在搜索栏中输入
ssh。 - 找到微软官方的 Remote - SSH 插件。
- 点击 Install 进行安装。
- 安装完成后，左侧边栏中应该会出现图中 5 所示的远程连接图标。
没有看到 Remote SSH 图标？
如果安装完成后左侧边栏没有出现对应图标，可以尝试关闭 VS Code 后重新打开。
获取虚拟机 IP 地址¶
在配置 VS Code 之前，我们首先需要获取虚拟机的 IP 地址。
重新进入虚拟机，并使用默认账户登录：
| 项目 | 内容 |
|---|---|
| 用户名 | cs323 |
| 密码 | 123456 |
进入虚拟机桌面后，按照下图所示的方法打开终端：
在终端中输入：
命令执行后，会输出当前虚拟机的 IP 地址，例如： 这个地址就是后面配置 VS Code 时需要使用的虚拟机 IP 地址。
请记录你自己的 IP 地址
每个人虚拟机的 IP 地址可能不同。
后续配置中的 HostName 必须填写你自己通过 hostname -I 查询到的 IP 地址，不要直接复制教程中的示例地址。
配置 VS Code Remote SSH¶
获取虚拟机 IP 地址后，重新回到 VS Code。
按照下图所示的步骤打开 SSH 配置文件：
此时 VS Code 可能会弹出多个 SSH 配置文件供你选择，通常直接选择 第一个 即可。
打开配置文件后，在其中加入：
其中：| 配置项 | 含义 |
|---|---|
Host |
远程连接在 VS Code 中显示的名称 |
HostName |
虚拟机的 IP 地址 |
User |
登录虚拟机时使用的用户名 |
不要直接复制示例 IP
上面的：
只是示例 IP 地址。
请将 HostName 修改为你自己的虚拟机 IP 地址。
例如，如果你前面通过 hostname -I 查询到的地址为：
那么配置应该写成：
连接虚拟机¶
保存 SSH 配置文件后，回到 VS Code 的 Remote Explorer 。
此时应该可以看到一个新的远程主机：
点击对应的连接按钮，即可连接虚拟机。第一次连接时，VS Code 可能会要求你选择远程服务器的操作系统类型，此时请选择：
随后可能会要求输入 SSH 登录密码，默认密码为：第一次连接可能出现安全提示
第一次连接虚拟机时，SSH 可能会询问是否信任该主机。
如果看到类似：
的提示，选择 Continue 即可。 连接成功后，VS Code 左下角通常会显示类似： 这表示 VS Code 已经成功连接到虚拟机。连接成功
当 VS Code 左下角出现 SSH: cs323 后，就说明远程开发环境已经配置完成。
之后可以直接使用 VS Code 打开虚拟机中的代码目录，在虚拟机环境中进行代码编写、编译、运行和调试。
安装 Java 开发插件¶
由于后续实验将主要使用 Java 进行开发，因此还需要为 VS Code 安装 Java 开发相关插件。
安装方法和前面安装 Remote - SSH 插件基本相同：
- 首先确认当前 VS Code 已经连接到虚拟机，左下角应显示：
- 点击 VS Code 左侧
- 在搜索栏中输入：
- 找到微软提供的 Extension Pack for Java。
- 点击 Install in SSH: cs323，将插件安装到远程虚拟机中。
必须安装在远程虚拟机中
这里需要特别注意：Java 插件必须安装在 SSH: cs323 远程环境中，而不是只安装在本地电脑中。
后续实验中的 Java 项目、JDK 以及代码运行环境都位于虚拟机中，因此 Java 的代码补全、跳转、编译、运行、调试等功能也需要在远程环境中工作。
安装时请确认按钮显示的是：
而不是普通的：什么是 Extension Pack for Java？
Extension Pack for Java 是一个 Java 开发插件集合。
安装后，VS Code 会自动安装 Java 开发中常用的一系列插件，包括代码补全、代码跳转、运行、调试、测试以及 Maven 项目支持等功能。
因此大家只需要安装这个插件集合，不需要逐个安装其中的插件。
安装完成后，VS Code 就具备了在虚拟机中进行 Java 开发所需的基本功能。
暂时使用本机完成前期实验¶
这是虚拟机不可用时的兜底方案
不需要为此安装 WSL，也不需要提前搭建完整的 Linux 环境。只要本机能够运行 Java 和 Make，就可以先完成课程前期内容。课程推荐环境仍然是虚拟机 + Remote SSH。
检查基础工具¶
在 VS Code 的终端中依次执行：
能够正常显示版本号后，再继续配置编辑器。Java 推荐使用 JDK 21。macOS 用户如果缺少 Git 或 Make，可以安装 Xcode 命令行工具：
Windows 用户可以直接安装 Git、JDK 21 和 Make。Make 可以通过 MinGW-w64 或 Chocolatey 安装；MinGW 提供的命令可能叫作mingw32-make，后续命令中的 make 需要相应替换。
安装 Java 开发插件¶
打开 VS Code 左侧的 Extensions（扩展） 面板，搜索并安装微软提供的 Extension Pack for Java。安装完成且 Java 语言服务启动后，VS Code 状态栏会显示 Java 已就绪。
配置课程 Java 项目¶
课程项目通过 libs 目录提供 JAR 依赖。在项目根目录创建 .vscode/settings.json：
{
"java.project.sourcePaths": ["src/main/java"],
"java.project.referencedLibraries": [
"libs/**/*.jar"
],
"java.project.outputPath": "bin"
}
再在命令面板输入并执行：Debug: Add Configuration，选择 Java，生成 .vscode/launch.json，替换为以下配置：
{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Launch Current File",
"request": "launch",
"mainClass": "${file}",
"classPaths": [
"libs/*",
"bin"
]
}
]
}
${file}：内置变量，自动运行 当前编辑器打开的、带 main 方法的 Java 文件 ，无需为每个文件单独配置classPaths：运行时的类路径，包含依赖 Jar 包和编译输出目录
这里可以直接创建这两个文件，在项目的根目录：
保存后，打开命令面板并执行 Developer: Reload Window。在 VS Code 的 JAVA PROJECTS 视图中看到 Referenced Libraries，说明 JAR 已被识别。
Java 扩展可以直接运行当前打开的、包含 main 方法的类。只有需要固定主类、参数或环境变量时，才需要通过 Run and Debug: Add Configuration 创建 .vscode/launch.json。
使用 Makefile¶
执行 Make 命令前，确认终端位于包含 Makefile 的项目根目录：
Makefile 为准。如果希望在 VS Code 中查看和执行 Makefile 目标，可以安装微软提供的 Makefile Tools 扩展。
Windows 版本 Makefile¶
在 Windows 中使用 Make 工具时候需要将项目根目录的 Makefile 改为下面的版本：
ANTLR_JAR := libs/antlr-4.13.2-complete.jar
OUTPUT_DIR := src/main/java/generated
GRAMMARS := $(basename $(wildcard *.g4))
.DEFAULT_GOAL := all
.PHONY: all clean
all: $(GRAMMARS)
$(GRAMMARS): %: $(OUTPUT_DIR)/%Parser.java
$(OUTPUT_DIR)/%Parser.java: %.g4
@if not exist "$(OUTPUT_DIR)" mkdir "$(OUTPUT_DIR)"
@echo Building $(basename $<)
java -jar $(ANTLR_JAR) -visitor -o $(OUTPUT_DIR)/$(basename $<) -package generated.$(basename $<) $<
clean:
@if exist "$(OUTPUT_DIR)" rmdir /S /Q "$(OUTPUT_DIR)"
命令行必须以 Tab 开头
if、echo、java 和 rmdir 四行前面必须是 Tab，不能用空格代替。这里使用 .DEFAULT_GOAL := all 指定默认目标；原来的 .DEFAULT = all 并不是 GNU Make 设置默认目标的正确写法。
该版本不包含 Maven 的 jar 目标。编译与清理命令分别为：
make，则直接使用 make 和 make clean。