85 lines
5.8 KiB
Markdown
85 lines
5.8 KiB
Markdown
# XDG - Base Directory Specification
|
||
|
||
XDG environment variables are not set by default on Debian, as per the XDG Base Directory Specification, which defines them as optional. If unset, applications fall back to default paths like $HOME/.config, $HOME/.local/share, and $HOME/.cache.
|
||
|
||
To ensure XDG variables are set system-wide, define them in /etc/security/pam_env.conf using the DEFAULT syntax, which is reliably loaded during graphical login and session initialization:
|
||
|
||
conf_print_xdg() {
|
||
cat <<EOF
|
||
XDG_CONFIG_HOME DEFAULT=@{HOME}/.config
|
||
XDG_CACHE_HOME DEFAULT=@{HOME}/.cache
|
||
XDG_DATA_HOME DEFAULT=@{HOME}/.local/share
|
||
XDG_STATE_HOME DEFAULT=@{HOME}/.local/state
|
||
EOF
|
||
}
|
||
conf_print_xdg | sudo tee /etc/security/pam_env.conf
|
||
|
||
Alternatively, for shell environments, set them in /etc/profile.d/xdg.sh:
|
||
|
||
conf_print_xdg() {
|
||
cat <<EOF
|
||
export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
|
||
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
|
||
export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
|
||
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
|
||
EOF
|
||
}
|
||
conf_print_xdg | sudo tee /etc/profile.d/xdg.sh
|
||
|
||
⚠️ Note: Variables set in shell files like .zshrc or .profile may not be
|
||
available during graphical sessions (e.g., via a display manager). Use PAM
|
||
for system-wide, session-aware consistency.
|
||
|
||
## Base
|
||
|
||
The intended use-case for BaseDirectories is to query the paths of user-
|
||
invisible standard directories that have been defined according to the
|
||
conventions of the operating system the library is running on.
|
||
|
||
If you want to compute the location of cache, config or data folders for your
|
||
own application or project, use ProjectDirectories instead.
|
||
|
||
| Type | Purpose | XDG Environment Variable | Linux / BSD | MacOS |
|
||
| ---- | ---------- | ------------------------ | ------------------------------------ | --------------------------------- |
|
||
| Base | home | HOME | $HOME | $HOME |
|
||
| Base | cache | XDG_CACHE_HOME | $XDG_CACHE_HOME or $HOME/.cache | $HOME/Library/Caches |
|
||
| Base | config | XDG_CONFIG_HOME | $XDG_CONFIG_HOME or $HOME/.config | $HOME/Library/Application Support |
|
||
| Base | data | XDG_DATA_HOME | $XDG_DATA_HOME or $HOME/.local/share | $HOME/Library/Application Support |
|
||
| Base | dataLocal | XDG_DATA_HOME | $XDG_DATA_HOME or $HOME/.local/share | $HOME/Library/Application Support |
|
||
| Base | executable | XDG_BIN_HOME | $XDG_BIN_HOME or $HOME/.local/bin | null |
|
||
| Base | preference | XDG_CONFIG_HOME | $XDG_CONFIG_HOME or $HOME/.config | $HOME/Library/Preferences |
|
||
| Base | runtime | XDG_RUNTIME_DIR | $XDG_RUNTIME_DIR or null | null |
|
||
|
||
## User
|
||
|
||
The intended use-case for UserDirectories is to query the paths of user-facing
|
||
standard directories that have been defined according to the conventions of the
|
||
operating system the library is running on.
|
||
|
||
| Type | Purpose | XDG Environment Variable | Linux / BSD | MacOS |
|
||
| ---- | -------- | ------------------------ | ------------------------------------------------ | ------------------- |
|
||
| User | audio | XDG_MUSIC_DIR | $XDG_MUSIC_DIR | $HOME/Music |
|
||
| User | desktop | XDG_DESKTOP_DIR | $XDG_DESKTOP_DIR | $HOME/Desktop |
|
||
| User | document | XDG_DOCUMENTS_DIR | $XDG_DOCUMENTS_DIR | $HOME/Documents |
|
||
| User | download | XDG_DOWNLOAD_DIR | $XDG_DOWNLOAD_DIR | $HOME/Downloads |
|
||
| User | font | XDG_DATA_HOME | $XDG_DATA_HOME/fonts or $HOME/.local/share/fonts | $HOME/Library/Fonts |
|
||
| User | picture | XDG_PICTURES_DIR | $XDG_PICTURES_DIR | $HOME/Pictures |
|
||
| User | public | XDG_PUBLICSHARE_DIR | $XDG_PUBLICSHARE_DIR | $HOME/Public |
|
||
| User | template | XDG_TEMPLATES_DIR | $XDG_TEMPLATES_DIR | null |
|
||
| User | video | XDG_VIDEOS_DIR | $XDG_VIDEOS_DIR | $HOME/Movies |
|
||
|
||
## Project
|
||
|
||
The intended use-case for ProjectDirectories is to compute the location of
|
||
cache, config or data folders for your own application or project, which are
|
||
derived from the standard directories.
|
||
|
||
| Type | Purpose | XDG Environment Variable | Linux / BSD | MacOS |
|
||
| ------- | ---------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------ |
|
||
| Project | cache | XDG_CACHE_HOME/<project_path> | $XDG_CACHE_HOME or $HOME/.cache/<project_path> | $HOME/Library/Caches/<project_path> |
|
||
| Project | config | XDG_CONFIG_HOME/<project_path> | $XDG_CONFIG_HOME or $HOME/.config/<project_path> | $HOME/Library/Preferences/<project_path> |
|
||
| Project | data | XDG_CONFIG_HOME/<project_path> | $XDG_CONFIG_HOME or $HOME/.config/<project_path> | $HOME/Library/Application Support/<project_path> |
|
||
| Project | dataLocal | XDG_DATA_HOME/<project_path> | $XDG_DATA_HOME or $HOME/.local/share/<project_path> | $HOME/Library/Application Support/<project_path> |
|
||
| Project | preference | XDG_DATA_HOME/<project_path> | $XDG_DATA_HOME or $HOME/.local/share/<project_path> | $HOME/Library/Application Support/<project_path> |
|
||
| Project | runtime | XDG_RUNTIME_DIR/<project_path> | $XDG_RUNTIME_DIR/<project_path> | null |
|