nixos: XDG Base Directory Specification environment variables

nixos/doc/manual/release-notes/rl-2511.section.md

@@ -78,6 +78,8 @@
 
 - Docker now defaults to 28.x, because version 27.x stopped receiving security updates and bug fixes after [May 2, 2025](https://github.com/moby/moby/pull/49910).
 
+- Management of `$XDG_*_HOME` environment variables from [XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/). Available as [xdg.directories](#opt-xdg.directories.enable).
+
 - [Corteza](https://cortezaproject.org/), a low-code platform. Available as [services.corteza](#opt-services.corteza.enable).
 
 - [TuneD](https://tuned-project.org/), a system tuning service for Linux. Available as [services.tuned](#opt-services.tuned.enable).
@@ -204,6 +206,11 @@
 - The non-LTS Forgejo package (`forgejo`) has been updated to 12.0.0. This release contains breaking changes, see the [release blog post](https://forgejo.org/2025-07-release-v12-0/)
   for all the details and how to ensure smooth upgrades.
 
+- By default, `$XDG_CACHE_HOME`, `$XDG_CONFIG_HOME`, `$XDG_DATA_HOME`, and `$XDG_STATE_HOME` environment variables are now set to the values that should be used as a fallback if the variables are not set, as per [XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+  Theoretically, this should have no effect on compliant applications, but some applications only comply when they see those variables set, and otherwise just spam into the `$HOME` directory.
+  This is wrong, but, hopefully, those applications at least know to not ignore their old files/directories in `$HOME` if those already exist.
+  Otherwise, some breakage is going to happen.
+
 - `sing-box` has been updated to 1.12.3, which includes a number of breaking changes, old configurations may need updating or they will cause the tool to fail to run.
   See the [change log](https://sing-box.sagernet.org/changelog/#1123) for details and [migration](https://sing-box.sagernet.org/migration/#1120) for how to update old configurations.
 

nixos/modules/config/xdg/directories.nix

@@ -0,0 +1,49 @@
+{ config, lib, ... }:
+{
+  meta = {
+    maintainers = [ lib.maintainers.sandarukasa ] ++ lib.teams.freedesktop.members;
+  };
+
+  options = {
+    xdg.directories =
+      let
+        mkXdgHome =
+          name: default:
+          lib.mkOption {
+            type = lib.types.str;
+            default = "$HOME/${default}/";
+            description = "Value of `$XDG_${name}_HOME` environment variable";
+          };
+      in
+      {
+        enable = lib.mkOption {
+          type = lib.types.bool;
+          default = lib.versionAtLeast config.system.stateVersion "25.11";
+          defaultText = lib.literalExpression "lib.versionAtLeast config.system.stateVersion \"25.11\"";
+          description = ''
+            Whether to define environment variables for some directories from
+            [XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+            Namely:
+            - `$XDG_CACHE_HOME`
+            - `$XDG_CONFIG_HOME`
+            - `$XDG_DATA_HOME`
+            - `$XDG_STATE_HOME`
+          '';
+        };
+        cache-home = mkXdgHome "CACHE" ".cache";
+        config-home = mkXdgHome "CONFIG" ".config";
+        data-home = mkXdgHome "DATA" ".local/share";
+        state-home = mkXdgHome "STATE" ".local/state";
+      };
+  };
+
+  config = lib.mkIf config.xdg.directories.enable {
+    environment.sessionVariables = {
+      XDG_CACHE_HOME = lib.mkDefault config.xdg.directories.cache-home;
+      XDG_CONFIG_HOME = lib.mkDefault config.xdg.directories.config-home;
+      XDG_DATA_HOME = lib.mkDefault config.xdg.directories.data-home;
+      XDG_STATE_HOME = lib.mkDefault config.xdg.directories.state-home;
+    };
+  };
+
+}

nixos/modules/module-list.nix

@@ -39,6 +39,7 @@
   ./config/users-groups.nix
   ./config/vte.nix
   ./config/xdg/autostart.nix
+  ./config/xdg/directories.nix
   ./config/xdg/icons.nix
   ./config/xdg/menus.nix
   ./config/xdg/mime.nix