feat: use numtide/devshell to improve devshell experience

[phanirithvij]

[phanirithvij]

TODO

• docs
  • documenting the devshell in contributing.md
  • clearly specify that DEVSHELL_NO_MOTD=1 can be used to disable the motd.
• upstream fixes
  • build(deps): bump actions/checkout from 5 to 6 numtide/devshell#358
  • fix: support pure mode numtide/devshell#359
  • non-blocker fix: use overrideAttrs to override wrapper.meta numtide/treefmt-nix#465

We need to decide on

• Do we need numtide/devshell or just a welcome and menu scripts that we maintain?
  • I vote for numtide/devshell. given the upstream is reliable and it is an actively maintained project fix: support pure mode numtide/devshell#359
  • We well have to slowly recreate the numtide devshell functionality ourselves on top of pkgs.mkShell, where devshell.mkShell uses a derivation with a stripped out stdenv under the hood.
• The welcome message
• What categories to include
• What commands can be made scripts which would be worth adding to the menu
  • noticed the metrics and added two mentioned in the maintainers/reporting.md
  • watchdocs livedocs or something which would be devmode for ju1m's docs pr. doc: init #1891 (comment)
• Whether to recommend direnv, or just mention it in the contribution docs somewhere
  • echo use nix > .direnv
  • direnv allow
  • echo -en '.direnv\n.envrc' >> .git/info/exclude
  • Many valid arguments exist for not adding it to the repo, but I think it is fine to recommend it
    • Remove .envrc NixOS/nixpkgs#325793
    • Load different env file direnv/direnv#348 (comment)
    • mv .envrc → .envrc.example NixOS/nixfmt#178

[phanirithvij]

We can review some prs in the office hours today if you are up to it.

[eljamm]

Key points from reviewing this in the office hours:

• what should the welcome message be?
  • whole shell or just run this for help
  • can we add an option?
• this modifies the terminal's PS1, which users might not be okay with
• if you don't clear direnv's cache, the environment does not load the welcome message
• we don't want to auto-enable the pre-commit hook anymore when entering the shell env
• on my machine nix-shell and nix develop doesn't show me the message and I need to wrap the devshell in a pkgs.mkShell's shellHook

review.patch

diff --git a/maintainers/shells/default.nix b/maintainers/shells/default.nix
index 03d6eeb4..8dfe3dbb 100644
--- a/maintainers/shells/default.nix
+++ b/maintainers/shells/default.nix
@@ -1,17 +1,18 @@
 {
   lib,
   pkgs,
-  devshell,
-  nixdoc-to-github,
+  sources,
+
+  callPackage,
 
   # toplevel attributes
-  ngipkgs,
   formatter,
   ...
 }:
 let
-  devshellArgs = lib.makeExtensible (final: {
+  devshell = import sources.devshell { nixpkgs = pkgs; };
 
+  shellEnv = lib.makeExtensible (final: {
     generalCategory = "[general commands]";
 
     mkAliases =
@@ -35,13 +36,6 @@ let
             (value.help or value.cmd);
       }) aliases;
 
-    mapCommands =
-      category: packages:
-      builtins.map (p: {
-        inherit category;
-        package = p;
-      }) packages;
-
     # from numtide/devshell, copyright Numtide, MIT licensed
     # Returns a list of all the input derivation ... for a derivation.
     inputsOf =
@@ -68,6 +62,13 @@ let
       $(type -p menu &>/dev/null && menu)
     '';
 
+    mapCommands =
+      category: packages:
+      builtins.map (p: {
+        inherit category;
+        package = p;
+      }) packages;
+
     commands =
       (final.mapCommands "formatter" final.formatters)
       ++ final.defaultCmds
@@ -81,13 +82,12 @@ let
 
     packagesFrom = [ ]; # inputsFrom equivalent, are hidden in the menu
 
-    # End devshell.mkShell args
-
-    _devshell = devshell.mkShell (
+    finalPackage = devshell.mkShell (
       lib.filterAttrs (
         name: value:
         # filter only the valid args for devshell.mkShell
         builtins.elem name [
+          "shellHook"
           "name"
           "motd"
           "commands"
@@ -97,25 +97,6 @@ let
       ) final
     );
 
-    finalPackage =
-      if (final.shellHook != "") then
-        # allow shellHook overriding by embedding into another shell
-        # FIXME(phanirithvij): possible to fix this in numtide/devshell, a shellHook argument to mkShell
-        pkgs.mkShellNoCC {
-          inherit (final) name;
-          shellHook = ''
-            source ${final._devshell.hook}/nix-support/setup-hook
-            ${final.shellHook}
-          '';
-          packages = [ final._devshell ];
-        }
-      else
-        # use the minimal numtide shell if shellHook override is not required
-        final._devshell;
-
-    # default empty shellHook, implies no override
-    shellHook = "";
-
     # Include all formatter packages. Format with:
     # $ treefmt
     # $ nix fmt
@@ -140,9 +121,15 @@ let
             lib.fileset.fileFilter (file: file.hasExt "nix") ./commands
           )
         );
-        callPackage' = lib.callPackageWith (pkgs // { inherit nixdoc-to-github ngipkgs; });
       in
-      final.mapCommands "commands" (builtins.map (path: callPackage' path { }) files);
+      final.mapCommands "commands" (map (path: callPackage path { }) files);
   });
+
+  shell.finalPackage = pkgs.mkShell {
+    packages = [ shellEnv.finalPackage ];
+    shellHook = ''
+      menu
+    '';
+  };
 in
-devshellArgs
+shell

[phanirithvij]

this modifies the terminal's PS1, which users might not be okay with

There is NIX_SHELL_PRESERVE_PROMPT for nix versions later than 2.4

if you don't clear direnv's cache, the environment does not load the welcome message

This can be documented, cannot be fixed by us.

we don't want to auto-enable the pre-commit hook anymore when entering the shell env

made the flake shell the same as the shells/default.nix, not extending it anymore with the pre-commit checks hooks and packages.

on my machine nix-shell and nix develop doesn't show me the message

I wasn't able to reproduce this in two other machines. I think it is something we can investigate and fix. But even with this setup menu and other tools are available in the shell, not so different from the current shell before this pr.

[eljamm]

on my machine nix-shell and nix develop doesn't show me the message

I wasn't able to reproduce this in two other machines. I think it is something we can investigate and fix. But even with this setup menu and other tools are available in the shell, not so different from the current shell before this pr.

Just for clarity, @phanirithvij and I were able to debug this yesterday and it turned out it was caused by my fish config. Not sure what the exact culprit is, but this will probably not affect users.

[phanirithvij]

I'll try to refactor this to use the module system later, but I think it is good enough, we can extend the shell too.

[eljamm]

Looks good to me and is working as intended.