Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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/,以便每轮从源码和安装命令开始;本地评测直接使用现有目录,保留已安装依赖。