dotfiles/.config/voidshell/README.md

VoidShell Configuration

VoidShell is configured using a YAML file consisting of multiple top-level objects:

• outputs contains output definitions, which are referenced elsewhere by name
• workspaces contains worksapce definitions, which are referenced by ID
• layouts contains information about various output layouts that VoidShell will attempt to load when connected outputs change
• contexts contains information about a "context", which describes what workspaces should be present on which outputs and in what order, based on the current layout
• config contains global configuration variables that can be referenced elsewhere in the config file using Python format string syntax ({var_name}). Due to limitations with Python's format function, this object must be flat, i.e., contain only primitive values.

Additionally, there is a top-level import directive, which takes a list of file paths to other YAML files, allowing composable configuration. Relative paths are interpreted as being from the location of the main config file, not the file in which the import directive appears. If a listed file does not exist, it is ignored.

Imports are processed in a depth-first manner.

Finally, there is a top-level default-context directive, which specifies which context VoidShell should start in. If not specified, the first non-default context will be used, unless default is the only defined context in which case default will be used.

Output Section

The output section defines the display outputs known to VoidShell. These are physical monitors, identified by various criteria, but should form a one-to-one mapping from the definition to the monitor. This should generally be accomplished by including make, model, and serial number, but for a laptop, the name eDP-1 will nearly always refer exclusively to the built-in display, making it useful for those laptop panels which do not report a serial number in their EDIDs.

It consists of a mapping of internal output name to output definition.

Multiple output sections are concatenated together. If an output is defined twice, the definitions will be merged, with later appearances overwriting duplicate keys, unless stated otherwise.

Structure

• criteria: Match criteria. The following criteria are available, and all must match for the output to be used:
  • name: The name of the output as reported by the compositor. This changes based on what port the monitor is plugged into, and should therefore not be used for any external displays unless absolutely necessary. Can also be a list of names, in which case will match on any of them (OR filter)
  • hostname: The hostname of the computer VoidShell is running on. Can also be a list of hostnames, in which case will match on any of them (OR filter)
  • make: The make of the monitor, reported by EDID
  • model: The model of the monitor, reported by EDID
  • serial: The serial "number" of the monitor, reported by EDID
  • modes: A list of modes which must be available. All modes listed must be available (AND filter). Undefined attributes are ignored (wildcard match).
    • width: The width in pixels
    • height: The height in pixels
    • refresh: The integer refresh rate in millihertz
    • picture_aspect_ratio: The aspect ratio listed in the EDID (not necessarily equal to width / height)
• eww-windows: A list of EWW (ElKowar's Wacky Widgets) windows to open when this output is activated, or an object mapping the name of an EWW window to additional variables to pass when opening the window.
• options: An object mapping configuration option names to values. When running under Sway, any unrecognized options will simply be added to the configuration command in the form {option_name} {option_value}. Duplicate options are merged, with later appearances overwriting duplicate keys. All options are optional, with the compositor determining what to do when an option is absent. The following options are understood:
  • resolution: The resolution to set the output to. Must be a defined mode reported by the monitor EDID. Mutually exclusive with custom-mode.
  • refresh: The refresh rate in millihertz. Added to resolution to produce the final mode line. Must be a defined refresh rate for the resolution. Mutually exclusive with custom-mode.
  • custom-mode: The modeline to set the output to. Does not need to be defined by the monitor's EDID. Use with caution. Mutually exclusive with mode and refresh.
  • scale: The scaling factor of the output.

Workspaces Section

The workspaces section defines the workspaces that VoidShell manages. These are implemented using the underlying compositor's workspace system.

Workspaces have a concept of a "default application", which is the program that will be executed on this workspace when the default application keybind is pressed. These applications are run in their own cgroups, with logs directed to the user journal unless this is overridden.

It consists of a mapping of workspace IDs to workspace definitions. The IDs are used to relate the definition to a workspace in the compositor.

Multiple workspace sections are concatenated together. If a workspace ID is defined multiple times, the last definition is used.

Structure

• name: The name of the workspace that is presented to the user
• application: The default application of the workspace. The name will have .desktop added to the end, and a matching file will be searched for in the standard desktop file locations. Mutually exclusive with exec, args, and unit.
• exec: The default application of the workspace. This is assumed to be an executable in VoidShell's PATH. It should contain only the executable name or a path to the executable. Mutually exclusive with application and unit.
• args: The arguments to pass to the command run with exec, excluding argv[0] (the program name itself). Optional. Mutually exclusive with application and unit.
• environ: A key-value mapping of environment variables and their values to set for the process. Mutually exclusive with unit.
• unit: A SystemD user unit to start as the default application of the workspace. Mutually exclusive with all other default application options.
• systemd: Boolean value indicating whether the default application should be run under SystemD for process control and logging. Defaults to true, and disabling has no effect if the unit option is used.
• log-output: Boolean value indicating whether the default application should be run with its ouptut (stdout/stderr) connected to the user journal (true), or to /dev/null (false). Defaults to true, and disabling has no effect if the unit option is used.

Layouts Section

The layouts section defines the display layouts that VoidShell will attempt to configure. A scoring system is used to determine the best-fit layout for a given set of connected monitors, and the highest-scoring layout will be activated automatically. However, any compatible layout may be manually selected at any time.

It consists of a mapping of layout names to layout definitions.

Multiple layout sections are concatenated together. If a layout name is defined multiple times, the last definition is used.

Structure

A layout object is a key-value mapping specifying the outputs used. The keys provide layout-local generic names for the outputs (e.g. "left" or "right"), which are referenced by contexts to define workspace groups. These objects have the following structure:

• required: Boolean value indicating whether the output must be present to activate the layout. Optional outputs still contribute to score when present, but do not remove the layout from consideration when absent. Defaults to true.
• score: The score that this output contributes to the layout when matched. Default is based on how the output was matched, detailed in the Scoring section.
• position: The position within the framebuffer to place the output, as a tuple of the form [x, y]. Values can be integers, in which case they are used directly, or strings, in which case they are processed as follows:
  • They are formatted with both the global configuration (set in the config section), and an additional value for each previously-defined output equal to its framebuffer resolution (resolution after scaling) in the current dimension.
    • This allows to create dynamic output positioning formulae
    • Unmatched optional outputs will have their values here set to 0, so they can be safely used.
  • They are then evaluated as mathematical expressions, and the result is used as the position.
• outputs: A list of outputs that can be used in this layout. If multiple listed outputs are connected, an earlier-listed output will be preferred if it is available.
• options: An options mapping as in an output definition. It is merged the same as other duplicate option sets, and overrides any keys set in the definition. Useful for e.g. layout-dependent scaling.

Contexts Section

The contexts section defines the "contexts" that VoidShell can be used in (e.g. personal, work, school). These contexts define the mappings of workspaces to outputs based on layout.

It consists of a mapping of context names to context definitions.

Multiple context sections are concatenated together. If a context name is defined multiple times, the definitions will be merged, with duplicate groups being overridden in full by later definitions and configs merged.

The special context name default allows for the configuration of fallback workspace assignments in case a group is present in the current layout but not configured in the current context. This context cannot be marked active unless it is the only context defined.

Structure

• config: A key-value pairing of configuration values local to this context. Values duplicated from the global config override those in the global config.
• groups: A key-value pairing of group names to workspace lists. These are matched against the layout-specific output names of the current layout, with group names not defined in the layout being ignored. The workspaces are identified by their IDs.