pyrox.dev
1# Development Shell helpers {#chap-devShellTools}
2
3The `nix-shell` command has popularized the concept of transient shell environments for development or testing purposes.
4<!--
5 We should try to document the product, not its development process in the Nixpkgs reference manual,
6 but *something* needs to be said to provide context for this library.
7 This is the most future proof sentence I could come up with while Nix itself does yet make use of this.
8 Relevant is the current status of the devShell attribute "project": https://github.com/NixOS/nix/issues/7501
9 -->
10However, `nix-shell` is not the only way to create such environments, and even `nix-shell` itself can indirectly benefit from this library.
11
12This library provides a set of functions that help create such environments.
13
14## `devShellTools.valueToString` {#sec-devShellTools-valueToString}
15
16Converts Nix values to strings in the way the [`derivation` built-in function](https://nix.dev/manual/nix/2.23/language/derivations) does.
17
18:::{.example}
19## `valueToString` usage examples
20
21```nix
22devShellTools.valueToString (builtins.toFile "foo" "bar")
23# => "/nix/store/...-foo"
24```
25
26```nix
27devShellTools.valueToString false
28# => ""
29```
30
31:::
32
33## `devShellTools.unstructuredDerivationInputEnv` {#sec-devShellTools-unstructuredDerivationInputEnv}
34
35Convert a set of derivation attributes (as would be passed to [`derivation`]) to a set of environment variables that can be used in a shell script.
36This function does not support `__structuredAttrs`, but does support `passAsFile`.
37
38:::{.example}
39## `unstructuredDerivationInputEnv` usage example
40
41```nix
42devShellTools.unstructuredDerivationInputEnv {
43 drvAttrs = {
44 name = "foo";
45 buildInputs = [
46 hello
47 figlet
48 ];
49 builder = bash;
50 args = [
51 "-c"
52 "${./builder.sh}"
53 ];
54 };
55}
56# => {
57# name = "foo";
58# buildInputs = "/nix/store/...-hello /nix/store/...-figlet";
59# builder = "/nix/store/...-bash";
60#}
61```
62
63Note that `args` is not included, because Nix does not added it to the builder process environment.
64
65:::
66
67## `devShellTools.derivationOutputEnv` {#sec-devShellTools-derivationOutputEnv}
68
69Takes the relevant parts of a derivation and returns a set of environment variables, that would be present in the derivation.
70
71:::{.example}
72## `derivationOutputEnv` usage example
73
74```nix
75let
76 pkg = hello;
77in
78devShellTools.derivationOutputEnv {
79 outputList = pkg.outputs;
80 outputMap = pkg;
81}
82```
83
84:::