doc/build-helpers/special/mkshell.section.md

   1 # pkgs.mkShell {#sec-pkgs-mkShell}
   2
   3 `pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
   4 repetition when using it with `nix-shell` (or `nix develop`).
   5
   6 ## Usage {#sec-pkgs-mkShell-usage}
   7
   8 Here is a common usage example:
   9
  10 ```nix
  11 { pkgs ? import <nixpkgs> {} }:
  12 pkgs.mkShell {
  13   packages = [ pkgs.gnumake ];
  14
  15   inputsFrom = [ pkgs.hello pkgs.gnutar ];
  16
  17   shellHook = ''
  18     export DEBUG=1
  19   '';
  20 }
  21 ```
  22
  23 ## Attributes {#sec-pkgs-mkShell-attributes}
  24
  25 * `name` (default: `nix-shell`). Set the name of the derivation.
  26 * `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
  27 * `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
  28 * `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.
  29
  30 ... all the attributes of `stdenv.mkDerivation`.
  31
  32 ## Variants {#sec-pkgs-mkShell-variants}
  33
  34 `pkgs.mkShellNoCC` is a variant that uses `stdenvNoCC` instead of `stdenv` as base environment. This is useful if no C compiler is needed in the shell environment.
  35
  36 ## Building the shell {#sec-pkgs-mkShell-building}
  37
  38 This derivation output will contain a text file that contains a reference to
  39 all the build inputs. This is useful in CI where we want to make sure that
  40 every derivation, and its dependencies, build properly. Or when creating a GC
  41 root so that the build dependencies don't get garbage-collected.