hierconf#

Loads TOML configuration files from standard Unix hierarchy paths. Requires the facet crate for deserialization and man page generation.

The name is inspired by man hier, which documents the Unix filesystem hierarchy.

How it works#

Loads first configuration file it finds iterating over the following locations:

1. User-specific directories:
   • Linux/BSD: $XDG_CONFIG_HOME/{app_name}/config.toml or $HOME/.config/{app_name}/config.toml
   • macOS: $HOME/Library/Application Support/{app_name}/config.toml
2. /etc/{app_name}/config.toml
3. $HIERCONF_DISTRIBUTION_PREFIX/{app_name}/config.toml (if env var HIERCONF_DISTRIBUTION_PREFIX is set at compile time)
4. /usr/share/etc/{app_name}/config.toml

Usage#

use hierconf::HierConf;
use facet::Facet;

/// Application configuration.
#[derive(Facet, Debug)]
#[facet(hierconf::app_name("myapp"))]
struct Config {
    /// The hostname to bind to.
    host: String,
    /// The port number to bind to.
    port: u16,
    /// Database configuration.
    database: DatabaseConfig,
}

/// Database configuration.
#[derive(Facet, Debug)]
struct DatabaseConfig {
    /// Database hostname.
    host: String,
    /// Database port number.
    port: u16,
}

let config: Result<Config, _> = Config::load(); // Returns Err(_) in doctest

#[cfg(feature = "mangen")]
{
    if let Ok(man_page) = Config::generate_man_page() {
        println!("{}", man_page);
    }
}

For build-time man page generation, see the build.rs example (tangled, codeberg) which demonstrates the recommended approach.

Dependencies and features#

Direct dependencies:

• facet: Required for reflection and TOML deserialization.
• hierconf-core: Core configuration loading logic. Brings in camino, facet-error, and facet-toml.
• hierconf-mangen: Optional, enabled via mangen feature. Generates man pages, utilizing facet, roff, and time.

Features:

• user-config: Enable user-specific configuration directories.
• mangen: Enable man page generation via [HierConf::generate_man_page].

Distribution prefix#

Set HIERCONF_DISTRIBUTION_PREFIX at compile time to override the distribution path. Useful for package managers like Homebrew:

HIERCONF_DISTRIBUTION_PREFIX=/opt/homebrew/etc cargo build

License#

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.