site: more progress on configuration page

site/src/cargo_maelstrom/configuration.md

@@ -37,7 +37,7 @@ It can contain the following options
     - [`mounts`](./execution_environment.md#the-mounts-field) Mounts done in
         test container
     - [`devices`](./execution_environment.md#the-devices-field) Devices created
-      in test contaienr
+      in test container
     - [`environment`](./execution_environment.md#the-environment-field)
         Environment variables set in test container
     - [`added_environment`](
@@ -47,12 +47,13 @@ It can contain the following options
         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
+    - [`layers`](./layers.md#the-layers-field) File-system layers when running
+        the test
+    - [`added_layers`](./layers.md#the-added_layers-field) File-system layers
+        appended to existing ones
+    - [`include_shared_libraries`](./layers.md#the-include_shared_libraries-field) Include
         shared libraries in dependency layer.
-    - [`image`](#the-image-field) Configures a container image
+    - [`image`](./container_images.md#the-image-field) Configures a container image
 
 ### The `[directives]` section
 
@@ -69,3 +70,5 @@ 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.
+
+If the `filter` field isn't provided, it defaults to matching all tests.

site/src/cargo_maelstrom/container_images.md

@@ -1 +1,53 @@
 # Container Images
+
+`cargo-maelstrom` supports using container images from Docker by using the
+`image` field. These container images are downloaded and cached on the local
+file-system. The `latest` tag is used for these images, and once resolved this
+is stored in the [Container Tags Lockfile](#container-tags-lockfile).
+
+## Cached Container Images
+
+The container images are cached on the local file-system. They are stored in the
+user's cache directory (usually ~/.cache/) under `maelstrom/containers`.
+
+## Container Tags Lockfile
+
+Docker container images have tags which are short strings that resolve to a
+specific image. `cargo-maelstrom` uses the `latest` tag to download an image.
+
+The first time it looks up the image, it resolves the `latest` tag to some hash
+and stores it in the lock file which is stored at
+`<workspace-root>/maelstrom-container-tags.lock`. This locks down the exact
+container image being used, any subsequent resolution of the tag will use what
+is recorded in the lockfile. This file is intended to be committed as part of
+your project's version control.
+
+When you wish to update a given container image to the latest version, remove
+the corresponding line in the lockfile and then rerun `cargo-maelstrom`
+
+## The `image` field
+```toml
+[[directives]]
+image = { name = "rust", use = ["layers", "environment"] }
+```
+
+The `image` field specifies a Docker container image to download and use. The
+`use` field specifies what things should be used from the container image.
+
+- `"layers"` the file-system layers from the container image
+- `"environment"` the environment variables from the container image
+- `"working_directory"` the working directory form the container image
+
+If any of these things are specified with the container image, then the
+corresponding field may not be provided. Instead the `added_*` variants must be
+used.
+
+```toml
+[[directives]]
+image = { name = "rust", use = ["layers", "environment"] }
+added_layers = ["layers/my_other_files.tar"]
+```
+
+This uses the file-system layers from the Docker "rust" container image, but it
+also adds an extra layer containing the things found in
+`layers/my_other_files.tar`.

site/src/cargo_maelstrom/layers.md

@@ -1 +1,47 @@
 # Layers
+
+When a test is run on a worker, it is run inside a lightweight container. The
+file-system for the container is specified by the given layers or container
+image.
+
+The layers are extracted in their own directories, and layered on top of each
+other using an [Overlay
+Filesystem](https://docs.kernel.org/filesystems/overlayfs.html).
+
+`cargo-maelstrom` itself adds some implicit layers which contain the test binary
+itself, and optionally dependencies for the test binary.
+
+## The `layers` Field
+```toml
+[[directives]]
+layers = ["layers/foo.tar", "layers/bar.tar"]
+```
+
+This field provides an ordered list of `.tar` files to be used when creating the
+file-system for the test container. The `.tar` files are layered on top of
+each other in the order provided.
+
+This field can't be used together with the `image` field, since the `image`
+field sets the layers itself. The `added_layers` field can still be used though.
+
+If this field is provided, `include_shared_libraries` is also set to `false`,
+unless it is explicitly set to `true`.
+
+## The `added_layers` Field
+
+This field is just like the `layers` field except that the given layers are
+appended to the existing layers. Also this field works together with the `image`
+field to added extra layers.
+
+## The `include_shared_libraries` field
+
+```toml
+[[directives]]
+include_shared_libraries = true
+```
+
+If this field is set to true, an extra layer containing the shared libraries
+that the test binary depends on is added.
+
+If the `layers` field or `image` field is provided, this option is set to
+`false` by default, otherwise it defaults to `true`.