Embed Settings in your app

Distribute Settings with your schema embedded as a separate executable alongside your app. Pass the absolute path of the configuration file at launch to avoid depending on the installation layout. See Getting started for a minimal example and Building for build instructions.

Single-instance constraint

Only one Settings process can open a given configuration file at a time. A second process launched with the same path exits. Different files can have separate windows.

Default config.toml path

When no argument is supplied, the lookup works as follows.

OS or packaging	Lookup without an argument
macOS inside an .app	If the executable is under Contents/MacOS/, use Contents/Resources/config.toml
Windows or Linux	Use config.toml beside the executable if it exists
Development fallback when neither resolves a path	demo/config.toml in the Settings source repository used for the build

Create a valid TOML file before launching Settings. This also applies when passing an explicit path: Settings does not automatically initialize a missing configuration file.

For your own app, choose a writable user configuration location in the parent app and pass that path. The demo's default paths are not recommendations for storing production user settings.

Bundle into a macOS .app

MyApp.app/Contents/MacOS/
├── MyApp
└── settings

let settings = std::env::current_exe()?.parent().unwrap().join("settings");
std::process::Command::new(settings).arg(config_path).spawn()?;

Here, config_path is the path of the file prepared by your app. Include the bundled Settings executable in your app's signing and distribution process.

Windows

Place settings.exe, or the packaged name Settings.exe, beside your main executable. Launch it with the configuration path. Without an argument, it uses config.toml beside the executable if that file exists.

Linux

Choose a location for Settings and have your app launch it with the configuration path. Without an argument, it uses config.toml beside the executable if present.

Saving and applying changes in your app

Settings reads and writes the specified TOML file. The parent app provides any notification or app-specific reload behavior.

• To apply changes while Settings remains open, have your app watch the configuration file.
• To apply changes after Settings closes, wait for the child process to exit and reload the file.

See Save modes for macOS automatic saving and the Windows and Linux save bar.

Integrate into a Cargo workspace

The Settings repository contains two crates: the GUI and settings-schema. Bring the source in through a Git submodule or a similar arrangement, then either integrate it into your workspace or invoke it as a separate build. Because Settings runs as a separate process, the parent app does not have to be written in Rust.

Keep your own schema.toml with the parent app and select it at build time with SETTINGS_SCHEMA or SCHEMA. Without an override, just binary uses schema.toml one directory above the Settings repository root. See Select a schema.