From 42b9e98408fd4c716d63b98e97a39b50e8f76b53 Mon Sep 17 00:00:00 2001
From: Paul Pan <i@0x7f.app>
Date: Sun, 16 Jul 2023 15:42:26 +0800
Subject: [PATCH] feat: more comments on judge framework

---
 resource/runner/.gitignore                    |  5 +++
 resource/runner/framework/scripts/.gitignore  |  3 ++
 resource/runner/framework/scripts/setup.sh    |  2 +-
 resource/runner/problem/.gitignore            |  4 +++
 resource/runner/problem/example/README.md     | 33 ++++++++---------
 resource/runner/problem/example/config.json   |  8 ++---
 .../runner/problem/example/description.md     | 35 +++++++++++++++++++
 .../runner/problem/example/judge/XYZ.Makefile |  6 ++--
 .../problem/example/judge/prebuild.Makefile   |  4 +++
 resource/runner/tmp/.gitignore                |  2 ++
 resource/runner/tmp/.gitkeep                  |  0
 resource/runner/user/.gitignore               |  3 +-
 12 files changed, 78 insertions(+), 27 deletions(-)
 create mode 100644 resource/runner/problem/.gitignore
 create mode 100644 resource/runner/problem/example/description.md
 create mode 100644 resource/runner/tmp/.gitignore
 delete mode 100644 resource/runner/tmp/.gitkeep

diff --git a/resource/runner/.gitignore b/resource/runner/.gitignore
index 0cf8d7b..8a603d9 100644
--- a/resource/runner/.gitignore
+++ b/resource/runner/.gitignore
@@ -1,2 +1,7 @@
+# docker image mark
 .mark.*
+# tmp dockerfile
+ubuntu-full.Dockerfile
+ubuntu-run.Dockerfile
+# other tmp files
 *.zip
diff --git a/resource/runner/framework/scripts/.gitignore b/resource/runner/framework/scripts/.gitignore
index bf3d440..7b0fd4d 100644
--- a/resource/runner/framework/scripts/.gitignore
+++ b/resource/runner/framework/scripts/.gitignore
@@ -1,2 +1,5 @@
+# bin
 /libwoj_sandbox.so
 /woj_launcher
+# source
+/woj-sandbox
diff --git a/resource/runner/framework/scripts/setup.sh b/resource/runner/framework/scripts/setup.sh
index 96a69cc..e97e402 100755
--- a/resource/runner/framework/scripts/setup.sh
+++ b/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
diff --git a/resource/runner/problem/.gitignore b/resource/runner/problem/.gitignore
new file mode 100644
index 0000000..9ec52b8
--- /dev/null
+++ b/resource/runner/problem/.gitignore
@@ -0,0 +1,4 @@
+*
+!.gitignore
+!example
+!example/*
diff --git a/resource/runner/problem/example/README.md b/resource/runner/problem/example/README.md
index ba9485d..39ffa40 100644
--- a/resource/runner/problem/example/README.md
+++ b/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` 在根目录下
 
diff --git a/resource/runner/problem/example/config.json b/resource/runner/problem/example/config.json
index 54dbaff..3e4effc 100644
--- a/resource/runner/problem/example/config.json
+++ b/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}
     ]
 }
\ No newline at end of file
diff --git a/resource/runner/problem/example/description.md b/resource/runner/problem/example/description.md
new file mode 100644
index 0000000..9eadab5
--- /dev/null
+++ b/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
+```
diff --git a/resource/runner/problem/example/judge/XYZ.Makefile b/resource/runner/problem/example/judge/XYZ.Makefile
index d15d183..1264083 100644
--- a/resource/runner/problem/example/judge/XYZ.Makefile
+++ b/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
diff --git a/resource/runner/problem/example/judge/prebuild.Makefile b/resource/runner/problem/example/judge/prebuild.Makefile
index 39daf6f..c07df39 100644
--- a/resource/runner/problem/example/judge/prebuild.Makefile
+++ b/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; \
diff --git a/resource/runner/tmp/.gitignore b/resource/runner/tmp/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/resource/runner/tmp/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/resource/runner/tmp/.gitkeep b/resource/runner/tmp/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/resource/runner/user/.gitignore b/resource/runner/user/.gitignore
index 2699330..d6b7ef3 100644
--- a/resource/runner/user/.gitignore
+++ b/resource/runner/user/.gitignore
@@ -1 +1,2 @@
-/test_user
\ No newline at end of file
+*
+!.gitignore