Maelstrom

https://maelstrom-software.com/doc/book/latest
Admin
Maelstrom is a suite of tools for running tests and arbitrary commands in isolated micro-containers...
Tokens:87,105
Snippets:742
Trust Score:6.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Maelstrom List Configuration Values Example

Source: https://maelstrom-software.com/doc/book/latest/print

Provides an example of how to invoke a Maelstrom program with list-type configuration values. Demonstrates the use of both flag-based and var-args for specifying list elements, illustrating a common invocation pattern.

```shell
maelstrom-prog --args-to-bar=bar-arg-1 --args-to-bar bar-arg-2 -- foo-arg-1 foo-arg-2

```

--------------------------------

### Enable and Start Maelstrom Broker Service (Shell)

Source: https://maelstrom-software.com/doc/book/latest/broker/systemd-service

Commands to enable the maelstrom-broker systemd service to start on boot and then immediately start the service.

```shell
sudo systemctl enable maelstrom-broker
sudo systemctl start maelstrom-broker
```

--------------------------------

### Run Maelstrom Client Tests with cargo-maelstrom in GitHub Actions

Source: https://maelstrom-software.com/doc/book/latest/print

This example shows a GitHub Actions job configured to run tests using `cargo-maelstrom`. It includes checking out the repository, installing and configuring `cargo-maelstrom-action`, and executing the tests.

```yaml
jobs:
  # [Other jobs...]

  run-tests-1:
    name: Run Tests 1
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure cargo-maelstrom
      uses: maelstrom-software/cargo-maelstrom-action@v1
    - name: Run cargo-maelstrom
      run: cargo maelstrom
```

--------------------------------

### pytest-maelstrom TOML Configuration Example

Source: https://maelstrom-software.com/doc/book/latest/print

Example TOML configuration for `pytest-maelstrom.toml`, demonstrating the structure for defining container specifications and directives. It shows interleaved and grouped elements.

```toml
[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

[[directives]]
filter = "package.equals(maelstrom) && name.starts_with(worker::executor::)"
parent = "executor"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[[directives]]
filter = "package.equals(maelstrom) && name.starts_with(worker::executor::tty)"
parent = "executor-with-pts"

```

```toml
[[directives]]
filter = "package.equals(maelstrom) && name.starts_with(worker::executor::)"
parent = "executor"

[[directives]]
filter = "package.equals(maelstrom) && name.starts_with(worker::executor::tty)"
parent = "executor-with-pts"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

```

--------------------------------

### GitHub Actions Workflow for Maelstrom CI

Source: https://maelstrom-software.com/doc/book/latest/print

This workflow automates the setup and execution of Maelstrom tests within a GitHub Actions environment. It includes jobs for starting the Maelstrom broker and workers, running tests using different language-specific actions (Rust/Cargo and Go), and finally stopping the cluster. Dependencies include various Maelstrom GitHub Actions for each job.

```yaml
jobs:
  maelstrom-broker:
    name: Maelstrom Broker
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Broker
      uses: maelstrom-software/maelstrom-broker-action@v1

  maelstrom-worker:
    strategy:
      matrix:
        worker-number: [1, 2, 3, 4]
    name: Maelstrom Worker ${{ matrix.worker-number }}
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Worker
      uses: maelstrom-software/maelstrom-worker-action@v1

  run-tests-1:
    name: Run Tests 1
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure cargo-maelstrom
      uses: maelstrom-software/cargo-maelstrom-action@v1
    - name: Run cargo-maelstrom
      run: cargo maelstrom

  run-tests-2:
    name: Run Tests 2
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure maelstrom-go-test
      uses: maelstrom-software/maelstrom-go-test-action@v1
    - name: Run cargo-maelstrom
      run: maelstrom-go-test

  stop-maelstrom:
    name: Stop Maelstrom Cluster
    runs-on: ubuntu-24.04
    if: ${{ always() }}
    needs: [run-tests-1, run-tests-2]
    steps:
    - name: Install and Configure maelstrom-admin
      uses: maelstrom-software/maelstrom-admin-action@v1
    - name: Stop Maelstrom Cluster
      run: maelstrom-admin stop

```

--------------------------------

### JSON examples using $env{} for client environment variables

Source: https://maelstrom-software.com/doc/book/latest/spec

Demonstrates using the `$env{}` syntax within `EnvironmentSpec` to import variables from the client's environment. Includes an example with a default value using `:-`.

```json
[{
    "vars": {
        "FOO": "$env{FOO}",
        "RUST_BACKTRACE": "$env{RUST_BACKTRACE:-0}"
    },
    "extend": false
}]
```

--------------------------------

### EnvironmentSpec JSON examples

Source: https://maelstrom-software.com/doc/book/latest/spec

Illustrates basic JSON structures for `EnvironmentSpec` with and without the `extend` flag set to `true`. These examples show how to define a simple map of environment variables.

```json
[{ "vars": { "FOO": "foo", "BAR": "bar" }, "extend": false }]
```

```json
[{ "vars": { "FOO": "foo", "BAR": "bar" }, "extend": true }]
```

--------------------------------

### JSON example using $prev{} for inherited environment variables

Source: https://maelstrom-software.com/doc/book/latest/spec

Shows how to use the `$prev{}` syntax in `EnvironmentSpec` to reference environment variables from an image ancestor or earlier elements in the configuration.

```json
[{ "vars": { "PATH": "/my-bin:$prev{PATH}" }, "extend": true }]
```

```json
[{ "vars": { "FOO": "$prev{FOO}", "BAR": "$prev{BAR}" }, "extend": false }]
```

--------------------------------

### cargo-maelstrom.toml Configuration Example (Grouped)

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/spec/format

An example of the `cargo-maelstrom.toml` file with elements grouped by type (directives first, then containers). This format highlights the separation of concerns but still allows containers to be referenced before their full definition.

```toml
[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::)"
parent = "executor"

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::tests::tty_)"
parent = "executor-with-pts"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

```

--------------------------------

### Container Layers Configuration Example

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/spec/containers

This example demonstrates the structure for defining container layers. It includes various types of layers such as tar, glob, paths, stubs, symlinks, and shared-library-dependencies, showcasing different configuration options available for each layer type.

```toml
[container.example]
layers = [
    { tar = "layers/foo.tar" },
    { paths = ["layers/a/b.bin", "layers/a/c.bin"], strip_prefix = "layers/a/" },
    { glob = "layers/b/**", strip_prefix = "layers/b/" },
    { stubs = ["/dev/{null, full}", "/proc/"] },
    { symlinks = [{ link = "/dev/stdout", target = "/proc/self/fd/1" }] },
    { shared-library-dependencies = ["/bin/bash"], prepend_prefix = "/usr" }
]

```

--------------------------------

### TOML Configuration File Example

Source: https://maelstrom-software.com/doc/book/latest/print

Illustrates the structure of a TOML configuration file used by Maelstrom programs. Configuration values map directly to keys, and data types correspond to TOML types. Multiple configuration files can be used, with settings from higher-preference files overriding lower-preference ones.

```toml
# Example configuration file (e.g., config.toml)

frob-name = "string"
frob-size = 42
enable-frobs = true
enable-qux = false
frobs = ["some", "list", "elements"]

# Example for a list with whitespace (note: currently not supported for elements)
# This would be interpreted as a single element with internal whitespace if supported:
# frobs = ["element with space"]

# Empty list example
empty_list = []
```

--------------------------------

### Enable and Start Maelstrom Worker Service (Shell)

Source: https://maelstrom-software.com/doc/book/latest/worker/systemd-service

Enables the 'maelstrom-worker' systemd service to start on boot and then immediately starts the service. This command assumes the service file has already been created and configured.

```shell
sudo systemctl enable maelstrom-worker
sudo systemctl start maelstrom-worker
```

--------------------------------

### Full Maelstrom CI Workflow Setup with Cluster Management

Source: https://maelstrom-software.com/doc/book/latest/github

This YAML configuration outlines a comprehensive GitHub Actions workflow for Maelstrom. It includes jobs for starting the Maelstrom broker and multiple workers, running tests using different runners (`cargo-maelstrom` and `maelstrom-go-test`), and a dedicated job to stop the Maelstrom cluster using `maelstrom-admin-action`, ensuring cleanup even after test failures. The worker job utilizes a matrix strategy to run multiple worker instances.

```yaml
jobs:
  maelstrom-broker:
    name: Maelstrom Broker
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Broker
      uses: maelstrom-software/maelstrom-broker-action@v1

  maelstrom-worker:
    strategy:
      matrix:
        worker-number: [1, 2, 3, 4]
    name: Maelstrom Worker ${{ matrix.worker-number }}
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Worker
      uses: maelstrom-software/maelstrom-worker-action@v1

  run-tests-1:
    name: Run Tests 1
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure cargo-maelstrom
      uses: maelstrom-software/cargo-maelstrom-action@v1
    - name: Run cargo-maelstrom
      run: cargo maelstrom

  run-tests-2:
    name: Run Tests 2
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure maelstrom-go-test
      uses: maelstrom-software/maelstrom-go-test-action@v1
    - name: Run cargo-maelstrom
      run: maelstrom-go-test

  stop-maelstrom:
    name: Stop Maelstrom Cluster
    runs-on: ubuntu-24.04
    if: ${{ always() }}
    needs: [run-tests-1, run-tests-2]
    steps:
    - name: Install and Configure maelstrom-admin
      uses: maelstrom-software/maelstrom-admin-action@v1
    - name: Stop Maelstrom Cluster
      run: maelstrom-admin stop
```

--------------------------------

### Initialize cargo-maelstrom.toml Configuration

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/spec/initializing

This command initializes the 'cargo-maelstrom.toml' file in the workspace root. If the file does not exist, it will be created with the default configuration and commented-out examples. If the file already exists, the command will exit without making changes.

```shell
cargo maelstrom --init

```

--------------------------------

### Start Maelstrom Broker in GitHub Actions

Source: https://maelstrom-software.com/doc/book/latest/github

This snippet shows how to define a GitHub Actions job to start the Maelstrom broker. It uses the `maelstrom-software/maelstrom-broker-action@v1` to initiate the broker service, which is essential for managing Maelstrom clusters within a workflow.

```yaml
jobs:
  # [Other jobs...]

  maelstrom-broker:
    name: Maelstrom Broker
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Broker
      uses: maelstrom-software/maelstrom-broker-action@v1
```

--------------------------------

### Initialize maelstrom-pytest.toml Configuration

Source: https://maelstrom-software.com/doc/book/latest/pytest/spec/initializing

This command initializes the `maelstrom-pytest.toml` configuration file if it does not already exist. The generated file includes default settings and commented-out examples for customization. No external dependencies are required beyond the `maelstrom-pytest` tool itself.

```bash
maelstrom-pytest --init
```

--------------------------------

### cargo-maelstrom.toml Configuration Example (Interleaved)

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/spec/format

An example of the `cargo-maelstrom.toml` file showing interleaved container and directive definitions. This format demonstrates how containers and directives can be defined in any order within their respective top-level sections, with the exception of the order of directives in the `directives` array.

```toml
[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::)"
parent = "executor"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::tests::tty_)"
parent = "executor-with-pts"

```

--------------------------------

### Example Maelstrom Job Specification (JSON)

Source: https://maelstrom-software.com/doc/book/latest/run/spec

A basic example demonstrating the JSON format for specifying jobs in Maelstrom. Each JSON object represents a single job with 'image', 'program', and 'arguments' fields.

```json
{
        "image": "docker://alpine",
        "program": "echo",
        "arguments": ["Hello", "world!"]
}
{
        "image": "docker://alpine",
        "program": "echo",
        "arguments": ["¡Hola", "mundo!"]
}
```

--------------------------------

### JSON example with multiple EnvironmentSpec elements

Source: https://maelstrom-software.com/doc/book/latest/spec

Illustrates the processing order and merging behavior of multiple `EnvironmentSpec` elements in a job configuration, including interactions between `$env{}` and `$prev{}`.

```json
[
    { "vars": { "FOO": "foo1", "BAR": "bar1" }, "extend": false },
    { "vars": { "FOO": "foo2", "BAZ": "$env{BAZ}" }, "extend": true },
    { "vars": { "FOO": "$prev{BAZ}", "BAR": "$prev{BAR}" }, "extend": false },
]
```

--------------------------------

### CARGO MAELSTROM TOML: Define Containers and Directives

Source: https://maelstrom-software.com/doc/book/latest/print

Example TOML configuration for `cargo-maelstrom.toml`, demonstrating the structure for defining container specifications and directives. It shows interleaved and grouped elements for clarity, illustrating how containers can reference each other.

```toml
[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::)"
parent = "executor"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::tests::tty_)"
parent = "executor-with-pts"

```

```toml
[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::)"
parent = "executor"

[[directives]]
filter = "package.equals(maelstrom-worker) && name.starts_with(executor::tests::tty_)"
parent = "executor-with-pts"

[containers.executor-with-pts]
parent = "executor"
added_layers = [
    { stubs = [ "dev/pts/" ] },
    { symlinks = [ { link = "/dev/ptmx", target = "/dev/pts/ptmx" } ] },
]
added_mounts = [
    { type = "devpts", mount_point = "/dev/pts" },
]

[containers.executor]
layers = [
    { stubs = [ "{proc,tmp}/", "dev/{null,random,urandom,zero}" ] },
]
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "devices", devices = ["null", "random", "urandom", "zero"] },
]

```

--------------------------------

### Environment Variable Configuration Examples

Source: https://maelstrom-software.com/doc/book/latest/print

Demonstrates how configuration values are translated into environment variable names for Maelstrom programs. Environment variable names are formed by converting configuration keys to screaming snake case and prepending a program-specific prefix. Boolean values can be 'true' or 'false', and list values are whitespace-delimited.

```bash
# Example for a program named 'maelstrom-prog'

# String configuration value 'frob-name'
export MAELSTROM_PROG_FROB_NAME="some string"

# Number configuration value 'frob-size'
export MAELSTROM_PROG_FROB_SIZE=42

# Boolean configuration value 'enable-frobs' set to true
export MAELSTROM_PROG_ENABLE_FROBS=true

# Boolean configuration value 'enable-frobs' set to false
export MAELSTROM_PROG_ENABLE_FROBS=false

# List configuration value 'frobs'
export MAELSTROM_PROG_FROBS="element1 element2 element3"

# Empty list configuration value
export MAELSTROM_PROG_EMPTY_LIST=""
export MAELSTROM_PROG_EMPTY_LIST_WHITESPACE="   "

# Generic Maelstrom environment variable example (e.g., for 'broker')
export MAELSTROM_BROKER="tcp://localhost:9001"

# Program-specific generic example (e.g., 'cargo-maelstrom' checking 'manifest-path')
export MAELSTROM_MANIFEST_PATH="/path/to/Cargo.toml"
```

--------------------------------

### Maelstrom Go Test: Simple Pattern Language Examples

Source: https://maelstrom-software.com/doc/book/latest/print

Illustrates the basic 'simple selectors' of maelstrom-go-test's pattern language, used for filtering tests. These include 'true', 'any', 'all' to match any test, and 'false', 'none' to match no tests.

```plaintext
true
any
all
all()
false
none
```

--------------------------------

### Add Environment Variables to Containers

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/spec/containers

Illustrates how to add environment variables to a container specification, either by prepending to or merging with inherited environment variables. Example 1 shows explicit variable additions with `extend` flags, while Example 2 demonstrates a more concise syntax for setting environment variables, including using `$env{}` for dynamic values.

```toml
# Example 1.
# The end result will be two environment variables, PATH and USER. PATH will contain
# "/foo/bar/bin:" prepended to the PATH inherited from "parent". USER will be "bob".
[container.example-1]
parent = "parent"
added_environment = [
    { vars = { PATH = "/foo/bar/bin:$prev{PATH}" }, extend = false },
    { vars = { USER = "bob" }, extend = true },
]

# Example 2.
# The end result will be the union of the environment variables inherited from the
# specified image, plus USER, PATH, and RUST_BACKTRACE. PATH and BOB will be
# set as above. RUST_BACKTRACE will be taken from the client's environment
# variables, unless the client doesn't have that variable set, in which case it
# will be set to "0".
[container.example-2]
image = "docker://rust"
added_environment.USER = "bob"
added_environment.PATH = "/foo/bar/bin:$prev{PATH}"
added_environment.RUST_BACKTRACE = "$env{RUST_BACKTRACE:-0}"

```

--------------------------------

### Package Import Path Abbreviation Examples

Source: https://maelstrom-software.com/doc/book/latest/go-test/filter

Demonstrates special abbreviation rules for 'package_import_path', where any prefix of 'package' resolves to it, unlike other package selectors.

```text
package_import_path.equals(foo)
package_i.equals(foo)
package.equals(foo)
p.equals(foo)
```

--------------------------------

### Container Spec with Named Parent (Specific 'use')

Source: https://maelstrom-software.com/doc/book/latest/print

This example shows a container specification where a named parent is specified with a 'use' sub-field. The 'use' field is a list of strings, indicating which specific fields (e.g., 'layers', 'environment') should be inherited from the parent container.

```hcl
container {
  name = "my-container"
  parent = {
    name = "other-container"
    use = ["layers", "environment"]
  }
}
```

--------------------------------

### Selector and Matcher Abbreviations

Source: https://maelstrom-software.com/doc/book/latest/print

Demonstrates how selector and matcher names in Maelstrom can be shortened to any unambiguous prefix. This improves conciseness in code. Example shows 'name.equals(foo)' can be shortened to 'n.eq(foo)' if 'n' and 'eq' are unambiguous.

```plaintext
__
name.equals(foo)
name.eq(foo)
n.eq(foo)

```

--------------------------------

### Container Spec with Named Parent (No 'use')

Source: https://maelstrom-software.com/doc/book/latest/print

This example demonstrates setting a container specification with a named parent container. When the 'parent' field is a string, it implies inheritance of all available fields from the parent, as no 'use' sub-field is specified.

```hcl
container {
  name = "my-container"
  parent = "other-container"
}
```

--------------------------------

### Maelstrom Default Directives Without Parent/Image

Source: https://maelstrom-software.com/doc/book/latest/print

This example illustrates Maelstrom directives used when 'parent' or 'image' are not specified. In this scenario, 'added_layers', 'added_environment', and 'added_mounts' are additive and always allowed. 'layers', 'environment', and 'mounts' overwrite existing fields.

```toml
# Because it has no `filter` field, this directive applies to all tests.
[[directives]]

# This layer just includes files and directories for mounting the following
# file-systems and devices.
layers = [
    { stubs = [ "/{proc,sys,tmp}/", "/dev/{full,null,random,urandom,zero}" ] },
]

# Provide /tmp, /proc, /sys, and some devices in /dev/. These are used pretty
# commonly by tests.
mounts = [
    { type = "tmp", mount_point = "/tmp" },
    { type = "proc", mount_point = "/proc" },
    { type = "sys", mount_point = "/sys" },
    { type = "devices", devices = ["full", "null", "random", "urandom", "zero"] },
]

# Forward the RUST_BACKTRACE and RUST_LIB_BACKTRACE environment variables.
# Later directives can override the `environment` key, but the `added_environment` key is only
# additive. By using it here we ensure it applies to all tests regardless of other directives.
[directives.added_environment]
RUST_BACKTRACE = "$env{RUST_BACKTRACE:-0}"
RUST_LIB_BACKTRACE = "$env{RUST_LIB_BACKTRACE:-0}"


```

--------------------------------

### Run Maelstrom Client Jobs in GitHub Actions

Source: https://maelstrom-software.com/doc/book/latest/github

This configuration demonstrates how to set up GitHub Actions to run Maelstrom client jobs. It includes steps for checking out the repository, installing and configuring test runners such as `cargo-maelstrom-action` and `maelstrom-go-test-action`, and executing the tests. It also shows how to ensure the Maelstrom cluster is stopped using `maelstrom-admin-action` even if test jobs fail.

```yaml
jobs:
  # [Other jobs...]

  run-tests-1:
    name: Run Tests 1
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure cargo-maelstrom
      uses: maelstrom-software/cargo-maelstrom-action@v1
    - name: Run cargo-maelstrom
      run: cargo maelstrom

  run-tests-2:
    name: Run Tests 2
    runs-on: ubuntu-24.04
    steps:
    - name: Check Out Repository
      uses: actions/checkout@v4
    - name: Install and Configure maelstrom-go-test
      uses: maelstrom-software/maelstrom-go-test-action@v1
    - name: Run cargo-maelstrom
      run: maelstrom-go-test

  stop-maelstrom:
    name: Stop Maelstrom Cluster
    runs-on: ubuntu-24.04
    if: ${{ always() }}
    needs: [run-tests-1, run-tests-2]
    steps:
    - name: Install and Configure maelstrom-admin
      uses: maelstrom-software/maelstrom-admin-action@v1
    - name: Stop Maelstrom Cluster
      run: maelstrom-admin stop
```

--------------------------------

### Container Spec with Named Parent (Added Layers)

Source: https://maelstrom-software.com/doc/book/latest/print

This example illustrates using the 'added_layers' pseudo-field to prepend new layers to inherited layers from a parent container. This method allows extending inherited configurations without losing them. It requires the parent to have the 'layers' field in its 'use' set.

```hcl
container {
  name = "my-container"
  parent = {
    name = "other-container"
    use = ["layers"]
  }
  added_layers = [
    "my-custom-layer"
  ]
}
```

--------------------------------

### Start Maelstrom Workers in GitHub Actions

Source: https://maelstrom-software.com/doc/book/latest/github

This snippet demonstrates how to configure GitHub Actions jobs to launch multiple Maelstrom worker instances. It utilizes a matrix strategy to scale the number of workers and employs the `maelstrom-software/maelstrom-worker-action@v1` for each worker. The worker architecture must align with the client jobs.

```yaml
jobs:
  # [Other jobs...]

  maelstrom-worker:
    strategy:
      matrix:
        worker-number: [1, 2, 3, 4]
    name: Maelstrom Worker ${{ matrix.worker-number }}
    runs-on: ubuntu-24.04
    steps:
    - name: Install and Run Maelstrom Worker
      uses: maelstrom-software/maelstrom-worker-action@v1
```

--------------------------------

### Maelstrom Directives with Parent/Image Reset

Source: https://maelstrom-software.com/doc/book/latest/print

This example shows how Maelstrom directives can specify 'parent' or 'image' fields, which reset all other container spec fields. This ensures a clean slate for tests matching the directive, though fields like 'timeout' are retained as they are not container spec fields.

```toml
__
[[directives]]
user = 42
added_layers = [{ stubs = ["/tmp/"] }]
added_mounts = [{ type = "tmp", mount_point = "/tmp" }]
timeout = 10

[[directives]]
filter = "package.eq(cargo-maelstrom) && test.contains(integration)"
image = "docker://rust"


```

--------------------------------

### Create Maelstrom Broker User and Files (Shell)

Source: https://maelstrom-software.com/doc/book/latest/broker/systemd-service

Creates a dedicated non-privileged user 'maelstrom-broker', sets up necessary directories and files, and copies the broker binary. Assumes the binary is located in '~/.cargo/bin/'.

```shell
sudo adduser --disabled-login --gecos "Maelstrom Broker User" maelstrom-broker
sudo -u maelstrom-broker mkdir ~maelstrom-broker/cache
sudo -u maelstrom-broker touch ~maelstrom-broker/config.toml
sudo cp ~/.cargo/bin/maelstrom-broker ~maelstrom-broker/
```

--------------------------------

### Maelstrom Command-Line Options for Configuration

Source: https://maelstrom-software.com/doc/book/latest/print

Details the syntax for setting configuration values via command-line arguments. Covers different formats for strings and numbers, boolean flags, and how list-type values can be specified using flags or var-args. Notes limitations such as setting boolean false or empty lists.

```markdown
Type| Example  
---|---  
string| `--frob-name=string`  
string| `--frob-name string`  
number| `--frob-size=42`  
number| `--frob-size 42`  
boolean| `--enable-frobs`  
list as flags| `--extra-args=some --extra-args=list --extra-args=elements`  
list as var-args| `-- some list elements`  
```

--------------------------------

### Abbreviated Selector and Matcher Example

Source: https://maelstrom-software.com/doc/book/latest/cargo-maelstrom/filter

This example shows how selector and matcher names can be shortened to their unambiguous prefixes. 'name.equals(foo)' can be abbreviated to 'n.eq(foo)' because 'n' is unambiguous for 'name' and 'eq' is unambiguous for 'equals' in this context.

```text
name.equals(foo)
name.eq(foo)
n.eq(foo)
```
Tokens:
Raw