mkShell: make it buildable (#153194)

When I designed `mkShell`, I didn't have a good idea of what the output
should look like and so decided to make the build fail. In practice,
this causes quite a bit of confusion and complications because now the
shell cannot be part of a normal package set without failing the CI as
well.

This commit changes that build phase to record all the build inputs in a
file. That way it becomes possible to build it, makes sure that all the
build inputs get built as well, and also can be used as a GC root.
(by applying the same trick as #95536).

The documentation has also been improved to better describe what mkShell
does and how to use it.

1 files changed, 26 insertions, 6 deletions

diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
index 8a62c50e17dd3..73cc57f485bd2 100644
--- a/doc/builders/special/mkshell.section.md
+++ b/doc/builders/special/mkshell.section.md
@@ -1,17 +1,37 @@
 # pkgs.mkShell {#sec-pkgs-mkShell}
 
-`pkgs.mkShell` is a special kind of derivation that is only useful when using
-it combined with `nix-shell`. It will in fact fail to instantiate when invoked
-with `nix-build`.
+`pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
+repetition when using it with `nix-shell` (or `nix develop`).
 
 ## Usage {#sec-pkgs-mkShell-usage}
 
+Here is a common usage example:
+
 ```nix
 { pkgs ? import <nixpkgs> {} }:
 pkgs.mkShell {
-  # specify which packages to add to the shell environment
   packages = [ pkgs.gnumake ];
-  # add all the dependencies, of the given packages, to the shell environment
-  inputsFrom = with pkgs; [ hello gnutar ];
+
+  inputsFrom = [ pkgs.hello pkgs.gnutar ];
+
+  shellHook = ''
+    export DEBUG=1
+  '';
 }
 ```
+
+## Attributes
+
+* `name` (default: `nix-shell`). Set the name of the derivation.
+* `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
+* `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
+* `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.
+
+... all the attributes of `stdenv.mkDerivation`.
+
+## Building the shell
+
+This derivation output will contain a text file that contains a reference to
+all the build inputs. This is useful in CI where we want to make sure that
+every derivation, and its dependencies, build properly. Or when creating a GC
+root so that the build dependencies don't get garbage-collected.