Configure Modeler

Syside Modeler reads settings from two places: a syside.toml configuration file that travels with the project, and the extension’s own syside.* settings in VS Code or a compatible editor. Prefer syside.toml wherever both can hold a setting:

Note that Modeler needs to be restarted for any changes to take effect.

Settings in syside.toml

A syside.toml at the project or workspace root is the recommended way of configuring Syside: it is editor-agnostic, it is the only way to configure format options, and keeping it version tracked ensures that every team member working on the project maintains a consistent environment.

Config file discovery

If a path to the configuration file is not provided, Syside looks for syside.toml in parent directories until either one is found, or a directory with a root marker is reached. Currently, root markers include:

  • .git for a root git directory

  • sysand-lock.toml for a root Sysand directory

Up to three configuration files are discovered and merged, in order, with later files winning:

  1. Global config found at:

    • Windows: %APPDATA%\syside\syside.toml

    • Linux/macOS: $XDG_CONFIG_HOME/syside/syside.toml if exists, otherwise $HOME/.config/syside/syside.toml

    This configuration can be transferred between machines.

  2. Project-wide syside.toml, expected to be version controlled and shared between team members.

  3. Project-wide syside.user.toml in the same directory as syside.toml, or found the same way as syside.toml. This should only be used for user specific configuration options, e.g. lsp.inlay-hints, and not version controlled.

Merging is recursive for configuration objects, i.e. TOML tables, while other values, like booleans and arrays, are overwritten by the next file. An exception to this is the exclude option, which concatenates values, just like .gitignore would.

If only the global config is found, paths are resolved relative to the current working directory, otherwise they are resolved relative to the config file directory.

Settings in the editor

The Modeler extension adds a smaller set of settings to the editor that hosts it, all under syside.*. Most mirror a syside.toml option; a few, such as the path to the language server executable and logging, exist only there. See Settings in the editor for the full list.

Precedence

Configuration files win in discovery order, later over earlier. A setting made in the editor beats any file for the options it mirrors. On a command line, flags beat everything, and passing --config <FILE> explicitly both disables config file discovery and changes path resolution to be relative to the current working directory irrespective of the config file location.