site: progress on the configuration section

site/src/SUMMARY.md

@@ -13,7 +13,7 @@
     - [Listing](./cargo_maelstrom/listing.md)
     - [Configuration](./cargo_maelstrom/configuration.md)
         - [Execution Environment](./cargo_maelstrom/execution_environment.md)
-        - [Including Files](./cargo_maelstrom/including_files.md)
-        - [Using Container Images](./cargo_maelstrom/using_container_images.md)
+        - [Layers](./cargo_maelstrom/layers.md)
+        - [Container Images](./cargo_maelstrom/container_images.md)
 - [Clustered Job Runner Management](./clustered_job_runner_management.md)
     - [Job States](./clustered_job_runner_management/job_states.md)

site/src/cargo_maelstrom/configuration.md

@@ -1 +1,71 @@
 # Configuration
+
+`cargo-maelstrom` can be configured with two different files. One for
+configuring operation of the command itself, and another for configuring how
+tests are run.
+
+## Configuring `cargo-maelstrom`
+
+The default configuration file path is
+`<workspace-root>/.config/cargo-maelstrom.toml`. This path can be overridden by
+passing the `--config-file` option via the CLI.
+
+It can contain the following options
+- `broker`: the address of the broker to connect to
+- `[run]`: contains options about the `run` sub-command
+    - `quiet`: if true, use quiet mode by default
+    (See [Running Tests >> Terminal Output](./running_tests.html#terminal-output))
+
+## Configuring Tests
+
+The configuration file path for tests is `<workspace-root>/maelstrom-test.toml`.
+
+It can contain the following options
+
+- [`[[directives]]`](#the-directives-section) Defines a directive
+    - [`filter`](#the-filter-field) Directive test filter
+    - [`enable_loopback`](./execution_environment.md#the-enable_loopback-field)
+        Enables loopback device
+    - [`enable_writable_file_system`](
+        ./execution_environment.md#the-enable_writable_file_system-field)
+        Enables files-system writes
+    - [`user`](./execution_environment.md#the-user-field) User test runs as
+    - [`group`](./execution_environment.md#the-group-field) Group test runs as
+    - [`working_directory`](
+        ./execution_environment.md#the-working_directory-field)
+        Test container path used as working directory when running the test
+    - [`mounts`](./execution_environment.md#the-mounts-field) Mounts done in
+        test container
+    - [`devices`](./execution_environment.md#the-devices-field) Devices created
+      in test contaienr
+    - [`environment`](./execution_environment.md#the-environment-field)
+        Environment variables set in test container
+    - [`added_environment`](
+        ./execution_environment.md#the-added_environment-field)
+        Environment variables added to existing ones
+    - [`added_devices`](./execution_environment.md#the-added_devices-field)
+        Devices added to existing ones
+    - [`added_mounts`](./execution_environment.md#the-added_mounts-field)
+        Mounts added to existing ones
+    - [`layers`](#the-layers-field) File-system layers when running the test
+    - [`added_layers`](#the-added_layers-field) File-system layers appended to
+        existing ones
+    - [`include_shared_libraries`](#the-include_shared_libraries-field) Include
+        shared libraries in dependency layer.
+    - [`image`](#the-image-field) Configures a container image
+
+### The `[directives]` section
+
+Each directive contains a filter which describes which tests this directive
+should apply to, and an array of settings about how the tests are run on the
+worker.
+
+### The `filter` field
+
+```toml
+[[directives]]
+filter = "package.equals(foo) && name.equals(bar)"
+```
+
+This contains a [Test Pattern DSL](./test_pattern_dsl.md) snippet that describes
+the set of tests the directive applies to.

site/src/cargo_maelstrom/container_images.md

@@ -0,0 +1 @@
+# Container Images

site/src/cargo_maelstrom/execution_environment.md

@@ -1 +1,126 @@
 # Execution Environment
+
+The fields on this page all control the way the test container is set up. The
+test container is the lightweight container the worker creates and runs a test
+inside.
+
+## The `enable_loopback` field
+
+```toml
+[[directive]]
+enable_loopback = true
+```
+If this field is set to true, the loopback device in the container is ifup'd
+before the test is run.
+
+## The `enable_writable_file_system` field
+
+```toml
+[[directives]]
+enable_writable_file_system = true
+```
+If this field is set to true, the file-system of the test container is made
+writable. If possible, it is better to mount a tmpfs device and use that instead
+of this field.
+
+## The `user` field
+
+```toml
+[[directives]]
+user = "1001"
+```
+The test is ran as whatever user this field is set to. It supports using both a
+UID number and a username.
+
+## The `group` field
+
+```toml
+[[directives]]
+group = "1001"
+```
+The test is ran as whatever group this field is set to. It supports using both a
+GID number and a group name.
+
+## The `working_directory` field
+
+```toml
+[[directives]]
+working_directory = "/home/root/"
+```
+The `working_directory` field is a path inside the test container and used as the
+working directory for the test being run.
+
+## The `mounts` field
+
+```toml
+[[directives]]
+mounts = [
+    { fs_type = "tmp", mount_point = "/tmp" },
+    { fs_type = "proc", mount_point = "/proc" },
+    { fs_type = "sys", mount_point = "/sys" },
+]
+```
+The `mounts` field allows you to mount special file-systems inside the test
+container. The `mount_point` given must be a path that exists in the layers.
+
+Supported values for `fs_type` are:
+- `"tmp"`: [Tmpfs Kernel Docs](https://docs.kernel.org/filesystems/tmpfs.html)
+- `"proc"`: [proc Kernel Docs](https://docs.kernel.org/filesystems/proc.html)
+- `"sys"`: [sysfs Kernel Docs](https://docs.kernel.org/filesystems/sysfs.html)
+
+## The `added_mounts` field
+This is the same as the `mounts` field except the given mounts are added to the
+existing list of `mounts`
+
+## The `devices` field
+
+```toml
+[[directives]]
+devices = ["null", "random", "zero"]
+```
+The `devices` field mounts the given special devices to their corresponding
+path. The path for the device must have some (usually empty) file in the layers
+that the device can be mounted on.
+
+The supported devices are
+- `"full"`: All supported devices
+- `"null"`: `/dev/null`
+- `"random"`: `/dev/random`
+- `"tty"`: `/dev/tty`
+- `"urandom"`: `/dev/urandom`
+- `"zero"`: `/dev/zero`
+
+## The `added_devices` field
+This is the same as the `devices` field except the given devices are added to
+the existing list of devices
+
+## The `environment` field
+```toml
+[[directives]]
+environment = {
+    USER = "bob",
+    RUST_BACKTRACE = "$env{RUST_BACKTRACE:-0}",
+}
+```
+
+This field allows you to set environment variables that will be available when
+executing the test.
+
+When setting the value for environment variables, you can reference some
+other sources.
+
+- `$env` `cargo-maelstrom`'s environment variables
+- `$prev` the previously set environment variables in this directive
+
+You are able to key into these sources by using `{<key>}`. If the source doesn't
+have that key set, you can provide a default value for the key by using `:-`.
+
+```toml
+FOO = "$env{FOO:-bar}"
+```
+This sets the environment variable "FOO" to whatever value is set when running
+`cargo-maelstrom`. If the environment variable isn't set, it is set to "bar"
+
+## The `added_environment` field
+This is the same as the `environment` field except the given environment is
+applied on top of the existing environment

site/src/cargo_maelstrom/layers.md

@@ -0,0 +1 @@
+# Layers

site/src/cargo_maelstrom/running_tests.md

@@ -10,6 +10,7 @@ cargo-maelstrom](../install/cargo_maelstrom.md).)
 We need to provide the address of the broker to cargo-maelstrom. This can be
 done via the command line by passing `--broker`. Since this is required every
 time the command is run, it is easier to provide it via the configuration file.
+See [Configuration](./configuration.md) for more details.
 
 Create a file in `.config/cargo-maelstrom.toml` and put the following contents