mkShell: make it buildable

[zimbatm]

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.

Motivation for this change

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 22.05 Release Notes (or backporting 21.11 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

[roberth]

You could also write out a shell script that behaves like a better nix-shell.

Right now, the output is a single file with no room for extension, because it is not a directory. A good first step is to write to $out/env.sh instead, so other files can be added.

[zimbatm]

There is an infinite number of things I could do. The question is; is this PR better than before? I will make it so that the file is unusable, as it's not meant to be part of the interface.

[roberth]

I'm not asking you to do an infinite number of things, just to prevent a future breaking change.

I will make it so that the file is unusable

That makes it a non-breaking change. 👍

[roberth]

I don't quite understand why. Could you explain it here in the message?

[zimbatm]

Ok, this is ready for another round of review.

[zimbatm]

Waiting for a last round of reviews.

[rvl]

Very helpful, thanks @zimbatm and @roberth - I can remove my nobuildPhase overrides now.

[Atry]

buildEnv is not used anywhere. Shall we delete it?

[roberth]

@Atry well spotted. Feel free to go ahead.

[charles-dyfis-net]

There's still equivalent logic to the restriction this pulls elsewhere in nixpkgs:

pkgs/build-support/build-fhsenv-bubblewrap/default.nix:      echo >&2 "*** User chroot 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"
pkgs/build-support/build-fhsenv-chroot/default.nix:      echo >&2 "*** User chroot 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"
pkgs/development/interpreters/lua-5/wrapper.nix:          echo >&2 "*** lua 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"
pkgs/development/interpreters/octave/build-env.nix:        echo >&2 "*** octave 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"
pkgs/development/interpreters/python/wrapper.nix:          echo >&2 "*** Python 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"
pkgs/development/ruby-modules/bundled-common/default.nix:            echo >&2 "*** Ruby 'env' attributes are intended for interactive nix-shell sessions, not for building! ***"