Crate cfg_rs 

cfg-rs: A Configuration Library for Rust Applications

cfg-rs is a lightweight, flexible configuration loader for Rust applications. It composes multiple sources (files, env, inline maps, random, etc.), supports live refresh, placeholder expansion, and derive-based typed configs — all without a serde dependency.

See the examples directory for end-to-end demos: https://github.com/leptonyu/cfg-rs/tree/main/examples

Features

• Single call to load typed config: see Configuration::get
• Derive your config types: see FromConfig
• Default values via field attributes: see field attributes
• Placeholder expansion like ${cfg.key}: see ConfigValue
• Random values under the rand feature (e.g. configuration.get::<u8>("random.u8"))
• Refreshable values via RefValue and refreshable Configuration
• Pluggable sources with clear priority: see register_source¹
• No serde dependency

Supported formats and feature flags

Built-in file parsers (enable via Cargo features):

• toml: extensions .toml, .tml
• yaml: extensions .yaml, .yml
• json: extension .json
• ini: extension .ini

Other useful features:

• rand: random value provider (e.g. random.u8, random.string)
• log: minimal logging integration for value parsing
• coarsetime: coarse time helpers for time-related values

Installation

Add to your Cargo.toml with the features you need:

[dependencies]
cfg-rs = { version = "^0.6", features = ["toml"] }

For a batteries-included setup, use the convenience feature set:

cfg-rs = { version = "^0.6", features = ["full"] }

Quick start

1) One-liner with predefined sources

use cfg_rs::*;

let configuration = Configuration::with_predefined().unwrap();
// use configuration.get::<T>("your.key") or derive types (see below)

See PredefinedConfigurationBuilder::init for details.

2) Customize predefined builder

use cfg_rs::*;
init_cargo_env!();

let configuration = Configuration::with_predefined_builder()
    .set_cargo_env(init_cargo_env())
    .init()
    .unwrap();

3) Compose your own sources (priority = registration order)

use cfg_rs::*;
init_cargo_env!();

let mut configuration = Configuration::new()
    // Layer 0: Cargo env source.
    .register_source(init_cargo_env()).unwrap()
    // Layer 1: Inline key-values.
    .register_kv("inline")
        .set("hello", "world")
        .finish()
        .unwrap();

// Layer 2: Random values (feature = "rand").
#[cfg(feature = "rand")]
{
    configuration = configuration.register_random().unwrap();
}

// Layer 3: All environment variables with prefix `CFG_`.
configuration = configuration.register_prefix_env("CFG").unwrap();

// Layer 4: File(s) — extension inferred by feature (e.g. yaml).
configuration = configuration.register_file("/conf/app.yaml", true).unwrap();

// Optional: register an inline file content (e.g. TOML) and merge.
#[cfg(feature = "toml")]
{
    let toml = inline_source!("../app.toml").unwrap();
    configuration = configuration.register_source(toml).unwrap();
}

// Finally use it.
// let port: u16 = configuration.get("server.port").unwrap();

See register_kv, register_file, register_random, and register_prefix_env.

4) Handy helpers for tests and small apps

• From inline map (macro):

#[derive(Debug, cfg_rs::FromConfig)]
struct AppCfg { port: u16, host: String }

let cfg: AppCfg = cfg_rs::from_static_map!(AppCfg, {
    "port" => "8080",
    "host" => "localhost",
});

• From environment variables:

#[derive(Debug, cfg_rs::FromConfig)]
struct AppCfg { port: u16, host: String }

std::env::set_var("CFG_APP_PORT", "8080");
std::env::set_var("CFG_APP_HOST", "localhost");
let cfg: AppCfg = cfg_rs::from_env("CFG_APP").unwrap();

Derive typed configs

Implement strong-typed configs via derive:

#[derive(Debug, cfg_rs::FromConfig)]
#[config(prefix = "cfg.app")] // optional, implements FromConfigWithPrefix
struct AppCfg {
    port: u16,              // required
    #[config(default = true)]
    enabled: bool,          // has default value
    #[config(name = "ip")] // remap field name
    host: String,
}

Attributes summary:

• #[config(prefix = "cfg.app")] on struct: implement FromConfigWithPrefix
• #[config(name = "...")] on field: rename field key
• #[config(default = <expr>)] on field: default value when missing

See the full reference in derive.FromConfig.

Placeholders, randoms, and refresh

• Placeholder expansion: use ${some.key} inside string values; see ConfigValue
• Random values: under rand, keys like random.u8, random.string provide per-read randoms
• Refreshing: Configuration::refresh() re-reads sources that allow refresh; RefValue<T> updates on refresh

Examples

Browse runnable examples covering common patterns:

• simple: minimal setup (full feature set)
• profile: working with profiles (requires toml)
• watch: basic file watching and refresh (requires yaml)
• refresh: manual refresh and RefValue
• logger: logging integration (requires full)
• thread_pool, salak, test_suit: larger samples and integrations

https://github.com/leptonyu/cfg-rs/tree/main/examples

Minimum supported Rust version

rustc 1.81+

License

MIT © contributors. See LICENSE.

Tips and notes

• Source priority is deterministic: earlier registrations override later ones¹
• This crate intentionally does not depend on serde
• Docs.rs builds enable all features for a comprehensive reference

---

1. Source precedence follows registration order — earlier registrations have higher priority. ↩ ^1 2

Modules

source

Configuration sources module, see the examples for general usage information.

Macros

from_static_map

Macro to generate config instance from a map of key-value pairs. The keys in the map are config keys, e.g. “port”. The values in the map are string values, e.g. “8080”. This macro will panic if any required config is missing or if any config value cannot be parsed into the expected type.

impl_enum

Implement FromConfig for enums.

init_cargo_env

Collect all CARGO_PKG_* env variables, and CARGO_BIN_NAME into configuration.

inline_source

Inline config file in repo, see Supported File Formats.

Structs

ConfigContext

Configuration Context.

Configuration

Configuration Instance, See Examples, How to Initialize Configuration for details.

FromStrHolder

Wrapper for all FromStr type.

PredefinedConfigurationBuilder

Predefined Configuration Builder. See init for details.

RefValue

RefValue means reference of value or refreshable value, it holds a value which can be updated when Configuration is refreshed.

Enums

ConfigError

Configuration Error.

ConfigValue

Config value, ConfigSource use this value to store config properties.

Traits

FromConfig

Generate config instance from configuration.

FromConfigWithPrefix

Config with prefix. This trait is auto derived by FromConfig.

FromStringValue

Get from string.

Functions

from_env

Generate config instance from environment variables. The prefix is used to scope the config keys, e.g. “CFG_APP”. This function will return an error if any required config is missing or if any config value cannot be parsed into the expected type.

from_map

Generate config instance from a map of key-value pairs. The keys in the map are full config keys, e.g. “cfg.app.port”. The values in the map are string values, e.g. “8080”. The prefix is used to scope the config keys, e.g. “cfg.app”. This function will return an error if any required config is missing or if any config value cannot be parsed into the expected type.

Type Aliases

ConfigKey

Config key, ConfigSource use this key to access config properties.

Derive Macros

FromConfig

Automatic derive FromConfig instance.