13 files changed, 40 insertions, 31 deletions
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
index 1feb75cbd6f..8a62c50e17d 100644
--- a/doc/builders/special/mkshell.section.md
+++ b/doc/builders/special/mkshell.section.md
@@ -1,15 +1,17 @@
 # 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 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`.
 
 ## Usage {#sec-pkgs-mkShell-usage}
 
 ```nix
 { pkgs ? import <nixpkgs> {} }:
 pkgs.mkShell {
-  # this will make all the build inputs from hello and gnutar
-  # available to the shell environment
+  # 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 ];
-  buildInputs = [ pkgs.gnumake ];
 }
 ```
diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index 36369fd4e63..725ffd4becc 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -10,7 +10,7 @@ with import <nixpkgs> {};
 
 mkShell {
   name = "dotnet-env";
-  buildInputs = [
+  packages = [
     dotnet-sdk_3
   ];
 }
@@ -25,7 +25,7 @@ with import <nixpkgs> {};
 
 mkShell {
   name = "dotnet-env";
-  buildInputs = [
+  packages = [
     (with dotnetCorePackages; combinePackages [
       sdk_3_1
       sdk_3_0
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 96ac61ab54c..b466748f548 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -245,7 +245,7 @@ let
     ps.toolz
   ]);
 in mkShell {
-  buildInputs = [
+  packages = [
     pythonEnv
 
     black
diff --git a/doc/languages-frameworks/ruby.section.md b/doc/languages-frameworks/ruby.section.md
index c519d79d3da..b8fc19eb6b0 100644
--- a/doc/languages-frameworks/ruby.section.md
+++ b/doc/languages-frameworks/ruby.section.md
@@ -106,7 +106,7 @@ let
     name = "gems-for-some-project";
     gemdir = ./.;
   };
-in mkShell { buildInputs = [ gems gems.wrappedRuby ]; }
+in mkShell { packages = [ gems gems.wrappedRuby ]; }
 ```
 
 With this file in your directory, you can run `nix-shell` to build and use the gems. The important parts here are `bundlerEnv` and `wrappedRuby`.
diff --git a/maintainers/scripts/update-luarocks-shell.nix b/maintainers/scripts/update-luarocks-shell.nix
index 23a940b3691..d3f342b07a9 100644
--- a/maintainers/scripts/update-luarocks-shell.nix
+++ b/maintainers/scripts/update-luarocks-shell.nix
@@ -2,8 +2,11 @@
 }:
 with nixpkgs;
 mkShell {
-  buildInputs = [
-    bash luarocks-nix nix-prefetch-scripts parallel
+  packages = [
+    bash
+    luarocks-nix
+    nix-prefetch-scripts
+    parallel
   ];
   LUAROCKS_NIXPKGS_PATH = toString nixpkgs.path;
 }
diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix
index cc3609d750e..e5ec9b8f97f 100644
--- a/nixos/doc/manual/shell.nix
+++ b/nixos/doc/manual/shell.nix
@@ -4,5 +4,5 @@ in
 pkgs.mkShell {
   name = "nixos-manual";
 
-  buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ];
+  packages = with pkgs; [ xmlformat jing xmloscopy ruby ];
 }
diff --git a/pkgs/applications/editors/emacs-modes/emacs2nix.nix b/pkgs/applications/editors/emacs-modes/emacs2nix.nix
index cc82646870c..658756250a0 100644
--- a/pkgs/applications/editors/emacs-modes/emacs2nix.nix
+++ b/pkgs/applications/editors/emacs-modes/emacs2nix.nix
@@ -7,10 +7,10 @@ let
     rev = "860da04ca91cbb69c9b881a54248d16bdaaf9923";
     sha256 = "1r3xmyk9rfgx7ln69dk8mgbnh3awcalm3r1c5ia2shlsrymvv1df";
   };
+in
+pkgs.mkShell {
 
-in pkgs.mkShell {
-
-  buildInputs = [
+  packages = [
     pkgs.bash
   ];
 
diff --git a/pkgs/applications/editors/emacs-modes/updater-emacs.nix b/pkgs/applications/editors/emacs-modes/updater-emacs.nix
index 4c321065445..7502bcc2fee 100644
--- a/pkgs/applications/editors/emacs-modes/updater-emacs.nix
+++ b/pkgs/applications/editors/emacs-modes/updater-emacs.nix
@@ -29,7 +29,7 @@ let
   in [ promise semaphore ]);
 
 in pkgs.mkShell {
-  buildInputs = [
+  packages = [
     pkgs.git
     pkgs.nix
     pkgs.bash
diff --git a/pkgs/applications/networking/cluster/nixops/shell.nix b/pkgs/applications/networking/cluster/nixops/shell.nix
index 3fc06b0bc73..0139cb2c812 100644
--- a/pkgs/applications/networking/cluster/nixops/shell.nix
+++ b/pkgs/applications/networking/cluster/nixops/shell.nix
@@ -1,7 +1,7 @@
-{ pkgs ? import <nixpkgs> {} }:
+{ pkgs ? import <nixpkgs> { } }:
 
 pkgs.mkShell {
-  buildInputs = [
+  packages = [
     pkgs.poetry2nix.cli
     pkgs.pkg-config
     pkgs.libvirt
diff --git a/pkgs/build-support/agda/default.nix b/pkgs/build-support/agda/default.nix
index 984d61f1f75..ed7d11a1314 100644
--- a/pkgs/build-support/agda/default.nix
+++ b/pkgs/build-support/agda/default.nix
@@ -1,6 +1,6 @@
 # Builder for Agda packages.
 
-{ stdenv, lib, self, Agda, runCommandNoCC, makeWrapper, writeText, mkShell, ghcWithPackages, nixosTests }:
+{ stdenv, lib, self, Agda, runCommandNoCC, makeWrapper, writeText, ghcWithPackages, nixosTests }:
 
 with lib.strings;
 
diff --git a/pkgs/build-support/mkshell/default.nix b/pkgs/build-support/mkshell/default.nix
index a70dc0390cb..7ca4cc23c1d 100644
--- a/pkgs/build-support/mkshell/default.nix
+++ b/pkgs/build-support/mkshell/default.nix
@@ -3,18 +3,22 @@
 # A special kind of derivation that is only meant to be consumed by the
 # nix-shell.
 {
-  inputsFrom ? [], # a list of derivations whose inputs will be made available to the environment
-  buildInputs ? [],
-  nativeBuildInputs ? [],
-  propagatedBuildInputs ? [],
-  propagatedNativeBuildInputs ? [],
-  ...
+  # a list of packages to add to the shell environment
+  packages ? [ ]
+, # propagate all the inputs from the given derivations
+  inputsFrom ? [ ]
+, buildInputs ? [ ]
+, nativeBuildInputs ? [ ]
+, propagatedBuildInputs ? [ ]
+, propagatedNativeBuildInputs ? [ ]
+, ...
 }@attrs:
 let
   mergeInputs = name: lib.concatLists (lib.catAttrs name
-    ([attrs] ++ inputsFrom));
+    ([ attrs ] ++ inputsFrom));
 
   rest = builtins.removeAttrs attrs [
+    "packages"
     "inputsFrom"
     "buildInputs"
     "nativeBuildInputs"
@@ -26,15 +30,15 @@ in
 
 stdenv.mkDerivation ({
   name = "nix-shell";
-  phases = ["nobuildPhase"];
+  phases = [ "nobuildPhase" ];
 
   buildInputs = mergeInputs "buildInputs";
-  nativeBuildInputs = mergeInputs "nativeBuildInputs";
+  nativeBuildInputs = packages ++ (mergeInputs "nativeBuildInputs");
   propagatedBuildInputs = mergeInputs "propagatedBuildInputs";
   propagatedNativeBuildInputs = mergeInputs "propagatedNativeBuildInputs";
 
   shellHook = lib.concatStringsSep "\n" (lib.catAttrs "shellHook"
-    (lib.reverseList inputsFrom ++ [attrs]));
+    (lib.reverseList inputsFrom ++ [ attrs ]));
 
   nobuildPhase = ''
     echo
diff --git a/pkgs/development/mobile/androidenv/examples/shell.nix b/pkgs/development/mobile/androidenv/examples/shell.nix
index 95f6a3bdbba..45cccf22c7d 100644
--- a/pkgs/development/mobile/androidenv/examples/shell.nix
+++ b/pkgs/development/mobile/androidenv/examples/shell.nix
@@ -115,7 +115,7 @@ let
 in
 pkgs.mkShell rec {
   name = "androidenv-demo";
-  buildInputs = [ androidSdk platformTools jdk pkgs.android-studio ];
+  packages = [ androidSdk platformTools jdk pkgs.android-studio ];
 
   LANG = "C.UTF-8";
   LC_ALL = "C.UTF-8";
diff --git a/pkgs/tools/X11/opentabletdriver/shell.nix b/pkgs/tools/X11/opentabletdriver/shell.nix
index 526fa4a4432..4367d22e9df 100644
--- a/pkgs/tools/X11/opentabletdriver/shell.nix
+++ b/pkgs/tools/X11/opentabletdriver/shell.nix
@@ -1,9 +1,9 @@
-{ pkgs ? import ../../../../. {} }:
+{ pkgs ? import ../../../../. { } }:
 
 with pkgs;
 
 mkShell {
-  buildInputs = [
+  packages = [
     common-updater-scripts
     curl
     dotnetCorePackages.sdk_5_0