From 2082b95034d303f6452e0928da7a1ff55f9a2ca6 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Fri, 20 Dec 2024 11:16:25 -0800 Subject: [PATCH] Update readme to reflect actual behavior of user directory functions --- README.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 027e556718..74e3d50918 100644 --- a/README.md +++ b/README.md @@ -1903,14 +1903,20 @@ for details. @echo '{{ style("error") }}OH NO{{ NORMAL }}' ``` -##### XDG Directories1.23.0 +##### User Directories1.23.0 These functions return paths to user-specific directories for things like -configuration, data, caches, executables, and the user's home directory. These -functions follow the -[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), -and are implemented with the -[`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate. +configuration, data, caches, executables, and the user's home directory. + +On Unix, these functions follow the +[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). + +On MacOS and Windows, these functions return the system-specified user-specific +directories. For example, `cache_directory()` returns `~/Library/Caches` on +MacOS and `{FOLDERID_LocalAppData}` on Windows. + +See the [`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate for more +details. - `cache_directory()` - The user-specific cache directory. - `config_directory()` - The user-specific configuration directory. @@ -1920,6 +1926,10 @@ and are implemented with the - `executable_directory()` - The user-specific executable directory. - `home_directory()` - The user's home directory. +If you would like to use XDG base directories on all platforms you can use the +`env(…)` function with the appropriate environment variable, e.g., +`env('XDG_CACHE_HOME')`. + ### Constants A number of constants are predefined: