mkShell: add builder (#30975)

2 files changed, 24 insertions, 0 deletions

diff --git a/doc/default.nix b/doc/default.nix
index e3d7ef2ef9d6..60c613878c72 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -50,6 +50,10 @@ pkgs.stdenv.mkDerivation {
       useChapters = true;
     }
   + toDocbook {
+      inputFile = ./shell.md;
+      outputFile = "shell.xml";
+    }
+  + toDocbook {
       inputFile = ./languages-frameworks/python.md;
       outputFile = "./languages-frameworks/python.xml";
     }
diff --git a/doc/shell.md b/doc/shell.md
new file mode 100644
index 000000000000..a4f999695cbc
--- /dev/null
+++ b/doc/shell.md
@@ -0,0 +1,20 @@
+---
+title: stdenv.mkShell
+author: zimbatm
+date: 2017-10-30
+---
+
+stdenv.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
+
+```nix
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.mkShell {
+  # this will make all the build inputs from hello and gnutar available to the shell environment
+  inputsFrom = with pkgs; [ hello gnutar ];
+  buildInputs = [ pkgs.gnumake ];
+}
+```