2026 编译原理课程实验开发指南
本文档旨在带领同学们完成课程实验开发的准备工作,并介绍评测相关的事项,帮助同学们尽快上手课程实验。
Tip
对课程实验文档有疑问的,可以及时和助教沟通反馈。
前置准备
注册 GitLab 账号
- 登录我们课程自建的 GitLab 平台:CompilerLab · GitLab;
- 进入注册页面,输入基本信息进行注册,要求见下图;
- 请大家务必妥善保管 GitLab 密码,丢失密码后,只能通过清除账号来重置密码。
创建代码仓库
登录课程 GitLab 平台后,新建一个项目,名称固定为 compilerlab-2026,Visibility 选 Private。此项目仓库为你最终代码提交位置。
Important
你有义务保护好自己的代码,防止被他人抄袭。
Note
请在 Lab 发布后两周内(2026年10月30日前)完成仓库创建。
获取公共资料和基础环境
课程的公共资料位于 course / materials,注册并登录 GitLab 账号后可以查看。将其下载 / clone 到本地:
materials
├── ci/
├── grader/
├── public-tests/
├── student-template/
├── teacher/
├── .dockerignore
├── Dockerfile
└── README.md
各文件的详细说明请查看 README.md 文件,我们这里只介绍最基础的配置环节。
你需要将 student-template/.gitlab-ci.yml 拷贝到你的项目仓库中,并最终和你的项目一起提交。评测代码和 CI 配置原则上都不可以改动。
本次实验可以在 Windows、macOS 和 GNU/Linux 等平台上完成开发,但是我们只会在 GNU/Linux 平台上进行测试,确切来说,我们会将公共资料中提供的基础 Docker 环境作为测试环境。
Tip
我们建议使用 Windows 电脑的同学安装 WSL 2 或者虚拟机进行开发测试;使用 macOS 和 GNU/Linux 系统的同学可以直接在本地进行开发测试。如果你打算使用 Ubuntu 系统,建议使用 24.04 版本,与 CI 测试版本保持一致。无论哪一种开发平台,都需要保证测试用的 Docker 环境可以运行评测。
基础 Docker 环境基于 Ubuntu 24.04,平台为 amd64,已经包含部分常用开发工具链。可以在 materials 目录下自行构建:
# 确保 Docker 环境构建为 linux/amd64 平台。
docker build --platform=linux/amd64 . -t se3355-2026-env:latest
也可以直接下载我们预构建好的镜像文件并进行导入:
Note
Share content: se3355-2026-env.tar.gz
Link: SJTU Netdisk, Extraction code: 6uzr
docker load < se3355-2026-env.tar.gz
使用我们提供的示例项目测试环境配置正确(示例项目需要在 amd64 平台上运行):
# 在 materials 目录下
docker run -it -v .:/workspace se3355-2026-env:latest
root@aaaaaaaaaaaa:/workspace# python3 -m grader grade \
--submission ./student-template \
--suite public-tests/suite.yaml \
--output ./local-results
自定义测试说明(compilerlab.yaml)
由于本次实验不限制目标语言和实现方式,为了检查你的编译器的完整性,你需要为设计需求中的每个具体功能点自行设计测试用例,并声明在“语言符合性测试清单”(language conformance test manifest)中,也即项目根目录的 compilerlab.yaml 文件。我们的评测脚本会读取该文件并按照其中的声明细则来执行评测。
例如,评测脚本接收这样一份 compilerlab.yaml:
features:
- id: integer_output # 功能点唯一标识名
title: 整数常量输出 # 标题任取,评测脚本中会输出
tests: # 测试如何执行,你可以使用多个测试用例来证明同一个功能点
- id: print_42
source: features/print_42.toy # 你设计的语言的源代码,用来测试语言功能
artifact: out/print_42 # 编译源码后的产物名称
kind: run # 执行方式,详情见后文
expect_stdout: features/print_42.out # 预期输出
评测脚本便会读取 features 字段中的功能点,编译你提供的源码,执行编译产物并和你提供的预期输出进行对比。具体来说,对于上面的清单,评测脚本大致等同于执行:
echo "Testing 整数常量输出"
bash ./compile.sh features/print_42.toy out/print_42
bash ./run.sh out/print_42 > /tmp/output
diff features/print_42.out /tmp/output
该情形下,如果执行过程中出现任何错误,包括编译器出错、编译产物执行出错、最终输出结果不匹配,都会使得该功能点测试失败,你便无法拿到该功能点的分数。
你所提供的 compilerlab.yaml 整体上需要包含两个小节:
compilerlab.yaml 的详细格式约定可以参考文档 compilerlab.yaml 格式文档。评测脚本的执行细节可以参考下一小节。
自动化评测工具介绍
自动化评测工具位于公共资料的 grader/ 目录,使用 Python 实现。本地运行需要进行依赖安装,推荐使用 Python >= 3.12 和 venv 管理环境:
# 在 materials 目录下
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r grader/requirements.txt
python3 -m grader --help
本文档后续我们将简单介绍评测工具的两个功能,具体使用可以参考命令行 --help 文档和 compilerlab.yaml 的 API 文档,必要时也可以直接参考源码理解。
YAML 格式校验
评测工具可以对你提供的 compilerlab.yaml 进行格式校验:
python3 -m grader validate ./compilerlab-2026
提供的唯一参数为代码仓库的根目录,不运行评测。成功应提示符合提交规范;如果失败,可以按错误信息修复 YAML 必需字段、字段类型、路径、缺失脚本或重复 ID 等问题。
执行评测
python3 -m grader grade \
--submission ./compilerlab-2026 \
--suite ./public-tests/suite.yaml \
--output ./local-results
--submission:必需参数,指定需要评测的项目代码根目录。--suite:指定测试数据集。--output参数:测试结果输出目录,必须在代码仓库之外。
测试接口约定
为了给予同学们一定的自由度,本次 Lab 不限定实现语言和开发环境。但是我们最终使用基础 Docker 环境运行自动化测试,为了测试的正常运行,你需要自行提供四个脚本,对应评测需要的四个阶段。这四个脚本最终都是需要在 Docker 容器中执行的:
setup.sh:配置编译和测试环境(只执行一次);build.sh:构建你的语言编译器(只执行一次);compile.sh:使用你的编译器编译源码(每个测试用例都会执行);run.sh:运行编译后的产物(执行与否取决于当前测试用例是否编译成功);
具体来说,线上评测会先启动 Docker 容器,执行你的项目根目录的 setup.sh 脚本来进一步配置你所需要的环境,然后运行 grader 评测脚本。评测脚本会先执行一次 build.sh 来构建编译器,然后读取 compilerlab.yaml,对于每个测试用例,使用 compile.sh 脚本编译你的源代码,如果编译成功,就调用 run.sh 来完成测试。四个脚本都是独立的 Bash 进程,评测脚本会单独启用 Bash 进程读取脚本内容并执行。
Note
为了简化测试接口的设计,本次实验对跨平台不作出任何要求。你只需要保证在我们提供的基础 Docker 环境(也就是非常标准的 Linux/x86-64 环境)中可以运行这些脚本并进行测评即可。你的日常开发测试可以使用任意命令。
你可以在项目完成的后期再进行脚本编写,完成测试接口的适配工作,尝试本地评测和提交线上评测前可以参考提交指南。
setup
线上评测全部在容器中使用 root 用户执行,所以安装依赖的时候不需要使用 sudo 提权。例如,添加 Python 包可以在 setup.sh 中写:
set -e
python3 -m pip install --no-cache-dir --break-system-packages 'lark==1.2.2'
安装系统包可以直接写:
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends libboost-dev
build
build.sh 负责从你提交的源码构建编译器,不接收参数。C/C++ 项目例如:
set -e
# 当前目录为项目根目录。
mkdir -p build
# 如需自定义工具链路径,在本脚本设置 PATH 等环境变量。
g++ -std=c++20 -O2 src/main.cpp -o build/my-compiler
你可以通过直接在脚本中留空来跳过某个步骤。例如,如果使用 Python 实现编译器,通常不需要额外编译过程,就可以在 build.sh 中直接写:
exit 0
空脚本也是合法的成功空操作,但文件仍须提交。build 任意非零返回或超时均表示编译器准备失败,显示 BUILD_FAILED,后续功能点和算法测试跳过。
compile
compile.sh 用来编译测试源文件。compile.sh 接收两个或更多参数,其中最后一个参数应当被作为编译输出文件名处理。评测脚本读取 source 和 artifact 字段后,会将其依次作为 compile.sh 的参数传入,如果 source 字段是一个列表,则先依次传入每个 source。
compile.sh 应当输出 artifact 文件。建议使用返回值来表示编译结果:
| compile.sh 返回值 | 含义 | 平台处理 |
|---|---|---|
0 | 源程序编译成功 | 正例继续调用 run.sh;负例判 NOT_REJECTED |
1 | 编译器正常拒绝非法源程序 | stderr 应包含诊断;负例核对诊断,正例判 CE |
2 或其他非零 | 编译器崩溃、脚本、IR 校验、后端或链接工具故障 | COMPILER_ERROR,不能算负例通过 |
具体例子可以参考示例代码仓库中的实现模板。
run
所有产物都通过 run.sh 运行,它只接收需要执行的程序路径作为唯一参数。如果上一步的编译产物可以直接在评测平台上执行,可以写:
exec "$1"
若二进制依赖动态库,run.sh 可以额外设置 LD_LIBRARY_PATH 等环境变量后执行。如果编译产物需要通过自制虚拟机执行,也可以通过 run.sh 进行包装。虚拟机的编译过程需要在 build 阶段完成。
线上评测细节
Caution
建议在本地 Docker 环境中通过评测后,再尝试进行线上评测。
我们利用 GitLab Pipeline 实现线上评测,核心逻辑位于公共资料中的 ci/run.py。
为了执行线上评测,你必须提交 .gitlab-ci.yml 文件,并将需要评测的分支提交到 GitLab 仓库的 submit 分支:
# 示例:提交当前 commit 到远端 submit 分支
git push origin HEAD:submit
也可以在 GitLab 平台上手动触发 Pipeline:Build → Pipelines → New pipeline/Run pipeline。
打开项目 Build → Pipelines。你可以查看作业日志、流水线 Tests、作业 artifacts(默认保留 7 天及最新一次)。
-
作业日志:每个阶段的 stdout/stderr、退出码和最终判定。
-
Tests:JUnit 报告展示功能点、算法题和输入测试编号。
-
Artifacts:下载
reports/report.json、reports/student.json、reports/junit.xml和reports/source.tar.gz,包括失败阶段和隐藏测试的完整输出捕获。文件 内容 report.json 判定、执行记录、策略、提交信息和摘要 student.json 学生查看的判定及各阶段 stdout/stderr junit.xml GitLab Tests 展示所需的报告 source.tar.gz 本次提交源码,不含 .git 或未提交文件
结果代码理解:
| 结果 | 含义及优先检查方向 |
|---|---|
| PASS / AC | 指定检查通过 / 输出符合比较规则 |
| EXIT_OK | 编译和退出通过,该功能点未声明输出检查 |
| LOCAL_ENV | 本地自测使用已安装环境,跳过 setup;不是失败 |
| EXPECTED_REJECTION | 负例被正常拒绝,诊断符合要求 |
| INVALID_SUBMISSION | 必需字段、字段类型、ID、引用路径或必需脚本不合规;先运行 validate |
| BUILD_FAILED | build.sh 无法构建编译器,后续测试跳过 |
| SETUP_FAILED | 依赖安装失败;检查下载源、容器网络、安装目录和锁定版本 |
| COMPILER_ERROR | compile.sh 执行时编译器、脚本或后端工具链发生错误、对应源码被编译器拒绝 |
| BAD_ARTIFACT | 未生成指定文件、路径不合法、产物不是普通文件或使用了符号链接 |
| NOT_REJECTED | 功能负例未被按约定拒绝 |
| DIAGNOSTIC_MISMATCH | 正常拒绝,诊断不包含 YAML 声明的文本 |
| WA | stdout 不匹配;检查额外提示、数字格式、逻辑错误 |
| RE | 运行非零退出、崩溃或未能正常启动 |
| TLE / OLE | 时间超限 / 输出超限;容器 OOM 可能直接中止整轮 |
| INCOMPLETE | 作业开始后中断,尚无最终判定 |
| ROUND_LIMIT | 整轮超过测试设置的总时限 |
| SKIP | 前置步骤失败,测试点没有运行 |
| FAILED | 汇总项中至少一项没有通过,查看对应子项 |
其他开发注意事项
开发环境
推荐大家选择常见的通用编程语言和使用频率较高的工具链和相关依赖。如果需要使用包管理工具(比如 pip、cargo 等)也请使用最常见的标准配置流程,方便评测环境复现。
Git 版本管理
使用 Git 版本控制系统管理你的项目源码,合理提交文件,使用 .gitignore 忽略构建产物、下载资源、个人信息等无关文件。Agent 相关文件,如 SKILL.md、AGENTS.md,可以选择加入 Git 管理。
Git commit message 应当言简意赅,清晰描述当前修改行为。推荐遵循 Conventional Commits 之类的提交范式。
提交前请务必妥善保存源码,至少在本地和 GitLab 服务器上都保存一份。