JOJ3

module
v0.0.0-...-ee117b3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2025 License: MIT

README

JOJ3

Go Report Card Go Reference

Quick Start

  1. Clone this repo in a Linux computer. For Windows, use WSL 2.
$ git clone ssh://git@focs.ji.sjtu.edu.cn:2222/JOJ/JOJ3.git

  1. Install Go. 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 and run go env -w GOPROXY=https://goproxy.io,direct to set the Go modules mirror proxy after installing Go.

  2. Enable cgroup v2 for your OS. For WSL2, check here. Also, enable linger for the user you used to run go-judge if you are using systemd, e.g. if the user is go-judge, run loginctl enable-linger go-judge. So that you do not need root permission to run go-judge (it can create a nesting cgroup in its user slice).

  3. Clone go-judge.

$ git clone https://github.com/criyle/go-judge && cd go-judge
$ go build -o ./tmp/go-judge ./cmd/go-judge
  1. Run go-judge.
$ # make sure you are in go-judge directory
$ ./tmp/go-judge -http-addr 0.0.0.0:5050 -grpc-addr 0.0.0.0:5051 -monitor-addr 0.0.0.0:5052 -enable-grpc -enable-debug -enable-metrics
  1. Pull submodules. It might be slow, so only run it when the test branches are out of date.
$ # make sure you are in JOJ3 directory
$ make prepare-test
  1. Build binaries in /cmd.
$ make
  1. Check the functions of joj3 with the make test, which should pass all the test cases. The cases used here are in /examples.

For now, the following checking tools are needed for test:

  1. clang/clang++
  2. clang-tidy-18
  3. cmake
  4. make
  5. cpplint
$ make test
go test -coverprofile cover.out -v ./...
...
PASS
coverage: 74.0% of statements
ok      github.com/joint-online-judge/JOJ3/cmd/joj3  2.290s  coverage: 74.0% of statements
For developers
  1. Install pre-commit, golangci-lint.
  2. Install the pre-commit hooks. It will run some checks before you commit.
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
  1. You only need to run steps 5, 7, and 8 in the quick start during development. If the test cases need to be updated, step 6 is also needed.

Workflow

These steps are executed in runner-images. We use sudo -E -u tt to elevate the permission and run joj3 with environment variables from gitea actions. 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. Parse the message.
    • It will use the git commit message from HEAD. The message should meet the Conventional Commits specification. We use scope and description here. Also, a suffix [group] will be used to decide which stages will be run later.
    • 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 <conf-root>/<scope>/<conf-name>.
    • If that configuration file does not exist, and fallback-conf-name is passed, it will try to read <conf-root>/<fallback-conf-name>.
  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. Stages with non-empty group field requires that value (case insensitive) appears in the commit group. e.g. with commit msg feat(h5/e3): joj msan [joj], stages with the following group field will run: "", "joj". If the group specified in the commit message is [all], then all groups will run.
    • 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 multiple parsers. The executor executes the command and parsers parse the output generated by the executor. The parsers in one stage will run sequentially, and all the output will be aggregated (scores being summed up and comment being concatenated).
    • The parser can return a force quit, which means all the stages after it will be skipped, but the remaining parsers in the current stage will run.
  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.
  6. Run optional stages.
    • If pre-stages and post-stages is specified, it will run before step 4 and after step 5, responsively. The result of these optional stages will not affect regular stages. Now we run joint-teapot in post-stages as it needs the output file from regulara stages to post the issue to the corresponding repo for students.

Models

The program parses the configuration file to run multiple stages.

Each stage contains an executor and multiple parsers. An executor takes a Cmd and returns an ExecutorResult, while a parser takes an ExecutorResult and its configuration and returns a ParserResult and bool to indicate whether we should skip the rest stages.

Cmd

Check Cmd at https://github.com/criyle/go-judge#rest-api-interface. Some difference:

  • CopyInDir string: set to non-empty string to add everything in that directory to CopyIn.
  • CopyInCached map[string]string: key: file name in the sandbox, value: file name used in CopyOutCached.
  • LocalFile: now supports the relative path
ExecutorResult

Check the Result at https://github.com/criyle/go-judge#rest-api-interface.

ParserResult
  • Score int: score of the executor result.
  • Comment string: comment on the executor result.

Directories

Path Synopsis
cmd
joj3
Package main provides a joj3 executable, which runs various stages based on configuration files and commit message.
 Package main provides a joj3 executable, which runs various stages based on configuration files and commit message.
joj3/conf
Package conf provides a configuration file parser for JOJ3.
 Package conf provides a configuration file parser for JOJ3.
joj3/env
Package env stores the environment variables from actions environment.
 Package env stores the environment variables from actions environment.
repo-health-checker
Package main provides a repo-health-checker executable that checks the health of a repository.
 Package main provides a repo-health-checker executable that checks the health of a repository.
sample
Package main provides a sample executable that demonstrates how JOJ3 works.
 Package main provides a sample executable that demonstrates how JOJ3 works.
internal
executor
Package executor contains all the executors.
 Package executor contains all the executors.
executor/dummy
Package dummy provides a mock executor implementation for testing purposes and serves as a template for new executor development.
 Package dummy provides a mock executor implementation for testing purposes and serves as a template for new executor development.
executor/local
Package local implements an executor that runs commands directly on the local system.
 Package local implements an executor that runs commands directly on the local system.
executor/sandbox
Package sandbox provides a sandboxed execution environment for running untrusted code.
 Package sandbox provides a sandboxed execution environment for running untrusted code.
parser
Package parser contains all the parsers.
 Package parser contains all the parsers.
parser/clangtidy
Package clangtidy parses output of the clang-tidy C/C++ linter tool to assign scores based on detected code issues.
 Package clangtidy parses output of the clang-tidy C/C++ linter tool to assign scores based on detected code issues.
parser/cppcheck
Package clangtidy parses output of the cppcheck static analysis tool to assign scores based on detected code issues.
 Package clangtidy parses output of the cppcheck static analysis tool to assign scores based on detected code issues.
parser/cpplint
Package clangtidy parses output of the cpplint style checker tool to assign scores based on detected code issues.
 Package clangtidy parses output of the cpplint style checker tool to assign scores based on detected code issues.
parser/debug
Package debug logs the executor result to help in troubleshooting.
 Package debug logs the executor result to help in troubleshooting.
parser/diff
Package diff implements string comparison functionality for the specific output files, comparing then with expected answers and assigning scores based on results.
 Package diff implements string comparison functionality for the specific output files, comparing then with expected answers and assigning scores based on results.
parser/dummy
Package dummy provides a simple parser implementation that serves as a template for new parser development.
 Package dummy provides a simple parser implementation that serves as a template for new parser development.
parser/healthcheck
Package healthcheck parses the output of the repo-health-checker tool and return forced quit status on error.
 Package healthcheck parses the output of the repo-health-checker tool and return forced quit status on error.
parser/keyword
Package keyword implements keyword-based output analysis functionality.
 Package keyword implements keyword-based output analysis functionality.
parser/log
Package log logs the json key-value pairs from given file.
 Package log logs the json key-value pairs from given file.
parser/plugin
Package plugin provides functionality to load and run parser plugins dynamically.
 Package plugin provides functionality to load and run parser plugins dynamically.
parser/resultdetail
Package resultdetail provides detailed execution result output.
 Package resultdetail provides detailed execution result output.
parser/resultstatus
Package resultstatus provides functionality to parse execution results and determine success/failure status.
 Package resultstatus provides functionality to parse execution results and determine success/failure status.
parser/sample
Package sample provides functionality to parse and process sample outputs from stdout and stderr of the sample program.
 Package sample provides functionality to parse and process sample outputs from stdout and stderr of the sample program.
parser/tierscore
Package tierscore provides a parser for tiered scoring based on time and memory constraints.
 Package tierscore provides a parser for tiered scoring based on time and memory constraints.
stage
Package stage provides functionality to run stages.
 Package stage provides functionality to run stages.
pkg
healthcheck
Package healthcheck provides a set of health checks for a repository.
 Package healthcheck provides a set of health checks for a repository.
sample
Package sample provides a sample function that returns a Result.
 Package sample provides a sample function that returns a Result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.