Deprecate use of `builtins.getEnv`

This removes the use of the non-deterministic function
`builtins.getEnv` for state version ≥ 20.09.

PR #1269

doc/release-notes/rl-2009.adoc

@@ -18,4 +18,28 @@ The state version in this release includes the changes below. These
 changes are only active if the `home.stateVersion` option is set to
 "20.09" or later.
 
-* Nothing has happened.
+* The options <<opt-home.homeDirectory>> and <<opt-home.username>> no
+longer have default values and must therefore be provided in your
+configuration. Previously their values would default to the content of
+the environment variables `HOME` and `USER`, respectively.
++
+--
+Further, the options <<opt-xdg.cacheHome>>, <<opt-xdg.configHome>>,
+and <<opt-xdg.dataHome>> will no longer be affected by the
+`XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, and `XDG_DATA_HOME` environment
+variables. They now unconditionally default to
+
+- `"${config.home.homeDirectory}/.cache"`,
+- `"${config.home.homeDirectory}/.config"`, and
+- `"${config.home.homeDirectory}/.local/share"`.
+
+If you choose to switch to state version 20.09 then you must set these
+options if you use non-default XDG base directory paths.
+
+The initial configuration generated by
+
+[source,console]
+$ nix-shell '<home-manager>' -A install
+
+will automatically include these options, when necessary.
+--

home-manager/install.nix

@@ -12,6 +12,18 @@ runCommand "home-manager-install" {
       echo
       echo "Creating initial Home Manager configuration..."
 
+      nl=$'\n'
+      xdgVars=""
+      if [[ -v XDG_CACHE_HOME && $XDG_CACHE_HOME != "$HOME/.cache" ]]; then
+        xdgVars="$xdgVars  xdg.cacheHome = \"$XDG_CACHE_HOME\";$nl"
+      fi
+      if [[ -v XDG_CONFIG_HOME && $XDG_CONFIG_HOME != "$HOME/.config" ]]; then
+        xdgVars="$xdgVars  xdg.configHome = \"$XDG_CONFIG_HOME\";$nl"
+      fi
+      if [[ -v XDG_DATA_HOME && $XDG_DATA_HOME != "$HOME/.local/share" ]]; then
+        xdgVars="$xdgVars  xdg.dataHome = \"$XDG_DATA_HOME\";$nl"
+      fi
+
       mkdir -p "$(dirname "$confFile")"
       cat > $confFile <<EOF
     { config, pkgs, ... }:
@@ -20,6 +32,11 @@ runCommand "home-manager-install" {
       # Let Home Manager install and manage itself.
       programs.home-manager.enable = true;
 
+      # Home Manager needs a bit of information about you and the
+      # paths it should manage.
+      home.username = "$USER";
+      home.homeDirectory = "$HOME";
+    $xdgVars
       # This value determines the Home Manager release that your
       # configuration is compatible with. This helps avoid breakage
       # when a new Home Manager release introduces backwards
@@ -28,7 +45,7 @@ runCommand "home-manager-install" {
       # You can update Home Manager without changing this value. See
       # the Home Manager release notes for a list of state version
       # changes in each release.
-      home.stateVersion = "20.03";
+      home.stateVersion = "20.09";
     }
     EOF
     fi

modules/home-environment.nix

@@ -125,14 +125,22 @@ in
   options = {
     home.username = mkOption {
       type = types.str;
-      defaultText = "$USER";
+      defaultText = literalExample ''
+        "$USER"   for state version < 20.09,
+        undefined for state version ≥ 20.09
+      '';
+      example = "jane.doe";
       description = "The user's username.";
     };
 
     home.homeDirectory = mkOption {
       type = types.path;
-      defaultText = "$HOME";
-      description = "The user's home directory.";
+      defaultText = literalExample ''
+        "$HOME"   for state version < 20.09,
+        undefined for state version ≥ 20.09
+      '';
+      example = "/home/jane.doe";
+      description = "The user's home directory. Must be an absolute path.";
     };
 
     home.profileDirectory = mkOption {
@@ -327,8 +335,12 @@ in
       }
     ];
 
-    home.username = mkDefault (builtins.getEnv "USER");
-    home.homeDirectory = mkDefault (builtins.getEnv "HOME");
+    home.username =
+      mkIf (versionOlder config.home.stateVersion "20.09")
+        (mkDefault (builtins.getEnv "USER"));
+    home.homeDirectory =
+      mkIf (versionOlder config.home.stateVersion "20.09")
+        (mkDefault (builtins.getEnv "HOME"));
 
     home.profileDirectory =
       if config.submoduleSupport.enable

modules/misc/xdg.nix

@@ -85,12 +85,20 @@ in
       };
     })
 
-    (mkIf (!cfg.enable) {
+    # Legacy non-deterministic setup.
+    (mkIf (!cfg.enable && versionOlder config.home.stateVersion "20.09") {
       xdg.cacheHome = getXdgDir "XDG_CACHE_HOME" defaultCacheHome;
       xdg.configHome = getXdgDir "XDG_CONFIG_HOME" defaultConfigHome;
       xdg.dataHome = getXdgDir "XDG_DATA_HOME" defaultDataHome;
     })
 
+    # "Modern" deterministic setup.
+    (mkIf (!cfg.enable && versionAtLeast config.home.stateVersion "20.09") {
+      xdg.cacheHome = mkDefault defaultCacheHome;
+      xdg.configHome = mkDefault defaultConfigHome;
+      xdg.dataHome = mkDefault defaultDataHome;
+    })
+
     {
       home.file = mkMerge [
         cfg.configFile