home-environment: add home.sessionSearchVariables

This commit introduces `home.sessionSearchVariables` option, that is
created to be a "generic" version of `home.sessionPath` for any
environment variables that is similar to PATH (e.g.: MANPATH). This
allows composition of those variables between multiple modules, avoiding
issues like this one:

https://github.com/nix-community/home-manager/pull/4579/files#r1364374048

This commit also reimplements `home.sessionPath` as terms of
`home.sessionSearchVariables`, to reduce code duplication and show that
the code is correct.

The behavior is to prepend the new search paths. This will allow
the user to override the defaults easily by setting it later in the
configuration.

modules/home-environment.nix

@@ -309,7 +309,7 @@ in
         ".git/safe/../../bin"
       ];
       description = ''
-        Extra directories to add to {env}`PATH`.
+        Extra directories to prepend to {env}`PATH`.
 
         These directories are added to the {env}`PATH` variable in a
         double-quoted context, so expressions like `$HOME` are
@@ -319,6 +319,27 @@ in
       '';
     };
 
+    home.sessionSearchVariables = mkOption {
+      default = { };
+      type = with types; attrsOf (listOf str);
+      example = {
+        MANPATH = [
+          "$HOME/.npm-packages/man"
+          "\${xdg.configHome}/.local/share/man"
+        ];
+      };
+      description = ''
+        Extra directories to prepend to arbitrary PATH-like
+        environment variables (e.g.: {env}`MANPATH`). The values
+        will be concatenated by `:`.
+        These directories are added to the environment variable in a
+        double-quoted context, so expressions like `$HOME` are
+        expanded by the shell. However, since expressions like `~` or
+        `*` are escaped, they will end up in the environment
+        verbatim.
+      '';
+    };
+
     home.sessionVariablesExtra = mkOption {
       type = types.lines;
       default = "";
@@ -575,11 +596,18 @@ in
         export __HM_SESS_VARS_SOURCED=1
 
         ${config.lib.shell.exportAll cfg.sessionVariables}
-      '' + lib.optionalString (cfg.sessionPath != [ ]) ''
-        export PATH="$PATH''${PATH:+:}${lib.concatStringsSep ":" cfg.sessionPath}"
-      '' + cfg.sessionVariablesExtra;
+      '' + lib.concatStringsSep "\n"
+        (lib.mapAttrsToList
+          (env: values: config.lib.shell.export
+            env
+            (config.lib.shell.prependToVar ":" env values))
+          cfg.sessionSearchVariables)
+        + cfg.sessionVariablesExtra;
     };
 
+    home.sessionSearchVariables.PATH =
+      lib.mkIf (cfg.sessionPath != [ ]) cfg.sessionPath;
+
     home.packages = [ config.home.sessionVariablesPackage ];
 
     # The entry acting as a boundary between the activation script's "check" and

modules/lib/shell.nix

@@ -17,6 +17,14 @@ let
     };
 
 in rec {
+  # Produces a Bourne shell like statement that prepend new values to
+  # an possibly existing variable, using sep(arator).
+  # Example:
+  #   prependToVar ":" "PATH" [ "$HOME/bin" "$HOME/.local/bin" ]
+  #   => "$HOME/bin:$HOME/.local/bin:${PATH:+:}\$PATH"
+  prependToVar = sep: n: v:
+    "${lib.concatStringsSep sep v}\${${n}:+${sep}}\$${n}";
+
   # Produces a Bourne shell like variable export statement.
   export = n: v: ''export ${n}="${toString v}"'';
 

tests/modules/home-environment/default.nix

@@ -1,4 +1,5 @@
 {
-  home-session-variables = ./session-variables.nix;
   home-session-path = ./session-path.nix;
+  home-session-search-variables = ./session-search-variables.nix;
+  home-session-variables = ./session-variables.nix;
 }

tests/modules/home-environment/session-path.nix

@@ -1,4 +1,4 @@
-{ config, lib, pkgs, ... }:
+{ ... }:
 
 {
   imports = [
@@ -10,6 +10,6 @@
     hmSessVars=home-path/etc/profile.d/hm-session-vars.sh
     assertFileExists $hmSessVars
     assertFileContains $hmSessVars \
-      'export PATH="$PATH''${PATH:+:}bar:baz:foo"'
+      'export PATH="bar:baz:foo''${PATH:+:}$PATH"'
   '';
 }

tests/modules/home-environment/session-search-variables.nix

@@ -0,0 +1,15 @@
+{ ... }:
+
+{
+  imports = [
+    ({ ... }: { config.home.sessionSearchVariables.TEST = [ "foo" ]; })
+    ({ ... }: { config.home.sessionSearchVariables.TEST = [ "bar" "baz" ]; })
+  ];
+
+  nmt.script = ''
+    hmSessVars=home-path/etc/profile.d/hm-session-vars.sh
+    assertFileExists $hmSessVars
+    assertFileContains $hmSessVars \
+      'export TEST="bar:baz:foo''${TEST:+:}$TEST"'
+  '';
+}