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.main
parent
cacab72b75
commit
1e910209ae
@ -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. |
||||
|
Loading…
Reference in new issue