nixpkgs/doc/builders/special/mkshell.section.md
pennae 052bb41410 doc: assign ids to many headings
without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.

a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).
2023-03-27 22:39:11 +02:00

38 lines
1.2 KiB
Markdown

# 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 {#sec-pkgs-mkShell-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 {#sec-pkgs-mkShell-building}
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.