man: make package nullable and default to null on darwin

docs/release-notes/rl-2605.md

@@ -36,3 +36,9 @@ changes are only active if the `home.stateVersion` option is set to
   you had the key `XDG_DESKTOP_DIR` before, you should now use the key
   `DESKTOP`. Home Manager 26.05 introduced a warning when the `XDG_<name>_DIR`
   form is used.
+
+- The [](#opt-programs.man.package) option now defaults to `null` on
+  Darwin because the GNU `man` from nixpkgs ships `apropos`/`man -k`
+  and `whatis`/`man -f` binaries that don't work on Darwin. Nix-installed
+  manual pages still work with macOS's built-in `man` via
+  [](#opt-home.extraOutputsToInstall).

modules/programs/man.nix

@@ -21,7 +21,18 @@ in
         '';
       };
 
-      package = lib.mkPackageOption pkgs "man" { };
+      package = mkOption {
+        type = with types; nullOr package;
+        default =
+          if pkgs.stdenv.isDarwin && lib.versionAtLeast config.home.stateVersion "26.05" then
+            null
+          else
+            pkgs.man;
+        defaultText = lib.literalExpression ''
+          if pkgs.stdenv.isDarwin && lib.versionAtLeast config.home.stateVersion "26.05" then null else pkgs.man
+        '';
+        description = "The {command}`man` package to use.";
+      };
 
       extraConfig = mkOption {
         type = types.lines;
@@ -51,11 +62,15 @@ in
   };
 
   config = lib.mkIf cfg.enable {
-    home.packages = [ cfg.package ];
+    warnings = lib.optional (
+      cfg.generateCaches && cfg.package == null
+    ) "programs.man.generateCaches has no effect when programs.man.package is null";
+
+    home.packages = lib.optional (cfg.package != null) cfg.package;
     home.extraOutputsToInstall = [ "man" ];
 
     # This is mostly copy/pasted/adapted from NixOS' documentation.nix.
-    home.file = lib.mkIf cfg.generateCaches {
+    home.file = lib.mkIf (cfg.generateCaches && cfg.package != null) {
       ".manpath".text =
         let
           # Generate a directory containing installed packages' manpages.

tests/modules/programs/man/default.nix

@@ -1,4 +1,10 @@
+{ lib, pkgs, ... }:
+
 {
   man-apropos = ./apropos.nix;
   man-no-manpath = ./no-manpath.nix;
+  man-no-caches-without-package = ./no-caches-without-package.nix;
+}
+// lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {
+  man-no-package-on-darwin = ./no-package-on-darwin.nix;
 }

tests/modules/programs/man/no-caches-without-package.nix

@@ -0,0 +1,19 @@
+{
+  config = {
+    home.stateVersion = "26.05";
+
+    programs.man = {
+      enable = true;
+      package = null;
+      generateCaches = true;
+    };
+
+    test.asserts.warnings.expected = [
+      "programs.man.generateCaches has no effect when programs.man.package is null"
+    ];
+
+    nmt.script = ''
+      assertPathNotExists home-files/.manpath
+    '';
+  };
+}

tests/modules/programs/man/no-package-on-darwin.nix

@@ -0,0 +1,12 @@
+{
+  config = {
+    home.stateVersion = "26.05";
+
+    programs.man.enable = true;
+
+    nmt.script = ''
+      assertPathNotExists home-path/bin/man
+      assertPathNotExists home-files/.manpath
+    '';
+  };
+}