Crate user_dirs

Help

Expand description

A respectful, XDG-first user directories implementation for obtaining the home, cache, config, data, runtime, and state directories.

The library provides the location of these directories by leveraging the mechanisms defined by

the XDG base directory on all platforms primarily,
the Known Folder API on Windows,
and the Standard Directories guidelines on macOS.

§Why?

The key differentiator of the user_dirs crate is that it always prefers user-defined XDG variables, regardless of platform. Then and only then are system-defined directories used. The developer of the popular dirs and directories crates has refused time and time again to respect explicitly-defined XDG variables.

I’m a big fan of the etcetera library, however it overcomplicates the process by providing multiple strategies; user_dirs picks one.

§Examples

For a user named Leah:

user_dirs::home_dir();
// See the [`home`](https://docs.rs/home) crate.

user_dirs::cache_dir();
// XDG? => $XDG_CACHE_HOME
// macOS => /Users/Leah/Library/Caches
// Windows => C:\Users\Leah\AppData\Local
// Linux => /home/leah/.cache

user_dirs::config_dir();
// XDG? => $XDG_CONFIG_HOME
// macOS => /Users/Leah/Library/Preferences
// Windows => C:\Users\Leah\AppData\Roaming
// Linux => /home/leah/.config

user_dirs::data_dir();
// XDG? => $XDG_DATA_HOME
// macOS => /Users/Leah/Library/Application Support
// Windows => C:\Users\Leah\AppData\Roaming
// Linux => /home/leah/.local/share

user_dirs::runtime_dir();
// XDG? => Some($XDG_RUNTIME_DIR)
// macOS => None
// Windows => None
// Linux => None

user_dirs::state_dir();
// XDG? => Some($XDG_STATE_HOME)
// macOS => None
// Windows => None
// Linux => Some(/home/leah/.local/state)

Modules§

os: Directory functions for obtaining operating system specified locations.

Structs§

HomeDirError: This error occurs when the home directory cannot be located.

Functions§

cache_dir: Returns the path to the cache directory.
config_dir: Returns the path to the config directory.
data_dir: Returns the path to the data directory.
home_dir: Returns the path to the home directory.
runtime_dir: Returns the path to the runtime directory, if available.
state_dir: Returns the path to the state directory, if available.