home.pointerCursor: init (#2891)

* home.pointerCursor: init

The current architecture for cursor configurations is composed of individual
options for different backends. For example, X specific settings are managed under
`xsession.pointerCursor` and gtk specific settings are managed under `gtk.cursorTheme`.
While this architecture is modular, it causes duplication of similar structures for
each component. In theory, this provides flexibility because the components are independent
of each other which can be arranged in arbitrary ways to achieve the desired result.
However in practice, users wish to have one cursor theme applied to their entire system
The duplication of options correspond to duplication of settings on the user side and it
becomes a burden to keep track of all necessary settings.

This commit is an attempt to unify cursor configurations for different window systems and
GUI toolkits based on https://github.com/nix-community/home-manager/pull/2481#issuecomment-978917480.
`home.pointerCursor` is introduced as the interface for all cursor configurations.
It contain all options relevant to cursor themes with eneral options delcared under `home.pointerCursor.*`
and backend specific options declared under `home.pointerCursor.<backend>.*`. By default, a backend
independent configuration is generated. Backend specific configurations can be toggled via the
`home.pointerCursor.<backend>.enable` option for each backend. This was decided over using a
list of enums because it allows easy access to the state of the backend. Note generating different
cursor configurations for different backends is still possible by defining only `home.pointerCursor`
and managing the respective options manually.

* xcursor: migrate options to home.pointerCursor

- Removed `xession.pointerCursor` as x11 cursor configurations are now handled in `home.pointerCursor.x11`.
- Updated `meta.maintainer` field in `home.pointerCursor` and CODEOWNERS.

.github/CODEOWNERS

@@ -16,6 +16,8 @@
 
 /modules/misc/gtk.nix                                 @rycee
 
+/modules/config/home-cursor.nix                       @polykernel @league
+
 /modules/config/i18n.nix                              @midchildan
 /tests/modules/config/i18n                            @midchildan
 
@@ -440,8 +442,6 @@
 
 /modules/systemd.nix                                  @rycee
 
-/modules/xcursor.nix                                  @league
-
 /modules/xresources.nix                               @rycee
 
 /modules/xsession.nix                                 @rycee

modules/config/home-cursor.nix

@@ -0,0 +1,157 @@
+{ config, options, lib, pkgs, ... }:
+
+with lib;
+
+let
+
+  cfg = config.home.pointerCursor;
+
+  pointerCursorModule = types.submodule {
+    options = {
+      package = mkOption {
+        type = types.package;
+        example = literalExpression "pkgs.vanilla-dmz";
+        description = "Package providing the cursor theme.";
+      };
+
+      name = mkOption {
+        type = types.str;
+        example = "Vanilla-DMZ";
+        description = "The cursor name within the package.";
+      };
+
+      size = mkOption {
+        type = types.int;
+        default = 32;
+        example = 64;
+        description = "The cursor size.";
+      };
+
+      x11 = {
+        enable = mkEnableOption ''
+          x11 config generation for <option>home.pointerCursor</option>
+        '';
+
+        defaultCursor = mkOption {
+          type = types.str;
+          default = "left_ptr";
+          example = "X_cursor";
+          description = "The default cursor file to use within the package.";
+        };
+      };
+
+      gtk = {
+        enable = mkEnableOption ''
+          gtk config generation for <option>home.pointerCursor</option>
+        '';
+      };
+    };
+  };
+
+  cursorPath = "${cfg.package}/share/icons/${escapeShellArg cfg.name}/cursors/${
+      escapeShellArg cfg.defaultCursor
+    }";
+
+in {
+  meta.maintainers = [ maintainers.polykernel maintainers.league ];
+
+  imports = [
+    (mkAliasOptionModule [ "xsession" "pointerCursor" "package" ] [
+      "home"
+      "pointerCursor"
+      "package"
+    ])
+    (mkAliasOptionModule [ "xsession" "pointerCursor" "name" ] [
+      "home"
+      "pointerCursor"
+      "name"
+    ])
+    (mkAliasOptionModule [ "xsession" "pointerCursor" "size" ] [
+      "home"
+      "pointerCursor"
+      "size"
+    ])
+    (mkAliasOptionModule [ "xsession" "pointerCursor" "defaultCursor" ] [
+      "home"
+      "pointerCursor"
+      "x11"
+      "defaultCursor"
+    ])
+
+    ({ ... }: {
+      warnings = optional (any (x:
+        getAttrFromPath
+        ([ "xsession" "pointerCursor" ] ++ [ x ] ++ [ "isDefined" ])
+        options) [ "package" "name" "size" "defaultCursor" ]) ''
+          The option `xsession.pointerCursor` has been merged into `home.pointerCursor` and will be removed
+          in the future. Please change to set `home.pointerCursor` directly and enable `home.pointerCursor.x11.enable`
+          to generate x11 specific cursor configurations. You can refer to the documentation for more details.
+        '';
+    })
+  ];
+
+  options = {
+    home.pointerCursor = mkOption {
+      type = types.nullOr pointerCursorModule;
+      default = null;
+      description = ''
+        Cursor configuration. Set to <literal>null</literal> to disable.
+        </para><para>
+        Top-level options declared under this submodule are backend indepedent
+        options. Options declared under namespaces such as <literal>x11</literal>
+        are backend specific options. By default, only backend independent cursor
+        configurations are generated. If you need configurations for specific
+        backends, you can toggle them via the enable option. For example, <varname>
+        <link linkend="opt-home.pointerCursor.x11.enable">home.pointerCursor.x11.enable</link>
+        </varname> will enable x11 cursor configurations.
+      '';
+    };
+  };
+
+  config = mkIf (cfg != null) (mkMerge [
+    {
+      assertions = [
+        (hm.assertions.assertPlatform "home.pointerCursor" pkgs platforms.linux)
+      ];
+
+      home.packages = [ cfg.package ];
+
+      # Set name in icons theme, for compatibility with AwesomeWM etc. See:
+      # https://github.com/nix-community/home-manager/issues/2081
+      # https://wiki.archlinux.org/title/Cursor_themes#XDG_specification
+      home.file.".icons/default/index.theme".text = ''
+        [icon theme]
+        Name=Default
+        Comment=Default Cursor Theme
+        Inherits=${cfg.name}
+      '';
+
+      # Set directory to look for cursors in, needed for some applications
+      # that are unable to find cursors otherwise. See:
+      # https://github.com/nix-community/home-manager/issues/2812
+      # https://wiki.archlinux.org/title/Cursor_themes#Environment_variable
+      home.sessionVariables = {
+        XCURSOR_PATH = mkDefault ("$XCURSOR_PATH\${XCURSOR_PATH:+:}"
+          + concatStringsSep ":"
+          [ "${config.home.profileDirectory}/share/icons" ]);
+      };
+    }
+
+    (mkIf cfg.x11.enable {
+      xsession.initExtra = ''
+        ${pkgs.xorg.xsetroot}/bin/xsetroot -xcf ${cursorPath} ${
+          toString cfg.size
+        }
+      '';
+
+      xresources.properties = {
+        "Xcursor.theme" = cfg.name;
+        "Xcursor.size" = cfg.size;
+      };
+    })
+
+    (mkIf cfg.gtk.enable {
+      gtk.cursorTheme = mkDefault { inherit (cfg) package name size; };
+    })
+  ]);
+}

modules/modules.nix

@@ -15,6 +15,7 @@ let
 
   modules = [
     ./accounts/email.nix
+    ./config/home-cursor.nix
     ./config/i18n.nix
     ./files.nix
     ./home-environment.nix
@@ -272,7 +273,6 @@ let
     ./systemd.nix
     ./targets/darwin
     ./targets/generic-linux.nix
-    ./xcursor.nix
     ./xresources.nix
     ./xsession.nix
     ./misc/nix.nix

modules/xcursor.nix

@@ -1,90 +0,0 @@
-{ config, lib, pkgs, ... }:
-
-with lib;
-
-let
-
-  cfg = config.xsession.pointerCursor;
-
-  cursorType = types.submodule {
-    options = {
-      package = mkOption {
-        type = types.package;
-        example = literalExpression "pkgs.vanilla-dmz";
-        description = "Package providing the cursor theme.";
-      };
-
-      name = mkOption {
-        type = types.str;
-        example = "Vanilla-DMZ";
-        description = "The cursor name within the package.";
-      };
-
-      size = mkOption {
-        type = types.int;
-        default = 32;
-        example = 64;
-        description = "The cursor size.";
-      };
-
-      defaultCursor = mkOption {
-        type = types.str;
-        default = "left_ptr";
-        example = "X_cursor";
-        description = "The default cursor file to use within the package.";
-      };
-    };
-  };
-
-  cursorPath = "${cfg.package}/share/icons/${escapeShellArg cfg.name}/cursors/${
-      escapeShellArg cfg.defaultCursor
-    }";
-
-in {
-  meta.maintainers = [ maintainers.league ];
-
-  options = {
-    xsession.pointerCursor = mkOption {
-      type = types.nullOr cursorType;
-      default = null;
-      description = ''
-        The X cursor theme and settings. The package
-        <varname>xorg.xcursorthemes</varname> contains cursors named
-        whiteglass, redglass, and handhelds. The package
-        <varname>vanilla-dmz</varname> contains cursors named Vanilla-DMZ
-        and Vanilla-DMZ-AA. Note: handhelds does not seem to work at
-        custom sizes.
-      '';
-    };
-  };
-
-  config = mkIf (cfg != null) {
-    assertions = [
-      (hm.assertions.assertPlatform "xsession.pointerCursor" pkgs
-        platforms.linux)
-    ];
-
-    home.packages = [ cfg.package ];
-
-    xsession.initExtra = ''
-      ${pkgs.xorg.xsetroot}/bin/xsetroot -xcf ${cursorPath} ${toString cfg.size}
-    '';
-
-    xresources.properties = {
-      "Xcursor.theme" = cfg.name;
-      "Xcursor.size" = cfg.size;
-    };
-
-    gtk.cursorTheme = mkDefault { inherit (cfg) package name size; };
-
-    # Set name in icons theme, for compatibility with AwesomeWM etc. See:
-    # https://github.com/nix-community/home-manager/issues/2081
-    # https://wiki.archlinux.org/title/Cursor_themes#XDG_specification
-    home.file.".icons/default/index.theme".text = ''
-      [icon theme]
-      Name=Default
-      Comment=Default Cursor Theme
-      Inherits=${cfg.name}
-    '';
-  };
-}