Nixpkgs: mkShell needs more documentation in the manual

[deliciouslytyped]

[worldofpeace]

Only thing I see that really could be more helpful is explaining these parameters

  inputsFrom ? [],
  buildInputs ? [],
  nativeBuildInputs ? [],
  propagatedBuildInputs ? [],
  propagatedNativeBuildInputs ? [],

All of which are the same for stdenv.mkDerivation except inputsFrom which should have a more detailed description.

And maybe get a link to https://nixos.org/nix/manual/#sec-nix-shell somewhere in there.

[toraritte]

Adding @manveru's summary (from discourse thread):

all [mkShell] does is provide some defaults for a stdenv.mkDerivation. So you don’t need to give it a src or name, all you really need is buildInputs, maybe a shellHook that runs when you enter the nix-shell, and any env variables you want.

I always wondered why certain examples use mkDerivation while others prefer mkShell, and the Nixpkgs manuals mkShell section is not overly informative.

EDIT:

• initial PR for 'mkShell` (via Ryan Chan's blog post)
• PR to make mkShell more composable

[jtojnar]

When using mkDerivation, you need to set name and src. mkShell is a convenience utility that does not require that.

In fact it is just mkDerivation wrapper:

https://github.com/NixOS/nixpkgs/blob/d0017d7b7e0d36ec7c905ab75b59494eb36fb2d0/pkgs/build-support/mkshell/default.nix#L31

that

1. sets a default name:
   https://github.com/NixOS/nixpkgs/blob/d0017d7b7e0d36ec7c905ab75b59494eb36fb2d0/pkgs/build-support/mkshell/default.nix#L32
2. removes phases in order to not need src:
   https://github.com/NixOS/nixpkgs/blob/d0017d7b7e0d36ec7c905ab75b59494eb36fb2d0/pkgs/build-support/mkshell/default.nix#L33
3. Sets up dummy phase to prevent nix build:
   https://github.com/NixOS/nixpkgs/blob/d0017d7b7e0d36ec7c905ab75b59494eb36fb2d0/pkgs/build-support/mkshell/default.nix#L40-L45
4. Also, there is inputsFrom, that allows you to inherit inputs from other packages:
   https://github.com/NixOS/nixpkgs/blob/d0017d7b7e0d36ec7c905ab75b59494eb36fb2d0/pkgs/build-support/mkshell/default.nix#L14-L20

The last part is little harder to understand and perhaps it would deserve a comment but otherwise the code is quite legible and linking there from manual should be enough.

[hyperfekt]

Is there any reason to ever use non-native buildInputs, since the derivation is never built and thus there is no build target, but instead the inputs should be working on the 'builder' that invokes the shell?

[drewmullen]

When using mkDerivation, you need to set name and src. mkShell is a convenience utility that does not require that.

it appears as though src is no longer required with mkDerivation as ive been running $ nix-shell shell.nix. name is still required though.

shell.nix:

with import <nixpkgs> {};

stdenv.mkDerivation {
  name = "my-environment";

  buildInputs = with pkgs; [
     coreutils
     bash
     wget
     zip
     awscli
  ];
}