feat: more comments on judge framework

resource/runner/.gitignore

@@ -1,2 +1,7 @@
+# docker image mark
 .mark.*
+# tmp dockerfile
+ubuntu-full.Dockerfile
+ubuntu-run.Dockerfile
+# other tmp files
 *.zip

resource/runner/framework/scripts/.gitignore

@@ -1,2 +1,5 @@
+# bin
 /libwoj_sandbox.so
 /woj_launcher
+# source
+/woj-sandbox

resource/runner/framework/scripts/setup.sh

@@ -12,4 +12,4 @@ make -j || exit 1
 cd ../..
 cp woj-sandbox/build/libwoj_sandbox.so . || exit 1
 cp woj-sandbox/build/woj_launcher . || exit 1
-rm -rf woj-sandbox
+rm -rf woj-sandbox || exit 1

resource/runner/problem/.gitignore

@@ -0,0 +1,4 @@
+*
+!.gitignore
+!example
+!example/*

resource/runner/problem/example/README.md

@@ -5,6 +5,7 @@
 ```
 .
 ├── config.json            # 题目配置信息
+├── description.md         # (not used) 题目描述必须通过 API 提交给系统
 ├── data                   # 数据目录
 │   ├── input              # 输入数据
 │   │   ├── (x).input      # 第 x 组输入数据
@@ -15,7 +16,7 @@
 └── judge                  # 评测脚本目录
     ├── c.Makefile         # (optional) 自定义评测脚本
     ├── prebuild.Makefile  # (optional) 题目初始化脚本
-    └── ...
+    └── ...                # 其余可能用到的程序、脚本等
 ```
 
 ## 详细说明
@@ -28,37 +29,31 @@
         // 运行时配置
         "TimeLimit": 1000, // 时间限制 (ms)
         "MemoryLimit": 16, // 内存限制 (MB)
-        "NProcLimit": 1     // 进(线)程 限制
+        "NProcLimit": 1    // 进(线)程 限制
     },
     "Languages": [
+        // c 语言，使用自定义评测脚本，脚本为 ./judge/XYZ.Makefile
         {"Lang": "c", "Type": "custom", "Script": "XYZ.Makefile", "Cmp": ""},
+        // c++ 语言，使用默认评测脚本，答案比对方式为 NCMP(testlib)
         {"Lang": "cpp", "Type": "default", "Script": "", "Cmp": "NCMP"}
     ], // 支持的语言
     "Tasks": [
         // 评测点信息
-        {"Id": 1, "Points": 25}, // 第一个评测点，分值 25 分，使用 ./data/1.? 为测试数据
-        {"Id": 2, "Points": 25},
-        {"Id": 3, "Points": 25},
-        {"Id": 4, "Points": 25}
+        {"Id": 1, "Points": 10}, // 第一个评测点，分值 25 分，使用 ./data/{input,output}/1.{input,output} 为测试数据
+        {"Id": 2, "Points": 20},
+        {"Id": 3, "Points": 30},
+        {"Id": 4, "Points": 40}
     ]
 }
 ```
 
 ### 评测脚本
 
-见注释
-
-
-
-
-
-
-
-
-
-
-
-
+1. 默认评测脚本目前只支持 `c` 语言和 `cpp`，参见 `../../framework/template/default/{c,cpp}.Makefile`
+2. 自定义评测脚本参见 `./judge/XYZ.Makefile`
+3. `prebuild.Makefile`: 题目初始化脚本，用于编译辅助程序、生成数据等。如果存在改文件，系统会在题目分发到判机后自动执行，否则跳过改步骤
 
+## 注意事项
 
+1. 打包的时候确保 `config.json`, `data`, `judge` 在根目录下
 

resource/runner/problem/example/config.json

@@ -9,9 +9,9 @@
         {"Lang": "cpp", "Type": "default", "Script": "", "Cmp": "NCMP"}
     ],
     "Tasks": [
-        {"Id": 1, "Points": 25},
-        {"Id": 2, "Points": 25},
-        {"Id": 3, "Points": 25},
-        {"Id": 4, "Points": 25}
+        {"Id": 1, "Points": 10},
+        {"Id": 2, "Points": 20},
+        {"Id": 3, "Points": 30},
+        {"Id": 4, "Points": 40}
     ]
 }

resource/runner/problem/example/description.md

@@ -0,0 +1,35 @@
+# A+B Problem
+
+## Description
+
+Given two integers `a` and `b`, calculate the sum of them.
+
+## Scope
+
+- $|a|,|b| \le {10}^9$
+
+## I/O Format
+
+### Input Format
+
+Two integers separated by spaces.
+
+### Output Format
+
+One integer.
+
+## Example Cases
+
+### Case 1
+
+#### Input
+
+```
+20 30
+```
+
+#### Output
+
+```
+50
+```

resource/runner/problem/example/judge/XYZ.Makefile

@@ -17,6 +17,8 @@ compile:
 	$(CC) $(CFLAGS) -o $(PREFIX)/user/$(USER_PROG).out $(PREFIX)/user/$(USER_PROG).$(LANG) $(PREFIX)/judge/gadget.c
 
 judge:
-	# Rename on *.out.usr or *.judge is not allowed
-	sed '/gadgets/d' $(PREFIX)/user/$(TEST_NUM).out.usr > $(PREFIX)/user/$(TEST_NUM).out.usr1
+	# !! Rename on *.out.usr or *.judge is not allowed !!
+	# 自定义评测方式
+	sed '/gadgets/d' $(PREFIX)/user/$(TEST_NUM).out.usr >$(PREFIX)/user/$(TEST_NUM).out.usr1
+	# 评测结果要求符合 testlib 的格式 -> $(TEST_NUM).judge
 	$(NCMP) $(PREFIX)/data/input/$(TEST_NUM).input $(PREFIX)/user/$(TEST_NUM).out.usr1 $(PREFIX)/data/output/$(TEST_NUM).output $(PREFIX)/user/$(TEST_NUM).judge -appes

resource/runner/problem/example/judge/prebuild.Makefile

@@ -1,7 +1,11 @@
 include ${TEMPLATE}/c.mk ${TEMPLATE}/Judger.mk
 
+# 当题目被下载到 runner 后，会自动执行 prebuild 阶段，判题时不会再次执行
+
 prebuild:
+	# 生成测试数据生成工具
 	clang++ -I$(TESTLIB) -Ofast -o $(PREFIX)/judge/gen.out $(PREFIX)/judge/gen.cpp
+	# 生成 2,4 号测试数据
 	@if [ ! -f $(PREFIX)/data/input/2.input ]; then \
 		$(PREFIX)/judge/gen.out > $(PREFIX)/data/input/2.input; \
 		python3 -c "print(sum(map(int, input().split())))" < $(PREFIX)/data/input/2.input > $(PREFIX)/data/output/2.output; \

resource/runner/tmp/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

resource/runner/user/.gitignore

@@ -1 +1,2 @@
-/test_user
+*
+!.gitignore