Add shell.nix tutorial #671

zmitchell · 2023-08-03T03:58:08Z

Creates a tutorial to complete #516

proofconstruction

Good start, but we should either make this sufficiently different from Declarative and Reproducible Developer Environments or combine them and reorganize.

source/tutorials/learning-journey/shell-dot-nix.md

proofconstruction · 2023-08-03T04:59:17Z

source/tutorials/learning-journey/shell-dot-nix.md

+        PS1 = "\u@\h [myEnv] $ ";
+    }
+```
+


Suggested change

Other variables are protected: the shell prompt format is set by the `PS1` environment variable, but `nix-shell` already overrides this by default, and does not allow us to alter the `PS1` attribute directly. In these cases, we can still set a new value for that environment variable by manually exporting it in the [`shellHook` attribute](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell-attributes) passed to `mkShell`.

To set the shell prompt to the format `<username>@<hostname> [myEnv] $ `, the `shell.nix` file would look like this:

```nix

let

pkgs = import <nixpkgs> {};

in

pkgs.mkShell {

packages = [

pkgs.python310

pkgs.curl

];

# Database username and password

DB_USER = "db_user";

DB_PASSWORD = "super secret don't look";

# Set the shell prompt to '<username>@<hostname> [myEnv] $ '

mkShell = ''

export PS1="\u@\h [myEnv] $ ";

'';

}

source/tutorials/learning-journey/shell-dot-nix.md

infinisil

We discussed this together in todays Learning journey meeting.

There's duplication with the existing tutorial, but this is the first tutorial in the new learning journey series and it can be reconciled later with the existing material. We can add this to the landing page of the learning journey section.

Does it overlap with https://nix.dev/tutorials/first-steps/declarative-and-reproducible-developer-environments?
- @zmitchell: Doesn't have motivation, doesn't cover everything
- @proofconstruction: There should be a flow between these tutorials
- @zmitchell: That one isn't in the learning journey track
Regarding PS1 not being settable in env vars
- @roberth: nix-shell is messy, not worth going in-depth
- @infinisil: Warning to say that some attributes can't be set in derivation attributes, need to use shellHook instead
- @proofconstruction: Apparently the PS1 thing it's a feature in some Nix release notes
- @roberth: shellHook is also useful for e.g. appending to variables
@infinisil:
- Use python3 instead of python310

source/tutorials/learning-journey/shell-dot-nix.md

nixos-discourse · 2023-08-03T14:07:48Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-03-learning-journey-working-group-meeting-notes-20/31251/1

zmitchell · 2023-08-10T13:24:12Z

source/tutorials/learning-journey/shell-dot-nix.md

+  }
+```
+
+


Discussed online: mention this as a warning rather than guidance. Mention that you can use shellHook to still set these variables if you need to. Then illustrate the Bash syntax for exporting environment variables to do this as a one line example. Another example is setting secrets you get from another command.

zmitchell · 2023-08-10T13:24:45Z

source/tutorials/learning-journey/shell-dot-nix.md

+      touch should_exist.txt
+    '';
+  }
+```


Discussed online: Provide other examples such as initializing a data directory for a database, getting secrets, etc.

nixos-discourse · 2023-08-10T14:02:53Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-10-learning-journey-meeting-notes-21/31556/1

infinisil · 2023-08-10T15:24:38Z

@zmitchell Oh, I said in the meeting that I would like to review it again, which I was just doing right now 😅

zmitchell · 2023-08-10T15:27:10Z

Shoot, I totally forgot. I can revert the commit.

infinisil · 2023-08-10T15:23:32Z

source/tutorials/learning-journey/shell-dot-nix.md

+The `nix-shell` command by default looks for a file called `shell.nix` in the current directory and tries to build a shell environment by evaluating the Nix expression in this file.
+So, if you properly describe the shell environment you want in a `shell.nix` file, you can enter it with just the `nix-shell` command without any further arguments.
+No more specifying packages on the command line.
+Here's what a basic `shell.nix` looks like that installs Python 3.10 as before:


Suggested change

Here's what a basic `shell.nix` looks like that installs Python 3.10 as before:

Here's what a basic `shell.nix` looks like that installs Python 3 as before:

infinisil · 2023-08-10T15:24:04Z

source/tutorials/learning-journey/shell-dot-nix.md

+    ];
+  }
+```
+where `mkShell` is a function that when called produces a shell environment.


Suggested change

where `mkShell` is a function that when called produces a shell environment.

where `mkShell` is a function that produces a shell environment.

infinisil · 2023-08-10T15:26:34Z

source/tutorials/learning-journey/shell-dot-nix.md

+```
+
+:::{note}
+`nix-shell` was originally conceived as a way to construct a shell environment containing the tools needed to *develop software*; only later was it widely used as a general way to construct temporary environments for other purposes. Also note that `mkShell` is a [wrapper around `mkDerivation`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell) so strictly speaking you can provide any attributes to `mkShell` that you could to `mkDerivation` such as `buildInputs`. However, the `packages` attribute provided to `mkShell` is an alias for `buildInputs`, so you shouldn't need to provide both `packages` and `buildInputs`.


packages is an alias for nativeBuildInputs: https://github.com/NixOS/nixpkgs/blob/bfe04ea76ce84de0ecc00ff219867aac2f890a47/pkgs/build-support/mkshell/default.nix#L37

infinisil · 2023-08-10T15:29:07Z

source/tutorials/learning-journey/shell-dot-nix.md

+For example, the shell prompt format for most shells is set by the `PS1` environment variable, but `nix-shell` already overrides this by default, and will ignore a `PS1` attribute listed in `env`.
+
+If you _really_ need to override these protected environment variables you can use the `shellHook` feature discussed in the next section and `export MYVAR="value"` in the hook script.
+It's generally discouraged to set environment variables this way.


It shouldn't be called discouraged, it's very valid for secret environment variables.

infinisil · 2023-08-10T15:30:29Z

A follow-up PR sounds fine, it's very small things

Add shell.nix tutorial

5b29e71

zmitchell requested review from brianmcgee, henrik-ch, infinisil and proofconstruction August 3, 2023 03:58

proofconstruction reviewed Aug 3, 2023

View reviewed changes

roberth reviewed Aug 3, 2023

View reviewed changes

source/tutorials/learning-journey/shell-dot-nix.md Show resolved Hide resolved

source/tutorials/learning-journey/shell-dot-nix.md Outdated Show resolved Hide resolved

infinisil suggested changes Aug 3, 2023

View reviewed changes

Update with review comments

a0a4cd8

zmitchell marked this pull request as ready for review August 10, 2023 13:19

zmitchell requested review from domenkozar and fricklerhandwerk as code owners August 10, 2023 13:19

zmitchell commented Aug 10, 2023

View reviewed changes

Update with docs team review

56429a2

zmitchell merged commit 31f269d into NixOS:master Aug 10, 2023
1 check passed

infinisil reviewed Aug 10, 2023

View reviewed changes

infinisil mentioned this pull request Aug 10, 2023

add a tutorial on packaging existing software #650

Merged

zmitchell mentioned this pull request Aug 17, 2023

Tutorials overview #572

Open

26 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add shell.nix tutorial #671

Add shell.nix tutorial #671

zmitchell commented Aug 3, 2023

proofconstruction left a comment

proofconstruction Aug 3, 2023

infinisil left a comment •

edited

nixos-discourse commented Aug 3, 2023

zmitchell Aug 10, 2023

zmitchell Aug 10, 2023

nixos-discourse commented Aug 10, 2023

infinisil commented Aug 10, 2023

zmitchell commented Aug 10, 2023

infinisil Aug 10, 2023

infinisil Aug 10, 2023

infinisil Aug 10, 2023

infinisil Aug 10, 2023

infinisil commented Aug 10, 2023

+Other variables are protected: the shell prompt format is set by the `PS1` environment variable, but `nix-shell` already overrides this by default, and does not allow us to alter the `PS1` attribute directly. In these cases, we can still set a new value for that environment variable by manually exporting it in the [`shellHook` attribute](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell-attributes) passed to `mkShell`.
+To set the shell prompt to the format `<username>@<hostname> [myEnv] $ `, the `shell.nix` file would look like this:
+```nix
+let
+    pkgs = import <nixpkgs> {};
+in
+    pkgs.mkShell {
+        packages = [
+          pkgs.python310
+          pkgs.curl
+        ];
+        # Database username and password
+        DB_USER = "db_user";
+        DB_PASSWORD = "super secret don't look";
+        # Set the shell prompt to '<username>@<hostname> [myEnv] $ '
+        mkShell = ''
+          export PS1="\u@\h [myEnv] $ ";
+        '';
+    }

	Here's what a basic `shell.nix` looks like that installs Python 3.10 as before:
	Here's what a basic `shell.nix` looks like that installs Python 3 as before:

	where `mkShell` is a function that when called produces a shell environment.
	where `mkShell` is a function that produces a shell environment.

		}
		```

Add shell.nix tutorial #671

Add shell.nix tutorial #671

Conversation

zmitchell commented Aug 3, 2023

proofconstruction left a comment

Choose a reason for hiding this comment

proofconstruction Aug 3, 2023

Choose a reason for hiding this comment

infinisil left a comment • edited

Choose a reason for hiding this comment

nixos-discourse commented Aug 3, 2023

zmitchell Aug 10, 2023

Choose a reason for hiding this comment

zmitchell Aug 10, 2023

Choose a reason for hiding this comment

nixos-discourse commented Aug 10, 2023

infinisil commented Aug 10, 2023

zmitchell commented Aug 10, 2023

infinisil Aug 10, 2023

Choose a reason for hiding this comment

infinisil Aug 10, 2023

Choose a reason for hiding this comment

infinisil Aug 10, 2023

Choose a reason for hiding this comment

infinisil Aug 10, 2023

Choose a reason for hiding this comment

infinisil commented Aug 10, 2023

infinisil left a comment •

edited