diff --git a/site/src/cargo_maelstrom/configuration.md b/site/src/cargo_maelstrom/configuration.md index 61075bac..c817a387 100644 --- a/site/src/cargo_maelstrom/configuration.md +++ b/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. diff --git a/site/src/cargo_maelstrom/container_images.md b/site/src/cargo_maelstrom/container_images.md index 63f04e55..55675f56 100644 --- a/site/src/cargo_maelstrom/container_images.md +++ b/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 +`/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`. diff --git a/site/src/cargo_maelstrom/layers.md b/site/src/cargo_maelstrom/layers.md index 488c8d16..0a4acfac 100644 --- a/site/src/cargo_maelstrom/layers.md +++ b/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`.