From 498746dc3260e2659a8e92ed1162f3b123446957 Mon Sep 17 00:00:00 2001 From: Boming Zhang Date: Sat, 19 Oct 2024 17:18:14 -0400 Subject: [PATCH] docs: list needed programs for test --- README.md | 54 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index f023ed9..864aad3 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ $ git clone ssh://git@focs.ji.sjtu.edu.cn:2222/JOJ/JOJ3.git ``` 2. Install [Go](https://go.dev/doc/install). Also, make sure `make` and `git` are installed and all 3 programs are presented in `$PATH`. - - If you have problem on connecting to the Go website and Go packages, download Go from [studygolang](https://studygolang.com/dl) and run `go env -w GOPROXY=https://goproxy.io,direct` to set the Go modules mirror proxy after installing Go. + + - If you have problem on connecting to the Go website and Go packages, download Go from [studygolang](https://studygolang.com/dl) and run `go env -w GOPROXY=https://goproxy.io,direct` to set the Go modules mirror proxy after installing Go. 3. Enable cgroup v2 for your OS. For WSL2, check [here](https://stackoverflow.com/a/73376219/13724598). So that you do not need root permission to run `go-judge`. @@ -44,7 +45,14 @@ $ make 8. Check the functions of `joj3` with the `make test`, which should pass all the test cases. The cases used here are in `/examples`. -Note: you may fail the test if the checking tools are not installed. e.g. For the test case `cpplint/sillycode`, you need to install `cpplint` in `/usr/bin` or `/usr/local/bin`. +For now, the following checking tools are needed for test: + +1. `clang`/`clang++` +2. `clang-tidy-18` +3. `cmake` +4. `make` +5. `cpplint` +6. `cppcheck` ```bash $ make test @@ -73,28 +81,28 @@ pre-commit installed at .git/hooks/pre-commit These steps are executed in runner-images. We use `sudo -u tt` to elevate the permission and run `joj3` and `joint-teapot`. All the secret files should be stored in the host machine with user `tt` and mounted into the runner (e.g. `/home/tt/.config`). Since the runner uses user `student`, we can keep the data safe. 1. Run JOJ3 - 1. Parse the message. - - It will use the git commit message from `HEAD`. The message should meet the [Conventional Commits specification](https://www.conventionalcommits.org/). We use `scope` and `description` here. - - If `-tag` is specified, then it should equal to the scope of the message, or JOJ3 will not run. - 2. Find the configuration file. - - We have `conf-root` and `conf-name` specified in the CLI argument. Then the full path of configuration file is `//`. - 3. Generate stages. - - We have an empty list of stages at the beginning. - - We check all the stages from the configuration file. Stages with empty `group` field will always be added. And stages with `group = joj` will be added when `description` contains "joj" (case insensitive). - - Every stage needs to have an unique `name`, which means if two stages have the same name, only the first one will be added. - 4. Run stages. - - By default, all the stages will run sequentially. - - Each stage contains a executor and a parser. Executor (currently only sandbox) executes the command and parser parses the output generated by the executor. - - The parser can return a force quit, which means all the stages after it will be skipped. - 5. Generate results. - - Once the running of stages is done, it will generate a result file where the path is specified in the configuration file. + 1. Parse the message. + - It will use the git commit message from `HEAD`. The message should meet the [Conventional Commits specification](https://www.conventionalcommits.org/). We use `scope` and `description` here. + - If `-tag` is specified, then it should equal to the scope of the message, or JOJ3 will not run. + 2. Find the configuration file. + - We have `conf-root` and `conf-name` specified in the CLI argument. Then the full path of configuration file is `//`. + 3. Generate stages. + - We have an empty list of stages at the beginning. + - We check all the stages from the configuration file. Stages with empty `group` field will always be added. And stages with `group = joj` will be added when `description` contains "joj" (case insensitive). + - Every stage needs to have an unique `name`, which means if two stages have the same name, only the first one will be added. + 4. Run stages. + - By default, all the stages will run sequentially. + - Each stage contains a executor and a parser. Executor (currently only sandbox) executes the command and parser parses the output generated by the executor. + - The parser can return a force quit, which means all the stages after it will be skipped. + 5. Generate results. + - Once the running of stages is done, it will generate a result file where the path is specified in the configuration file. 2. Run Joint-Teapot. - 1. Generally speaking, it reads the JOJ3 results file and output results on Gitea. - - We use a wrapper script `joj3-teapot` to limit the commands can be run in the original `joint-teapot` for safety. - - Currently, the environment file path and joj3 result file path are hardcoded, as `/home/tt/.config/teapot/teapot.env` and `/tmp/joj3_result.json`, respectively. - 2. With `joint-teapot joj3-scoreboard`, it will update the scoreboard file in grading repo. - 3. With `joint-teapot joj3-failed-table`, it will update the failed table file in grading repo. - 4. With `joint-teapot joj3-create-result-issue`, it create an issue in the submitter's repo to show the results. + 1. Generally speaking, it reads the JOJ3 results file and output results on Gitea. + - We use a wrapper script `joj3-teapot` to limit the commands can be run in the original `joint-teapot` for safety. + - Currently, the environment file path and joj3 result file path are hardcoded, as `/home/tt/.config/teapot/teapot.env` and `/tmp/joj3_result.json`, respectively. + 2. With `joint-teapot joj3-scoreboard`, it will update the scoreboard file in grading repo. + 3. With `joint-teapot joj3-failed-table`, it will update the failed table file in grading repo. + 4. With `joint-teapot joj3-create-result-issue`, it create an issue in the submitter's repo to show the results. ## Components