diff options
author | Jonas Chevalier <zimbatm@zimbatm.com> | 2022-01-08 01:54:04 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-01-08 01:54:04 +0100 |
commit | 1e910209ae414755415ed8ef990fa3cbb07c8cd9 (patch) | |
tree | 5d30274a7721d2eae947d1fef599a10365fcc4a4 /doc/builders | |
parent | cacab72b753b3793bc3d6bbe41374044d990cfa9 (diff) |
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.
Diffstat (limited to 'doc/builders')
-rw-r--r-- | doc/builders/special/mkshell.section.md | 32 |
1 files changed, 26 insertions, 6 deletions
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md index 8a62c50e17dd3..73cc57f485bd2 100644 --- a/doc/builders/special/mkshell.section.md +++ b/doc/builders/special/mkshell.section.md @@ -1,17 +1,37 @@ # 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 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 { - # 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 ]; + + 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. |