Skip to content

Commit 38112b2

Browse files
funnyboy-roksfunnyboy-roks
authored
Merge pull request #1 from basalt-rs/config-docs
Config docs
2 parents 6c6bf64 + 71198ef commit 38112b2

File tree

7 files changed

+489
-2
lines changed

7 files changed

+489
-2
lines changed

‎src/SUMMARY.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
---
44

55
- [Getting Started](./getting-started/index.md)
6-
- [Configuration]()
7-
- [Defining Packets]()
6+
- [Configuration](./config/index.md)
7+
- [Runtime](./config/runtime.md)
8+
- [Setup](./config/setup.md)
9+
- [Languages](./config/languages.md)
10+
- [Account](./config/account.md)
11+
- [Packet](./config/packet.md)
812
- [Basalt CLI]()

‎src/config/account.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Account Configuration
2+
3+
The two types of accounts, [admin](#admin-accounts) and
4+
[competitor](#competitor-accounts) can be specified using the toml array
5+
syntax.
6+
7+
Competitor accounts and admin accounts must not have the same names.
8+
9+
```toml
10+
[[accounts.admins]]
11+
name = "Host"
12+
password = "HostP@ssword1"
13+
14+
[[accounts.competitors]]
15+
name = "Team1"
16+
password = "Team1P@ssword"
17+
18+
[[accounts.competitors]]
19+
name = "Team2"
20+
password = "Team2P@ssword"
21+
```
22+
23+
## Admin Accounts
24+
25+
Admin accounts have access to the host view when using the basalt app
26+
and can manage the competition at run time.
27+
28+
## Competitor Accounts
29+
30+
Competitor accounts have access to the competitor view when using the
31+
basalt app and will test and submit their solutions.
32+
33+
## Imports
34+
35+
Account configuration may be imported from another toml file.
36+
37+
```toml
38+
# In config.toml
39+
accounts = { import = "./accounts.toml" }
40+
```
41+
42+
```toml
43+
# In accounts.toml
44+
[[admins]]
45+
name = "Host"
46+
password = "HostP@ssword1"
47+
48+
[[competitors]]
49+
name = "Team1"
50+
password = "Team1P@ssword"
51+
52+
[[competitors]]
53+
name = "Team2"
54+
password = "Team2P@ssword"
55+
```

‎src/config/index.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Configuration
2+
3+
The configuration of basalt is written using [toml].
4+
This configuration is used by the [`basalt-cli`] and the [`basalt-server`]
5+
to host a competition.
6+
7+
[toml]: https://toml.io/en/v1.0.0
8+
[`basalt-cli`]: https://github.com/basalt-rs/basalt-cli
9+
[`basalt-server`]: https://github.com/basalt-rs/basalt-server
10+
11+
The configuration is broken up into four main sections:
12+
13+
- [Runtime Config](./runtime.md)
14+
- [Setup Config](./setup.md)
15+
- [Language Config](./languages.md)
16+
- [Account Config](./account.md)
17+
- [Packet Config](./packet.md)
18+
19+
## Example
20+
21+
An example configuration is shown below.
22+
23+
```toml
24+
# Host competition on port 1234
25+
port = 1234
26+
27+
# Setup configuration
28+
[setup]
29+
# Install `opam` package
30+
install = '''
31+
apt-get install opam
32+
'''
33+
34+
# Initialise opam so we can run ocaml
35+
init = '''
36+
opam init -y
37+
eval $(opam env)
38+
'''
39+
40+
# Language configuration
41+
[languages]
42+
# Enable python3 default
43+
python3 = "*"
44+
# Enable built-in Java 21
45+
java = "21"
46+
# Add custom `ocaml` language type
47+
[languges.ocaml]
48+
build = "ocamlc -o out {{SOURCEFILE}}"
49+
run = "./out"
50+
51+
52+
# Account configurations
53+
[[accounts.admins]]
54+
name = "Host"
55+
password = "HostP@ssword1"
56+
57+
[[accounts.competitors]]
58+
name = "Team1"
59+
password = "Team1P@ssword"
60+
61+
[[accounts.competitors]]
62+
name = "Team2"
63+
password = "Team2P@ssword"
64+
65+
66+
# packet configuration
67+
[packet]
68+
title = "Example Packet"
69+
preamble = '''
70+
This packet includes problems of a difficulty *vastly*
71+
surpassing the capabilities of the average computer
72+
science student. Be wary as these problems will
73+
certainly give you great intellectual trouble. There
74+
is little hope for anyone without a Ph.D in computer
75+
science.
76+
77+
If you decide to attempt these problems anyways, good
78+
luck. You will be rewarded for swiftness in your answers.
79+
'''
80+
81+
# Add a problem to this packet that requires the competitor to reverse a
82+
# string
83+
[[packet.problems]]
84+
title = "Reversing a string"
85+
description = '''
86+
Reversing a string is one of the most _basic_ algorithmic
87+
problems for a beginner computer science student to solve.
88+
89+
Solve it.
90+
'''
91+
92+
# Simple "hello" -> "olleh" test
93+
# Since this is the first test that is visible, it will be shown as the
94+
# example to the user.
95+
[[packet.problems.tests]]
96+
input = "hello"
97+
output = "olleh"
98+
visible = true
99+
100+
[[packet.problems.tests]]
101+
input = "world"
102+
output = "dlrow"
103+
visible = true
104+
105+
# Test that is not visible, and thus will not show the input or expected
106+
# output to the competitor.
107+
# This test is still used for scoring the competitor's solution.
108+
[[packet.problems.tests]]
109+
input = ""
110+
output = ""
111+
112+
[[packet.problems.tests]]
113+
input = "aa"
114+
output = "aa"
115+
116+
[[packet.problems.tests]]
117+
input = "racecar"
118+
output = "racecar"
119+
```
120+
121+
## Imports
122+
123+
Because these configuration files can easily become out of hand, we
124+
offer the ability to import sections of the file using `import`.
125+
126+
This example shows many sections broken into their own files. Of
127+
course, if only want to take certain sections out, you may.
128+
129+
```toml
130+
# In config.toml
131+
132+
port = 1234 # Host competition on port 1234
133+
134+
setup = { import = "./setup.toml" }
135+
languages = { import = "./languages.toml" }
136+
accounts = { import = "./accounts.toml" }
137+
packet = { import = "./packet.toml" }
138+
```
139+
140+
```toml
141+
# In setup.toml
142+
143+
# Install `opam` package
144+
install = '''
145+
apt-get install opam
146+
'''
147+
148+
# Initialise opam so we can run ocaml
149+
init = '''
150+
opam init -y
151+
eval $(opam env)
152+
'''
153+
```
154+
155+
```toml
156+
# In languages.toml
157+
158+
python3 = "*" # Enable python3 default
159+
java = "21" # Enable built-in Java 21
160+
161+
[ocaml] # Add custom `ocaml` language type
162+
build = "ocamlc -o out {{SOURCEFILE}}"
163+
run = "./out"
164+
```
165+
166+
```toml
167+
# In accounts.toml
168+
[[admins]]
169+
name = "Host"
170+
password = "HostP@ssword1"
171+
172+
[[competitors]]
173+
name = "Team1"
174+
password = "Team1P@ssword"
175+
176+
[[competitors]]
177+
name = "Team2"
178+
password = "Team2P@ssword"
179+
```
180+
181+
```toml
182+
# In packet.toml
183+
title = "Example Packet"
184+
preamble = '''
185+
This packet includes problems of a difficulty *vastly*
186+
surpassing the capabilities of the average computer
187+
science student. Be wary as these problems will
188+
certainly give you great intellectual trouble. There
189+
is little hope for anyone without a Ph.D in computer
190+
science.
191+
192+
If you decide to attempt these problems anyways, good
193+
luck. You will be rewarded for swiftness in your answers.
194+
'''
195+
196+
problems = [{ import = "./problem1.toml" }]
197+
```
198+
199+
```toml
200+
# In problem1.toml
201+
title = "Reversing a string"
202+
description = '''
203+
Reversing a string is one of the most _basic_ algorithmic
204+
problems for a beginner computer science student to solve.
205+
206+
Solve it.
207+
'''
208+
209+
# Simple "hello" -> "olleh" test
210+
# Since this is the first test that is visible, it will be shown as the
211+
# example to the user.
212+
[[tests]]
213+
input = "hello"
214+
output = "olleh"
215+
visible = true
216+
217+
[[tests]]
218+
input = "world"
219+
output = "dlrow"
220+
visible = true
221+
222+
# Test that is not visible, and thus will not show the input or expected
223+
# output to the competitor.
224+
# This test is still used for scoring the competitor's solution.
225+
[[tests]]
226+
input = ""
227+
output = ""
228+
229+
[[tests]]
230+
input = "aa"
231+
output = "aa"
232+
233+
[[tests]]
234+
input = "racecar"
235+
output = "racecar"
236+
```

‎src/config/languages.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Language Config
2+
3+
Configuration for languages that may be used by competitors. We have a
4+
number of [built-in languages](#built-in-languages), but also offer support for adding [custom
5+
languages](#custom-languages).
6+
7+
```toml
8+
[languages]
9+
# Enable python3 default
10+
python3 = "*"
11+
# Enable built-in Java 21
12+
java = "21"
13+
# Add custom `ocaml` language type
14+
[languges.ocaml]
15+
build = "ocamlc -o out {{SOURCEFILE}}"
16+
run = "./out"
17+
```
18+
19+
## Built-in Languages
20+
21+
- `python3`
22+
- `java`
23+
- versions: `8`, `11`, `21`
24+
- `javascript`
25+
- `rust`
26+
27+
## Custom Languages
28+
29+
Custom languages may be specified by using a table instead of the
30+
version.
31+
32+
| Key | Optional | Description |
33+
| ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34+
| `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. |
35+
| `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. |
36+
| `name` | true | Optional name for this language profile. This will be used in the UI. |

0 commit comments

Comments
 (0)