Getting started

If you can define a Rust struct, dotcfg can store it as configuration. This guide starts from the Rust pieces too, so you do not need to already know how Serde-based config libraries work.

1. Add dotcfg

TOML support is enabled by default. You also need serde with its derive feature so Rust can turn your struct into config data and back again.

[dependencies]
dotcfg = "0.3.0"
serde = { version = "1", features = ["derive"] }

2. Define your configuration

Serialize means the struct can be written to a file. Deserialize means it can be reconstructed from that file. Default is only needed when you want load_or_default() to create a starting config automatically.

use dotcfg::DotCfg;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default)]
struct AppConfig {
    theme: String,
    port: u16,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg = DotCfg::new("myapp");
    let config: AppConfig = cfg.load_or_default()?;

    println!("{config:#?}");
    println!("Stored at {:?}", cfg.file_path()?);
    Ok(())
}

3. Understand what just happened

DotCfg::new("myapp") uses the default dot-directory strategy. With TOML and the default filename, the config resolves to ~/.myapp/config.toml. load_or_default() loads that file when it exists; otherwise it saves AppConfig::default() first and returns it.

Choose how missing config behaves

Where next?

Learn where dotcfg can store files, or jump to loading and saving for the full behavior of each method.