Configuration Values

All Maelstrom executables are configured through "configuration values". Configuration values can be set through commmand-line options, environment variables, or configuration files.

Each configuration value has a type, which is either string, number, or boolean.

Imagine a configuration value named config-value in a program called maelstrom-prog. This configuration value can be specified via:

• The --config-value command-line option.
• The MAELSTROM_PROG_CONFIG_VALUE environment variable.
• The config-value key in a configuration file.

Command-Line Options

Configuration values set on the command line override settings from environment variables or configuration files.

There is currently no way to set a boolean configuration value to false from the command-line.

Environment Variables

Configuration values set via environment variables override settings from configuration files, but are overridden by command-line options.

The environment variable name is created by converting the configuration value to "screaming snake case", and prepending a program-specific prefix. Image that we're evaluating configuration values for a program name "maelstrom-prog":

Note that you don't need to put quotation marks around string values. You also can set boolean values to either true or false.

Configuration Files

Configuration files are in TOML format. In TOML files, configuration values map to keys of the same name. Values types map to the corresponding TOML types. For example:

frob-name = "string"
frob-size = 42
enable-frobs = true
enable-qux = false

Maelstrom programs support the existence of multiple configuration files. In this case, the program will read each one in preference order, with the settings from the higher-preference files overriding those from lower-preference files.

Configuration File Search

By default, Maelstrom programs will use the XDG Base Directory Specification for searching for configuration files.

Specifically, any configuration file found in XDG_CONFIG_HOME has the higest preference, followed by those found in XDG_CONFIG_DIRS. If XDG_CONFIG_HOME is not set, or is empty, then ~/.config/ is used. Similiarly, if XDG_CONFIG_DIRS is not set, or is empty, then /etc/xdg/ is used.

Each program has a program-specific suffix that it appends to the directory it gets from XDG. This has the form maelstrom/prog, where prog is program-specific.

Finally, the program looks for a file named config.toml in these directories.

More concretely, these are where Maelstrom programs will look for configuration files:

For example, if neither XDG_CONFIG_HOME nor XDG_CONFIG_DIRS is set, then cargo-maelstrom will look for two configuration files:

• ~/.config/maelstrom/cargo-maelstrom/config.toml
• /etc/xdg/maelstrom/cargo-maelstrom/config.toml

Overriding Configuration File Location

Maelstrom programs also support the --config-file (-c) command-line option. If this option is provided, the specified configuration file, and only that file, will be used.

If --config-file is given - as an argument, then no configuration file is used.