nixpkgs-suyu/doc/builders/special/mkshell.section.md

# pkgs.mkShell {#sec-pkgs-mkShell}

`pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
repetition when using it with `nix-shell` (or `nix develop`).

## Usage {#sec-pkgs-mkShell-usage}

Here is a common usage example:

```nix
{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  packages = [ pkgs.gnumake ];

  inputsFrom = [ pkgs.hello pkgs.gnutar ];

  shellHook = ''
    export DEBUG=1
  '';
}
```

## Attributes

* `name` (default: `nix-shell`). Set the name of the derivation.
* `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
* `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
* `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.

... all the attributes of `stdenv.mkDerivation`.

## Building the shell

This derivation output will contain a text file that contains a reference to
all the build inputs. This is useful in CI where we want to make sure that
every derivation, and its dependencies, build properly. Or when creating a GC
root so that the build dependencies don't get garbage-collected.
Convert mkShell from DocBook to CommonMark 2020-12-13 19:47:22 +01:00			`# pkgs.mkShell {#sec-pkgs-mkShell}`

mkShell: make it buildable (#153194) 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. 2022-01-08 01:54:04 +01:00			`pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
			repetition when using it with `nix-shell` (or `nix develop`).
Convert mkShell from DocBook to CommonMark 2020-12-13 19:47:22 +01:00
			`## Usage {#sec-pkgs-mkShell-usage}`

mkShell: make it buildable (#153194) 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. 2022-01-08 01:54:04 +01:00			`Here is a common usage example:`

Convert mkShell from DocBook to CommonMark 2020-12-13 19:47:22 +01:00			```nix
			`{ pkgs ? import <nixpkgs> {} }:`
			`pkgs.mkShell {`
mkShell: introduce packages argument (#122180) The distinction between the inputs doesn't really make sense in the mkShell context. Technically speaking, we should be using the nativeBuildInputs most of the time. So in order to make this function more beginner-friendly, add "packages" as an attribute, that maps to nativeBuildInputs. This commit also updates all the uses in nixpkgs. 2021-05-13 19:17:29 +02:00			`packages = [ pkgs.gnumake ];`
mkShell: make it buildable (#153194) 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. 2022-01-08 01:54:04 +01:00
			`inputsFrom = [ pkgs.hello pkgs.gnutar ];`

			`shellHook = ''`
			`export DEBUG=1`
			`'';`
Convert mkShell from DocBook to CommonMark 2020-12-13 19:47:22 +01:00			`}`
			```
mkShell: make it buildable (#153194) 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. 2022-01-08 01:54:04 +01:00
			`## Attributes`

			* `name` (default: `nix-shell`). Set the name of the derivation.
			* `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
			* `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
			* `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.

			... all the attributes of `stdenv.mkDerivation`.

			`## Building the shell`

			`This derivation output will contain a text file that contains a reference to`
			`all the build inputs. This is useful in CI where we want to make sure that`
			`every derivation, and its dependencies, build properly. Or when creating a GC`
			`root so that the build dependencies don't get garbage-collected.`