diff --git a/src/SUMMARY.md b/src/SUMMARY.md index a2de31d..281b3cc 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -3,6 +3,10 @@ --- - [Getting Started](./getting-started/index.md) -- [Configuration]() - - [Defining Packets]() +- [Configuration](./config/index.md) + - [Runtime](./config/runtime.md) + - [Setup](./config/setup.md) + - [Languages](./config/languages.md) + - [Account](./config/account.md) + - [Packet](./config/packet.md) - [Basalt CLI]() diff --git a/src/config/account.md b/src/config/account.md new file mode 100644 index 0000000..8d5f33e --- /dev/null +++ b/src/config/account.md @@ -0,0 +1,55 @@ +# Account Configuration + +The two types of accounts, [admin](#admin-accounts) and +[competitor](#competitor-accounts) can be specified using the toml array +syntax. + +Competitor accounts and admin accounts must not have the same names. + +```toml +[[accounts.admins]] +name = "Host" +password = "HostP@ssword1" + +[[accounts.competitors]] +name = "Team1" +password = "Team1P@ssword" + +[[accounts.competitors]] +name = "Team2" +password = "Team2P@ssword" +``` + +## Admin Accounts + +Admin accounts have access to the host view when using the basalt app +and can manage the competition at run time. + +## Competitor Accounts + +Competitor accounts have access to the competitor view when using the +basalt app and will test and submit their solutions. + +## Imports + +Account configuration may be imported from another toml file. + +```toml +# In config.toml +accounts = { import = "./accounts.toml" } +``` + +```toml +# In accounts.toml +[[admins]] +name = "Host" +password = "HostP@ssword1" + +[[competitors]] +name = "Team1" +password = "Team1P@ssword" + +[[competitors]] +name = "Team2" +password = "Team2P@ssword" +``` diff --git a/src/config/index.md b/src/config/index.md new file mode 100644 index 0000000..958401d --- /dev/null +++ b/src/config/index.md @@ -0,0 +1,236 @@ +# Configuration + +The configuration of basalt is written using [toml]. +This configuration is used by the [`basalt-cli`] and the [`basalt-server`] +to host a competition. + +[toml]: https://toml.io/en/v1.0.0 +[`basalt-cli`]: https://github.com/basalt-rs/basalt-cli +[`basalt-server`]: https://github.com/basalt-rs/basalt-server + +The configuration is broken up into four main sections: + +- [Runtime Config](./runtime.md) +- [Setup Config](./setup.md) +- [Language Config](./languages.md) +- [Account Config](./account.md) +- [Packet Config](./packet.md) + +## Example + +An example configuration is shown below. + +```toml +# Host competition on port 1234 +port = 1234 + +# Setup configuration +[setup] +# Install `opam` package +install = ''' +apt-get install opam +''' + +# Initialise opam so we can run ocaml +init = ''' +opam init -y +eval $(opam env) +''' + +# Language configuration +[languages] +# Enable python3 default +python3 = "*" +# Enable built-in Java 21 +java = "21" +# Add custom `ocaml` language type +[languges.ocaml] +build = "ocamlc -o out {{SOURCEFILE}}" +run = "./out" + + +# Account configurations +[[accounts.admins]] +name = "Host" +password = "HostP@ssword1" + +[[accounts.competitors]] +name = "Team1" +password = "Team1P@ssword" + +[[accounts.competitors]] +name = "Team2" +password = "Team2P@ssword" + + +# packet configuration +[packet] +title = "Example Packet" +preamble = ''' +This packet includes problems of a difficulty *vastly* +surpassing the capabilities of the average computer +science student. Be wary as these problems will +certainly give you great intellectual trouble. There +is little hope for anyone without a Ph.D in computer +science. + +If you decide to attempt these problems anyways, good +luck. You will be rewarded for swiftness in your answers. +''' + +# Add a problem to this packet that requires the competitor to reverse a +# string +[[packet.problems]] +title = "Reversing a string" +description = ''' +Reversing a string is one of the most _basic_ algorithmic +problems for a beginner computer science student to solve. + +Solve it. +''' + +# Simple "hello" -> "olleh" test +# Since this is the first test that is visible, it will be shown as the +# example to the user. +[[packet.problems.tests]] +input = "hello" +output = "olleh" +visible = true + +[[packet.problems.tests]] +input = "world" +output = "dlrow" +visible = true + +# Test that is not visible, and thus will not show the input or expected +# output to the competitor. +# This test is still used for scoring the competitor's solution. +[[packet.problems.tests]] +input = "" +output = "" + +[[packet.problems.tests]] +input = "aa" +output = "aa" + +[[packet.problems.tests]] +input = "racecar" +output = "racecar" +``` + +## Imports + +Because these configuration files can easily become out of hand, we +offer the ability to import sections of the file using `import`. + +This example shows many sections broken into their own files. Of +course, if only want to take certain sections out, you may. + +```toml +# In config.toml + +port = 1234 # Host competition on port 1234 + +setup = { import = "./setup.toml" } +languages = { import = "./languages.toml" } +accounts = { import = "./accounts.toml" } +packet = { import = "./packet.toml" } +``` + +```toml +# In setup.toml + +# Install `opam` package +install = ''' +apt-get install opam +''' + +# Initialise opam so we can run ocaml +init = ''' +opam init -y +eval $(opam env) +''' +``` + +```toml +# In languages.toml + +python3 = "*" # Enable python3 default +java = "21" # Enable built-in Java 21 + +[ocaml] # Add custom `ocaml` language type +build = "ocamlc -o out {{SOURCEFILE}}" +run = "./out" +``` + +```toml +# In accounts.toml +[[admins]] +name = "Host" +password = "HostP@ssword1" + +[[competitors]] +name = "Team1" +password = "Team1P@ssword" + +[[competitors]] +name = "Team2" +password = "Team2P@ssword" +``` + +```toml +# In packet.toml +title = "Example Packet" +preamble = ''' +This packet includes problems of a difficulty *vastly* +surpassing the capabilities of the average computer +science student. Be wary as these problems will +certainly give you great intellectual trouble. There +is little hope for anyone without a Ph.D in computer +science. + +If you decide to attempt these problems anyways, good +luck. You will be rewarded for swiftness in your answers. +''' + +problems = [{ import = "./problem1.toml" }] +``` + +```toml +# In problem1.toml +title = "Reversing a string" +description = ''' +Reversing a string is one of the most _basic_ algorithmic +problems for a beginner computer science student to solve. + +Solve it. +''' + +# Simple "hello" -> "olleh" test +# Since this is the first test that is visible, it will be shown as the +# example to the user. +[[tests]] +input = "hello" +output = "olleh" +visible = true + +[[tests]] +input = "world" +output = "dlrow" +visible = true + +# Test that is not visible, and thus will not show the input or expected +# output to the competitor. +# This test is still used for scoring the competitor's solution. +[[tests]] +input = "" +output = "" + +[[tests]] +input = "aa" +output = "aa" + +[[tests]] +input = "racecar" +output = "racecar" +``` diff --git a/src/config/languages.md b/src/config/languages.md new file mode 100644 index 0000000..af23eb6 --- /dev/null +++ b/src/config/languages.md @@ -0,0 +1,36 @@ +# Language Config + +Configuration for languages that may be used by competitors. We have a +number of [built-in languages](#built-in-languages), but also offer support for adding [custom +languages](#custom-languages). + +```toml +[languages] +# Enable python3 default +python3 = "*" +# Enable built-in Java 21 +java = "21" +# Add custom `ocaml` language type +[languges.ocaml] +build = "ocamlc -o out {{SOURCEFILE}}" +run = "./out" +``` + +## Built-in Languages + +- `python3` +- `java` + - versions: `8`, `11`, `21` +- `javascript` +- `rust` + +## Custom Languages + +Custom languages may be specified by using a table instead of the +version. + +| Key | Optional | Description | +| ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `build` | true | The command that will be used to build the solution. This is run in a temporary directory that gets deleted after all tests have run, so extra generated files will be removed. | +| `run` | false | The command that will be used to run the solution. This is run in a temporary directory that gets deleted after all tests have run, so extra generated files will be removed. | +| `name` | true | Optional name for this language profile. This will be used in the UI. | diff --git a/src/config/packet.md b/src/config/packet.md new file mode 100644 index 0000000..4595a7d --- /dev/null +++ b/src/config/packet.md @@ -0,0 +1,108 @@ +# Packet Configuration + +Configuration for the packet of questions that is used for prompts and +testing of problems. + +```toml +[packet] +title = "Example Packet" +preamble = ''' +This is an optional preamble that has markdown support. This preamble +will be shown on the first page of the packet. +''' + +[[packet.problems]] +title = "Reversing a string" +description = ''' +Accept a single string as input. You must reverse the order of this +string and print it back out. +''' + +[[packet.problems.tests]] +input = "hello" +output = "olleh" +visible = true +trim_output = true + +[[packet.problems.tests]] +input = "world" +output = "dlrow" +visible = true +trim_output = true + +[[packet.problems.tests]] +input = "" +output = "" +trim_output = true + +[[packet.problems.tests]] +input = "aa" +output = "aa" +trim_output = true + +[[packet.problems.tests]] +input = "racecar" +output = "racecar" +trim_output = true +``` + +## Problems + +The `problems` array contains all of the problems that will be presented +to the user in packet. + +- `title` - the title of this problem, this will also be used as a preview + in the UI. +- `description` - Detailed description of this problem, supports Markdown +- `supported_languages` - Optional list of languages that are allowed + for this problem. All languages must appear in the [Languages + configuration](./languages.md). + +### Tests + +Each problem contains a suite of tests that will be used to validate the +code that the competitor has submitted. + +- `input` - Input that will be provided to the competitor's program + through standard input +- `output` - Expected output that the competitor's code should produce + out to standard output +- `trim_output` - Whether the output should be have starting and trailing + whitespace removed before comparing. i.e., `" hello "` would match + `"hello"` +- `visible` - Whether this test should be visible to the user. The + first visible test listed will be shown as an example in the problem + description. + +## Imports + +Many items in the packet spec may be imported from neighbouring files. + +`packet`: + +```toml +packet = { import = "./packet.toml" } +``` + +`packet.preamble`: + +```toml +[packet] +preamble = { import = "./preamble.md" } +``` + +`packet.problems`: + +```toml +[[packet.problems]] +import = "./problem1.toml" + +[[packet.problems]] +import = "./problem2.toml" + +# OR + +[packet] +problems = [{ import = "./problem1.toml" }, + { import = "./problem2.toml" }] +``` diff --git a/src/config/runtime.md b/src/config/runtime.md new file mode 100644 index 0000000..8a7657f --- /dev/null +++ b/src/config/runtime.md @@ -0,0 +1,14 @@ +# Runtime Configuration + +This configuration section consists of information about how the program +should be run. + +```toml +port = 1234 +``` + +## Fields + +| name | type | range | default | description | +| ------ | ------- | ----------- | ------- | ----------------------------------------------------------- | +| `port` | integer | `0`-`65535` | `8517` | The port on which the server will be exposed to the network | diff --git a/src/config/setup.md b/src/config/setup.md new file mode 100644 index 0000000..4de2d98 --- /dev/null +++ b/src/config/setup.md @@ -0,0 +1,34 @@ +# Setup Configuration + +The setup configuration is used to declare how the docker container +should be built. + +```toml +[setup] +install = ''' +apt-get install opam +''' + +init = ''' +opam init -y +eval $(opam env) +''' +``` + +## Imports + +The value of both `install` and `init` may be replaced with an import to +read from another file: + +```toml +[setup] +install = { import = "./install.sh" } +init = { import = "./init.sh" } +``` + +## Fields + +| name | type | range | default | description | +| ------ | ------- | ----------- | ------- | ----------------------------------------------------------- | +| `install` | string/import | N/A | None | A shell script that will be run while building the docker container. Used for installing programs for language support | +| `init` | string/import | N/A | None | A shell script that will be run before the basalt server is started. Used for initialising environment variables that may be necessary for language support. |