feat(config): XDG_CONFIG_HOME and XDG_CACHE_HOME compliance (#1050)

Co-authored-by: Ruben Arts <[email protected]>

docs/advanced/explain_info_command.md

@@ -61,11 +61,12 @@ Pixi caches all previously downloaded packages in a cache folder.
 This cache folder is shared between all pixi projects and globally installed tools.
 Normally the locations would be:
 
-| Platform | Value                                               |
-|----------|-----------------------------------------------------|
-| Linux    | `$XDG_CACHE_HOME/rattler` or `$HOME`/.cache/rattler |
-| macOS    | `$HOME`/Library/Caches/rattler                      |
-| Windows  | `{FOLDERID_LocalAppData}/rattler`                   |
+1. XDG compliant cache folder when it's available (`$XDG_CACHE_HOME/pixi`
+   or `$HOME/.cache/pixi`)
+2. Platform-specific default cache folder:
+   - Linux: `$XDG_CACHE_HOME/rattler` or `$HOME`/.cache/rattler
+   - macOS: `$HOME`/Library/Caches/rattler
+   - Windows: `%APPDATA%\rattler`
 
 When your system is filling up you can easily remove this folder.
 It will re-download everything it needs the next time you install a project.

docs/advanced/global_configuration.md

@@ -4,12 +4,16 @@ Pixi supports some global configuration options, as well as project-scoped
 configuration (that does not belong into the project file). The configuration is
 loaded in the following order:
 
-1. Global configuration folder (e.g. `~/.config/pixi/config.toml` on Linux,
-   dependent on XDG_CONFIG_HOME)
-2. Global .pixi folder: `~/.pixi/config.toml` (or `$PIXI_HOME/config.toml` if
+1. XDG compliant configuration folder (`$XDG_CONFIG_HOME/pixi/config.toml` or
+   `$HOME/.config/pixi/config.toml`)
+2. Global configuration folder, depending on the OS:
+   - Linux: `$HOME/.config/pixi/config.toml`
+   - macOS: `$HOME/Library/Application Support/pixi/config.toml`
+   - Windows: `%APPDATA%\pixi\config.toml`
+3. Global .pixi folder: `~/.pixi/config.toml` (or `$PIXI_HOME/config.toml` if
    the `PIXI_HOME` environment variable is set)
-3. Project-local .pixi folder: `$PIXI_PROJECT/.pixi/config.toml`
-4. Command line arguments (`--tls-no-verify`, `--change-ps1=false` etc.)
+4. Project-local .pixi folder: `$PIXI_PROJECT/.pixi/config.toml`
+5. Command line arguments (`--tls-no-verify`, `--change-ps1=false` etc.)
 
 !!! note
     To find the locations where `pixi` looks for configuration files, run

docs/cli.md

@@ -523,9 +523,9 @@ Global is the main entry point for the part of pixi that executes on the
 global(system) level.
 
 !!! tip
-Binaries and environments installed globally are stored in `~/.pixi`
-by default, this can be changed by setting the `PIXI_HOME` environment
-variable.
+    Binaries and environments installed globally are stored in `~/.pixi`
+    by default, this can be changed by setting the `PIXI_HOME` environment
+    variable.
 
 ### `global install`
 

src/config.rs

@@ -56,12 +56,26 @@ pub fn home_path() -> Option<PathBuf> {
 
 /// Returns the default cache directory.
 /// Most important is the `PIXI_CACHE_DIR` environment variable.
-/// If that is not set, the `RATTLER_CACHE_DIR` environment variable is used.
-/// If that is not set, the default cache directory of [`rattler::default_cache_dir`] is used.
+/// - If that is not set, the `RATTLER_CACHE_DIR` environment variable is used.
+/// - If that is not set, `XDG_CACHE_HOME/pixi` is used when the directory exists.
+/// - If that is not set, the default cache directory of [`rattler::default_cache_dir`] is used.
 pub fn get_cache_dir() -> miette::Result<PathBuf> {
     std::env::var("PIXI_CACHE_DIR")
         .map(PathBuf::from)
         .or_else(|_| std::env::var("RATTLER_CACHE_DIR").map(PathBuf::from))
+        .or_else(|_| {
+            let xdg_cache_pixi_dir = std::env::var_os("XDG_CACHE_HOME")
+                .map_or_else(
+                    || dirs::home_dir().map(|d| d.join(".cache")),
+                    |p| Some(PathBuf::from(p)),
+                )
+                .map(|d| d.join("pixi"));
+
+            // Only use the xdg cache pixi directory when it exists
+            xdg_cache_pixi_dir
+                .and_then(|d| d.exists().then_some(d))
+                .ok_or_else(|| miette::miette!("could not determine xdg cache directory"))
+        })
         .or_else(|_| {
             rattler::default_cache_dir()
                 .map_err(|_| miette::miette!("could not determine default cache directory"))
@@ -160,7 +174,13 @@ impl Config {
 
     /// Load the global config file from the home directory (~/.pixi/config.toml)
     pub fn load_global() -> Config {
+        let xdg_config_home = std::env::var_os("XDG_CONFIG_HOME").map_or_else(
+            || dirs::home_dir().map(|d| d.join(".config")),
+            |p| Some(PathBuf::from(p)),
+        );
+
         let global_locations = vec![
+            xdg_config_home.map(|d| d.join("pixi").join(consts::CONFIG_FILE)),
             dirs::config_dir().map(|d| d.join("pixi").join(consts::CONFIG_FILE)),
             home_path().map(|d| d.join(consts::CONFIG_FILE)),
         ];