compilerlab.yaml API 文档
本文档会严谨给出 compilerlab.yaml 的约定格式和含义。多数情况下,同学们可以查看示例用法来仿写 compilerlab.yaml,并使用评测脚本验证,本文档旨在给细节部分作出更详细的解释,方便同学们查阅。遇到问题时,也可以尝试结合评测脚本源码理解。
完整 YAML 实例
文件名固定为根目录下的 compilerlab.yaml,使用 UTF-8。缩进用空格,建议每级两个空格,不用 Tab。
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
- id: integer_input
title: 多组整数输入与求和
tests:
- id: read_two
source: features/read_two.toy
artifact: out/read_two
kind: run
cases:
- id: positive
input: features/read_two-positive.in
output: features/read_two-positive.out
- id: negative
input: features/read_two-negative.in
output: features/read_two-negative.out
- id: syntax_errors
title: 拒绝非法语法
tests:
- id: reject_invalid
source: features/invalid.toy
artifact: out/invalid
kind: compile_error
diagnostic_contains: "syntax error"
algorithms:
- id: a_plus_b
source: algorithms/a_plus_b.toy
artifact: out/a_plus_b
.toy、.src 和 .c 都只是源文件扩展名示例,按自己的源语言选择。你也可以在公共资料中查看此文件,其引用的文件也全部提供。
字段
顶层字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
features | 列表 | 是 | 支持的功能点;无内容时写 [],不能省略或写空值 |
algorithms | 列表 | 是 | 算法题目 ID 到项目源文件的映射;无内容时写 [] |
功能点字段 features[]
| 字段 | 类型 | 要求 |
|---|---|---|
id | 字符串 | 稳定功能点 ID,同一提交内唯一,课程必做项采用助教公布的 ID |
title | 字符串 | 1~80 个字符的说明,可以使用中文 |
tests | 列表 | 至少一个测试,支持正例和编译拒绝负例混排 |
ID 只能匹配 [a-z][a-z0-9_-]{0,47}:小写英文字母开头,后续可用小写字母、数字、下划线、连字符,总长不超过 48。不要使用空格、中文或斜杠作为 ID。
功能测试字段 tests[]
| 字段 | 必填 | 解释 |
|---|---|---|
id | 是 | 该功能点内唯一,不得使用保留名 summary |
source | 是 | 自己源语言的源文件:一个仓库相对路径或非空路径列表 |
artifact | 是 | 完整输出文件的仓库相对路径,例如 out/program;负例也要填写 |
kind | 是 | run 或 compile_error |
stdin | 否 | run 的单组写法,提供运行输入的仓库相对路径;省略表示空输入,与 cases 互斥 |
expect_stdout | 否 | run 的单组写法,预期 stdout 文件路径;省略时只检查编译及正常退出,与 cases 互斥 |
cases | 否 | run 的多组写法,非空列表;每项必须有 id、input、output,不能同时填写 stdin/expect_stdout |
diagnostic_contains | 否 | 仅 compile_error 可用,1~160 字符的普通文本片段,检查 stderr 包含它;不是正则表达式 |
artifact 是相对于项目仓库根目录的完整输出文件路径。文件名、扩展名和子目录由你自己选择,无须与源文件名一致。artifact: program 表示仓库根目录的 program;artifact: out/program.exe 表示 out/program.exe,脚本必须给路径变量加双引号。建议把产物放在已忽略的 out/ 或 build/。使用其他位置时,在自己的 .gitignore 中加入相应文件或目录,避免把生成的程序提交到仓库。
例如,合并数组题的声明可以写为:
algorithms:
- id: merge_sorted_arrays
source: algorithms/merge.src
artifact: out/program
source 同时支持单文件字符串和多文件列表。多文件示例:
algorithms:
- id: merge_sorted_arrays
source:
- algorithms/merge.src
- algorithms/array_utils.src
artifact: out/program
列表至少包含一个文件,平台保留文件顺序,每个路径都是一个独立参数;也可写成 source: [algorithms/merge.src, algorithms/array_utils.src]。文件必须实际提交且符合源文件路径规则,不能把多个文件名用空格拼成一个字符串,也不展开通配符。多文件编译是可选能力。
kind: run 的流程是:编译成功、指定路径下存在普通产物文件、run.sh 运行退出码为 0;填写 expect_stdout 时再检查输出。不提供预期输出只会得到 EXIT_OK。
kind: compile_error 的流程是:在时间和输出限制内,compile.sh 返回 1,且 stderr 有非空诊断;若指定 diagnostic_contains,诊断还需包含该文本。不执行产物。崩溃、缺包、超时、OOM、返回 2 都不能算正确拒绝。
功能负例不要写 stdin、expect_stdout 或 cases;正例不要写 diagnostic_contains。多个应拒绝的源程序使用多个 tests,每个都设置 kind: compile_error。预期结果必须是文件路径,不能直接填 expect_stdout: "42" 来表示内容。
带输入的功能测试示例(需要自行创建引用文件):
- id: read_two_numbers
source: features/read_two.toy
artifact: out/read_two
kind: run
stdin: features/read_two.in
expect_stdout: features/read_two.out
同一个源程序需要多组输入时,使用与算法题类似的 cases:
- id: read_two
source: features/read_two.toy
artifact: out/read_two
kind: run
cases:
- id: positive
input: features/read_two-positive.in
output: features/read_two-positive.out
- id: negative
input: features/read_two-negative.in
output: features/read_two-negative.out
cases[] 字段 | 要求 |
|---|---|
id | 必填,同一个 test 内唯一,不能是 summary |
input | 必填,仓库相对路径;文件内容作为本组 stdin,空输入可用空文件 |
output | 必填,仓库相对路径;文件内容是本组预期 stdout |
功能点的各个 tests 可以使用不同源文件;一个 test 的所有 cases 共用它的源文件和产物。
单组写法和多组写法不能在同一个 test 中混用,功能点之间可以分别使用。
算法字段 algorithms[]
每项需提供 id、source、artifact 三个字段,均为必填字符串;额外字段不参与评测。
id 必须与助教发布的题目 ID 完全相同。
路径约定
-
路径必须相对于仓库根目录,例如
features/test.toy;不用绝对路径、../、./或 Windows 反斜杠。 -
source、stdin、expect_stdout 和 cases 的输入输出路径,各级名称以英文字母、数字或下划线开头,后续可包含这些字符及
.、-;这些输入路径不用空格或中文。artifact 可以使用中文和空格。完整路径最多 240 字符。 -
artifact填完整输出文件的仓库相对路径;不得覆盖源码、测试数据、脚本、元数据或reports/、.git/。待测源码不能位于 out/、build/、deps/ 等生成目录。正式 CI 下载源码时不带 deps/、.venv/、build/、out/,以便每轮从源码和安装命令开始;本地评测直接使用现有目录,保留已安装依赖。