xdge

A complete, zero-dependency implementation of the XDG Base Directory Specification v0.8 for Linux and Unix systems.

Why xdge?

The XDG Base Directory Specification tells applications where to put user data, config, cache, state, and runtime files — so they don't litter $HOME with hidden dot-directories.
xdge implements the full spec, including:

• Correct fallback defaults for every variable
• Silent rejection of relative paths (required by the spec)
• $XDG_RUNTIME_DIR handling with automatic fallback + stderr warning
• find_* helpers to search all directories in precedence order
• place_* helpers that auto-create parent dirs with mode 0700
• create_* helpers for all base directories and arbitrary sub-paths

Quick Start

Add to Cargo.toml:

[dependencies]
xdge = "0.1"

use xdge::XdgDirs;

fn main() {
    let xdg = XdgDirs::new();

    // ── Reading paths ──────────────────────────────────────────────────────

    println!("Data home:   {}", xdg.data_home().display());
    // e.g.  ~/.local/share

    println!("Config home: {}", xdg.config_home().display());
    // e.g.  ~/.config

    println!("State home:  {}", xdg.state_home().display());
    // e.g.  ~/.local/state

    println!("Cache home:  {}", xdg.cache_home().display());
    // e.g.  ~/.cache

    println!("User bin:    {}", xdg.user_bin_dir().display());
    // e.g.  ~/.local/bin

    println!("Runtime dir: {:?}", xdg.runtime_dir().unwrap());
    // e.g.  Some("/run/user/1000")  or  None

    // ── Searching ─────────────────────────────────────────────────────────

    // Find first matching file across all data directories (user → system):
    if let Some(path) = xdg.find_data_file("myapp/icons/logo.png") {
        println!("Found data file: {}", path.display());
    }

    // Find first matching config (user → system):
    if let Some(path) = xdg.find_config_file("myapp/settings.toml") {
        println!("Found config: {}", path.display());
    }

    // ── Writing ───────────────────────────────────────────────────────────

    // Get path to write a config file (parent dirs created automatically):
    let cfg_path = xdg.place_config_file("myapp/settings.toml").unwrap();
    std::fs::write(&cfg_path, b"key = \"value\"\n").unwrap();

    // Get path to write a data file:
    let db_path = xdg.place_data_file("myapp/db.sqlite").unwrap();
    println!("Will write DB to {}", db_path.display());

    // ── Creating directories ───────────────────────────────────────────────

    xdg.create_cache_subdir("myapp/thumbnails").unwrap();
    xdg.create_state_subdir("myapp/logs").unwrap();
}

XDG Variables Reference

API Summary

Path accessors

File-finding helpers

Directory-creation helpers

File-placement helpers

Spec Compliance Notes

• All environment variable values that are relative paths are silently ignored and the spec default is used instead (§3).
• In $XDG_DATA_DIRS / $XDG_CONFIG_DIRS, individual relative entries are filtered out; if all entries are relative the full default list is used.
• $XDG_DATA_HOME and $XDG_CONFIG_HOME take precedence over their respective *_DIRS variables (§3).
• When creating directories, mode 0700 is applied; existing directories are not chmod'd (§4).
• $XDG_RUNTIME_DIR is optional; when unset runtime_dir_or_fallback() emits a warning to stderr as required by the spec (§3).

License

• MIT license