xdg

xdg (published as the rust-xdg repository) is a small Rust library that implements the XDG Base Directory Specification, the freedesktop.org standard for where Linux and Unix applications should place configuration, data, cache, and state files. Instead of hand-rolling $HOME-relative paths, applications construct a BaseDirectories instance and ask it for config/data/cache/state file locations, with automatic fallback to the spec’s defined defaults when the corresponding environment variables aren’t set.

The crate also handles directory creation, multi-directory search-path resolution (for reading files that may exist in several XDG data/config directories), and optional runtime-directory handling, making it a common low-level dependency for CLI tools and desktop applications targeting Linux.

What You Get

• A BaseDirectories struct with with_prefix/with_profile constructors scoping all paths to your app
• get_*_file, place_*_file, and create_*_directory methods for config/data/cache/state files with automatic directory creation
• find_*_file(s) methods that search across all XDG search-path directories (not just the home-relative one) for spec compliance
• Runtime directory handling (get_runtime_directory) with the required permission checks the spec mandates
• Optional serde feature flag for structs that need to (de)serialize paths
• Zero required dependencies in the default feature set — a thin, dependency-light wrapper around std::env and std::fs

Common Use Cases

• CLI tools that need a standard, user-expected location for their config file rather than a hardcoded dotfile in $HOME
• Desktop Linux applications following the freedesktop.org XDG spec for cache/data separation
• Applications supporting multiple profiles/instances via with_profile, each getting isolated config/data paths
• Tools that read config from multiple layers (system-wide + user) using the find_config_files search-path resolution

Under The Hood

Architecture - The crate is a single-module library (src/lib.rs re-exporting src/base_directories.rs) centered on the BaseDirectories struct, which reads the relevant XDG_* environment variables at construction time, falls back to the spec-mandated defaults (e.g. ~/.config for XDG_CONFIG_HOME) when unset, and exposes a consistent method-naming convention (get_*, place_*, find_*, create_*) across the four directory kinds (config/data/cache/state) plus runtime directory support.

Tech Stack - Pure Rust, 2021 edition, MSRV 1.60.0, with only std::env/std::fs/std::path at its core and a single optional dependency (serde, feature-gated) for structs that need to serialize resolved paths; no unsafe code, no platform-specific bindings beyond std.

Code Quality - The crate is small (~1,350 lines including tests) with unit tests covering directory resolution and permission handling in base_directories.rs, CI running via GitHub Actions across the MSRV and stable toolchains, and rustdoc comments on every public method; it has been stable for years with infrequent but deliberate releases (semver 1.x through 3.x), reflecting a mature, low-churn library rather than active feature development.

API Design - The method-naming scheme (get_config_file vs place_config_file vs find_config_file) is consistent and self-documenting once learned, closely mirroring the XDG spec’s own vocabulary; the small public surface (one struct, one error type) makes it quick to adopt, though newcomers unfamiliar with the XDG spec itself may need to read the spec to understand get/place/find distinctions.